ruby-changes:62188
From: Burdette <ko1@a...>
Date: Sat, 11 Jul 2020 22:02:37 +0900 (JST)
Subject: [ruby-changes:62188] 3b96ad9b54 (master): Enhanced RDoc for Array#fill (#3301)
https://git.ruby-lang.org/ruby.git/commit/?id=3b96ad9b54 From 3b96ad9b54455aef66edd758fa1ef931fa748ce5 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sat, 11 Jul 2020 08:01:56 -0500 Subject: Enhanced RDoc for Array#fill (#3301) * Enhanced RDoc for Array#fill * Update array.c There's one more at 5072. I'll get it. Co-authored-by: Eric Hodel <drbrain@s...> * Update array.c Co-authored-by: Eric Hodel <drbrain@s...> * Update array.c Co-authored-by: Eric Hodel <drbrain@s...> * Update array.c Co-authored-by: Eric Hodel <drbrain@s...> * Update array.c Co-authored-by: Eric Hodel <drbrain@s...> * Update array.c Co-authored-by: Eric Hodel <drbrain@s...> diff --git a/array.c b/array.c index 1864497..7d1fdf2 100644 --- a/array.c +++ b/array.c @@ -5067,32 +5067,220 @@ rb_ary_clear(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L5067 /* * call-seq: - * ary.fill(obj) -> ary - * ary.fill(obj, start [, length]) -> ary - * ary.fill(obj, range) -> ary - * ary.fill {|index| block} -> ary - * ary.fill(start [, length]) {|index| block} -> ary - * ary.fill(range) {|index| block} -> ary + * array.fill(obj) -> self + * array.fill(obj, start) -> self + * array.fill(obj, start, length) -> self + * array.fill(obj, range) -> self + * array.fill { |index| ... } -> self + * array.fill(start) { |index| ... } -> self + * array.fill(start, length) { |index| ... } -> self + * array.fill(range) { |index| ... } -> self + * + * Replaces specified elements in +self+ with specified objects; returns +self+. + * + * - Arguments +start+ and +length+, if given, must be + * {Integer-convertible objects}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]. + * - Argument +range+, if given, must be a \Range object. + * + * --- + * + * With argument +obj+ and no block given, replaces all elements with that one object: + * a = ['a', 'b', 'c', 'd'] + * a # => ["a", "b", "c", "d"] + * a1 = a.fill(:X) + * a1 # => [:X, :X, :X, :X] + * a.equal?(a) # => true # Retrurned self + * + * --- + * + * With arguments +obj+ and +start+, and no block given, replaces elements based on the given start. + * + * If +start+ is in range (<tt>0 <= start < ary.size</tt>), + * replaces all elements from offset +start+ through the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 2) # => ["a", "b", :X, :X] + * + * If +start+ is too large (<tt>start >= ary.size</tt>), does nothing: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 4) # => ["a", "b", "c", "d"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 5) # => ["a", "b", "c", "d"] + * + * If +start+ is negative, counts from the end (starting index is <tt>start + ary.size</tt>): + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, -2) # => ["a", "b", :X, :X] + * + * If +start+ is too small (less than and far from zero), replaces all elements: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, -6) # => [:X, :X, :X, :X] + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, -50) # => [:X, :X, :X, :X] + * + * --- + * + * With arguments +obj+, +start+, and +length+, and no block given, + * replaces elements based on the given +start+ and +length+. + * + * If +start+ is in range, replaces +length+ elements beginning at offset +start+: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 1, 1) # => ["a", :X, "c", "d"] + * + * If +start+ is negative, counts from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, -2, 1) # => ["a", "b", :X, "d"] + * + * If +start+ is large (<tt>start >= ary.size</tt>), extends +self+ with +nil+: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil] + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X] + * + * --- + * + * If +length+ is zero or negative, replaces no elements: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, 1, 0) # => ["a", "b", "c", "d"] + * a.fill(:X, 1, -1) # => ["a", "b", "c", "d"] + * + * --- + * + * With arguments +obj+ and +range+, and no block given, + * replaces elements based on the given range. + * + * If the range is positive and ascending (<tt>0 < range.begin <= range.end</tt>), + * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (1..1)) # => ["a", :X, "c", "d"] + * + * If <tt>range.first</tt> is negative, replaces no elements: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"] + * + * If <tt>range.last</tt> is negative, counts from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"] + * + * If <tt>range.last</tt> and <tt>range.last</tt> are both negative, + * both count from the end of the array: + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X] + * a = ['a', 'b', 'c', 'd'] + * a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"] + * + * --- + * + * With no arguments and a block given, calls the block with each index; + * replaces the corresponding element with the block's return value: + * a = ['a', 'b', 'c', 'd'] + * a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"] + * + * --- * - * The first three forms set the selected elements of +self+ (which - * may be the entire array) to +obj+. + * With argument +start+ and a block given, calls the block with each index + * from offset +start+ to the end; replaces the corresponding element + * with the block's return value: * - * A +start+ of +nil+ is equivalent to zero. + * If start is in range (<tt>0 <= start < ary.size</tt>), + * replaces from offset +start+ to the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"] * - * A +length+ of +nil+ is equivalent to the length of the array. + * If +start+ is too large(<tt>start >= ary.size</tt>), does nothing: + * a = ['a', 'b', 'c', 'd'] + * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"] + * + * If +start+ is negative, counts from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"] + * + * If start is too small (<tt>start <= -ary.size</tt>, replaces all elements: + * a = ['a', 'b', 'c', 'd'] + * a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"] + * + * --- + * + * With arguments +start+ and +length+, and a block given, + * calls the block for each index specified by start length; + * replaces the corresponding element with the block's return value. + * + * If +start+ is in range, replaces +length+ elements beginning at offset +start+: + * a = ['a', 'b', 'c', 'd'] + * a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"] + * + * If start is negative, counts from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"] + * + * If +start+ is large (<tt>start >= ary.size</tt>), extends +self+ with +nil+: + * a = ['a', 'b', 'c', 'd'] + * a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil] + * a = ['a', 'b', 'c', 'd'] + * a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"] + * + * If +length+ is zero or less, replaces no elements: + * a = ['a', 'b', 'c', 'd'] + * a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"] + * a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"] + * + * --- * - * The last three forms fill the array with the value of the given block, - * which is passed the absolute index of each element to be filled. + * With arguments +obj+ and +range+, and a block given, + * calls the block with each index in the given range; + * replaces the corresponding element with the block's return value. * - * Negative values of +start+ count from the end of the array, where +-1+ is - * the last element. + * If the range is positive and ascending (<tt>range 0 < range.begin <= range.end</tt>, + * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>: + * a = ['a', 'b', 'c', 'd'] + * a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"] * - * a = [ "a", "b", "c", "d" ] - * a.fill("x") #=> ["x", "x", "x", "x"] - * a.fill("z", 2, 2) #=> ["x", "x", "z", "z"] - * a.fill("y", 0..1) #=> ["y", "y", "z", "z"] - * a.fill {|i| i*i} #=> [0, 1, 4, 9] - * a.fill(-2) {|i| i*i*i} #=> [0, 1, 8, 27] + * If +range.first+ is negative, does nothing: + * a = ['a', 'b', 'c', 'd'] + * a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"] + * + * If <tt>range.last</tt> is negative, counts from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"] + * + * If <tt>range.first</tt> and <tt>range.last</tt> are both negative, + * both count from the end: + * a = ['a', 'b', 'c', 'd'] + * a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"] + * a = ['a', 'b', 'c', 'd'] + * a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"] + * + * --- + * + * Raises an exception if no block is given and the second argument is not a Range + * or an Integer-convertible object, + * # Raises TypeErr (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/