ruby-changes:68029
From: Burdette <ko1@a...>
Date: Sat, 18 Sep 2021 21:27:27 +0900 (JST)
Subject: [ruby-changes:68029] 1c07c98229 (master): Enhanced RDoc for Range (#4847)
https://git.ruby-lang.org/ruby.git/commit/?id=1c07c98229 From 1c07c98229aa16bf13cbd3997d32230d5324b4f2 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sat, 18 Sep 2021 07:27:02 -0500 Subject: Enhanced RDoc for Range (#4847) Treated: #to_s #inspect #=== #include? #cover? #count --- range.c | 256 +++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 190 insertions(+), 66 deletions(-) diff --git a/range.c b/range.c index c7ed836..c37a2c8 100644 --- a/range.c +++ b/range.c @@ -788,6 +788,8 @@ sym_each_i(VALUE v, VALUE arg) https://github.com/ruby/ruby/blob/trunk/range.c#L788 * (1...4).size # => 3 * (1..).size # => Infinity * ('a'..'z').size #=> nil + * + * Related: Range#count. */ static VALUE @@ -1580,10 +1582,23 @@ rb_range_beg_len(VALUE range, long *begp, long *lenp, long len, int err) https://github.com/ruby/ruby/blob/trunk/range.c#L1582 /* * call-seq: - * rng.to_s -> string + * to_s -> string + * + * Returns a string representation of +self+, + * including <tt>begin.to_s</tt> and <tt>end.to_s</tt>: + * + * (1..4).to_s # => "1..4" + * (1...4).to_s # => "1...4" + * (1..).to_s # => "1.." + * (..4).to_s # => "..4" + * + * Note that returns from #to_s and #inspect may differ: + * + * ('a'..'d').to_s # => "a..d" + * ('a'..'d').inspect # => "\"a\"..\"d\"" + * + * Related: Range#inspect. * - * Convert this range object to a printable form (using #to_s to convert the - * begin and end objects). */ static VALUE @@ -1625,10 +1640,23 @@ inspect_range(VALUE range, VALUE dummy, int recur) https://github.com/ruby/ruby/blob/trunk/range.c#L1640 /* * call-seq: - * rng.inspect -> string + * inspect -> string + * + * Returns a string representation of +self+, + * including <tt>begin.inspect</tt> and <tt>end.inspect</tt>: + * + * (1..4).inspect # => "1..4" + * (1...4).inspect # => "1...4" + * (1..).inspect # => "1.." + * (..4).inspect # => "..4" + * + * Note that returns from #to_s and #inspect may differ: + * + * ('a'..'d').to_s # => "a..d" + * ('a'..'d').inspect # => "\"a\"..\"d\"" + * + * Related: Range#to_s. * - * Convert this range object to a printable form (using #inspect to - * convert the begin and end objects). */ @@ -1642,27 +1670,40 @@ static VALUE range_include_internal(VALUE range, VALUE val, int string_use_cover https://github.com/ruby/ruby/blob/trunk/range.c#L1670 /* * call-seq: - * rng === obj -> true or false + * rng === object -> true or false + * + * Returns +true+ if +object+ is between <tt>self.begin</tt> and <tt>self.end</tt>. + * +false+ otherwise: * - * Returns <code>true</code> if +obj+ is between begin and end of range, - * <code>false</code> otherwise (same as #cover?). Conveniently, - * <code>===</code> is the comparison operator used by <code>case</code> - * statements. + * (1..4) === 2 # => true + * (1..4) === 5 # => false + * (1..4) === 'a' # => false + * (1..4) === 4 # => true + * (1...4) === 4 # => false + * ('a'..'d') === 'c' # => true + * ('a'..'d') === 'e' # => false + * + * A case statement uses method <tt>===</tt>, and so: * * case 79 - * when 1..50 then puts "low" - * when 51..75 then puts "medium" - * when 76..100 then puts "high" - * end - * # Prints "high" + * when (1..50) + * "low" + * when (51..75) + * "medium" + * when (76..100) + * "high" + * end # => "high" * * case "2.6.5" - * when ..."2.4" then puts "EOL" - * when "2.4"..."2.5" then puts "maintenance" - * when "2.5"..."2.7" then puts "stable" - * when "2.7".. then puts "upcoming" - * end - * # Prints "stable" + * when ..."2.4" + * "EOL" + * when "2.4"..."2.5" + * "maintenance" + * when "2.5"..."3.0" + * "stable" + * when "3.1".. + * "upcoming" + * end # => "stable" * */ @@ -1677,23 +1718,33 @@ range_eqq(VALUE range, VALUE val) https://github.com/ruby/ruby/blob/trunk/range.c#L1718 /* * call-seq: - * rng.member?(obj) -> true or false - * rng.include?(obj) -> true or false + * include?(object) -> true or false * - * Returns <code>true</code> if +obj+ is an element of - * the range, <code>false</code> otherwise. + * Returns +true+ if +object+ is an element of +self+, +false+ otherwise: * - * ("a".."z").include?("g") #=> true - * ("a".."z").include?("A") #=> false - * ("a".."z").include?("cc") #=> false + * (1..4).include?(2) # => true + * (1..4).include?(5) # => false + * (1..4).include?(4) # => true + * (1...4).include?(4) # => false + * ('a'..'d').include?('b') # => true + * ('a'..'d').include?('e') # => false + * ('a'..'d').include?('B') # => false + * ('a'..'d').include?('d') # => true + * ('a'...'d').include?('d') # => false * - * If you need to ensure +obj+ is between +begin+ and +end+, use #cover? + * If begin and end are numeric, #include? behaves like #cover? * - * ("a".."z").cover?("cc") #=> true + * (1..3).include?(1.5) # => true + * (1..3).cover?(1.5) # => true * - * If begin and end are numeric, #include? behaves like #cover? + * But when not numeric, the two methods may differ: + * + * ('a'..'d').include?('cc') # => false + * ('a'..'d').cover?('cc') # => true * - * (1..3).include?(1.5) # => true + * Related: Range#cover?. + * + * Range#member? is an alias for Range#include?. */ static VALUE @@ -1747,34 +1798,86 @@ static int r_cover_range_p(VALUE range, VALUE beg, VALUE end, VALUE val); https://github.com/ruby/ruby/blob/trunk/range.c#L1798 /* * call-seq: - * rng.cover?(obj) -> true or false - * rng.cover?(range) -> true or false - * - * Returns <code>true</code> if +obj+ is between the begin and end of - * the range. - * - * This tests <code>begin <= obj <= end</code> when #exclude_end? is +false+ - * and <code>begin <= obj < end</code> when #exclude_end? is +true+. - * - * If called with a Range argument, returns <code>true</code> when the - * given range is covered by the receiver, - * by comparing the begin and end values. If the argument can be treated as - * a sequence, this method treats it that way. In the specific case of - * <code>(a..b).cover?(c...d)</code> with <code>a <= c && b < d</code>, - * the end of the sequence must be calculated, which may exhibit poor - * performance if <code>c</code> is non-numeric. - * Returns <code>false</code> if the begin value of the - * range is larger than the end value. Also returns +false+ if one of the - * internal calls to <code><=></code> returns +nil+ (indicating the objects - * are not comparable). - * - * ("a".."z").cover?("c") #=> true - * ("a".."z").cover?("5") #=> false - * ("a".."z").cover?("cc") #=> true - * ("a".."z").cover?(1) #=> false - * (1..5).cover?(2..3) #=> true - * (1..5).cover?(0..6) #=> false - * (1..5).cover?(1...6) #=> true + * cover?(object) -> true or false + * cover?(range) -> true or false + * + * Returns +true+ if the given argument is within +self+, +false+ otherwise. + * + * With non-range argument +object+, evaluates with <tt><=</tt> and <tt><</tt>. + * + * For range +self+ with included end value (<tt>#exclude_end? == false</tt>), + * evaluates thus: + * + * self.begin <= object <= self.end + * + * Examples: + * + * r = (1..4) + * r.cover?(1) # => true + * r.cover?(4) # => true + * r.cover?(0) # => false + * r.cover?(5) # => false + * r.cover?('foo') # => false + + * r = ('a'..'d') + * r.cover?('a') # => true + * r.cover?('d') # => true + * r.cover?(' ') # => false + * r.cover?('e') # => false + * r.cover?(0) # => false + * + * For range +r+ with excluded end value (<tt>#exclude_end? == true</tt>), + * evaluates thus: + * + * r.begin <= object < r.end + * + * Examples: + * + * r = (1...4) + * r.cover?(1) # => true + * r.cover?(3) # => true + * r.cover?(0) # => false + * r.cover?(4) # => false + * r.cover?('foo') # => false + + * r = ('a'...'d') + * r.cover?('a') # => true + * r.cover?('c') # => true + * r.cover?(' ') # => false + * r.cover?('d') # => false + * r.cover?(0) # => false + * + * With range argument +range+, compares the first and last + * elements of +self+ and +range+: + * + * r = (1..4) + * r.cover?(1..4) # => true + * r.cover?(0..4) # => false + * r.cover?(1..5) # => false + * r.cover?('a'..'d') # => false + + * r = (1...4) + * r.cover?(1..3) # => true + * r.cover?(1..4) # => false + * + * If begin and end are numeric, #cover? behaves like #include? + * + * (1..3).cover?(1.5) # => true + * (1..3).include?(1.5) # => true + * + * But when not numeric, the two methods may differ: + * + * ('a'..'d').cover?('cc') # => true + * ('a'..'d').include?('cc') # => false + * + * Returns +false+ if either: + * + * - The begin value of +self+ is larger than its end value. + * - An internal call to <tt><=></tt> returns +nil+; + * that is, the operands are not comparable. + * + * Related: Range#include?. + * */ static VALUE @@ -1880,13 +1983,34 @@ range_alloc(VALUE klass) https://github.com/ruby/ruby/blob/trunk/range.c#L1983 /* * call-seq: - * range.count -> int - * range.count(item) -> int - * range.count { |obj| block } -> int + * count -> integer0 + * count(object) -> integer + * count {|element| ... } -> integer + * + * Returns the count of elements, based on an argument or block criterion, if given. + * + * With no argument and no block given, returns the number of elements: + * + * (1..4).count # => 4 + * (1...4).count # => 3 + * ('a'..'d').count # (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/