[DOC] Enhanced RDoc for String (#5726)

Treats:

    #ljust
    #rjust
    #center
    #partition
    #rpartition

7 files changed, 114 insertions, 54 deletions

diff --git a/doc/string/center.rdoc b/doc/string/center.rdoc
new file mode 100644
index 0000000000..d53d921ad5
--- /dev/null
+++ b/doc/string/center.rdoc
@@ -0,0 +1,16 @@
+Returns a centered copy of +self+.
+
+If integer argument +size+ is greater than the size (in characters) of +self+,
+returns a new string of length +size+ that is a copy of +self+,
+centered and padded on both ends with +pad_string+:
+
+  'hello'.center(10)       # => "  hello   "
+  '  hello'.center(10)     # => "   hello  "
+  'hello'.center(10, 'ab') # => "abhelloaba"
+  'тест'.center(10)        # => "   тест   "
+  'こんにちは'.center(10)    # => "  こんにちは   "
+
+If +size+ is not greater than the size of +self+, returns a copy of +self+:
+
+  'hello'.center(5)  # => "hello"
+  'hello'.center(1)  # => "hello"
diff --git a/doc/string/ljust.rdoc b/doc/string/ljust.rdoc
new file mode 100644
index 0000000000..8e23c1fc8f
--- /dev/null
+++ b/doc/string/ljust.rdoc
@@ -0,0 +1,16 @@
+Returns a left-justified copy of +self+.
+
+If integer argument +size+ is greater than the size (in characters) of +self+,
+returns a new string of length +size+ that is a copy of +self+,
+left justified and padded on the right with +pad_string+:
+
+  'hello'.ljust(10)       # => "hello     "
+  '  hello'.ljust(10)     # => "  hello   "
+  'hello'.ljust(10, 'ab') # => "helloababa"
+  'тест'.ljust(10)        # => "тест      "
+  'こんにちは'.ljust(10)    # => "こんにちは     "
+
+If +size+ is not greater than the size of +self+, returns a copy of +self+:
+
+  'hello'.ljust(5)  # => "hello"
+  'hello'.ljust(1)  # => "hello"
diff --git a/doc/string/partition.rdoc b/doc/string/partition.rdoc
new file mode 100644
index 0000000000..ebe575e8eb
--- /dev/null
+++ b/doc/string/partition.rdoc
@@ -0,0 +1,24 @@
+Returns a 3-element array of substrings of +self+.
+
+Matches a pattern against +self+, scanning from the beginning.
+The pattern is:
+
+- +string_or_regexp+ itself, if it is a Regexp.
+- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string.
+
+If the pattern is matched, returns pre-match, first-match, post-match:
+
+  'hello'.partition('l')      # => ["he", "l", "lo"]
+  'hello'.partition('ll')     # => ["he", "ll", "o"]
+  'hello'.partition('h')      # => ["", "h", "ello"]
+  'hello'.partition('o')      # => ["hell", "o", ""]
+  'hello'.partition(/l+/)     #=> ["he", "ll", "o"]
+  'hello'.partition('')       # => ["", "", "hello"]
+  'тест'.partition('т')       # => ["", "т", "ест"]
+  'こんにちは'.partition('に')  # => ["こん", "に", "ちは"]
+
+If the pattern is not matched, returns a copy of +self+ and two empty strings:
+
+  'hello'.partition('x') # => ["hello", "", ""]
+
+Related: String#rpartition, String#split.
diff --git a/doc/string/rjust.rdoc b/doc/string/rjust.rdoc
new file mode 100644
index 0000000000..24e7bf3159
--- /dev/null
+++ b/doc/string/rjust.rdoc
@@ -0,0 +1,16 @@
+Returns a right-justified copy of +self+.
+
+If integer argument +size+ is greater than the size (in characters) of +self+,
+returns a new string of length +size+ that is a copy of +self+,
+right justified and padded on the left with +pad_string+:
+
+  'hello'.rjust(10)       # => "     hello"
+  'hello  '.rjust(10)     # => "   hello  "
+  'hello'.rjust(10, 'ab') # => "ababahello"
+  'тест'.rjust(10)        # => "      тест"
+  'こんにちは'.rjust(10)    # => "     こんにちは"
+
+If +size+ is not greater than the size of +self+, returns a copy of +self+:
+
+  'hello'.rjust(5, 'ab')  # => "hello"
+  'hello'.rjust(1, 'ab')  # => "hello"
diff --git a/doc/string/rpartition.rdoc b/doc/string/rpartition.rdoc
new file mode 100644
index 0000000000..d24106fb9f
--- /dev/null
+++ b/doc/string/rpartition.rdoc
@@ -0,0 +1,24 @@
+Returns a 3-element array of substrings of +self+.
+
+Matches a pattern against +self+, scanning backwards from the end.
+The pattern is:
+
+- +string_or_regexp+ itself, if it is a Regexp.
+- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string.
+
+If the pattern is matched, returns pre-match, last-match, post-match:
+
+  'hello'.rpartition('l')      # => ["hel", "l", "o"]
+  'hello'.rpartition('ll')     # => ["he", "ll", "o"]
+  'hello'.rpartition('h')      # => ["", "h", "ello"]
+  'hello'.rpartition('o')      # => ["hell", "o", ""]
+  'hello'.rpartition(/l+/)     # => ["hel", "l", "o"]
+  'hello'.rpartition('')       # => ["hello", "", ""]
+  'тест'.rpartition('т')       # => ["тес", "т", ""]
+  'こんにちは'.rpartition('に')  # => ["こん", "に", "ちは"]
+
+If the pattern is not matched, returns two empty strings and a copy of +self+:
+
+  'hello'.rpartition('x') # => ["", "", "hello"]
+
+Related: String#partition, String#split.
diff --git a/doc/string/split.rdoc b/doc/string/split.rdoc
index d93b76d9b4..2b5e14ddb6 100644
--- a/doc/string/split.rdoc
+++ b/doc/string/split.rdoc
@@ -82,3 +82,5 @@ Output:
   "abc"
   "def"
   "ghi"
+
+Related: String#partition, String#rpartition.
diff --git a/string.c b/string.c
index 0917f56f35..56b2eca99b 100644
--- a/string.c
+++ b/string.c
@@ -10383,15 +10383,12 @@ rb_str_justify(int argc, VALUE *argv, VALUE str, char jflag)
 
 /*
  *  call-seq:
- *     str.ljust(integer, padstr=' ')   -> new_str
+ *    ljust(size, pad_string = ' ') -> new_string
  *
- *  If <i>integer</i> is greater than the length of <i>str</i>, returns a new
- *  String of length <i>integer</i> with <i>str</i> left justified
- *  and padded with <i>padstr</i>; otherwise, returns <i>str</i>.
+ *  :include: doc/string/ljust.rdoc
+ *
+ *  Related: String#rjust, String#center.
  *
- *     "hello".ljust(4)            #=> "hello"
- *     "hello".ljust(20)           #=> "hello               "
- *     "hello".ljust(20, '1234')   #=> "hello123412341234123"
  */
 
 static VALUE
@@ -10400,18 +10397,14 @@ rb_str_ljust(int argc, VALUE *argv, VALUE str)
     return rb_str_justify(argc, argv, str, 'l');
 }
 
