From 5230f835e807b7b6935b758de58ee26da6cb6a60 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 7 Jan 2026 17:01:56 -0600 Subject: [PATCH] [DOC] Harmonize #[] methods --- array.c | 34 +++++++++++++++------------------- doc/string/aref.rdoc | 24 ++++++++++++------------ re.c | 10 +++++----- string.c | 14 +++++++------- 4 files changed, 39 insertions(+), 43 deletions(-) diff --git a/array.c b/array.c index e13239ad3d..b471823876 100644 --- a/array.c +++ b/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 start + length is greater than self.length, - * returns all elements from offset +start+ to the end: + * If offset + size is greater than self.size, + * 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 start == self.size and length >= 0, + * If offset == self.size and size >= 0, * 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 range.min as +start+ above - * and range.size as +length+ above: + * treats range.min as +offset+ above + * and range.size as +size+ above: * * a = [:foo, 'bar', 2] * a[0..1] # => [:foo, "bar"] diff --git a/doc/string/aref.rdoc b/doc/string/aref.rdoc index 59c6ae97ac..a9ab8857bc 100644 --- a/doc/string/aref.rdoc +++ b/doc/string/aref.rdoc @@ -1,30 +1,30 @@ Returns the substring of +self+ specified by the arguments. -Form self[index] +Form self[offset] -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 -Form self[start, length] +Form self[offset, size] -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] # => "" diff --git a/re.c b/re.c index fe8e93c6a6..027fa597f4 100644 --- a/re.c +++ b/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.") diff --git a/string.c b/string.c index c8233be66f..234ef1edc8 100644 --- a/string.c +++ b/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 symbol.to_s[]; see String#[]. *