retourneert een kopie van str met alle voorkomen van patroon vervangen voor het tweede argument. Het patroon is typisch een Regexp; indien gegeven als een String, zullen alle reguliere expressie metacharacters die het bevat letterlijk worden geïnterpreteerd, bijvoorbeeld \d zal overeenkomen met een backslash gevolgd door ‘d’, in plaats van een cijfer.
als replacement een tekenreeks is, wordt de overeenkomende tekst vervangen. Het kan verwijzingen bevatten naar de capture-groepen van het patroon met de vorm \d, waarbij d een groepsnummer is, of \k<n>, waarbij n een groepsnaam is. Evenzo, \&, \', \`, en + komen overeen met speciale variabelen, $&, $', $`, en $+ respectievelijk. (Zie regexp.rdoc voor details.) is gelijk aan \&. \ wordt geïnterpreteerd als een escape, d.w.z. een enkele backslash. Merk op dat binnen replacement de speciale match variabelen, zoals $&, niet naar de huidige match zullen verwijzen.
als het tweede argument een Hash is en de overeenkomende tekst een van de sleutels is, is de overeenkomstige waarde de vervangende tekenreeks.
in de blokvorm wordt de huidige overeenkomstreeks doorgegeven als een parameter, en variabelen zoals , , $`, $&, en $' zal correct worden ingesteld. (Zie regexp.rdoc voor details.) De waarde geretourneerd door het blok zal worden vervangen voor de wedstrijd bij elke oproep.
wanneer noch een blok noch een tweede argument wordt gegeven, wordt een teller geretourneerd.
"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*"merk op dat een letterlijke tekenreeks backslashes gebruikt. (Zie syntaxis / literalen.rdoc voor details over string literals.) Back-referenties worden meestal voorafgegaan door een extra backslash. Als u bijvoorbeeld een back-reference \& in replacement wilt schrijven met een letterlijke tekst met dubbele aanhalingstekens, moet u schrijven: "..\&..". Als u een niet-back-reference string \& in replacement wilt schrijven, moet u eerst de backslash ontsnappen om te voorkomen dat deze methode het interpreteert als een back-reference, en dan moet u de backslashes opnieuw ontsnappen om te voorkomen dat een letterlijke string ze consumeert: "..\\&..". U kunt het blok formulier gebruiken om veel backslashes te voorkomen.