[DOC] Tweaks for String#rindex

3 files changed, 55 insertions, 52 deletions

diff --git a/doc/string/index.rdoc b/doc/string/index.rdoc
index cc34bc68e6..6045fac0f6 100644
--- a/doc/string/index.rdoc
+++ b/doc/string/index.rdoc
@@ -11,7 +11,7 @@ returns the index of the first matching substring in +self+:
   'тест'.index('с')        # => 2  # Characters, not bytes.
   'こんにちは'.index('ち')  # => 3
 
-When +pattern is a Regexp, returns the index of the first match in +self+:
+When +pattern+ is a Regexp, returns the index of the first match in +self+:
 
   'foo'.index(/o./) # => 1
   'foo'.index(/.o/) # => 0
diff --git a/doc/string/rindex.rdoc b/doc/string/rindex.rdoc
new file mode 100644
index 0000000000..8a1cc0106f
--- /dev/null
+++ b/doc/string/rindex.rdoc
@@ -0,0 +1,52 @@
+Returns the integer position of the _last_ substring that matches the given argument +pattern+,
+or +nil+ if none found.
+
+When +pattern+ is a string, returns the index of the last matching substring in self:
+
+  'foo'.rindex('f')       # => 0
+  'foo'.rindex('o')       # => 2
+  'foo'.rindex('oo'       # => 1
+  'foo'.rindex('ooo')     # => nil
+  'тест'.rindex('т')      # => 3
+  'こんにちは'.rindex('ち') # => 3
+
+When +pattern+ is a Regexp, returns the index of the last match in self:
+
+  'foo'.rindex(/f/)   # => 0
+  'foo'.rindex(/o/)   # => 2
+  'foo'.rindex(/oo/)  # => 1
+  'foo'.rindex(/ooo/) # => nil
+
+When +offset+ is non-negative, it specifies the maximum starting position in the
+string to end the search:
+
+  'foo'.rindex('o', 0) # => nil
+  'foo'.rindex('o', 1) # => 1
+  'foo'.rindex('o', 2) # => 2
+  'foo'.rindex('o', 3) # => 2
+
+With negative integer argument +offset+,
+selects the search position by counting backward from the end of +self+:
+
+  'foo'.rindex('o', -1) # => 2
+  'foo'.rindex('o', -2) # => 1
+  'foo'.rindex('o', -3) # => nil
+  'foo'.rindex('o', -4) # => nil
+
+The last match means starting at the possible last position, not
+the last of longest matches:
+
+  'foo'.rindex(/o+/) # => 2
+  $~                 # => #<MatchData "o">
+
+To get the last longest match, combine with negative lookbehind:
+
+  'foo'.rindex(/(?<!o)o+/) # => 1
+  $~                       # => #<MatchData "oo">
+
+Or String#index with negative lookforward.
+
+  'foo'.index(/o+(?!.*o)/) # => 1
+  $~                       # => #<MatchData "oo">
+
+Related: see {Querying}[rdoc-ref:String@Querying].
diff --git a/string.c b/string.c
index fab1509bac..47de66eca6 100644
--- a/string.c
+++ b/string.c
@@ -4770,59 +4770,10 @@ rb_str_rindex(VALUE str, VALUE sub, long pos)
 
 /*
  *  call-seq:
- *    rindex(substring, offset = self.length) -> integer or nil
- *    rindex(regexp, offset = self.length) -> integer or nil
+ *    rindex(pattern, offset = self.length) -> integer or nil
  *
- *  Returns the Integer index of the _last_ occurrence of the given +substring+,
- *  or +nil+ if none found:
+ *  :include:doc/string/rindex.rdoc
  *
- *    'foo'.rindex('f') # => 0
- *    'foo'.rindex('o') # => 2
- *    'foo'.rindex('oo') # => 1
- *    'foo'.rindex('ooo') # => nil
- *
- *  Returns the Integer index of the _last_ match for the given Regexp +regexp+,
- *  or +nil+ if none found:
- *
- *    'foo'.rindex(/f/) # => 0
- *    'foo'.rindex(/o/) # => 2
- *    'foo'.rindex(/oo/) # => 1
- *    'foo'.rindex(/ooo/) # => nil
- *
- *  The _last_ match means starting at the possible last position, not
- *  the last of longest matches.
- *
- *    'foo'.rindex(/o+/) # => 2
- *    $~ #=> #<MatchData "o">
- *
- *  To get the last longest match, needs to combine with negative
- *  lookbehind.
- *
- *    'foo'.rindex(/(?<!o)o+/) # => 1
- *    $~ #=> #<MatchData "oo">
- *
- *  Or String#index with negative lookforward.
- *
- *    'foo'.index(/o+(?!.*o)/) # => 1
- *    $~ #=> #<MatchData "oo">
- *
- *  Integer argument +offset+, if given and non-negative, specifies the maximum starting position in the
- *  string to _end_ the search:
- *
- *    'foo'.rindex('o', 0) # => nil
- *    'foo'.rindex('o', 1) # => 1
- *    'foo'.rindex('o', 2) # => 2
- *    'foo'.rindex('o', 3) # => 2
- *
- *  If +offset+ is a negative Integer, the maximum starting position in the
- *  string to _end_ the search is the sum of the string's length and +offset+:
- *
- *    'foo'.rindex('o', -1) # => 2
- *    'foo'.rindex('o', -2) # => 1
- *    'foo'.rindex('o', -3) # => nil
- *    'foo'.rindex('o', -4) # => nil
- *
- *  Related: String#index.
  */
 
 static VALUE