names=[],slice
visibility=public
kind=defined

--- [](nth) -> String | nil
--- slice(nth) -> String | nil

nth 番目の文字を返します。
nth が負の場合は文字列の末尾から数えます。
つまり、 self.size + nth 番目の文字を返します。

nth が範囲外を指す場合は nil を返します。

@param nth 文字の位置を表す整数
@return 指定した位置の文字を表す String オブジェクト

例:

  p 'bar'[2]       # => "r"
  p 'bar'[2] == ?r # => true
  p 'bar'[-1]      # => "r"
  p 'bar'[3]       # => nil
  p 'bar'[-4]      # => nil


このメソッドの仕様は 1.8.x 以前から大きく変更されていますので注意が必要
です。


--- [](nth, len) -> String | nil
--- slice(nth, len) -> String | nil
nth 文字目から長さ len 文字の部分文字列を新しく作って返します。
nth が負の場合は文字列の末尾から数えます。

@param nth    取得したい文字列の開始インデックスを整数で指定します。
@param len    取得したい文字列の長さを正の整数で指定します。

@return nth が範囲外を指す場合は nil を返します。

例:

  str0 = "bar"
  str0[2, 1]         #=> "r"
  str0[2, 0]         #=> ""
  str0[2, 100]       #=> "r"  (右側を超えても平気)
  str0[-1, 1]        #=> "r"
  str0[-1, 2]        #=> "r" (あくまでも「右に向かって len 文字」)

  str0[3, 1]         #=> ""
  str0[4, 1]         #=> nil
  str0[-4, 1]        #=> nil
  str1 = str0[0, 2]    # (str0 の「一部」を str1 とする)
  str1               #=> "ba"
  str1[0] = "XYZ"
  str1               #=> "XYZa" (str1 の内容が破壊的に変更された)
  str0               #=> "bar" (str0 は無傷、 str1 は str0 と内容を共有していない)

--- [](substr) -> String | nil
--- slice(substr) -> String | nil

self が substr を含む場合、一致した文字列を新しく作って返します。
substr を含まなければ nil を返します。

@param substr    取得したい文字列のパターン。文字列

例:
    substr = "bar"
    result = "foobar"[substr]
    p result   # => "bar"
    p substr.equal?(result)   # => false

--- [](regexp, nth = 0) -> String
--- slice(regexp, nth = 0) -> String

正規表現 regexp の nth 番目の括弧にマッチする最初の部分文字列を返します。
nth を省略したときや 0 の場合は正規表現がマッチした部分文字列全体を返します。
正規表現が self にマッチしなかった場合や nth に対応する括弧がないときは nil を返します。

このメソッドを実行すると、
マッチ結果に関する情報が組み込み変数 [[m:$~]] に設定されます。

@param regexp    取得したい文字列のパターンを示す正規表現
@param nth       取得したい正規表現レジスタのインデックス。整数

   p "foobar"[/bar/]  # => "bar"
   p $~.begin(0)      # => 3

   p "def getcnt(line)"[ /def\s+(\w+)/, 1 ]   # => "getcnt"

--- [](regexp, name) -> String
--- slice(regexp, name) -> String

正規表現 regexp の name で指定した名前付きキャプチャにマッチする最初の
部分文字列を返します。正規表現が self にマッチしなかった場合は nil を返
します。

@param regexp 正規表現を指定します。
@param name 取得したい部分文字列のパターンを示す正規表現レジスタを示す名前

@raise IndexError name に対応する括弧がない場合に発生します。

例:

  s = "FooBar"
  s[/(?<foo>[A-Z]..)(?<bar>[A-Z]..)/]        # => "FooBar"
  s[/(?<foo>[A-Z]..)(?<bar>[A-Z]..)/, "foo"] # => "Foo"
  s[/(?<foo>[A-Z]..)(?<bar>[A-Z]..)/, "bar"] # => "Bar"
  s[/(?<foo>[A-Z]..)(?<bar>[A-Z]..)/, "baz"] # => IndexError


--- [](range) -> String
--- slice(range) -> String

rangeで指定したインデックスの範囲に含まれる部分文字列を返します。

@param range   取得したい文字列の範囲を示す Range オブジェクト

=== rangeオブジェクトが終端を含む場合

インデックスと文字列の対応については以下の対照図も参照してください。

    0   1   2   3   4   5   (インデックス)
   -6  -5  -4  -3  -2  -1   (負のインデックス)
  | a | b | c | d | e | f |
  |<--------->|                'abcdef'[0..2]  # => 'abc'
                  |<----->|    'abcdef'[4..5]  # => 'ef'
          |<--------->|        'abcdef'[2..4]  # => 'cde'

range.last が文字列の長さ以上のときは
(文字列の長さ - 1) を指定したものとみなされます。

range.first が 0 より小さいか文字列の長さより大きいときは nil を
返します。ただし range.first および range.last のどちらか
または両方が負の数のときは一度だけ文字列の長さを足して
再試行します。

例:

  'abcd'[ 2 ..  1] # => ""
  'abcd'[ 2 ..  2] # => "c"
  'abcd'[ 2 ..  3] # => "cd"
  'abcd'[ 2 ..  4] # => "cd"

  'abcd'[ 2 .. -1] # => "cd"   # str[f..-1] は「f 文字目から
  'abcd'[ 3 .. -1] # => "d"    # 文字列の最後まで」を表す慣用句

  'abcd'[ 1 ..  2] # => "bc"
  'abcd'[ 2 ..  2] # => "c"
  'abcd'[ 3 ..  2] # => ""
  'abcd'[ 4 ..  2] # => ""
  'abcd'[ 5 ..  2] # => nil

  'abcd'[-3 ..  2] # => "bc"
  'abcd'[-4 ..  2] # => "abc"
  'abcd'[-5 ..  2] # => nil

=== rangeオブジェクトが終端を含まない場合

文字列と「隙間」の関係については以下の模式図を参照してください。

     0   1   2   3   4   5   6  (隙間番号)
    -6  -5  -4  -3  -2  -1      (負の隙間番号)
     | a | b | c | d | e | f |
     |<--------->|                'abcdef'[0...3]  # => 'abc'
                     |<----->|    'abcdef'[4...6]  # => 'ef'
             |<--------->|        'abcdef'[2...5]  # => 'cde'

range.last が文字列の長さよりも大きいときは文字列の長さを
指定したものとみなされます。

range.first が 0 より小さいか文字列の長さより大きいときは nil を返します。
ただし range.first と range.last のどちらかまたは両方が負の数
であるときは一度だけ文字列の長さを足して再試行します。

例:
    'abcd'[ 2 ... 3] # => "c"
    'abcd'[ 2 ... 4] # => "cd"
    'abcd'[ 2 ... 5] # => "cd"

    'abcd'[ 1 ... 2] # => "b"
    'abcd'[ 2 ... 2] # => ""
    'abcd'[ 3 ... 2] # => ""
    'abcd'[ 4 ... 2] # => ""
    'abcd'[ 5 ... 2] # => nil

    'abcd'[-3 ... 2] # => "b"
    'abcd'[-4 ... 2] # => "ab"
    'abcd'[-5 ... 2] # => nil

