names=sub!
visibility=public
kind=defined

--- sub!(pattern, replace) -> self | nil

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

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

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 の中で [[m:$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 [[m:String#gsub]]

--- sub!(pattern) {|matched| .... } -> self | nil

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

また、ブロックなしの sub と違い、ブロックの中からは
組み込み変数 [[m:$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 [[m:String#gsub]]

--- sub!(pattern, hash) -> String

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

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

