ruby-changes:67977
From: Burdette <ko1@a...>
Date: Tue, 14 Sep 2021 04:01:01 +0900 (JST)
Subject: [ruby-changes:67977] 4e03032a83 (master): Enhanced RDoc for Range (#4833)
https://git.ruby-lang.org/ruby.git/commit/?id=4e03032a83 From 4e03032a83a059e32da9d886df2552fd06799c01 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 13 Sep 2021 14:00:39 -0500 Subject: Enhanced RDoc for Range (#4833) Treated: ::new #include_end? #== #eql? #hash #step --- range.c | 149 ++++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 94 insertions(+), 55 deletions(-) diff --git a/range.c b/range.c index 16d443a..140abc3 100644 --- a/range.c +++ b/range.c @@ -84,11 +84,17 @@ range_modify(VALUE range) https://github.com/ruby/ruby/blob/trunk/range.c#L84 /* * call-seq: - * Range.new(begin, end, exclude_end=false) -> rng + * Range.new(begin, end, exclude_end = false) -> new_range + * + * Returns a new range based on the given objects +begin+ and +end+. + * Optional argument +exclude_end+ determines whether object +end+ + * is included as the last object in the range: + * + * Range.new(2, 5).to_a # => [2, 3, 4, 5] + * Range.new(2, 5, true).to_a # => [2, 3, 4] + * Range.new('a', 'd').to_a # => ["a", "b", "c", "d"] + * Range.new('a', 'd', true).to_a # => ["a", "b", "c"] * - * Constructs a range using the given +begin+ and +end+. If the +exclude_end+ - * parameter is omitted or is <code>false</code>, the range will include - * the end object; otherwise, it will be excluded. */ static VALUE @@ -113,12 +119,14 @@ range_initialize_copy(VALUE range, VALUE orig) https://github.com/ruby/ruby/blob/trunk/range.c#L119 /* * call-seq: - * rng.exclude_end? -> true or false + * exclude_end? -> true or false * - * Returns <code>true</code> if the range excludes its end value. + * Returns +true+ if +self+ excludes its end value; +false+ otherwise: * - * (1..5).exclude_end? #=> false - * (1...5).exclude_end? #=> true + * Range.new(2, 5).exclude_end? # => false + * Range.new(2, 5, true).exclude_end? # => true + * (2..5).exclude_end? # => false + * (2...5).exclude_end? # => true */ static VALUE @@ -142,15 +150,32 @@ recursive_equal(VALUE range, VALUE obj, int recur) https://github.com/ruby/ruby/blob/trunk/range.c#L150 /* * call-seq: - * rng == obj -> true or false + * self == other -> true or false + * + * Returns +true+ if and only if: + * + * - +other+ is a range. + * - <tt>other.begin == self.begin</tt>. + * - <tt>other.end == self.end</tt>. + * - <tt>other.exclude_end? == self.include_end?</tt>. + * + * Otherwise returns +false+. + * + * r = (1..5) + * r == (1..5) # => true + * r = Range.new(1, 5) + * r == 'foo' # => false + * r == (2..5) # => false + * r == (1..4) # => false + * r == (1...5) # => false + * r == Range.new(1, 5, true) # => false + * + * Note that even with the same argument, the return values of #== and #eql? can differ: * - * Returns <code>true</code> only if +obj+ is a Range, has equivalent - * begin and end items (by comparing them with <code>==</code>), and has - * the same #exclude_end? setting as the range. + * (1..2) == (1..2.0) # => true + * (1..2).eql? (1..2.0) # => false * - * (0..2) == (0..2) #=> true - * (0..2) == Range.new(0,2) #=> true - * (0..2) == (0...2) #=> false + * Related: Range#eql?. * */ @@ -194,16 +219,32 @@ recursive_eql(VALUE range, VALUE obj, int recur) https://github.com/ruby/ruby/blob/trunk/range.c#L219 /* * call-seq: - * rng.eql?(obj) -> true or false + * eql?(other) -> true or false * - * Returns <code>true</code> only if +obj+ is a Range, has equivalent - * begin and end items (by comparing them with <code>eql?</code>), - * and has the same #exclude_end? setting as the range. + * Returns +true+ if and only if: * - * (0..2).eql?(0..2) #=> true - * (0..2).eql?(Range.new(0,2)) #=> true - * (0..2).eql?(0...2) #=> false + * - +other+ is a range. + * - <tt>other.begin eql? self.begin</tt>. + * - <tt>other.end eql? self.end</tt>. + * - <tt>other.exclude_end? == self.include_end?</tt>. * + * Otherwise returns +false+. + * + * r = (1..5) + * r.eql?(1..5) # => true + * r = Range.new(1, 5) + * r.eql?('foo') # => false + * r.eql?(2..5) # => false + * r.eql?(1..4) # => false + * r.eql?(1...5) # => false + * r.eql?(Range.new(1, 5, true)) # => false + * + * Note that even with the same argument, the return values of #== and #eql? can differ: + * + * (1..2) == (1..2.0) # => true + * (1..2).eql? (1..2.0) # => false + * + * Related: Range#==. */ static VALUE @@ -218,13 +259,13 @@ range_eql(VALUE range, VALUE obj) https://github.com/ruby/ruby/blob/trunk/range.c#L259 /* * call-seq: - * rng.hash -> integer + * hash -> integer * - * Compute a hash-code for this range. Two ranges with equal - * begin and end points (using <code>eql?</code>), and the same - * #exclude_end? value will generate the same hash-code. + * Returns the integer hash value for +self+. + * Two range objects +r0+ and +r1+ have the same hash value + * if and only if <tt>r0.eql?(r1)</tt>. * - * See also Object#hash. + * Related: Range#eql?, Object#hash. */ static VALUE @@ -361,42 +402,40 @@ range_step_size(VALUE range, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/range.c#L402 } /* - * Document-method: Range#step - * Document-method: Range#% * call-seq: - * rng.step(n=1) {| obj | block } -> rng - * rng.step(n=1) -> an_enumerator - * rng.step(n=1) -> an_arithmetic_sequence - * rng % n -> an_enumerator - * rng % n -> an_arithmetic_sequence + * step(n = 1) {|element| ... } -> self + * step(n = 1) -> enumerator * - * Iterates over the range, passing each <code>n</code>th element to the block. - * If begin and end are numeric, +n+ is added for each iteration. - * Otherwise #step invokes #succ to iterate through range elements. + * Iterates over the elements of +self+. * - * If no block is given, an enumerator is returned instead. - * Especially, the enumerator is an Enumerator::ArithmeticSequence - * if begin and end of the range are numeric. + * With a block given and no argument, + * calls the block each element of the range; returns +self+: + * + * a = [] + * (1..5).step {|element| a.push(element) } # => 1..5 + * a # => [1, 2, 3, 4, 5] + * a = [] + * ('a'..'e').step {|element| a.push(element) } # => "a".."e" + * a # => ["a", "b", "c", "d", "e"] * - * range = Xs.new(1)..Xs.new(10) - * range.step(2) {|x| puts x} - * puts - * range.step(3) {|x| puts x} + * With a block given and a positive integer argument +n+ given, + * calls the block with element +0+, element +n+, element <tt>2n</tt>, and so on: * - * <em>produces:</em> + * a = [] + * (1..5).step(2) {|element| a.push(element) } # => 1..5 + * a # => [1, 3, 5] + * a = [] + * ('a'..'e').step(2) {|element| a.push(element) } # => "a".."e" + * a # => ["a", "c", "e"] * - * 1 x - * 3 xxx - * 5 xxxxx - * 7 xxxxxxx - * 9 xxxxxxxxx + * With no block given, returns an enumerator, + * which will be of class Enumerator::ArithmeticSequence if +self+ is numeric; + * otherwise of class Enumerator: * - * 1 x - * 4 xxxx - * 7 xxxxxxx - * 10 xxxxxxxxxx + * e = (1..5).step(2) # => ((1..5).step(2)) + * e.class # => Enumerator::ArithmeticSequence + * ('a'..'e').step # => #<Enumerator: ...> * - * See Range for the definition of class Xs. */ -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/