[DOC] Tweaks for String#sub

2 files changed, 34 insertions, 7 deletions

diff --git a/doc/string/sub.rdoc b/doc/string/sub.rdoc
new file mode 100644
index 0000000000..ff051ea177
--- /dev/null
+++ b/doc/string/sub.rdoc
@@ -0,0 +1,33 @@
+Returns a copy of self, possibly with a substring replaced.
+
+Argument +pattern+ may be a string or a Regexp;
+argument +replacement+ may be a string or a Hash.
+
+Varying types for the argument values makes this method very versatile.
+
+Below are some simple examples; for many more examples,
+see {Substitution Methods}[rdoc-ref:String@Substitution+Methods].
+
+With arguments +pattern+ and string +replacement+ given,
+replaces the first matching substring with the given replacement string:
+
+  s = 'abracadabra'       # => "abracadabra"
+  s.sub('bra', 'xyzzy')   # => "axyzzycadabra"
+  s.sub(/bra/, 'xyzzy')   # => "axyzzycadabra"
+  s.sub('nope', 'xyzzy')  # => "abracadabra"
+
+With arguments +pattern+ and hash +replacement+ given,
+replaces the first matching substring with a value from the given replacement hash, or removes it:
+
+  h = {'a' => 'A', 'b' => 'B', 'c' => 'C'}
+  s.sub('b', h)  # => "aBracadabra"
+  s.sub(/b/, h)  # => "aBracadabra"
+  s.sub(/d/, h)  # => "abracaabra"  # 'd' removed.
+
+With argument +pattern+ and a block given,
+calls the block with each matching substring;
+replaces that substring with the block’s return value:
+
+  s.sub('b') {|match| match.upcase } # => "aBracadabra"
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index 55a7eebc5a..824c04a5b2 100644
--- a/string.c
+++ b/string.c
@@ -6361,13 +6361,7 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
  *    sub(pattern, replacement)   -> new_string
  *    sub(pattern) {|match| ... } -> new_string
  *
- *  Returns a copy of +self+ with only the first occurrence
- *  (not all occurrences) of the given +pattern+ replaced.
- *
- *  See {Substitution Methods}[rdoc-ref:String@Substitution+Methods].
- *
- *  Related: String#sub!, String#gsub, String#gsub!.
- *
+ *  :include: doc/string/sub.rdoc
  */
 
 static VALUE