palauttaa kopion str: stä, jossa kaikki kuvion esiintymät korvataan toisella argumentilla. Kuvio on tyypillisesti Regexp; jos se annetaan merkkijonona, kaikki sen sisältämät säännölliset lausekkeet tulkitaan kirjaimellisesti, esim. \d vastaavat luvun sijasta ”d”: tä seuraavaa backslashia.
jos replacement on merkkijono, se korvataan sovitetulla tekstillä. Se voi sisältää takaviittauksia kuvion kaappausryhmiin muodossa \d, jossa d on ryhmäluku, tai \k<n>, jossa n on ryhmän nimi. Samoin, \&, \', \`, ja + vastaavat erityisiä muuttujia, $&, $', $`, ja $+ vastaavasti. (KS.regexp.rdoc lisätietoja.) on sama kuin \&. \ tulkitaan paoksi, eli yksittäiseksi takapakiksi. Huomaa, että replacement sisällä erityiset ottelumuuttujat, kuten $&, eivät viittaa nykyiseen otteluun.
jos toinen argumentti on Hash, ja hyväksytty teksti on yksi sen näppäimistä, vastaava arvo on korvaava merkkijono.
lohkomuodossa nykyinen ottelumerkkijono ohitetaan parametrina, ja muuttujia kuten , , $`, $&, ja $' asetetaan asianmukaisesti. (KS.regexp.rdoc lisätietoja.) Lohkon palauttama arvo korvataan ottelun jokaisella kutsulla.
kun ei anneta lohkoa eikä toista argumenttia, palautetaan Luetteloija.
"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*" huomaa, että merkkijono kirjaimellisesti kuluttaa takaviivaa. (KS. syntaksi / literals.rdoc lisätietoja merkkijono literals.) Back-viittauksia edeltää tyypillisesti ylimääräinen backslash. Jos haluat esimerkiksi kirjoittaa takaviitteen \& replacement kaksoislainatulla merkkijonon kirjaimella, sinun on kirjoitettava: "..\&..". Jos haluat kirjoittaa ei-back-reference-merkkijonon \& replacement, sinun täytyy ensin paeta backslashia, jotta tämä menetelmä ei tulkitse sitä back-referenceksi, ja sitten sinun täytyy paeta backslasheja uudelleen, jotta merkkijono kirjaimellinen kuluttaisi niitä: "..\\&..". Kannattaa käyttää lohkolomaketta, jotta vältytään monilta takaiskuviivoilta.