ruby-changes:61694
From: Burdette <ko1@a...>
Date: Sat, 13 Jun 2020 01:32:56 +0900 (JST)
Subject: [ruby-changes:61694] eabdad5e2f (master): [ci skip] Enhanced Rdoc for Array (#3216)
https://git.ruby-lang.org/ruby.git/commit/?id=eabdad5e2f From eabdad5e2f66355558286f38ba60703b1bfc8e89 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 12 Jun 2020 11:32:31 -0500 Subject: [ci skip] Enhanced Rdoc for Array (#3216) Methods: #insert #each #each_index #reverse_each #length #empty? diff --git a/array.c b/array.c index 5626eee..fa1acba 100644 --- a/array.c +++ b/array.c @@ -2403,7 +2403,7 @@ rb_ary_resize(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L2403 * a[7] = 'foo' # => "foo" * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"] * - * If +index+ is negative, counts backward from the end of the array: + * If +index+ is negative, counts backwards from the end of the array: * a = [:foo, 'bar', 2] * a[-1] = 'two' # => "two" * a # => [:foo, "bar", "two"] @@ -2417,7 +2417,7 @@ rb_ary_resize(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L2417 * a[0, 2] = 'foo' # => "foo" * a # => ["foo", 2] * - * If +start+ is negative, counts backward from the end of the array: + * If +start+ is negative, counts backwards from the end of the array: * a = [:foo, 'bar', 2] * a[-2, 2] = 'foo' # => "foo" * a # => [:foo, "foo"] @@ -2449,7 +2449,7 @@ rb_ary_resize(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L2449 * a[0..1] = 'foo' # => "foo" * a # => ["foo", 2] * - * if <tt>range.begin</tt> is negative, counts backward from the end of the array: + * if <tt>range.begin</tt> is negative, counts backwards from the end of the array: * a = [:foo, 'bar', 2] * a[-2..2] = 'foo' # => "foo" * a # => [:foo, "foo"] @@ -2551,18 +2551,54 @@ fixnum: https://github.com/ruby/ruby/blob/trunk/array.c#L2551 /* * call-seq: - * ary.insert(index, obj...) -> ary + * array.insert(index, *objects) -> self * - * Inserts the given values before the element with the given +index+. + * Inserts given +objects+ before or after the element at +offset+ index; + * returns +self+. + * + * Argument +index+ must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]. + * + * --- + * + * When +index+ is non-negative, inserts all given +objects+ + * before the element at offset +index+: + * a = [:foo, 'bar', 2] + * a1 = a.insert(1, :bat, :bam) + * a # => [:foo, :bat, :bam, "bar", 2] + * a1.object_id == a.object_id # => true + * + * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>): + * a = [:foo, 'bar', 2] + * a.insert(5, :bat, :bam) + * a # => [:foo, "bar", 2, nil, nil, :bat, :bam] + * + * Does nothing if no objects given: + * a = [:foo, 'bar', 2] + * a.insert(1) + * a.insert(50) + * a.insert(-50) + * a # => [:foo, "bar", 2] + * + * --- * - * Negative indices count backwards from the end of the array, where +-1+ is - * the last element. If a negative index is used, the given values will be - * inserted after that element, so using an index of +-1+ will insert the - * values at the end of the array. + * When +index+ is negative, inserts all given +objects+ + * _after_ the element at offset <tt>index+self.size</tt>: + * a = [:foo, 'bar', 2] + * a.insert(-2, :bat, :bam) + * a # => [:foo, "bar", :bat, :bam, 2] + * + * --- + * + * Raises an exception if +index+ is not an Integer-convertible object: + * a = [:foo, 'bar', 2, 'bar'] + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * a.insert(:foo) * - * a = %w{ a b c d } - * a.insert(2, 99) #=> ["a", "b", 99, "c", "d"] - * a.insert(-2, 1, 2, 3) #=> ["a", "b", 99, "c", 1, 2, 3, "d"] + * Raises an exception if +index+ is too small (<tt>index+self.size < 0</tt>): + * a = [:foo, 'bar', 2] + * # Raises IndexError (index -5 too small for array; minimum: -4): + * a.insert(-5, :bat, :bam) */ static VALUE @@ -2600,20 +2636,45 @@ ary_enum_length(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L2636 /* * call-seq: - * ary.each {|item| block} -> ary - * ary.each -> Enumerator + * array.each {|element| ... } -> self + * array.each -> Enumerator * - * Calls the given block once for each element in +self+, passing that element - * as a parameter. Returns the array itself. + * Iterates over array elements. * - * If no block is given, an Enumerator is returned. + * --- * - * a = [ "a", "b", "c" ] - * a.each {|x| print x, " -- " } + * When a block given, passes each successive array element to the block; + * returns +self+: + * a = [:foo, 'bar', 2] + * a1 = a.each {|element| puts "#{element.class} #{element}" } + * a1.equal?(a) # => true # Returned self + * + * Output: + * Symbol foo + * String bar + * Integer 2 + * + * Allows the array to be modified during iteration: + * a = [:foo, 'bar', 2] + * a.each {|element| puts element; a.clear if element.to_s.start_with?('b') } + * a # => [] * - * produces: + * Output: + * foo + * bar * - * a -- b -- c -- + * --- + * + * When no block given, returns a new \Enumerator: + * a = [:foo, 'bar', 2] + * e = a.each + * e # => #<Enumerator: [:foo, "bar", 2]:each> + * a1 = e.each { |element| puts "#{element.class} #{element}" } + * + * Output: + * Symbol foo + * String bar + * Integer 2 */ VALUE @@ -2630,20 +2691,45 @@ rb_ary_each(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2691 /* * call-seq: - * ary.each_index {|index| block} -> ary - * ary.each_index -> Enumerator + * array.each_index {|index| ... } -> self + * array.each_index -> Enumerator * - * Same as Array#each, but passes the +index+ of the element instead of the - * element itself. + * Iterates over array indexes. * - * An Enumerator is returned if no block is given. + * --- * - * a = [ "a", "b", "c" ] - * a.each_index {|x| print x, " -- " } + * When a block given, passes each successive array index to the block; + * returns +self+: + * a = [:foo, 'bar', 2] + * a1 = a.each_index {|index| puts "#{index} #{a[index]}" } + * a1.equal?(a) # => true # Returned self * - * produces: + * Output: + * 0 foo + * 1 bar + * 2 2 * - * 0 -- 1 -- 2 -- + * Allows the array to be modified during iteration: + * a = [:foo, 'bar', 2] + * a.each_index {|index| puts index; a.clear if index > 0 } + * a # => [] + * + * Output: + * 0 + * 1 + * + * --- + * + * When no block given, returns a new \Enumerator: + * a = [:foo, 'bar', 2] + * e = a.each_index + * e # => #<Enumerator: [:foo, "bar", 2]:each_index> + * a1 = e.each {|index| puts "#{index} #{a[index]}"} + * + * Output: + * 0 foo + * 1 bar + * 2 2 */ static VALUE @@ -2660,17 +2746,44 @@ rb_ary_each_index(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2746 /* * call-seq: - * ary.reverse_each {|item| block} -> ary - * ary.reverse_each -> Enumerator + * array.reverse_each {|element| ... } -> self + * array.reverse_each -> Enumerator * - * Same as Array#each, but traverses +self+ in reverse order. + * Iterates backwards over array elements. * - * a = [ "a", "b", "c" ] - * a.reverse_each {|x| print x, " " } + * --- + * + * When a block given, passes, in reverse order, each element to the block; + * returns +self+: + * a = [:foo, 'bar', 2] + * a1 = a.reverse_each {|element| puts "#{element.class} #{element}" } + * a1.equal?(a) # => true # Returned self + * + * Output: + * Integer 2 + * String bar + * Symbol foo + * + * Allows the array to be modified during iteration: + * a = [:foo, 'bar', 2] + * a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') } + * a # => [] + * + * Output: + * 2 + * bar * - * produces: + * --- * - * c b a + * When no block given, returns a new \Enumerator: + * a = [:foo, 'bar', 2] + * e = a.reverse_each + * e # => #<Enumerator: [:foo, "bar", 2]:reverse_each> + * a1 = e.each { |element| puts "#{element.class} #{element}" } + * Output: + * Integer 2 + * String bar + * Symbol foo */ static VALUE @@ -2693,12 +2806,12 @@ rb_ary_reverse_each(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2806 /* * call-seq: - * ary.length -> int + * array.length -> an_integer * - * Returns the number of elements in +self+. May be zero. - * - * [ 1, 2, 3, 4, 5 ].length #=> 5 - * [].length #=> 0 + * Returns the count of elements in the array: + * a = [:foo, 'bar', 2] + * a.length # => 3 + * [].length # => 0 */ static VALUE @@ -2710,11 +2823,12 @@ rb_ary_length(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2823 /* * call-seq: - * ary.empty? -> true or false - * - * Returns +true+ if +self+ contains no elements. + * array.empty? -> true or false * - * [].empty? #=> true + * Returns +true+ if the count of elements in the array is zero, + * +false+ otherwise: + * [].empty? # => true + * [:foo, 'bar', 2].empty? # => false */ static VALUE -- cgit v0.10.2 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/