ruby-changes:63079
From: Burdette <ko1@a...>
Date: Fri, 25 Sep 2020 00:56:02 +0900 (JST)
Subject: [ruby-changes:63079] 6fe2a9fcda (master): Enhanced RDoc for String (#3569)
https://git.ruby-lang.org/ruby.git/commit/?id=6fe2a9fcda From 6fe2a9fcda84fbc33a4cc913786db75a3d7f4102 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Thu, 24 Sep 2020 10:55:43 -0500 Subject: Enhanced RDoc for String (#3569) Makes some methods doc compliant with https://github.com/ruby/ruby/blob/master/doc/method_documentation.rdoc. Also, other minor revisions to make more consistent. Methods: == === eql? <=> casecmp casecmp? index rindex diff --git a/string.c b/string.c index 254e0bd..627823c 100644 --- a/string.c +++ b/string.c @@ -1954,7 +1954,7 @@ rb_str_empty(VALUE str) https://github.com/ruby/ruby/blob/trunk/string.c#L1954 * string + other_string -> new_string * * Returns a new \String containing +other_string+ concatenated to +self+: - * "Hello from " + self.to_s #=> "Hello from main" + * "Hello from " + self.to_s # => "Hello from main" */ VALUE @@ -3318,15 +3318,21 @@ rb_str_cmp(VALUE str1, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L3318 /* * call-seq: - * str == obj -> true or false - * str === obj -> true or false + * string == object -> true or false + * string === object -> true or false * - * Equality---Returns whether +str+ == +obj+, similar to Object#==. + * Returns +true+ if +object+ has the same length and content; + * as +self+; +false+ otherwise: + * s = 'foo' + * s == 'foo' # => true + * s == 'food' # => false + * s == 'FOO' # => false * - * If +obj+ is not an instance of String but responds to +to_str+, then the - * two strings are compared using <code>obj.==</code>. + * Returns +false+ if the two strings' encodings are not compatible: + * "\u{e4 f6 fc}".encode("ISO-8859-1") == ("\u{c4 d6 dc}") # => false * - * Otherwise, returns similarly to String#eql?, comparing length and content. + * If +object+ is not an instance of \String but responds to +to_str+, then the + * two strings are compared using <code>object.==</code>. */ VALUE @@ -3344,9 +3350,17 @@ rb_str_equal(VALUE str1, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L3350 /* * call-seq: - * str.eql?(other) -> true or false + * string.eql?(object) -> true or false + * + * Returns +true+ if +object+ has the same length and content; + * as +self+; +false+ otherwise: + * s = 'foo' + * s.eql?('foo') # => true + * s.eql?('food') # => false + * s.eql?('FOO') # => false * - * Two strings are equal if they have the same length and content. + * Returns +false+ if the two strings' encodings are not compatible: + * "\u{e4 f6 fc}".encode("ISO-8859-1").eql?("\u{c4 d6 dc}") # => false */ MJIT_FUNC_EXPORTED VALUE @@ -3359,27 +3373,21 @@ rb_str_eql(VALUE str1, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L3373 /* * call-seq: - * string <=> other_string -> -1, 0, +1, or nil - * - * Comparison---Returns -1, 0, +1, or +nil+ depending on whether +string+ is - * less than, equal to, or greater than +other_string+. + * string <=> other_string -> -1, 0, 1, or nil * - * +nil+ is returned if the two values are incomparable. + * Compares +self+ and +other_string+, returning: + * - -1 if +other_string+ is smaller. + * - 0 if the two are equal. + * - 1 if +other_string+ is larger. + * - +nil+ if the two are incomparable. * - * If the strings are of different lengths, and the strings are equal when - * compared up to the shortest length, then the longer string is considered - * greater than the shorter one. - * - * <code><=></code> is the basis for the methods <code><</code>, - * <code><=</code>, <code>></code>, <code>>=</code>, and - * <code>between?</code>, included from module Comparable. The method - * String#== does not use Comparable#==. - * - * "abcdef" <=> "abcde" #=> 1 - * "abcdef" <=> "abcdef" #=> 0 - * "abcdef" <=> "abcdefg" #=> -1 - * "abcdef" <=> "ABCDEF" #=> 1 - * "abcdef" <=> 1 #=> nil + * Examples: + * 'foo' <=> 'foo' # => 0 + * 'foo' <=> 'food' # => -1 + * 'food' <=> 'foo' # => 1 + * 'FOO' <=> 'foo' # => -1 + * 'foo' <=> 'FOO' # => 1 + * 'foo' <=> 1 # => nil */ static VALUE @@ -3399,22 +3407,21 @@ static VALUE str_casecmp_p(VALUE str1, VALUE str2); https://github.com/ruby/ruby/blob/trunk/string.c#L3407 /* * call-seq: - * str.casecmp(other_str) -> -1, 0, +1, or nil - * - * Case-insensitive version of String#<=>. - * Currently, case-insensitivity only works on characters A-Z/a-z, - * not all of Unicode. This is different from String#casecmp?. + * str.casecmp(other_str) -> -1, 0, 1, or nil * - * "aBcDeF".casecmp("abcde") #=> 1 - * "aBcDeF".casecmp("abcdef") #=> 0 - * "aBcDeF".casecmp("abcdefg") #=> -1 - * "abcdef".casecmp("ABCDEF") #=> 0 + * Compares +self+ and +other_string+, ignoring case, and returning: + * - -1 if +other_string+ is smaller. + * - 0 if the two are equal. + * - 1 if +other_string+ is larger. + * - +nil+ if the two are incomparable. * - * +nil+ is returned if the two strings have incompatible encodings, - * or if +other_str+ is not a string. - * - * "foo".casecmp(2) #=> nil - * "\u{e4 f6 fc}".encode("ISO-8859-1").casecmp("\u{c4 d6 dc}") #=> nil + * Examples: + * 'foo'.casecmp('foo') # => 0 + * 'foo'.casecmp('food') # => -1 + * 'food'.casecmp('foo') # => 1 + * 'FOO'.casecmp('foo') # => 0 + * 'foo'.casecmp('FOO') # => 0 + * 'foo'.casecmp(1) # => nil */ static VALUE @@ -3486,22 +3493,18 @@ str_casecmp(VALUE str1, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L3493 /* * call-seq: - * str.casecmp?(other_str) -> true, false, or nil - * - * Returns +true+ if +str+ and +other_str+ are equal after - * Unicode case folding, +false+ if they are not equal. - * - * "aBcDeF".casecmp?("abcde") #=> false - * "aBcDeF".casecmp?("abcdef") #=> true - * "aBcDeF".casecmp?("abcdefg") #=> false - * "abcdef".casecmp?("ABCDEF") #=> true - * "\u{e4 f6 fc}".casecmp?("\u{c4 d6 dc}") #=> true + * string.casecmp?(other_string) -> true, false, or nil * - * +nil+ is returned if the two strings have incompatible encodings, - * or if +other_str+ is not a string. + * Returns +true+ if +self+ and +other_string+ are equal after + * Unicode case folding, otherwise +false+: + * 'foo'.casecmp?('foo') # => true + * 'foo'.casecmp?('food') # => false + * 'food'.casecmp?('foo') # => true + * 'FOO'.casecmp?('foo') # => true + * 'foo'.casecmp?('FOO') # => true * - * "foo".casecmp?(2) #=> nil - * "\u{e4 f6 fc}".encode("ISO-8859-1").casecmp?("\u{c4 d6 dc}") #=> nil + * Returns +nil+ if the two values are incomparable: + * 'foo'.casecmp?(1) # => nil */ static VALUE @@ -3595,19 +3598,36 @@ rb_strseq_index(VALUE str, VALUE sub, long offset, int in_byte) https://github.com/ruby/ruby/blob/trunk/string.c#L3598 /* * call-seq: - * str.index(substring [, offset]) -> integer or nil - * str.index(regexp [, offset]) -> integer or nil + * string.index(substring, offset = 0) -> integer or nil + * string.index(regexp, offset = 0) -> integer or nil + * + * Returns the \Integer index of the first occurrence of the given +substring+, + * or +nil+ if none found: + * 'foo'.index('f') # => 0 + * 'foo'.index('o') # => 1 + * 'foo'.index('oo') # => 1 + * 'foo'.index('ooo') # => nil + * + * Returns the \Integer index of the first match for the given \Regexp +regexp+, + * or +nil+ if none found: + * 'foo'.index(/f/) # => 0 + * 'foo'.index(/o/) # => 1 + * 'foo'.index(/oo/) # => 1 + * 'foo'.index(/ooo/) # => nil + * + * \Integer argument +offset+, if given, specifies the position in the + * string to begin the search: + * 'foo'.index('o', 1) # => 1 + * 'foo'.index('o', 2) # => 2 + * 'foo'.index('o', 3) # => nil * - * Returns the index of the first occurrence of the given <i>substring</i> or - * pattern (<i>regexp</i>) in <i>str</i>. Returns <code>nil</code> if not - * found. If the second parameter is present, it specifies the position in the - * string to begin the search. + * If +offset+ is negative, counts backward from the end of +self+: + * 'foo'.index('o', -1) # => 2 + * 'foo'.index('o', -2) # => 1 + * 'foo'.index('o', -3) # => 1 + * 'foo'.index('o', -4) # => nil * - * "hello".index('e') #=> 1 - * "hello".index('lo') #=> 3 - * "hello".index('a') #=> nil - * "hello".index(?e) #=> 1 - * "hello".index(/[aeiou]/, -3) #=> 4 + * Related: String#rindex */ static VALUE @@ -3750,20 +3770,38 @@ rb_str_rindex(VALUE str, VALUE sub, long pos) https://github.com/ruby/ruby/blob/trunk/string.c#L3770 /* * call-seq: - * str.rindex(substring [, integer]) -> integer or nil - * str.rindex(regexp [, integer]) -> integer or nil - * - * Returns the index of the last occurrence of the given <i>substring</i> or - * pattern (<i>regexp</i>) in <i>str</i>. Returns <code>nil</code> if not - * found. If the second parameter is present, it specifies the position in the - * string to end the search---characters beyond this point will not be - * considered. - * - * "hello".rindex('e') #=> 1 - * "hello".rindex('l') #=> 3 - * "hello".rindex('a') #=> nil - * "hello".rindex(?e) #=> 1 - * "hello".rindex(/[aeiou]/, -2) #=> 1 + * string.rindex(substring, offset = self.length) -> integer or nil + * string.rindex(regexp, offset = self.length) -> integer or nil + * + * Returns the \Integer index of the _last_ occurrence of the given +substring+, + * or +nil+ if none found: + * 'foo'.rindex('f') # => 0 + * 'foo'.rindex('o') # => 2 + * 'foo'.rindex('oo') # => 1 + * 'foo'.rindex('ooo') # => nil + * + * Returns the \Integer index of the _last_ match for the given \Regexp +regexp+, + * or +nil+ if none (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/