ruby-changes:69568
From: Burdette <ko1@a...>
Date: Wed, 3 Nov 2021 03:05:20 +0900 (JST)
Subject: [ruby-changes:69568] ae2359f602 (master): Enhanced RDoc for String (#5060)
https://git.ruby-lang.org/ruby.git/commit/?id=ae2359f602 From ae2359f602bb467ca755eef02d73d361d35eaed7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 2 Nov 2021 13:04:58 -0500 Subject: Enhanced RDoc for String (#5060) Treated: #slice! #sub #sub! #gsub #gsub! --- string.c | 319 ++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 181 insertions(+), 138 deletions(-) diff --git a/string.c b/string.c index c1662be4779..aa26f35d60a 100644 --- a/string.c +++ b/string.c @@ -5301,21 +5301,26 @@ rb_str_insert(VALUE str, VALUE idx, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L5301 /* * call-seq: - * str.slice!(integer) -> new_str or nil - * str.slice!(integer, integer) -> new_str or nil - * str.slice!(range) -> new_str or nil - * str.slice!(regexp) -> new_str or nil - * str.slice!(other_str) -> new_str or nil + * slice!(index) -> new_string or nil + * slice!(start, length) -> new_string or nil + * slice!(range) -> new_string or nil + * slice!(regexp, capture = 0) -> new_string or nil + * slice!(substring) -> new_string or nil * - * Deletes the specified portion from <i>str</i>, and returns the portion - * deleted. + * Removes the substring of +self+ specified by the arguments; + * returns the removed substring. * - * string = "this is a string" + * See String#[] for details about the arguments that specify the substring. + * + * A few examples: + * + * string = "This is a string" * string.slice!(2) #=> "i" * string.slice!(3..6) #=> " is " * string.slice!(/s.*t/) #=> "sa st" * string.slice!("r") #=> "r" - * string #=> "thing" + * string #=> "Thing" + * */ static VALUE @@ -5477,13 +5482,16 @@ rb_pat_search(VALUE pat, VALUE str, long pos, int set_backref_str) https://github.com/ruby/ruby/blob/trunk/string.c#L5482 /* * call-seq: - * str.sub!(pattern, replacement) -> str or nil - * str.sub!(pattern) {|match| block } -> str or nil + * sub!(pattern, replacement) -> self or nil + * sub!(pattern) {|match| ... } -> self or nil + * + * Returns +self+ with only the first occurrence + * (not all occurrences) of the given +pattern+ replaced. + * + * See {Substitution Methods}[#class-String-label-Substitution+Methods]. * - * Performs the same substitution as String#sub in-place. + * Related: String#sub, String#gsub, String#gsub!. * - * Returns +str+ if a substitution was performed or +nil+ if no substitution - * was performed. */ static VALUE @@ -5597,58 +5605,16 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str) https://github.com/ruby/ruby/blob/trunk/string.c#L5605 /* * call-seq: - * str.sub(pattern, replacement) -> new_str - * str.sub(pattern, hash) -> new_str - * str.sub(pattern) {|match| block } -> new_str - * - * Returns a copy of +str+ with the _first_ occurrence of +pattern+ - * replaced by 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. <code>\d</code> will match a backslash - * 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 - * <code>\d</code>, where <i>d</i> is a group number, or - * <code>\k<n></code>, where <i>n</i> is a group name. - * Similarly, <code>\&</code>, <code>\'</code>, <code>\`</code>, and - * <code>\+</code> correspond to special variables, <code>$&</code>, - * <code>$'</code>, <code>$`</code>, and <code>$+</code>, respectively. - * (See rdoc-ref:regexp.rdoc for details.) - * <code>\0</code> is the same as <code>\&</code>. - * <code>\\\\</code> is interpreted as an escape, i.e., a single backslash. - * Note that, within +replacement+ the special match variables, such as - * <code>$&</code>, 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 <code>$1</code>, <code>$2</code>, <code>$`</code>, - * <code>$&</code>, and <code>$'</code> will be set appropriately. - * (See rdoc-ref:regexp.rdoc for details.) - * The value returned by the block will be substituted for the match on each - * call. - * - * "hello".sub(/[aeiou]/, '*') #=> "h*llo" - * "hello".sub(/([aeiou])/, '<\1>') #=> "h<e>llo" - * "hello".sub(/./) {|s| s.ord.to_s + ' ' } #=> "104 ello" - * "hello".sub(/(?<foo>[aeiou])/, '*\k<foo>*') #=> "h*e*llo" - * 'Is SHELL your preferred shell?'.sub(/[[:upper:]]{2,}/, ENV) - * #=> "Is /bin/bash your preferred shell?" - * - * Note that a string literal consumes backslashes. - * (See rdoc-ref:syntax/literals.rdoc for details about string literals.) - * Back-references are typically preceded by an additional backslash. - * For example, if you want to write a back-reference <code>\&</code> in - * +replacement+ with a double-quoted string literal, you need to write: - * <code>"..\\\\&.."</code>. - * If you want to write a non-back-reference string <code>\&</code> in - * +replacement+, you need first to escape the backslash to prevent - * this method from interpreting it as a back-reference, and then you - * need to escape the backslashes again to prevent a string literal from - * consuming them: <code>"..\\\\\\\\&.."</code>. - * You may want to use the block form to avoid a lot of backslashes. + * 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}[#class-String-label-Substitution+Methods]. + * + * Related: String#sub!, String#gsub, String#gsub!. + * */ static VALUE @@ -5784,15 +5750,19 @@ str_gsub(int argc, VALUE *argv, VALUE str, int bang) https://github.com/ruby/ruby/blob/trunk/string.c#L5750 /* * call-seq: - * str.gsub!(pattern, replacement) -> str or nil - * str.gsub!(pattern, hash) -> str or nil - * str.gsub!(pattern) {|match| block } -> str or nil - * str.gsub!(pattern) -> an_enumerator + * str.gsub!(pattern, replacement) -> self or nil + * str.gsub!(pattern) {|match| ... } -> self or nil + * str.gsub!(pattern) -> an_enumerator + * + * Performs the specified substring replacement(s) on +self+; + * returns +self+ if any replacement occurred, +nil+ otherwise. + * + * See {Substitution Methods}[#class-String-label-Substitution+Methods]. + * + * Returns an Enumerator if no +replacement+ and no block given. + * + * Related: String#sub, String#gsub, String#sub!. * - * Performs the substitutions of String#gsub in place, returning - * <i>str</i>, or <code>nil</code> if no substitutions were - * performed. If no block and no <i>replacement</i> is given, an - * enumerator is returned instead. */ static VALUE @@ -5805,62 +5775,18 @@ rb_str_gsub_bang(int argc, VALUE *argv, VALUE str) https://github.com/ruby/ruby/blob/trunk/string.c#L5775 /* * call-seq: - * str.gsub(pattern, replacement) -> new_str - * str.gsub(pattern, hash) -> new_str - * str.gsub(pattern) {|match| block } -> new_str - * str.gsub(pattern) -> enumerator - * - * Returns a copy of <i>str</i> with <em>all</em> occurrences of - * <i>pattern</i> substituted for the second argument. The <i>pattern</i> is - * typically a Regexp; if given as a String, any - * regular expression metacharacters it contains will be interpreted - * literally, e.g. <code>\d</code> will match a backslash 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 - * <code>\d</code>, where <i>d</i> is a group number, or - * <code>\k<n></code>, where <i>n</i> is a group name. - * Similarly, <code>\&</code>, <code>\'</code>, <code>\`</code>, and - * <code>\+</code> correspond to special variables, <code>$&</code>, - * <code>$'</code>, <code>$`</code>, and <code>$+</code>, respectively. - * (See rdoc-ref:regexp.rdoc for details.) - * <code>\0</code> is the same as <code>\&</code>. - * <code>\\\\</code> is interpreted as an escape, i.e., a single backslash. - * Note that, within +replacement+ the special match variables, such as - * <code>$&</code>, 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 <code>$1</code>, <code>$2</code>, <code>$`</code>, - * <code>$&</code>, and <code>$'</code> will be set appropriately. - * (See rdoc-ref:regexp.rdoc for details.) - * The value returned by the block will be substituted for the match on each - * call. - * - * When neither a block nor a second argument is supplied, an - * Enumerator is returned. - * - * "hello".gsub(/[aeiou]/, '*') #=> "h*ll*" - * "hello".gsub(/([aeiou])/, '<\1>') #=> "h<e>ll<o>" - * "hello".gsub(/./) {|s| s.ord.to_s + ' '} #=> "104 101 108 108 111 " - * "hello".gsub(/(?<foo>[aeiou])/, '{\k<foo>}') #=> "h{e}ll{o}" - * 'hello'.gsub(/[eo]/, 'e' => 3, 'o' => '*') #=> "h3ll*" - * - * Note that a string literal consumes backslashes. - * (Se (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/