instance method String#sub!

sub!(pattern, replace) -> self | nil[permalink][rdoc]

文字列中で pattern にマッチした最初の部分を文字列 replace へ破壊的に置き換えます。

置換文字列 replace 中の \& と \0 はマッチした部分文字列に、 \1 ... \9 は n 番目の括弧の内容に置き換えられます。置換文字列内では \`、\'、\+ も使えます。これらは $`、$'、$+ に対応します。

sub! は通常 self を変更して返しますが、置換が起こらなかった場合は nil を返します。

[PARAM] pattern:
置き換える文字列のパターンを表す文字列か正規表現。文字列を指定した場合は全く同じ文字列にだけマッチする
[PARAM] replace:
pattern で指定した文字列と置き換える文字列
[RETURN]
置換した場合は self、置換しなかった場合は nil 
例

buf = "String-String"
buf.sub!(/in./, "!!")
p buf   # => "Str!!-String"

buf = "String.String"
buf.sub!(/in./, '<<\&>>')
p buf   # => "Str<<ing>>-String"

注意:

引数 replace の中で $1 を使うことはできません。 replace は sub メソッドの呼び出しより先に評価されるので、まだ sub の正規表現マッチが行われておらず、 $1 がセットされていないからです。

また、sub では「\」が部分文字列との置き換えという特別な意味を持つため、 replace に「\」自身を入れたいときは「\」を二重にエスケープしなければなりません。 

ひとつめの括弧にマッチした部分に置き換えるときによくやる間違いと正しい例

'abbbcd'.sub!(/a(b+)/, "#{$1}")       # NG
'abbbcd'.sub!(/a(b+)/, "\1")          # NG
'abbbcd'.sub!(/a(b+)/, "\\1")         # OK
'abbbcd'.sub!(/a(b+)/, '\\1')         # OK
'abbbcd'.sub!(/a(b+)/, '\1')          # OK
'abbbcd'.sub!(/a(b+)/) { $1 }         # OK   これがもっとも安全

[SEE_ALSO] String#gsub

sub!(pattern) {|matched| .... } -> self | nil[permalink][rdoc]

文字列中で pattern にマッチした最初の部分をブロックに渡し、その評価結果へ破壊的に置き換えます。

また、ブロックなしの sub と違い、ブロックの中からは組み込み変数 $1, $2, $3, ... を問題なく参照できます。

[PARAM] pattern:
置き換える文字列のパターンを表す文字列か正規表現。文字列を指定した場合は全く同じ文字列にだけマッチする
[RETURN]
置換した場合は self、置換しなかった場合は nil 
例

str = 'abcabc'
str.sub!(/b/) {|s| s.upcase }
p str    #=> "aBcabc"

str = 'abcabc'
str.sub!(/b/) { $&.upcase }
p str    #=> "aBcabc"

[SEE_ALSO] String#gsub

sub!(pattern, hash) -> String[permalink][rdoc]

文字列中の pattern にマッチした部分をキーにして hash を引いた値で破壊的に置き換えます。

[PARAM] pattern:
置き換える文字列のパターン
[PARAM] hash:
置き換える文字列を与えるハッシュ
[RETURN]
置換した場合は self、置換しなかった場合は nil