1 files changed, 96 insertions, 0 deletions
diff --git a/doc/string/aref.rdoc b/doc/string/aref.rdoc
new file mode 100644
index 0000000000..a9ab8857bc
--- /dev/null
+++ b/doc/string/aref.rdoc
@@ -0,0 +1,96 @@
+Returns the substring of +self+ specified by the arguments.
+
+<b>Form <tt>self[offset]</tt></b>
+
+With non-negative integer argument +offset+ given,
+returns the 1-character substring found in self at character offset +offset+:
+
+  'hello'[0]    # => "h"
+  'hello'[4]    # => "o"
+  'hello'[5]    # => nil
+  'こんにちは'[4] # => "は"
+
+With negative integer argument +offset+ given,
+counts backward from the end of +self+:
+
+  'hello'[-1] # => "o"
+  'hello'[-5] # => "h"
+  'hello'[-6] # => nil
+
+<b>Form <tt>self[offset, size]</tt></b>
+
+With integer arguments +offset+ and +size+ given,
+returns a substring of size +size+ characters (as available)
+beginning at character offset specified by +offset+.
+
+If argument +offset+ is non-negative,
+the offset is +offset+:
+
+  'hello'[0, 1]  # => "h"
+  'hello'[0, 5]  # => "hello"
+  'hello'[0, 6]  # => "hello"
+  'hello'[2, 3]  # => "llo"
+  'hello'[2, 0]  # => ""
+  'hello'[2, -1] # => nil
+
+If argument +offset+ is negative,
+counts backward from the end of +self+:
+
+  'hello'[-1, 1] # => "o"
+  'hello'[-5, 5] # => "hello"
+  'hello'[-1, 0] # => ""
+  'hello'[-6, 5] # => nil
+
+Special case: if +offset+ equals the size of +self+,
+returns a new empty string:
+
+  'hello'[5, 3]  # => ""
+
+<b>Form <tt>self[range]</tt></b>
+
+With Range argument +range+ given,
+forms substring <tt>self[range.start, range.size]</tt>:
+
+  'hello'[0..2]  # => "hel"
+  'hello'[0, 3]  # => "hel"
+
+  'hello'[0...2] # => "he"
+  'hello'[0, 2]  # => "he"
+
+  'hello'[0, 0]  # => ""
+  'hello'[0...0] # => ""
+
+<b>Form <tt>self[regexp, capture = 0]</tt></b>
+
+With Regexp argument +regexp+ given and +capture+ as zero,
+searches for a matching substring in +self+;
+updates {Regexp-related global variables}[rdoc-ref:Regexp@Global+Variables]:
+
+  'hello'[/ell/]     # => "ell"
+  'hello'[/l+/]      # => "ll"
+  'hello'[//]        # => ""
+  'hello'[/nosuch/]  # => nil
+
+With +capture+ as a positive integer +n+,
+returns the +n+th matched group:
+
+  'hello'[/(h)(e)(l+)(o)/]    # => "hello"
+  'hello'[/(h)(e)(l+)(o)/, 1] # => "h"
+  $1                          # => "h"
+  'hello'[/(h)(e)(l+)(o)/, 2] # => "e"
+  $2                          # => "e"
+  'hello'[/(h)(e)(l+)(o)/, 3] # => "ll"
+  'hello'[/(h)(e)(l+)(o)/, 4] # => "o"
+  'hello'[/(h)(e)(l+)(o)/, 5] # => nil
+
+<b>Form <tt>self[substring]</tt></b>
+
+With string argument +substring+ given,
+returns the matching substring of +self+, if found:
+
+  'hello'['ell']      # => "ell"
+  'hello'['']         # => ""
+  'hello'['nosuch']   # => nil
+  'こんにちは'['んにち'] # => "んにち"
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].