zwraca kopię str ze wszystkimi wystąpieniami wzorca podstawionymi dla drugiego argumentu. Wzorzec jest zazwyczaj wyrażeniem regularnym; jeśli jest podany jako ciąg znaków, metaznaki wyrażenia regularnego, które zawiera, będą interpretowane dosłownie, np. \d będzie pasować do odwrotnego ukośnika, po którym następuje 'd’, zamiast cyfry.
jeśli replacement jest ciągiem, zostanie on zastąpiony dopasowanym tekstem. Może zawierać odniesienia wstecz do grup przechwytywania wzorca w postaci \d, gdzie d jest numerem grupy, lub \k<n>, gdzie n jest nazwą grupy. Podobnie, \&, \', \`, i + odpowiadają zmiennym specjalnym, $&, $', $`, i $+, odpowiednio. (Patrz Wyrażenie regularne.rdoc po szczegóły.) jest tym samym co \&. \ jest interpretowany jako ucieczka, czyli pojedynczy ukośnik wsteczny. Zauważ, że w replacement specjalne zmienne dopasowania, takie jak $&, nie będą odnosić się do bieżącego dopasowania.
jeśli drugi argument jest skrótem, a dopasowany tekst jest jednym z jego kluczy, odpowiednią wartością jest łańcuch zastępczy.
w postaci bloku, bieżący ciąg dopasowania jest przekazywany jako parametr, A zmienne takie jak , , $`, $&, i $' zostaną odpowiednio ustawione. (Patrz Wyrażenie regularne.rdoc po szczegóły.) Wartość zwracana przez blok zostanie zamieniona na dopasowanie przy każdym wywołaniu.
gdy nie podano ani bloku, ani drugiego argumentu, zwracany jest Enumerator.
"hello".gsub(//, '*') #=> "h*ll*""hello".gsub(/()/, '<>') #=> "h<e>ll<o>""hello".gsub(/./) {|s| s.ord.to_s + ' '} #=> "104 101 108 108 111 ""hello".gsub(/(?<foo>)/, '{\k<foo>}') #=> "h{e}ll{o}"'hello'.gsub(//, 'e' => 3, 'o' => '*') #=> "h3ll*"zauważ, że literał łańcucha zużywa odwrotne ukośniki. (Patrz składnia / literały.rdoc dla szczegółów dotyczących literałów łańcuchowych.) Back-odniesienia są zazwyczaj poprzedzone dodatkowym ukośnikiem wstecznym. Na przykład, jeśli chcesz napisać odwołanie zwrotne \& w replacement z podwójnym cudzysłowem, musisz napisać: "..\&..". Jeśli chcesz napisać ciąg \& nie będący odwrotnym odniesieniem w replacement, najpierw musisz uciec przed odwrotnym ukośnikiem, aby zapobiec interpretacji tej metody jako odwrotnego odniesienia, a następnie musisz ponownie uciec przed odwrotnym ukośnikiem, aby zapobiec ich zużyciu przez literał: "..\\&..". Możesz użyć formularza bloku, aby uniknąć wielu odwrotnych ukośników.