diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2020-06-12 11:32:31 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-06-12 11:32:31 -0500 |
commit | eabdad5e2f66355558286f38ba60703b1bfc8e89 (patch) | |
tree | 4f2c9e56aff9f6942b6bf258cf7873c4255c7d39 /array.c | |
parent | 90412d7a639069a045b3e06e37b709044833cf9a (diff) |
[ci skip] Enhanced Rdoc for Array (#3216)
Methods:
#insert
#each
#each_index
#reverse_each
#length
#empty?
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'array.c')
-rw-r--r-- | array.c | 206 |
1 files changed, 160 insertions, 46 deletions
@@ -2403,7 +2403,7 @@ rb_ary_resize(VALUE ary, long len) * 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) * 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) * 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: /* * 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) /* * 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) /* * 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) /* * 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) /* * 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) /* * 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 |