ruby-changes:61268
From: Burdette <ko1@a...>
Date: Sat, 16 May 2020 06:12:56 +0900 (JST)
Subject: [ruby-changes:61268] 24739c62e5 (master): [ci skip] Rdoc enhancements for Array (#3063)
https://git.ruby-lang.org/ruby.git/commit/?id=24739c62e5 From 24739c62e5cee1eaa0857fee2800c8bcba8c9ced Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 15 May 2020 16:12:40 -0500 Subject: [ci skip] Rdoc enhancements for Array (#3063) * Per @nobu review * Rdoc enhancements for Array * Responses to review diff --git a/array.c b/array.c index dbb40db..262d521 100644 --- a/array.c +++ b/array.c @@ -935,21 +935,26 @@ rb_check_to_array(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L935 /* * call-seq: - * Array.try_convert(obj) -> array or nil + * Array.try_convert(obj) -> new_array or nil * - * Tries to convert +obj+ into an array, using the +to_ary+ method. Returns - * the converted array or +nil+ if +obj+ cannot be converted. - * This method can be used to check if an argument is an array. + * Tries to convert +obj+ to an \Array. * - * Array.try_convert([1]) #=> [1] - * Array.try_convert("1") #=> nil + * When +obj+ is an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects] + * (implements +to_ary+), + * returns the \Array object created by converting it: * - * if tmp = Array.try_convert(arg) - * # the argument is an array - * elsif tmp = String.try_convert(arg) - * # the argument is a string - * end + * class ToAryReturnsArray < Set + * def to_ary + * self.to_a + * end + * end + * as = ToAryReturnsArray.new([:foo, :bar, :baz]) + * Array.try_convert(as) # => [:foo, :bar, :baz] * + * Returns +nil+ if +obj+ is not \Array-convertible: + * + * Array.try_convert(:foo) # => nil */ static VALUE @@ -960,58 +965,96 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L965 /* * call-seq: - * Array.new(size=0, default=nil) - * Array.new(array) - * Array.new(size) {|index| block } + * Array.new -> new_empty_array + * Array.new(array) -> new_array + * Array.new(size) -> new_array + * Array.new(size, default_value) -> new_array + * Array.new(size) {|index| ... } -> new_array + * + * Returns a new \Array. + * + * Argument +array+, if given, must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects] + * (implements +to_ary+). + * + * Argument +size+, if given must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * (implements +to_int+). + * + * Argument +default_value+ may be any object. * - * Returns a new array. + * --- * - * In the first form, if no arguments are sent, the new array will be empty. - * When a +size+ and an optional +default+ are sent, an array is created with - * +size+ copies of +default+. Take notice that all elements will reference the - * same object +default+. + * With no block and no arguments, returns a new empty \Array object: * - * The second form creates a copy of the array passed as a parameter (the - * array is generated by calling to_ary on the parameter). + * a = Array.new + * a # => [] * - * first_array = ["Matz", "Guido"] + * With no block and a single argument +array+, + * returns a new \Array formed from +array+: * - * second_array = Array.new(first_array) #=> ["Matz", "Guido"] + * a = Array.new([:foo, 'bar', 2]) + * a.class # => Array + * a # => [:foo, "bar", 2] * - * first_array.equal? second_array #=> false + * With no block and a single argument +size+, + * returns a new \Array of the given size + * whose elements are all +nil+: * - * In the last form, an array of the given size is created. Each element in - * this array is created by passing the element's index to the given block - * and storing the return value. + * a = Array.new(0) + * a # => [] + * a = Array.new(3) + * a # => [nil, nil, nil] * - * Array.new(3) {|index| index ** 2} - * # => [0, 1, 4] + * With no block and arguments +size+ and +default_value+, + * returns an \Array of the given size; + * each element is that same +default_value+: * - * == Common gotchas + * a = Array.new(3, 'x') + * a # => ['x', 'x', 'x'] + * a[1].equal?(a[0]) # => true # Identity check. + * a[2].equal?(a[0]) # => true # Identity check. * - * When sending the second parameter, the same object will be used as the - * value for all the array elements: + * With a block and argument +size+, + * returns an \Array of the given size; + * the block is called with each successive integer +index+; + * the element for that +index+ is the return value from the block: * - * a = Array.new(2, Hash.new) - * # => [{}, {}] + * a = Array.new(3) { |index| "Element #{index}" } + * a # => ["Element 0", "Element 1", "Element 2"] * - * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {"cat"=>"feline"}] + * With a block and no argument, + * or a single argument +0+, + * ignores the block and returns a new empty \Array: * - * a[1]['cat'] = 'Felix' - * a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}] + * a = Array.new(0) { |n| fail 'Cannot happen' } + * a # => [] + * a = Array.new { |n| fail 'Cannot happen' } + * a # => [] * - * Since all the Array elements store the same hash, changes to one of them - * will affect them all. + * With a block and arguments +size+ and +default_value+, + * gives a warning message + * ('warning: block supersedes default value argument'), + * and assigns elements from the block's return values: * - * If multiple copies are what you want, you should use the block - * version which uses the result of that block each time an element - * of the array needs to be initialized: + * Array.new(4, :default) {} # => [nil, nil, nil, nil] * - * a = Array.new(2) {Hash.new} - * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {}] + * --- * + * Raises an exception if +size+ is a negative integer: + * + * # Raises ArgumentError (negative array size): + * Array.new(-1) + * # Raises ArgumentError (negative array size): + * Array.new(-1, :default) + * # Raises ArgumentError (negative array size): + * Array.new(-1) { |n| } + * + * Raises an exception if the single argument is neither \Array-convertible + * nor \Integer-convertible. + * + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * Array.new(:foo) */ static VALUE @@ -1193,18 +1236,20 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos https://github.com/ruby/ruby/blob/trunk/array.c#L1236 /* * call-seq: - * ary << obj -> ary + * ary << obj -> self * - * Append---Pushes the given object on to the end of this array. This - * expression returns the array itself, so several appends - * may be chained together. + * Appends +obj+ to +ary+; returns +self+: * - * a = [ 1, 2 ] - * a << "c" << "d" << [ 3, 4 ] - * #=> [ 1, 2, "c", "d", [ 3, 4 ] ] - * a - * #=> [ 1, 2, "c", "d", [ 3, 4 ] ] + * a = [:foo, 'bar', 2] + * a1 = a << :baz + * a1 # => [:foo, "bar", 2, :baz] + * a1.equal?(a) # => true * + * Appends +obj+ as one element, even if it is another \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a << [3, 4] # => + * a1 # => [:foo, "bar", 2, [3, 4]] */ VALUE @@ -1232,19 +1277,21 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L1277 /* * call-seq: - * ary.push(obj, ...) -> ary - * ary.append(obj, ...) -> ary + * ary.push(*objects) -> self + * ary.append(*objects) -> self * - * Append --- Pushes the given object(s) on to the end of this array. This - * expression returns the array itself, so several appends - * may be chained together. See also Array#pop for the opposite - * effect. + * Appends each argument in +objects+ to the array; returns +self+: * - * a = [ "a", "b", "c" ] - * a.push("d", "e", "f") - * #=> ["a", "b", "c", "d", "e", "f"] - * [1, 2, 3].push(4).push(5) - * #=> [1, 2, 3, 4, 5] + * a = [:foo, 'bar', 2] + * a1 = a.push(:baz, :bat) + * a1 # => [:foo, "bar", 2, :baz, :bat] + * a1.equal?(a) # => true + * + * Appends each argument as one element, even if it is another \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a.push([:baz, :bat], [:bam, :bad]) + * a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]] */ static VALUE @@ -1274,20 +1321,62 @@ rb_ary_pop(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1321 /* * call-seq: - * ary.pop -> obj or nil - * ary.pop(n) -> new_ary + * ary.pop -> obj or nil + * ary.pop(n) -> new_array * - * Removes the last element from +self+ and returns it, or - * +nil+ if the array is empty. + * Removes and returns trailing elements from the array. * - * If a number +n+ is given, returns an array of the last +n+ elements - * (or less) just like <code>array.slice!(-n, n)</code> does. See also - * Array#push for the opposite effect. + * Argument +n+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * (implements +to_int+). * - * a = [ "a", "b", "c", "d" ] - * a.pop #=> "d" - * a.pop(2) #=> ["b", "c"] - * a #=> ["a"] + * --- + * + * When no argument is given and the array is not empty, + * removes and returns the last element in the array: + * + * a = [:foo, 'bar', 2] + * a.pop # => 2 + * a # => [:foo, "bar"] + * + * Returns +nil+ if the array is empty: + * + * a = [] + * a.pop # => nil + * + * --- + * + * When argument +n+ is given and is non-negative and in range, + * removes and returns the last +n+ elements in a new \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a.pop(2) + * a1 # => ["bar", 2] + * a # => [:foo] + * a.pop(0) # => [] + * + * If + (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/