[DOC] Harmonize #[] methods

Merged: https://github.com/ruby/ruby/pull/15815

Merged-By: peterzhu2118 <peter@peterzhu.ca>

array.c

@@ -1789,14 +1789,10 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
 
 /*
  *  call-seq:
- *    self[index] -> object or nil
- *    self[start, length] -> object or nil
+ *    self[offset] -> object or nil
+ *    self[offset, size] -> object or nil
  *    self[range] -> object or nil
  *    self[aseq] -> object or nil
- *    slice(index) -> object or nil
- *    slice(start, length) -> object or nil
- *    slice(range) -> object or nil
- *    slice(aseq) -> object or nil
  *
  *  Returns elements from +self+; does not modify +self+.
  *
@@ -1804,27 +1800,27 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *
  *    a = [:foo, 'bar', 2]
  *
- *    # Single argument index: returns one element.
+ *    # Single argument offset: returns one element.
  *    a[0]     # => :foo          # Zero-based index.
  *    a[-1]    # => 2             # Negative index counts backwards from end.
  *
- *    # Arguments start and length: returns an array.
+ *    # Arguments offset and size: returns an array.
  *    a[1, 2]  # => ["bar", 2]
- *    a[-2, 2] # => ["bar", 2]    # Negative start counts backwards from end.
+ *    a[-2, 2] # => ["bar", 2]    # Negative offset counts backwards from end.
  *
  *    # Single argument range: returns an array.
  *    a[0..1]  # => [:foo, "bar"]
  *    a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
  *    a[-2..2] # => ["bar", 2]    # Negative range-end counts backwards from end.
  *
- *  When a single integer argument +index+ is given, returns the element at offset +index+:
+ *  When a single integer argument +offset+ is given, returns the element at offset +offset+:
  *
  *    a = [:foo, 'bar', 2]
  *    a[0] # => :foo
  *    a[2] # => 2
  *    a # => [:foo, "bar", 2]
  *
- *  If +index+ is negative, counts backwards from the end of +self+:
+ *  If +offset+ is negative, counts backwards from the end of +self+:
  *
  *    a = [:foo, 'bar', 2]
  *    a[-1] # => 2
@@ -1832,29 +1828,29 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *
  *  If +index+ is out of range, returns +nil+.
  *
- *  When two Integer arguments +start+ and +length+ are given,
- *  returns a new array of size +length+ containing successive elements beginning at offset +start+:
+ *  When two Integer arguments +offset+ and +size+ are given,
+ *  returns a new array of size +size+ containing successive elements beginning at offset +offset+:
  *
  *    a = [:foo, 'bar', 2]
  *    a[0, 2] # => [:foo, "bar"]
  *    a[1, 2] # => ["bar", 2]
  *
- *  If <tt>start + length</tt> is greater than <tt>self.length</tt>,
- *  returns all elements from offset +start+ to the end:
+ *  If <tt>offset + size</tt> is greater than <tt>self.size</tt>,
+ *  returns all elements from offset +offset+ to the end:
  *
  *    a = [:foo, 'bar', 2]
  *    a[0, 4] # => [:foo, "bar", 2]
  *    a[1, 3] # => ["bar", 2]
  *    a[2, 2] # => [2]
  *
- *  If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
+ *  If <tt>offset == self.size</tt> and <tt>size >= 0</tt>,
  *  returns a new empty array.
  *
- *  If +length+ is negative, returns +nil+.
+ *  If +size+ is negative, returns +nil+.
  *
  *  When a single Range argument +range+ is given,
- *  treats <tt>range.min</tt> as +start+ above
- *  and <tt>range.size</tt> as +length+ above:
+ *  treats <tt>range.min</tt> as +offset+ above
+ *  and <tt>range.size</tt> as +size+ above:
  *
  *    a = [:foo, 'bar', 2]
  *    a[0..1] # => [:foo, "bar"]

doc/string/aref.rdoc

@@ -1,30 +1,30 @@
 Returns the substring of +self+ specified by the arguments.
 
-<b>Form <tt>self[index]</tt></b>
+<b>Form <tt>self[offset]</tt></b>
 
-With non-negative integer argument +index+ given,
-returns the 1-character substring found in self at character offset index:
+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 +index+ given,
+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[start, length]</tt></b>
+<b>Form <tt>self[offset, size]</tt></b>
 
-With integer arguments +start+ and +length+ given,
-returns a substring of size +length+ characters (as available)
-beginning at character offset specified by +start+.
+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 +start+ is non-negative,
-the offset is +start+:
+If argument +offset+ is non-negative,
+the offset is +offset+:
 
   'hello'[0, 1]  # => "h"
   'hello'[0, 5]  # => "hello"
@@ -33,7 +33,7 @@ the offset is +start+:
   'hello'[2, 0]  # => ""
   'hello'[2, -1] # => nil
 
-If argument +start+ is negative,
+If argument +offset+ is negative,
 counts backward from the end of +self+:
 
   'hello'[-1, 1] # => "o"
@@ -41,7 +41,7 @@ counts backward from the end of +self+:
   'hello'[-1, 0] # => ""
   'hello'[-6, 5] # => nil
 
-Special case: if +start+ equals the length of +self+,
+Special case: if +offset+ equals the size of +self+,
 returns a new empty string:
 
   'hello'[5, 3]  # => ""

re.c

@@ -2213,12 +2213,12 @@ match_ary_aref(VALUE match, VALUE idx, VALUE result)
 
 /*
  *  call-seq:
- *    matchdata[index] -> string or nil
- *    matchdata[start, length] -> array
- *    matchdata[range] -> array
- *    matchdata[name] -> string or nil
+ *    self[offset] -> string or nil
+ *    self[offset, size] -> array
+ *    self[range] -> array
+ *    self[name] -> string or nil
  *
- *  When arguments +index+, +start and +length+, or +range+ are given,
+ *  When arguments +offset+, +offset+ and +size+, or +range+ are given,
  *  returns match and captures in the style of Array#[]:
  *
  *    m = /(.)(.)(\d+)(\d)/.match("THX1138.")

string.c

@@ -5713,8 +5713,8 @@ rb_str_aref(VALUE str, VALUE indx)
 
 /*
  *  call-seq:
- *    self[index] -> new_string or nil
- *    self[start, length] -> new_string or nil
+ *    self[offset] -> new_string or nil
+ *    self[offset, size] -> new_string or nil
  *    self[range] -> new_string or nil
  *    self[regexp, capture = 0] -> new_string or nil
  *    self[substring] -> new_string or nil
@@ -12493,11 +12493,11 @@ sym_match_m_p(int argc, VALUE *argv, VALUE sym)
 
 /*
  *  call-seq:
- *    symbol[index] -> string or nil
- *    symbol[start, length] -> string or nil
- *    symbol[range] -> string or nil
- *    symbol[regexp, capture = 0] -> string or nil
- *    symbol[substring] -> string or nil
+ *    self[offset] -> string or nil
+ *    self[offset, size] -> string or nil
+ *    self[range] -> string or nil
+ *    self[regexp, capture = 0] -> string or nil
+ *    self[substring] -> string or nil
  *
  *  Equivalent to <tt>symbol.to_s[]</tt>; see String#[].
  *