From 211618419019f66e077e56e52c8a04f4db907a96 Mon Sep 17 00:00:00 2001 From: marcandre Date: Wed, 30 Jun 2010 22:14:38 +0000 Subject: * string.c (rb_str_gsub_bang, rb_str_sub_bang, str_gsub): rdoc fix based on patch by Run Paint [ruby-core:30938] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@28492 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- string.c | 88 ++++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 53 insertions(+), 35 deletions(-) (limited to 'string.c') diff --git a/string.c b/string.c index 703797f798..ba4ce86087 100644 --- a/string.c +++ b/string.c @@ -3550,35 +3550,41 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str) /* * call-seq: * str.sub(pattern, replacement) -> new_str + * str.sub(pattern, hash) -> new_str * str.sub(pattern) {|match| block } -> new_str - * str.sub(pattern) -> an_enumerator * * Returns a copy of str with the first occurrence of - * pattern replaced with either replacement or the value of the - * block. The pattern will typically be a Regexp; if it is - * a String then no regular expression metacharacters will be - * interpreted (that is /\d/ will match a digit, but - * '\d' will match a backslash followed by a 'd'). - * - * If the method call specifies replacement, special variables such as - * $& will not be useful, as substitution into the string occurs - * before the pattern match starts. However, the sequences \1, - * \2, \k, etc., may be used. - * - * In the block form, the current match string is passed in as a parameter, and - * variables such as $1, $2, $`, + * pattern substituted for the second argument. The pattern is + * typically a Regexp; if given as a String, any + * regular expression metacharacters it contains will be interpreted + * literally, e.g. '\\\d' will match a backlash followed by 'd', + * instead of a digit. + * + * If replacement is a String it will be substituted for + * the matched text. It may contain back-references to the pattern's capture + * groups of the form \\\d, where d is a group number, or + * \\\k, where n is a group name. If it is a + * double-quoted string, both back-references must be preceded by an + * additional backslash. However, within replacement the special match + * variables, such as &$, will not refer to the current match. + * + * If the second argument is a Hash, and the matched text is one + * of its keys, the corresponding value is the replacement string. + * + * In the block form, the current match string is passed in as a parameter, + * and variables such as $1, $2, $`, * $&, and $' will be set appropriately. The value * returned by the block will be substituted for the match on each call. * - * If no block and no replacement is given, an enumerator is returned instead. - * * The result inherits any tainting in the original string or any supplied * replacement string. * * "hello".sub(/[aeiou]/, '*') #=> "h*llo" * "hello".sub(/([aeiou])/, '<\1>') #=> "hllo" - * "hello".sub(/./) {|s| s[0].ord.to_s + ' ' } #=> "104 ello" + * "hello".sub(/./) {|s| s.ord.to_s + ' ' } #=> "104 ello" * "hello".sub(/(?[aeiou])/, '*\k*') #=> "h*e*llo" + * 'Is SHELL your preferred shell?'.sub(/[[:upper:]]{2,}/, ENV) + * #=> "Is /bin/bash your preferred shell?" */ static VALUE @@ -3705,9 +3711,11 @@ str_gsub(int argc, VALUE *argv, VALUE str, int bang) * call-seq: * str.gsub!(pattern, replacement) -> str or nil * str.gsub!(pattern) {|match| block } -> str or nil + * str.gsub!(pattern) -> an_enumerator * * Performs the substitutions of String#gsub in place, returning * str, or nil if no substitutions were performed. + * If no block and no replacement is given, an enumerator is returned instead. */ static VALUE @@ -3721,34 +3729,44 @@ rb_str_gsub_bang(int argc, VALUE *argv, VALUE str) /* * call-seq: * str.gsub(pattern, replacement) -> new_str + * str.gsub(pattern, hash) -> new_str * str.gsub(pattern) {|match| block } -> new_str - * - * Returns a copy of str with all occurrences of pattern - * replaced with either replacement or the value of the block. The - * pattern will typically be a Regexp; if it is a - * String then no regular expression metacharacters will be - * interpreted (that is /\d/ will match a digit, but - * '\d' will match a backslash followed by a 'd'). - * - * If a string is used as the replacement, special variables from the match - * (such as $& and $1) cannot be substituted into it, - * as substitution into the string occurs before the pattern match - * starts. However, the sequences \1, \2, - * \k, and so on may be used to interpolate - * successive groups in the match. - * - * In the block form, the current match string is passed in as a parameter, and - * variables such as $1, $2, $`, + * str.gsub(pattern) -> enumerator + * + * Returns a copy of str with the all occurrences of + * pattern substituted for the second argument. The pattern is + * typically a Regexp; if given as a String, any + * regular expression metacharacters it contains will be interpreted + * literally, e.g. '\\\d' will match a backlash followed by 'd', + * instead of a digit. + * + * If replacement is a String it will be substituted for + * the matched text. It may contain back-references to the pattern's capture + * groups of the form \\\d, where d is a group number, or + * \\\k, where n is a group name. If it is a + * double-quoted string, both back-references must be preceded by an + * additional backslash. However, within replacement the special match + * variables, such as &$, will not refer to the current match. + * + * If the second argument is a Hash, and the matched text is one + * of its keys, the corresponding value is the replacement string. + * + * In the block form, the current match string is passed in as a parameter, + * and variables such as $1, $2, $`, * $&, and $' will be set appropriately. The value * returned by the block will be substituted for the match on each call. * * The result inherits any tainting in the original string or any supplied * replacement string. * + * When neither a block nor a second argument is supplied, an + * Enumerator is returned. + * * "hello".gsub(/[aeiou]/, '*') #=> "h*ll*" * "hello".gsub(/([aeiou])/, '<\1>') #=> "hll" - * "hello".gsub(/./) {|s| s[0].ord.to_s + ' '} #=> "104 101 108 108 111 " + * "hello".gsub(/./) {|s| s.ord.to_s + ' '} #=> "104 101 108 108 111 " * "hello".gsub(/(?[aeiou])/, '{\k}') #=> "h{e}ll{o}" + * 'hello'.gsub(/[eo]/, 'e' => 3, 'o' => '*') #=> "h3ll*" */ static VALUE -- cgit v1.2.3