* array.c (rb_ary_aref): Updated documentation to indicate the

  starting index is an index into the array or string.  Updated
  examples to show behavior of indexes at the end of an array or
  string.  Based on patch by Marcus Stollsteimer.  [Bug #6680]
* array.c (rb_ary_aset):  ditto.
* string.c (rb_str_aref):  ditto.  Also added descriptive argument
  names to call-seq section.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36298 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 44 insertions, 29 deletions

diff --git a/string.c b/string.c
index c97bfc8047..e275e577ea 100644
--- a/string.c
+++ b/string.c
@@ -3202,49 +3202,64 @@ rb_str_aref(VALUE str, VALUE indx)
 
 /*
  *  call-seq:
- *     str[fixnum]                 -> new_str or nil
- *     str[fixnum, fixnum]         -> new_str or nil
- *     str[range]                  -> new_str or nil
- *     str[regexp]                 -> new_str or nil
- *     str[regexp, fixnum]         -> new_str or nil
- *     str[other_str]              -> new_str or nil
- *     str.slice(fixnum)           -> new_str or nil
- *     str.slice(fixnum, fixnum)   -> new_str or nil
- *     str.slice(range)            -> new_str or nil
- *     str.slice(regexp)           -> new_str or nil
- *     str.slice(regexp, fixnum)   -> new_str or nil
- *     str.slice(regexp, capname)  -> new_str or nil
- *     str.slice(other_str)        -> new_str or nil
- *
- *  Element Reference---If passed a single <code>Fixnum</code>, returns a
- *  substring of one character at that position. If passed two <code>Fixnum</code>
- *  objects, returns a substring starting at the offset given by the first, and
- *  with a length given by the second. If passed a range, its beginning and end
- *  are interpreted as offsets delimiting the substring to be returned. In all
- *  three cases, if an offset is negative, it is counted from the end of <i>str</i>.
- *  Returns <code>nil</code> if the initial offset falls outside the string or
- *  the length is negative.
- *
- *  If a <code>Regexp</code> is supplied, the matching portion of <i>str</i> is
- *  returned. If a numeric or name parameter follows the regular expression, that
- *  component of the <code>MatchData</code> is returned instead. If a
- *  <code>String</code> is given, that string is returned if it occurs in
- *  <i>str</i>. In both cases, <code>nil</code> is returned if there is no
- *  match.
+ *     str[index]                 -> new_str or nil
+ *     str[start, length]         -> new_str or nil
+ *     str[range]                 -> new_str or nil
+ *     str[regexp]                -> new_str or nil
+ *     str[regexp, capture]       -> new_str or nil
+ *     str[match_str]             -> new_str or nil
+ *     str.slice(index)           -> new_str or nil
+ *     str.slice(start, length)   -> new_str or nil
+ *     str.slice(range)           -> new_str or nil
+ *     str.slice(regexp)          -> new_str or nil
+ *     str.slice(regexp, capture) -> new_str or nil
+ *     str.slice(match_str)       -> new_str or nil
+ *
+ *  Element Reference --- If passed a single +index+, returns a substring of
+ *  one character at that index. If passed a +start+ index and a +length+,
+ *  returns a substring containing +length+ characters starting at the
+ *  +index+. If passed a range, its beginning and end are interpreted as
+ *  offsets delimiting the substring to be returned. In these three cases, if
+ *  an index is negative, it is counted from the end of the string.
+ *
+ *  Returns +nil+ if the initial index falls outside the string or the length
+ *  is negative.
+ *
+ *  If a +Regexp+ is supplied, the matching portion of the string is
+ *  returned.  If a +capture+ follows the regular expression, which may be a
+ *  capture group index or name, follows the regular expression that component
+ *  of the MatchData is returned instead.
+ *
+ *  If a +match_str+ is given, that string is returned if it occurs in
+ *  the string.
+ *
+ *  Returns +nil+ if the regular expression does not match or the match string
+ *  cannot be found.
  *
  *     a = "hello there"
+ *
  *     a[1]                   #=> "e"
  *     a[2, 3]                #=> "llo"
  *     a[2..3]                #=> "ll"
+ *
  *     a[-3, 2]               #=> "er"
  *     a[7..-2]               #=> "her"
  *     a[-4..-2]              #=> "her"
  *     a[-2..-4]              #=> ""
+ *
+ *     a[11, 0]               #=> ""
+ *     a[11]                  #=> nil
+ *     a[12, 0]               #=> nil
  *     a[12..-1]              #=> nil
+ *
  *     a[/[aeiou](.)\1/]      #=> "ell"
  *     a[/[aeiou](.)\1/, 0]   #=> "ell"
  *     a[/[aeiou](.)\1/, 1]   #=> "l"
  *     a[/[aeiou](.)\1/, 2]   #=> nil
+ *
+ *     a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] #=> "l"
+ *     a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "vowel"]     #=> "e"
+ *
  *     a["lo"]                #=> "lo"
  *     a["bye"]               #=> nil
  */