summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2020-09-24 15:55:43 (GMT)
committerGitHub <noreply@github.com>2020-09-24 15:55:43 (GMT)
commit6fe2a9fcda84fbc33a4cc913786db75a3d7f4102 (patch)
tree98119c64d0341e8fbad5ecb86ba99e522ee0995d
parentb30af31c37b91c8a918b340b24bfcd33e51d0167 (diff)
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
Notes
Notes: Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
-rw-r--r--string.c200
1 files changed, 119 insertions, 81 deletions
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)
* 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)
/*
* 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)
/*
* 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)
/*
* 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);
/*
* 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)
/*
* 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)
/*
* 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)
/*
* 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 found:
+ * 'foo'.rindex(/f/) # => 0
+ * 'foo'.rindex(/o/) # => 2
+ * 'foo'.rindex(/oo/) # => 1
+ * 'foo'.rindex(/ooo/) # => nil
+ *
+ * \Integer argument +offset+, if given and non-negative, specifies the maximum starting position in the
+ * string to _end_ the search:
+ * 'foo'.rindex('o', 0) # => nil
+ * 'foo'.rindex('o', 1) # => 1
+ * 'foo'.rindex('o', 2) # => 2
+ * 'foo'.rindex('o', 3) # => 2
+ *
+ * If +offset+ is a negative \Integer, the maximum starting position in the
+ * string to _end_ the search is the sum of the string's length and +offset+:
+ * 'foo'.rindex('o', -1) # => 2
+ * 'foo'.rindex('o', -2) # => 1
+ * 'foo'.rindex('o', -3) # => nil
+ * 'foo'.rindex('o', -4) # => nil
+ *
+ * Related: String#index
*/
static VALUE