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

--- [](nth) -> Integer
--- slice(nth) -> Integer

nth 番目のバイトを整数 (文字コード) で返します。
nth が負の場合は文字列の末尾から数えます。
つまり、 self.size + nth 番目のバイトを返します。

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

@param nth      バイトインデックスを表す整数
@return         文字コードを表す整数

例:

  p 'bar'[2]        # => 114
  p 'bar'[2] == ?r  # => true
  p 'bar'[-1]       # => 114

  p 'bar'[3]        # => nil
  p 'bar'[-4]       # => nil

このメソッドの逆に文字コードから文字列を得るには
[[m:Integer#chr]] を使ってください。

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

nth バイト番目から長さ len バイトの部分文字列を新しく作って返します。
nth が負の場合は文字列の末尾から数えます。

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

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

例:

  str0 = "bar"
  p str0[2, 1]         #=> "r"
  p str0[2, 0]         #=> ""
  p str0[2, 100]       #=> "r"  (右側を超えても平気)
  p str0[2, 1] == ?r   #=> false  (左辺は長さ1の文字列、右辺は整数の文字コード)
  p str0[-1, 1]        #=> "r"
  p str0[-1, 2]        #=> "r" (飽くまでも「右に向かって len バイト」)

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

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

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 "foobar"[/bar/]   # => "bar"
   p $~.begin(0)       # => 3

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

--- [](first..last) -> String
--- slice(first..last) -> String

インデックス first から last までのバイトを含む新しい文字列を作成して返します。
インデックスと文字列の対応については以下の対照図も参照してください。

    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'

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

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

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

例:

  '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] # =>  nil

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

--- [](first...last) -> String
--- slice(first...last) -> String

文字列先頭を 0 番目の隙間、末尾を self.length 番目の隙間として、
first 番目の隙間から last 番目の隙間までに含まれる
バイト列を含んだ新しい文字列を作成して返します。

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

     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'

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

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

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

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

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

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