-
 /*
  *  call-seq:
- *     str.rjust(integer, padstr=' ')   -> new_str
+ *    rjust(size, pad_string = ' ') -> new_string
+ *
+ *  :include: doc/string/rjust.rdoc
  *
- *  If <i>integer</i> is greater than the length of <i>str</i>, returns a new
- *  String of length <i>integer</i> with <i>str</i> right justified
- *  and padded with <i>padstr</i>; otherwise, returns <i>str</i>.
+ *  Related: String#ljust, String#center.
  *
- *     "hello".rjust(4)            #=> "hello"
- *     "hello".rjust(20)           #=> "               hello"
- *     "hello".rjust(20, '1234')   #=> "123412341234123hello"
  */
 
 static VALUE
@@ -10423,15 +10416,12 @@ rb_str_rjust(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.center(width, padstr=' ')   -> new_str
+ *    center(size, pad_string = ' ') -> new_string
  *
- *  Centers +str+ in +width+.  If +width+ is greater than the length of +str+,
- *  returns a new String of length +width+ with +str+ centered and padded with
- *  +padstr+; otherwise, returns +str+.
+ *  :include: doc/string/center.rdoc
+ *
+ *  Related: String#ljust, String#rjust.
  *
- *     "hello".center(4)         #=> "hello"
- *     "hello".center(20)        #=> "       hello        "
- *     "hello".center(20, '123') #=> "1231231hello12312312"
  */
 
 static VALUE
@@ -10442,17 +10432,10 @@ rb_str_center(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.partition(sep)              -> [head, sep, tail]
- *     str.partition(regexp)           -> [head, match, tail]
+ *    partition(string_or_regexp) -> [head, match, tail]
  *
- *  Searches <i>sep</i> or pattern (<i>regexp</i>) in the string
- *  and returns the part before it, the match, and the part
- *  after it.
- *  If it is not found, returns two empty strings and <i>str</i>.
+ *  :include: doc/string/partition.rdoc
  *
- *     "hello".partition("l")         #=> ["he", "l", "lo"]
- *     "hello".partition("x")         #=> ["hello", "", ""]
- *     "hello".partition(/.l/)        #=> ["h", "el", "lo"]
  */
 
 static VALUE
@@ -10486,31 +10469,10 @@ rb_str_partition(VALUE str, VALUE sep)
 
 /*
  *  call-seq:
- *     str.rpartition(sep)             -> [head, sep, tail]
- *     str.rpartition(regexp)          -> [head, match, tail]
- *
- *  Searches <i>sep</i> or pattern (<i>regexp</i>) in the string from the end
- *  of the string, and returns the part before it, the match, and the part
- *  after it.
- *  If it is not found, returns two empty strings and <i>str</i>.
- *
- *     "hello".rpartition("l")         #=> ["hel", "l", "o"]
- *     "hello".rpartition("x")         #=> ["", "", "hello"]
- *     "hello".rpartition(/.l/)        #=> ["he", "ll", "o"]
- *
- *  The match from the end means starting at the possible last position, not
- *  the last of longest matches.
- *
- *     "hello".rpartition(/l+/)        #=> ["hel", "l", "o"]
- *
- *  To partition at the last longest match, needs to combine with
- *  negative lookbehind.
- *
- *     "hello".rpartition(/(?<!l)l+/)  #=> ["he", "ll", "o"]
+ *    rpartition(sep) -> [head, match, tail]
  *
- *  Or String#partition with negative lookforward.
+ *  :include: doc/string/rpartition.rdoc
  *
- *     "hello".partition(/l+(?!.*l)/)  #=> ["he", "ll", "o"]
  */
 
 static VALUE