[DOC] Tweaks for String#partition

2 files changed, 37 insertions, 17 deletions

diff --git a/doc/string/partition.rdoc b/doc/string/partition.rdoc
index ebe575e8eb..ece034ee66 100644
--- a/doc/string/partition.rdoc
+++ b/doc/string/partition.rdoc
@@ -1,24 +1,44 @@
 Returns a 3-element array of substrings of +self+.
 
-Matches a pattern against +self+, scanning from the beginning.
-The pattern is:
+If +pattern+ is matched, returns the array:
 
-- +string_or_regexp+ itself, if it is a Regexp.
-- <tt>Regexp.quote(string_or_regexp)</tt>, if +string_or_regexp+ is a string.
+  [pre_match, first_match, post_match]
 
-If the pattern is matched, returns pre-match, first-match, post-match:
+where:
 
-  '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('に')  # => ["こん", "に", "ちは"]
+- +first_match+ is the first-found matching substring.
+- +pre_match+ and +post_match+ are the preceding and following substrings.
 
-If the pattern is not matched, returns a copy of +self+ and two empty strings:
+If +pattern+ is not matched, returns the array:
 
-  'hello'.partition('x') # => ["hello", "", ""]
+  [self.dup, "", ""]
 
-Related: String#rpartition, String#split.
+Note that in the examples below, a returned string <tt>'hello'</tt>
+is a copy of +self+, not +self+.
+
+If +pattern+ is a Regexp, performs the equivalent of <tt>self.match(pattern)</tt>
+(also setting {pattern-matching global variables}[rdoc-ref:globals.md@Pattern+Matching]):
+
+  'hello'.partition(/h/)  # => ["", "h", "ello"]
+  'hello'.partition(/l/)  # => ["he", "l", "lo"]
+  'hello'.partition(/l+/) # => ["he", "ll", "o"]
+  'hello'.partition(/o/)  # => ["hell", "o", ""]
+  'hello'.partition(/^/)  # => ["", "", "hello"]
+  'hello'.partition(//)   # => ["", "", "hello"]
+  'hello'.partition(/$/)  # => ["hello", "", ""]
+  'hello'.partition(/x/)  # => ["hello", "", ""]
+
+If +pattern+ is not a Regexp, converts it to a string (if it is not already one),
+then performs the equivalet of <tt>self.index(pattern)</tt>
+(and does _not_ set {pattern-matching global variables}[rdoc-ref:globals.md@Pattern+Matching]):
+
+  'hello'.partition('h')     # => ["", "h", "ello"]
+  'hello'.partition('l')     # => ["he", "l", "lo"]
+  'hello'.partition('ll')    # => ["he", "ll", "o"]
+  'hello'.partition('o')     # => ["hell", "o", ""]
+  'hello'.partition('')      # => ["", "", "hello"]
+  'hello'.partition('x')     # => ["hello", "", ""]
+  'тест'.partition('т')      # => ["", "т", "ест"]
+  'こんにちは'.partition('に') # => ["こん", "に", "ちは"]
+
+Related: see {Converting to Non-String}[rdoc-ref:String@Converting+to+Non--5CString].
diff --git a/string.c b/string.c
index 81353556c9..9d11936de7 100644
--- a/string.c
+++ b/string.c
@@ -11217,7 +11217,7 @@ rb_str_center(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *    partition(string_or_regexp) -> [head, match, tail]
+ *    partition(pattern) -> [pre_match, first_match, post_match]
  *
  *  :include: doc/string/partition.rdoc
  *