From de5aa98f396cfe900b456e78a9c451ac8a2a3e97 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 11 Apr 2022 15:23:25 -0500 Subject: Correct whitespace in array.c (#5791) --- array.c | 380 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 370 insertions(+), 10 deletions(-) (limited to 'array.c') diff --git a/array.c b/array.c index bc904ec420..9bb767d79f 100644 --- a/array.c +++ b/array.c @@ -693,6 +693,7 @@ ary_ensure_room_for_push(VALUE ary, long add_len) * array.freeze -> self * * Freezes +self+; returns +self+: + * * a = [] * a.frozen? # => false * a.freeze @@ -1132,6 +1133,7 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass) * * With no block and a single \Array argument +array+, * returns a new \Array formed from +array+: + * * a = Array.new([:foo, 'bar', 2]) * a.class # => Array * a # => [:foo, "bar", 2] @@ -1139,12 +1141,14 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass) * With no block and a single \Integer argument +size+, * returns a new \Array of the given size * whose elements are all +nil+: + * * a = Array.new(3) * a # => [nil, nil, nil] * * With no block and arguments +size+ and +default_value+, * returns an \Array of the given size; * each element is that same +default_value+: + * * a = Array.new(3, 'x') * a # => ['x', 'x', 'x'] * @@ -1152,6 +1156,7 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass) * 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(3) {|index| "Element #{index}" } * a # => ["Element 0", "Element 1", "Element 2"] * @@ -1388,13 +1393,16 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos * array << object -> self * * Appends +object+ to +self+; returns +self+: + * * a = [:foo, 'bar', 2] * a << :baz # => [:foo, "bar", 2, :baz] * * Appends +object+ as one element, even if it is another \Array: + * * a = [:foo, 'bar', 2] * a1 = a << [3, 4] * a1 # => [:foo, "bar", 2, [3, 4]] + * */ VALUE @@ -1427,10 +1435,12 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len) * Appends trailing elements. * * Appends each argument in +objects+ to +self+; returns +self+: + * * a = [:foo, 'bar', 2] * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat] * * 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]] @@ -1474,6 +1484,7 @@ rb_ary_pop(VALUE ary) * * When no argument is given and +self+ is not empty, * removes and returns the last element: + * * a = [:foo, 'bar', 2] * a.pop # => 2 * a # => [:foo, "bar"] @@ -1481,12 +1492,14 @@ rb_ary_pop(VALUE ary) * Returns +nil+ if the array is empty. * * When a non-negative \Integer argument +n+ is given and is in range, + * * removes and returns the last +n+ elements in a new \Array: * a = [:foo, 'bar', 2] * a.pop(2) # => ["bar", 2] * * If +n+ is positive and out of range, * removes and returns all elements: + * * a = [:foo, 'bar', 2] * a.pop(50) # => [:foo, "bar", 2] * @@ -1535,6 +1548,7 @@ rb_ary_shift(VALUE ary) * Removes and returns leading elements. * * When no argument is given, removes and returns the first element: + * * a = [:foo, 'bar', 2] * a.shift # => :foo * a # => ['bar', 2] @@ -1543,12 +1557,14 @@ rb_ary_shift(VALUE ary) * * When positive \Integer argument +n+ is given, removes the first +n+ elements; * returns those elements in a new \Array: + * * a = [:foo, 'bar', 2] * a.shift(2) # => [:foo, 'bar'] * a # => [2] * * If +n+ is as large as or larger than self.length, * removes all elements; returns those elements in a new \Array: + * * a = [:foo, 'bar', 2] * a.shift(3) # => [:foo, 'bar', 2] * @@ -1698,6 +1714,7 @@ ary_ensure_room_for_unshift(VALUE ary, int argc) * array.unshift(*objects) -> self * * Prepends the given +objects+ to +self+: + * * a = [:foo, 'bar', 2] * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2] * @@ -1791,12 +1808,14 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * Returns elements from +self+; does not modify +self+. * * When a single \Integer argument +index+ is given, returns the element at offset +index+: + * * a = [:foo, 'bar', 2] * a[0] # => :foo * a[2] # => 2 * a # => [:foo, "bar", 2] * * If +index+ is negative, counts relative to the end of +self+: + * * a = [:foo, 'bar', 2] * a[-1] # => 2 * a[-2] # => "bar" @@ -1805,12 +1824,14 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * * When two \Integer arguments +start+ and +length+ are given, * returns a new \Array of size +length+ containing successive elements beginning at offset +start+: + * * a = [:foo, 'bar', 2] * a[0, 2] # => [:foo, "bar"] * a[1, 2] # => ["bar", 2] * * If start + length is greater than self.length, * returns all elements from offset +start+ to the end: + * * a = [:foo, 'bar', 2] * a[0, 4] # => [:foo, "bar", 2] * a[1, 3] # => ["bar", 2] @@ -1824,6 +1845,7 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * When a single \Range argument +range+ is given, * treats range.min as +start+ above * and range.size as +length+ above: + * * a = [:foo, 'bar', 2] * a[0..1] # => [:foo, "bar"] * a[1..2] # => ["bar", 2] @@ -1831,18 +1853,21 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * Special case: If range.start == a.size, returns a new empty \Array. * * If range.end is negative, calculates the end index from the end: + * * a = [:foo, 'bar', 2] * a[0..-1] # => [:foo, "bar", 2] * a[0..-2] # => [:foo, "bar"] * a[0..-3] # => [:foo] * * If range.start is negative, calculates the start index from the end: + * * a = [:foo, 'bar', 2] * a[-1..2] # => [2] * a[-2..2] # => ["bar", 2] * a[-3..2] # => [:foo, "bar", 2] * * If range.start is larger than the array size, returns +nil+. + * * a = [:foo, 'bar', 2] * a[4..1] # => nil * a[4..0] # => nil @@ -1851,11 +1876,13 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * When a single Enumerator::ArithmeticSequence argument +aseq+ is given, * returns an \Array of elements corresponding to the indexes produced by * the sequence. + * * a = ['--', 'data1', '--', 'data2', '--', 'data3'] * a[(1..).step(2)] # => ["data1", "data2", "data3"] * * Unlike slicing with range, if the start or the end of the arithmetic sequence * is larger than array size, throws RangeError. + * * a = ['--', 'data1', '--', 'data2', '--', 'data3'] * a[(1..11).step(2)] * # RangeError (((1..11).step(2)) out of range) @@ -1864,6 +1891,7 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); * * If given a single argument, and its type is not one of the listed, tries to * convert it to Integer, and raises if it is impossible: + * * a = [:foo, 'bar', 2] * # Raises TypeError (no implicit conversion of Symbol into Integer): * a[:foo] @@ -1922,6 +1950,7 @@ rb_ary_aref1(VALUE ary, VALUE arg) * a = [:foo, 'bar', 2] * a.at(0) # => :foo * a.at(2) # => 2 + * */ VALUE @@ -1938,6 +1967,7 @@ rb_ary_at(VALUE ary, VALUE pos) * Returns elements from +self+; does not modify +self+. * * When no argument is given, returns the first element: + * * a = [:foo, 'bar', 2] * a.first # => :foo * a # => [:foo, "bar", 2] @@ -1946,14 +1976,17 @@ rb_ary_at(VALUE ary, VALUE pos) * * When non-negative \Integer argument +n+ is given, * returns the first +n+ elements in a new \Array: + * * a = [:foo, 'bar', 2] * a.first(2) # => [:foo, "bar"] * * If n >= array.size, returns all elements: + * * a = [:foo, 'bar', 2] * a.first(50) # => [:foo, "bar", 2] * * If n == 0 returns an new empty \Array: + * * a = [:foo, 'bar', 2] * a.first(0) # [] * @@ -1979,6 +2012,7 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) * Returns elements from +self+; +self+ is not modified. * * When no argument is given, returns the last element: + * * a = [:foo, 'bar', 2] * a.last # => 2 * a # => [:foo, "bar", 2] @@ -1987,14 +2021,17 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) * * When non-negative \Innteger argument +n+ is given, * returns the last +n+ elements in a new \Array: + * * a = [:foo, 'bar', 2] * a.last(2) # => ["bar", 2] * * If n >= array.size, returns all elements: + * * a = [:foo, 'bar', 2] * a.last(50) # => [:foo, "bar", 2] * * If n == 0, returns an new empty \Array: + * * a = [:foo, 'bar', 2] * a.last(0) # [] * @@ -2024,10 +2061,12 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) * * With the single \Integer argument +index+, * returns the element at offset +index+: + * * a = [:foo, 'bar', 2] * a.fetch(1) # => "bar" * * If +index+ is negative, counts from the end of the array: + * * a = [:foo, 'bar', 2] * a.fetch(-1) # => 2 * a.fetch(-2) # => "bar" @@ -2035,6 +2074,7 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) * With arguments +index+ and +default_value+, * returns the element at offset +index+ if index is in range, * otherwise returns +default_value+: + * * a = [:foo, 'bar', 2] * a.fetch(1, nil) # => "bar" * @@ -2045,6 +2085,7 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) * a = [:foo, 'bar', 2] * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar" * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50" + * */ static VALUE @@ -2086,6 +2127,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) * When argument +object+ is given but no block, * returns the index of the first element +element+ * for which object == element: + * * a = [:foo, 'bar', 2, 'bar'] * a.index('bar') # => 1 * @@ -2094,12 +2136,14 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) * When both argument +object+ and a block are given, * calls the block with each successive element; * returns the index of the first element for which the block returns a truthy value: + * * a = [:foo, 'bar', 2, 'bar'] * a.index {|element| element == 'bar' } # => 1 * * Returns +nil+ if the block never returns a truthy value. * * When neither an argument nor a block is given, returns a new Enumerator: + * * a = [:foo, 'bar', 2] * e = a.index * e # => # @@ -2147,6 +2191,7 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) * Returns the index of the last element for which object == element. * * When argument +object+ is given but no block, returns the index of the last such element found: + * * a = [:foo, 'bar', 2, 'bar'] * a.rindex('bar') # => 3 * @@ -2154,6 +2199,7 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) * * When a block is given but no argument, calls the block with each successive element; * returns the index of the last element for which the block returns a truthy value: + * * a = [:foo, 'bar', 2, 'bar'] * a.rindex {|element| element == 'bar' } # => 3 * @@ -2368,16 +2414,19 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) * When \Integer argument +index+ is given, assigns +object+ to an element in +self+. * * If +index+ is non-negative, assigns +object+ the element at offset +index+: + * * a = [:foo, 'bar', 2] * a[0] = 'foo' # => "foo" * a # => ["foo", "bar", 2] * * If +index+ is greater than self.length, extends the array: + * * a = [:foo, 'bar', 2] * a[7] = 'foo' # => "foo" * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"] * * If +index+ is negative, counts backwards from the end of the array: + * * a = [:foo, 'bar', 2] * a[-1] = 'two' # => "two" * a # => [:foo, "bar", "two"] @@ -2385,11 +2434,13 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) * When \Integer arguments +start+ and +length+ are given and +object+ is not an \Array, * removes length - 1 elements beginning at offset +start+, * and assigns +object+ at offset +start+: + * * a = [:foo, 'bar', 2] * a[0, 2] = 'foo' # => "foo" * a # => ["foo", 2] * * If +start+ is negative, counts backwards from the end of the array: + * * a = [:foo, 'bar', 2] * a[-2, 2] = 'foo' # => "foo" * a # => [:foo, "foo"] @@ -2397,17 +2448,20 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) * If +start+ is non-negative and outside the array ( >= self.size), * extends the array with +nil+, assigns +object+ at offset +start+, * and ignores +length+: + * * a = [:foo, 'bar', 2] * a[6, 50] = 'foo' # => "foo" * a # => [:foo, "bar", 2, nil, nil, nil, "foo"] * * If +length+ is zero, shifts elements at and following offset +start+ * and assigns +object+ at offset +start+: + * * a = [:foo, 'bar', 2] * a[1, 0] = 'foo' # => "foo" * a # => [:foo, "foo", "bar", 2] * * If +length+ is too large for the existing array, does not extend the array: + * * a = [:foo, 'bar', 2] * a[1, 5] = 'foo' # => "foo" * a # => [:foo, "foo"] @@ -2415,29 +2469,34 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) * When \Range argument +range+ is given and +object+ is an \Array, * removes length - 1 elements beginning at offset +start+, * and assigns +object+ at offset +start+: + * * a = [:foo, 'bar', 2] * a[0..1] = 'foo' # => "foo" * a # => ["foo", 2] * * if range.begin is negative, counts backwards from the end of the array: + * * a = [:foo, 'bar', 2] * a[-2..2] = 'foo' # => "foo" * a # => [:foo, "foo"] * * If the array length is less than range.begin, * assigns +object+ at offset range.begin, and ignores +length+: + * * a = [:foo, 'bar', 2] * a[6..50] = 'foo' # => "foo" * a # => [:foo, "bar", 2, nil, nil, nil, "foo"] * * If range.end is zero, shifts elements at and following offset +start+ * and assigns +object+ at offset +start+: + * * a = [:foo, 'bar', 2] * a[1..0] = 'foo' # => "foo" * a # => [:foo, "foo", "bar", 2] * * If range.end is negative, assigns +object+ at offset +start+, * retains range.end.abs -1 elements past that, and removes those beyond: + * * a = [:foo, 'bar', 2] * a[1..-1] = 'foo' # => "foo" * a # => [:foo, "foo"] @@ -2451,9 +2510,11 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) * * If range.end is too large for the existing array, * replaces array elements, but does not extend the array with +nil+ values: + * * a = [:foo, 'bar', 2] * a[1..5] = 'foo' # => "foo" * a # => [:foo, "foo"] + * */ static VALUE @@ -2490,15 +2551,18 @@ rb_ary_aset(int argc, VALUE *argv, VALUE ary) * * When +index+ is non-negative, inserts all given +objects+ * before the element at offset +index+: + * * a = [:foo, 'bar', 2] * a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2] * * Extends the array if +index+ is beyond the array (index >= self.size): + * * 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) @@ -2507,9 +2571,11 @@ rb_ary_aset(int argc, VALUE *argv, VALUE ary) * * When +index+ is negative, inserts all given +objects+ * _after_ the element at offset index+self.size: + * * a = [:foo, 'bar', 2] * a.insert(-2, :bat, :bam) * a # => [:foo, "bar", :bat, :bam, 2] + * */ static VALUE @@ -2554,29 +2620,35 @@ ary_enum_length(VALUE ary, VALUE args, VALUE eobj) * * When a block given, passes each successive array element to the block; * returns +self+: + * * a = [:foo, 'bar', 2] * a.each {|element| puts "#{element.class} #{element}" } * * 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') } * * Output: + * * foo * bar * * When no block given, returns a new \Enumerator: * a = [:foo, 'bar', 2] + * * e = a.each * e # => # * a1 = e.each {|element| puts "#{element.class} #{element}" } * * Output: + * * Symbol foo * String bar * Integer 2 @@ -2605,29 +2677,35 @@ rb_ary_each(VALUE ary) * * When a block given, passes each successive array index to the block; * returns +self+: + * * a = [:foo, 'bar', 2] * a.each_index {|index| puts "#{index} #{a[index]}" } * * Output: + * * 0 foo * 1 bar * 2 2 * * Allows the array to be modified during iteration: + * * a = [:foo, 'bar', 2] * a.each_index {|index| puts index; a.clear if index > 0 } * * Output: + * * 0 * 1 * * When no block given, returns a new \Enumerator: + * * a = [:foo, 'bar', 2] * e = a.each_index * e # => # * a1 = e.each {|index| puts "#{index} #{a[index]}"} * * Output: + * * 0 foo * 1 bar * 2 2 @@ -2656,28 +2734,35 @@ rb_ary_each_index(VALUE ary) * * When a block given, passes, in reverse order, each element to the block; * returns +self+: + * * a = [:foo, 'bar', 2] * a.reverse_each {|element| puts "#{element.class} #{element}" } * * 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') } * * Output: + * * 2 * bar * * When no block given, returns a new \Enumerator: + * * a = [:foo, 'bar', 2] * e = a.reverse_each * e # => # * a1 = e.each {|element| puts "#{element.class} #{element}" } + * * Output: + * * Integer 2 * String bar * Symbol foo @@ -2890,22 +2975,27 @@ rb_ary_join(VALUE ary, VALUE sep) * array.join(separator = $,) -> new_string * * Returns the new \String formed by joining the array elements after conversion. - * For each element +element+ + * For each element +element+: + * * - Uses element.to_s if +element+ is not a kind_of?(Array). * - Uses recursive element.join(separator) if +element+ is a kind_of?(Array). * * With no argument, joins using the output field separator, $,: + * * a = [:foo, 'bar', 2] * $, # => nil * a.join # => "foobar2" * * With \string argument +separator+, joins using that separator: + * * a = [:foo, 'bar', 2] * a.join("\n") # => "foo\nbar\n2" * * Joins recursively for nested Arrays: + * * a = [:foo, [:bar, [:baz, :bat]]] * a.join # => "foobarbazbat" + * */ static VALUE rb_ary_join_m(int argc, VALUE *argv, VALUE ary) @@ -2946,6 +3036,7 @@ inspect_ary(VALUE ary, VALUE dummy, int recur) * * Returns the new \String formed by calling method #inspect * on each array element: + * * a = [:foo, 'bar', 2] * a.inspect # => "[:foo, \"bar\", 2]" * @@ -2970,10 +3061,12 @@ rb_ary_to_s(VALUE ary) * to_a -> self or new_array * * When +self+ is an instance of \Array, returns +self+: + * * a = [:foo, 'bar', 2] * a.to_a # => [:foo, "bar", 2] * * Otherwise, returns a new \Array containing the elements of +self+: + * * class MyArray < Array; end * a = MyArray.new(['foo', 'bar', 'two']) * a.instance_of?(Array) # => false @@ -2981,6 +3074,7 @@ rb_ary_to_s(VALUE ary) * a1 = a.to_a * a1 # => ["foo", "bar", "two"] * a1.class # => Array # Not MyArray + * */ static VALUE @@ -3004,16 +3098,19 @@ rb_ary_to_a(VALUE ary) * When a block is given, calls the block with each array element; * the block must return a 2-element \Array whose two elements * form a key-value pair in the returned \Hash: + * * a = ['foo', :bar, 1, [2, 3], {baz: 4}] * h = a.to_h {|item| [item, item] } * h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}} * * When no block is given, +self+ must be an \Array of 2-element sub-arrays, * each sub-array is formed into a key-value pair in the new \Hash: + * * [].to_h # => {} * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']] * h = a.to_h * h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"} + * */ static VALUE @@ -3084,8 +3181,10 @@ rb_ary_reverse(VALUE ary) * array.reverse! -> self * * Reverses +self+ in place: + * * a = ['foo', 'bar', 'two'] * a.reverse! # => ["two", "bar", "foo"] + * */ static VALUE @@ -3098,10 +3197,12 @@ rb_ary_reverse_bang(VALUE ary) * call-seq: * array.reverse -> new_array * - * Returns a new \Array with the elements of +self+ in reverse order. + * Returns a new \Array with the elements of +self+ in reverse order: + * * a = ['foo', 'bar', 'two'] * a1 = a.reverse * a1 # => ["two", "bar", "foo"] + * */ static VALUE @@ -3169,35 +3270,42 @@ rb_ary_rotate(VALUE ary, long cnt) * Rotates +self+ in place by moving elements from one end to the other; returns +self+. * * When no argument given, rotates the first element to the last position: + * * a = [:foo, 'bar', 2, 'bar'] * a.rotate! # => ["bar", 2, "bar", :foo] * * When given a non-negative \Integer +count+, * rotates +count+ elements from the beginning to the end: + * * a = [:foo, 'bar', 2] * a.rotate!(2) * a # => [2, :foo, "bar"] * * If +count+ is large, uses count % array.size as the count: + * * a = [:foo, 'bar', 2] * a.rotate!(20) * a # => [2, :foo, "bar"] * * If +count+ is zero, returns +self+ unmodified: + * * a = [:foo, 'bar', 2] * a.rotate!(0) * a # => [:foo, "bar", 2] * * When given a negative Integer +count+, rotates in the opposite direction, * from end to beginning: + * * a = [:foo, 'bar', 2] * a.rotate!(-2) * a # => ["bar", 2, :foo] * * If +count+ is small (far from zero), uses count % array.size as the count: + * * a = [:foo, 'bar', 2] * a.rotate!(-5) * a # => ["bar", 2, :foo] + * */ static VALUE @@ -3218,36 +3326,43 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) * * When no argument given, returns a new \Array that is like +self+, * except that the first element has been rotated to the last position: + * * a = [:foo, 'bar', 2, 'bar'] * a1 = a.rotate * a1 # => ["bar", 2, "bar", :foo] * * When given a non-negative \Integer +count+, * returns a new \Array with +count+ elements rotated from the beginning to the end: + * * a = [:foo, 'bar', 2] * a1 = a.rotate(2) * a1 # => [2, :foo, "bar"] * * If +count+ is large, uses count % array.size as the count: + * * a = [:foo, 'bar', 2] * a1 = a.rotate(20) * a1 # => [2, :foo, "bar"] * * If +count+ is zero, returns a copy of +self+, unmodified: + * * a = [:foo, 'bar', 2] * a1 = a.rotate(0) * a1 # => [:foo, "bar", 2] * * When given a negative \Integer +count+, rotates in the opposite direction, * from end to beginning: + * * a = [:foo, 'bar', 2] * a1 = a.rotate(-2) * a1 # => ["bar", 2, :foo] * * If +count+ is small (far from zero), uses count % array.size as the count: + * * a = [:foo, 'bar', 2] * a1 = a.rotate(-5) * a1 # => ["bar", 2, :foo] + * */ static VALUE @@ -3348,6 +3463,7 @@ sort_2(const void *ap, const void *bp, void *dummy) * * With no block, compares elements using operator <=> * (see Comparable): + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a.sort! @@ -3355,11 +3471,13 @@ sort_2(const void *ap, const void *bp, void *dummy) * * With a block, calls the block with each element pair; * for each element pair +a+ and +b+, the block should return an integer: + * * - Negative when +b+ is to follow +a+. * - Zero when +a+ and +b+ are equivalent. * - Positive when +a+ is to follow +b+. * * Example: + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a.sort! {|a, b| a <=> b } @@ -3369,10 +3487,12 @@ sort_2(const void *ap, const void *bp, void *dummy) * * When the block returns zero, the order for +a+ and +b+ is indeterminate, * and may be unstable: + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a.sort! {|a, b| 0 } * a # => ["d", "e", "c", "a", "b"] + * */ VALUE @@ -3445,6 +3565,7 @@ rb_ary_sort_bang(VALUE ary) * * With no block, compares elements using operator <=> * (see Comparable): + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a1 = a.sort @@ -3452,11 +3573,13 @@ rb_ary_sort_bang(VALUE ary) * * With a block, calls the block with each element pair; * for each element pair +a+ and +b+, the block should return an integer: + * * - Negative when +b+ is to follow +a+. * - Zero when +a+ and +b+ are equivalent. * - Positive when +a+ is to follow +b+. * * Example: + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a1 = a.sort {|a, b| a <=> b } @@ -3466,6 +3589,7 @@ rb_ary_sort_bang(VALUE ary) * * When the block returns zero, the order for +a+ and +b+ is indeterminate, * and may be unstable: + * * a = 'abcde'.split('').shuffle * a # => ["e", "b", "d", "a", "c"] * a1 = a.sort {|a, b| 0 } @@ -3582,6 +3706,7 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy)) * For duplicates returned by the block, the ordering is indeterminate, and may be unstable. * * This example sorts strings based on their sizes: + * * a = ['aaaa', 'bbb', 'cc', 'd'] * a.sort_by! {|element| element.size } * a # => ["d", "cc", "bbb", "aaaa"] @@ -3590,6 +3715,7 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy)) * * a = ['aaaa', 'bbb', 'cc', 'd'] * a.sort_by! # => # + * */ static VALUE @@ -3612,6 +3738,7 @@ rb_ary_sort_by_bang(VALUE ary) * * Calls the block, if given, with each element of +self+; * returns a new \Array whose elements are the return values from the block: + * * a = [:foo, 'bar', 2] * a1 = a.map {|element| element.class } * a1 # => [Symbol, String, Integer] @@ -3646,10 +3773,12 @@ rb_ary_collect(VALUE ary) * * Calls the block, if given, with each element; * replaces the element with the block's return value: + * * a = [:foo, 'bar', 2] * a.map! { |element| element.class } # => [Symbol, String, Integer] * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2] * a1 = a.map! * a1 # => # @@ -3732,32 +3861,39 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx) * of +self+ at the given \Integer or \Range +indexes+. * * For each positive +index+, returns the element at offset +index+: + * * a = [:foo, 'bar', 2] * a.values_at(0, 2) # => [:foo, 2] * a.values_at(0..1) # => [:foo, "bar"] * * The given +indexes+ may be in any order, and may repeat: + * * a = [:foo, 'bar', 2] * a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2] * a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2] * * Assigns +nil+ for an +index+ that is too large: + * * a = [:foo, 'bar', 2] * a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil] * * Returns a new empty \Array if no arguments given. * * For each negative +index+, counts backward from the end of the array: + * * a = [:foo, 'bar', 2] * a.values_at(-1, -3) # => [2, :foo] * * Assigns +nil+ for an +index+ that is too small: + * * a = [:foo, 'bar', 2] * a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2] * * The given +indexes+ may have a mixture of signs: + * * a = [:foo, 'bar', 2] * a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2] + * */ static VALUE @@ -3781,11 +3917,13 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary) * Calls the block, if given, with each element of +self+; * returns a new \Array containing those elements of +self+ * for which the block returns a truthy value: + * * a = [:foo, 'bar', 2, :bam] * a1 = a.select {|element| element.to_s.start_with?('b') } * a1 # => ["bar", :bam] * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2, :bam] * a.select # => # * @@ -3862,12 +4000,14 @@ select_bang_ensure(VALUE a) * removes from +self+ those elements for which the block returns +false+ or +nil+. * * Returns +self+ if any elements were removed: + * * a = [:foo, 'bar', 2, :bam] * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam] * * Returns +nil+ if no elements were removed. * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2, :bam] * a.select! # => # * @@ -3894,12 +4034,15 @@ rb_ary_select_bang(VALUE ary) * * Retains those elements for which the block returns a truthy value; * deletes all other elements; returns +self+: + * * a = [:foo, 'bar', 2, :bam] * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam] * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2, :bam] * a.keep_if # => # + * */ static VALUE @@ -3933,6 +4076,7 @@ ary_resize_smaller(VALUE ary, long len) * When no block is given, * removes from +self+ each element +ele+ such that ele == obj; * returns the last deleted element: + * * s1 = 'bar'; s2 = 'bar' * a = [:foo, s1, 2, s2] * a.delete('bar') # => "bar" @@ -3945,14 +4089,17 @@ ary_resize_smaller(VALUE ary, long len) * * If any such elements are found, ignores the block * and returns the last deleted element: + * * s1 = 'bar'; s2 = 'bar' * a = [:foo, s1, 2, s2] * deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' } * a # => [:foo, 2] * * If no such elements are found, returns the block's return value: + * * a = [:foo, 'bar', 2] * a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found" + * */ VALUE @@ -4038,6 +4185,7 @@ rb_ary_delete_at(VALUE ary, long pos) * Deletes an element from +self+, per the given \Integer +index+. * * When +index+ is non-negative, deletes the element at offset +index+: + * * a = [:foo, 'bar', 2] * a.delete_at(1) # => "bar" * a # => [:foo, 2] @@ -4045,6 +4193,7 @@ rb_ary_delete_at(VALUE ary, long pos) * If index is too large, returns +nil+. * * When +index+ is negative, counts backward from the end of the array: + * * a = [:foo, 'bar', 2] * a.delete_at(-2) # => "bar" * a # => [:foo, 2] @@ -4098,11 +4247,13 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len) * * When the only argument is an \Integer +n+, * removes and returns the _nth_ element in +self+: + * * a = [:foo, 'bar', 2] * a.slice!(1) # => "bar" * a # => [:foo, 2] * * If +n+ is negative, counts backwards from the end of +self+: + * * a = [:foo, 'bar', 2] * a.slice!(-1) # => 2 * a # => [:foo, "bar"] @@ -4112,12 +4263,14 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len) * When the only arguments are Integers +start+ and +length+, * removes +length+ elements from +self+ beginning at offset +start+; * returns the deleted objects in a new \Array: + * * a = [:foo, 'bar', 2] * a.slice!(0, 2) # => [:foo, "bar"] * a # => [2] * * If start + length exceeds the array size, * removes and returns all elements from offset +start+ to the end: + * * a = [:foo, 'bar', 2] * a.slice!(1, 50) # => ["bar", 2] * a # => [:foo] @@ -4129,8 +4282,9 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len) * * When the only argument is a \Range object +range+, * treats range.min as +start+ above and range.size as +length+ above: + * * a = [:foo, 'bar', 2] - * a.slice!(1..2) # => ["bar", 2] + * a.slice!(1..2) # => ["bar", 2] * a # => [:foo] * * If range.start == a.size, returns a new empty \Array. @@ -4138,15 +4292,18 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len) * If range.start is larger than the array size, returns +nil+. * * If range.end is negative, counts backwards from the end of the array: + * * a = [:foo, 'bar', 2] * a.slice!(0..-2) # => [:foo, "bar"] * a # => [2] * * If range.start is negative, * calculates the start index backwards from the end of the array: + * * a = [:foo, 'bar', 2] * a.slice!(-2..2) # => ["bar", 2] * a # => [:foo] + * */ static VALUE @@ -4233,14 +4390,17 @@ ary_reject_bang(VALUE ary) * Removes each element for which the block returns a truthy value. * * Returns +self+ if any elements removed: + * * a = [:foo, 'bar', 2, 'bat'] * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2] * * Returns +nil+ if no elements removed. * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2] * a.reject! # => # + * */ static VALUE @@ -4258,13 +4418,16 @@ rb_ary_reject_bang(VALUE ary) * * Returns a new \Array whose elements are all those from +self+ * for which the block returns +false+ or +nil+: + * * a = [:foo, 'bar', 2, 'bat'] * a1 = a.reject {|element| element.to_s.start_with?('b') } * a1 # => [:foo, 2] * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2] * a.reject # => # + * */ static VALUE @@ -4285,13 +4448,16 @@ rb_ary_reject(VALUE ary) * * Removes each element in +self+ for which the block returns a truthy value; * returns +self+: + * * a = [:foo, 'bar', 2, 'bat'] * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2] * * Returns a new \Enumerator if no block given: + * * a = [:foo, 'bar', 2] * a.delete_if # => # - */ + * +3 */ static VALUE rb_ary_delete_if(VALUE ary) @@ -4339,10 +4505,12 @@ take_items(VALUE obj, long n) * * Each nested array new_array[n] is of size other_arrays.size+1, * and contains: + * * - The _nth_ element of +self+. * - The _nth_ element of each of the +other_arrays+. * * If all +other_arrays+ and +self+ are the same size: + * * a = [:a0, :a1, :a2, :a3] * b = [:b0, :b1, :b2, :b3] * c = [:c0, :c1, :c2, :c3] @@ -4351,6 +4519,7 @@ take_items(VALUE obj, long n) * * If any array in +other_arrays+ is smaller than +self+, * fills to self.size with +nil+: + * * a = [:a0, :a1, :a2, :a3] * b = [:b0, :b1, :b2] * c = [:c0, :c1] @@ -4359,23 +4528,27 @@ take_items(VALUE obj, long n) * * If any array in +other_arrays+ is larger than +self+, * its trailing elements are ignored: + * * a = [:a0, :a1, :a2, :a3] * b = [:b0, :b1, :b2, :b3, :b4] * c = [:c0, :c1, :c2, :c3, :c4, :c5] * d = a.zip(b, c) * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]] * - * When a block is given, calls the block with each of the sub-arrays (formed as above); returns nil + * When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+: + * * a = [:a0, :a1, :a2, :a3] * b = [:b0, :b1, :b2, :b3] * c = [:c0, :c1, :c2, :c3] * a.zip(b, c) {|sub_array| p sub_array} # => nil * * Output: + * * [:a0, :b0, :c0] * [:a1, :b1, :c1] * [:a2, :b2, :c2] * [:a3, :b3, :c3] + * */ static VALUE @@ -4442,8 +4615,10 @@ rb_ary_zip(int argc, VALUE *argv, VALUE ary) * * Transposes the rows and columns in an \Array of Arrays; * the nested Arrays must all be the same size: + * * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]] * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]] + * */ static VALUE @@ -4479,8 +4654,10 @@ rb_ary_transpose(VALUE ary) * array.replace(other_array) -> self * * Replaces the content of +self+ with the content of +other_array+; returns +self+: + * * a = [:foo, 'bar', 2] * a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3] + * */ VALUE @@ -4531,8 +4708,10 @@ rb_ary_replace(VALUE copy, VALUE orig) * array.clear -> self * * Removes all elements from +self+: + * * a = [:foo, 'bar', 2] * a.clear # => [] + * */ VALUE @@ -4570,6 +4749,7 @@ rb_ary_clear(VALUE ary) * Replaces specified elements in +self+ with specified objects; returns +self+. * * With argument +obj+ and no block given, replaces all elements with that one object: + * * a = ['a', 'b', 'c', 'd'] * a # => ["a", "b", "c", "d"] * a.fill(:X) # => [:X, :X, :X, :X] @@ -4579,20 +4759,24 @@ rb_ary_clear(VALUE ary) * * If +start+ is in range (0 <= start < array.size), * 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 (start >= array.size), 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 start + array.size): + * * 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'] @@ -4602,20 +4786,24 @@ rb_ary_clear(VALUE ary) * 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 (start >= array.size), 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"] @@ -4625,14 +4813,17 @@ rb_ary_clear(VALUE ary) * * If the range is positive and ascending (0 < range.begin <= range.end), * replaces elements from range.begin to range.end: + * * a = ['a', 'b', 'c', 'd'] * a.fill(:X, (1..1)) # => ["a", :X, "c", "d"] * * If range.first is negative, replaces no elements: + * * a = ['a', 'b', 'c', 'd'] * a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"] * * If range.last 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'] @@ -4640,6 +4831,7 @@ rb_ary_clear(VALUE ary) * * If range.last and range.last 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'] @@ -4647,29 +4839,34 @@ rb_ary_clear(VALUE ary) * * 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"] * * 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: + * with the block's return value. * * If start is in range (0 <= start < array.size), * 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"] * * If +start+ is too large(start >= array.size), 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 (start <= -array.size, 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'] @@ -4680,20 +4877,24 @@ rb_ary_clear(VALUE ary) * 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 (start >= array.size), 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"] @@ -4704,14 +4905,17 @@ rb_ary_clear(VALUE ary) * * If the range is positive and ascending (range 0 < range.begin <= range.end, * replaces elements from range.begin to range.end: + * * a = ['a', 'b', 'c', 'd'] * a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"] * * 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 range.last 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'] @@ -4719,10 +4923,12 @@ rb_ary_clear(VALUE ary) * * If range.first and range.last 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"] + * */ static VALUE @@ -4795,6 +5001,7 @@ rb_ary_fill(int argc, VALUE *argv, VALUE ary) * * Returns a new \Array containing all elements of +array+ * followed by all elements of +other_array+: + * * a = [0, 1] + [2, 3] * a # => [0, 1, 2, 3] * @@ -4835,6 +5042,7 @@ ary_append(VALUE x, VALUE y) * array.concat(*other_arrays) -> self * * Adds to +array+ all elements from each \Array in +other_arrays+; returns +self+: + * * a = [0, 1] * a.concat([2, 3], [4, 5]) # => [0, 1, 2, 3, 4, 5] */ @@ -4873,12 +5081,15 @@ rb_ary_concat(VALUE x, VALUE y) * * When non-negative argument \Integer +n+ is given, * returns a new \Array built by concatenating the +n+ copies of +self+: + * * a = ['x', 'y'] * a * 3 # => ["x", "y", "x", "y", "x", "y"] * * When \String argument +string_separator+ is given, * equivalent to array.join(string_separator): + * * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}" + * */ static VALUE @@ -4931,6 +5142,7 @@ rb_ary_times(VALUE ary, VALUE times) * * Returns the first element in +self+ that is an \Array * whose first element == +obj+: + * * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]] * a.assoc(4) # => [4, 5, 6] * @@ -4960,6 +5172,7 @@ rb_ary_assoc(VALUE ary, VALUE key) * * Returns the first element in +self+ that is an \Array * whose second element == +obj+: + * * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]] * a.rassoc(4) # => [2, 4] * @@ -5024,6 +5237,7 @@ recursive_equal(VALUE ary1, VALUE ary2, int recur) * * Returns +true+ if both array.size == other_array.size * and for each index +i+ in +array+, array[i] == other_array[i]: + * * a0 = [:foo, 'bar', 2] * a1 = [:foo, 'bar', 2.0] * a1 == a0 # => true @@ -5069,6 +5283,7 @@ recursive_eql(VALUE ary1, VALUE ary2, int recur) * * Returns +true+ if +self+ and +other_array+ are the same size, * and if, for each index +i+ in +self+, self[i].eql? other_array[i]: + * * a0 = [:foo, 'bar', 2] * a1 = [:foo, 'bar', 2] * a1.eql?(a0) # => true @@ -5096,8 +5311,10 @@ rb_ary_eql(VALUE ary1, VALUE ary2) * Returns the integer hash value for +self+. * * Two arrays with the same content will have the same hash code (and will compare using eql?): + * * [0, 1, 2].hash == [0, 1, 2].hash # => true * [0, 1, 2].hash == [0, 1, 3].hash # => false + * */ static VALUE @@ -5123,6 +5340,7 @@ rb_ary_hash(VALUE ary) * * Returns +true+ if for some index +i+ in +self+, obj == self[i]; * otherwise +false+: + * * [0, 1, 2].include?(2) # => true * [0, 1, 2].include?(3) # => false */ @@ -5185,18 +5403,27 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur) * For each index +i+ in +self+, evaluates result = self[i] <=> other_array[i]. * * Returns -1 if any result is -1: + * * [0, 1, 2] <=> [0, 1, 3] # => -1 * * Returns 1 if any result is 1: + * * [0, 1, 2] <=> [0, 1, 1] # => 1 * * When all results are zero: + * * - Returns -1 if +array+ is smaller than +other_array+: + * * [0, 1, 2] <=> [0, 1, 2, 3] # => -1 + * * - Returns 1 if +array+ is larger than +other_array+: + * * [0, 1, 2] <=> [0, 1] # => 1 + * * - Returns 0 if +array+ and +other_array+ are the same size: + * * [0, 1, 2] <=> [0, 1, 2] # => 0 + * */ VALUE @@ -5283,6 +5510,7 @@ ary_recycle_hash(VALUE hash) * that are not found in \Array +other_array+; * items are compared using eql?; * the order from +array+ is preserved: + * * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3] * [0, 1, 2, 3] - [3, 0] # => [1, 2] * [0, 1, 2] - [4] # => [0, 1, 2] @@ -5326,6 +5554,7 @@ rb_ary_diff(VALUE ary1, VALUE ary2) * Returns a new \Array containing only those elements from +self+ * that are not found in any of the Arrays +other_arrays+; * items are compared using eql?; order from +self+ is preserved: + * * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3] * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2] * [0, 1, 2].difference([4]) # => [0, 1, 2] @@ -5378,10 +5607,12 @@ rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary) * * Returns a new \Array containing each element found in both +array+ and \Array +other_array+; * duplicates are omitted; items are compared using eql?: + * * [0, 1, 2, 3] & [1, 2] # => [1, 2] * [0, 1, 0, 1] & [0, 1] # => [0, 1] * * Preserves order from +array+: + * * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2] * * Related: Array#intersection. @@ -5430,10 +5661,12 @@ rb_ary_and(VALUE ary1, VALUE ary2) * Returns a new \Array containing each element found both in +self+ * and in all of the given Arrays +other_arrays+; * duplicates are omitted; items are compared using eql?: + * * [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1] * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1] * * Preserves order from +self+: + * * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2] * * Returns a copy of +self+ if no arguments given. @@ -5492,6 +5725,7 @@ rb_ary_union_hash(VALUE hash, VALUE ary2) * Returns the union of +array+ and \Array +other_array+; * duplicates are removed; order is preserved; * items are compared using eql?: + * * [0, 1] | [2, 3] # => [0, 1, 2, 3] * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3] * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3] @@ -5526,6 +5760,7 @@ rb_ary_or(VALUE ary1, VALUE ary2) * * Returns a new \Array that is the union of +self+ and all given Arrays +other_arrays+; * duplicates are removed; order is preserved; items are compared using eql?: + * * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7] * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3] * [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3] @@ -5570,13 +5805,14 @@ rb_ary_union_multi(int argc, VALUE *argv, VALUE ary) * ary.intersect?(other_ary) -> true or false * * Returns +true+ if the array and +other_ary+ have at least one element in - * common, otherwise returns +false+. + * common, otherwise returns +false+: * * a = [ 1, 2, 3 ] * b = [ 3, 4, 5 ] * c = [ 5, 6, 7 ] * a.intersect?(b) #=> true * a.intersect?(c) #=> false + * */ static VALUE @@ -5717,6 +5953,7 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax) * array.max(n) {|a, b| ... } -> new_array * * Returns one of the following: + * * - The maximum-valued element from +self+. * - A new \Array of maximum-valued elements selected from +self+. * @@ -5725,10 +5962,12 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax) * * With no argument and no block, returns the element in +self+ * having the maximum value per method <=>: + * * [0, 1, 2].max # => 2 * * With an argument \Integer +n+ and no block, returns a new \Array with at most +n+ elements, * in descending order per method <=>: + * * [0, 1, 2, 3].max(3) # => [3, 2, 1] * [0, 1, 2, 3].max(6) # => [3, 2, 1, 0] * @@ -5736,11 +5975,14 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax) * * With a block and no argument, calls the block self.size-1 times to compare elements; * returns the element having the maximum value per the block: + * * ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000" * * With an argument +n+ and a block, returns a new \Array with at most +n+ elements, * in descending order per the block: + * * ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"] + * */ static VALUE rb_ary_max(int argc, VALUE *argv, VALUE ary) @@ -5880,6 +6122,7 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin) * array.min(n) { |a, b| ... } -> new_array * * Returns one of the following: + * * - The minimum-valued element from +self+. * - A new \Array of minimum-valued elements selected from +self+. * @@ -5888,10 +6131,12 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin) * * With no argument and no block, returns the element in +self+ * having the minimum value per method <=>: + * * [0, 1, 2].min # => 0 * * With \Integer argument +n+ and no block, returns a new \Array with at most +n+ elements, * in ascending order per method <=>: + * * [0, 1, 2, 3].min(3) # => [0, 1, 2] * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3] * @@ -5899,11 +6144,14 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin) * * With a block and no argument, calls the block self.size-1 times to compare elements; * returns the element having the minimum value per the block: + * * ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0" * * With an argument +n+ and a block, returns a new \Array with at most +n+ elements, * in ascending order per the block: + * * ['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"] + * */ static VALUE rb_ary_min(int argc, VALUE *argv, VALUE ary) @@ -5958,13 +6206,16 @@ rb_ary_min(int argc, VALUE *argv, VALUE ary) * with an \Integer; * returns a new 2-element \Array containing the minimum and maximum values * from +self+, per method <=>: + * * [0, 1, 2].minmax # => [0, 2] * * When a block is given, the block must return an \Integer; * the block is called self.size-1 times to compare elements; * returns a new 2-element \Array containing the minimum and maximum values * from +self+, per the block: + * * ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"] + * */ static VALUE rb_ary_minmax(VALUE ary) @@ -5994,6 +6245,7 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) * to compare. * * Returns +self+ if any elements removed: + * * a = [0, 0, 1, 1, 2, 2] * a.uniq! # => [0, 1, 2] * @@ -6004,6 +6256,7 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) * elements for which the block returns duplicate values. * * Returns +self+ if any elements removed: + * * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb'] * a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa'] * @@ -6049,15 +6302,18 @@ rb_ary_uniq_bang(VALUE ary) * the first occurrence always being retained. * * With no block given, identifies and omits duplicates using method eql? - * to compare. + * to compare: + * * a = [0, 0, 1, 1, 2, 2] * a.uniq # => [0, 1, 2] * * With a block given, calls the block for each element; * identifies (using method eql?) and omits duplicate values, * that is, those elements for which the block returns the same value: + * * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb'] * a.uniq {|element| element.size } # => ["a", "aa", "aaa"] + * */ static VALUE @@ -6121,6 +6377,7 @@ rb_ary_compact_bang(VALUE ary) * array.compact -> new_array * * Returns a new \Array containing all non-+nil+ elements from +self+: + * * a = [nil, 0, nil, 1, nil, 2, nil] * a.compact # => [0, 1, 2] */ @@ -6142,19 +6399,22 @@ rb_ary_compact(VALUE ary) * Returns a count of specified elements. * * With no argument and no block, returns the count of all elements: + * * [0, 1, 2].count # => 3 * [].count # => 0 * * With argument +obj+, returns the count of elements == to +obj+: + * * [0, 1, 2, 0.0].count(0) # => 2 * [0, 1, 2].count(3) # => 0 * * With no argument and a block given, calls the block with each element; * returns the count of elements for which the block returns a truthy value: + * * [0, 1, 2, 3].count {|element| element > 1} # => 2 * * With argument +obj+ and a block given, issues a warning, ignores the block, - * and returns the count of elements == to +obj+: + * and returns the count of elements == to +obj+. */ static VALUE @@ -6288,6 +6548,7 @@ flatten(VALUE ary, int level) * returns +self+ if any changes, +nil+ otherwise. * * With non-negative \Integer argument +level+, flattens recursively through +level+ levels: + * * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten!(1) # => [0, 1, [2, 3], 4, 5] * a = [ 0, [ 1, [2, 3], 4 ], 5 ] @@ -6297,6 +6558,7 @@ flatten(VALUE ary, int level) * [0, 1, 2].flatten!(1) # => nil * * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels: + * * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten! # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten! # => nil @@ -6305,6 +6567,7 @@ flatten(VALUE ary, int level) * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten!(-1) # => nil + * */ static VALUE @@ -6339,6 +6602,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) * - Each \Array is replaced by its individual elements. * * With non-negative \Integer argument +level+, flattens recursively through +level+ levels: + * * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten(0) # => [0, [1, [2, 3], 4], 5] * a = [ 0, [ 1, [2, 3], 4 ], 5 ] @@ -6349,6 +6613,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) * a.flatten(3) # => [0, 1, 2, 3, 4, 5] * * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels: + * * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten # => [0, 1, 2] @@ -6357,6 +6622,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten(-2) # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten(-1) # => [0, 1, 2] + * */ static VALUE @@ -6572,15 +6838,18 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj) * When called with positive \Integer argument +count+ and a block, * calls the block with each element, then does so again, * until it has done so +count+ times; returns +nil+: + * * output = [] * [0, 1].cycle(2) {|element| output.push(element) } # => nil * output # => [0, 1, 0, 1] * * If +count+ is zero or negative, does not call the block: + * * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil * * When a block is given, and argument is omitted or +nil+, cycles forever: + * * # Prints 0 and 1 forever. * [0, 1].cycle {|element| puts element } * [0, 1].cycle(nil) {|element| puts element } @@ -6590,6 +6859,7 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj) * [0, 1].cycle(2) # => # * [0, 1].cycle # => # => # * [0, 1].cycle.first(5) # => [0, 1, 0, 1, 0] + * */ static VALUE rb_ary_cycle(int argc, VALUE *argv, VALUE ary) @@ -6748,19 +7018,26 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) * are given, calls the block with all +n+-tuple permutations of +self+. * * Example: + * * a = [0, 1, 2] * a.permutation(2) {|permutation| p permutation } + * * Output: + * * [0, 1] * [0, 2] * [1, 0] * [1, 2] * [2, 0] * [2, 1] + * * Another example: + * * a = [0, 1, 2] * a.permutation(3) {|permutation| p permutation } + * * Output: + * * [0, 1, 2] * [0, 2, 1] * [1, 0, 2] @@ -6769,22 +7046,29 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) * [2, 1, 0] * * When +n+ is zero, calls the block once with a new empty \Array: + * * a = [0, 1, 2] * a.permutation(0) {|permutation| p permutation } + * * Output: + * * [] * * When +n+ is out of range (negative or larger than self.size), * does not call the block: + * * a = [0, 1, 2] * a.permutation(-1) {|permutation| fail 'Cannot happen' } * a.permutation(4) {|permutation| fail 'Cannot happen' } * * When a block given but no argument, * behaves the same as a.permutation(a.size): + * * a = [0, 1, 2] * a.permutation {|permutation| p permutation } + * * Output: + * * [0, 1, 2] * [0, 2, 1] * [1, 0, 2] @@ -6793,9 +7077,11 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) * [2, 1, 0] * * Returns a new \Enumerator if no block given: + * * a = [0, 1, 2] * a.permutation # => # * a.permutation(2) # => # + * */ static VALUE @@ -6878,34 +7164,46 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj) * are given, calls the block with all +n+-tuple combinations of +self+. * * Example: + * * a = [0, 1, 2] * a.combination(2) {|combination| p combination } + * * Output: + * * [0, 1] * [0, 2] * [1, 2] * * Another example: + * * a = [0, 1, 2] * a.combination(3) {|combination| p combination } + * * Output: + * * [0, 1, 2] * * When +n+ is zero, calls the block once with a new empty \Array: + * * a = [0, 1, 2] * a1 = a.combination(0) {|combination| p combination } + * * Output: + * * [] * * When +n+ is out of range (negative or larger than self.size), * does not call the block: + * * a = [0, 1, 2] * a.combination(-1) {|combination| fail 'Cannot happen' } * a.combination(4) {|combination| fail 'Cannot happen' } * * Returns a new \Enumerator if no block given: + * * a = [0, 1, 2] * a.combination(2) # => # + * */ static VALUE @@ -7004,16 +7302,22 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj) * The number of permutations is self.size**n. * * +n+ = 1: + * * a = [0, 1, 2] * a.repeated_permutation(1) {|permutation| p permutation } + * * Output: + * * [0] * [1] * [2] * * +n+ = 2: + * * a.repeated_permutation(2) {|permutation| p permutation } + * * Output: + * * [0, 0] * [0, 1] * [0, 2] @@ -7027,14 +7331,17 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj) * If +n+ is zero, calls the block once with an empty \Array. * * If +n+ is negative, does not call the block: + * * a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' } * * Returns a new \Enumerator if no block given: + * * a = [0, 1, 2] * a.repeated_permutation(2) # => # * * Using Enumerators, it's convenient to show the permutations and counts * for some values of +n+: + * * e = a.repeated_permutation(0) * e.size # => 1 * e.to_a # => [[]] @@ -7044,6 +7351,7 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj) * e = a.repeated_permutation(2) * e.size # => 9 * e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]] + * */ static VALUE rb_ary_repeated_permutation(VALUE ary, VALUE num) @@ -7126,16 +7434,22 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj) * The number of combinations is (n+1)(n+2)/2. * * +n+ = 1: + * * a = [0, 1, 2] * a.repeated_combination(1) {|combination| p combination } + * * Output: + * * [0] * [1] * [2] * * +n+ = 2: + * * a.repeated_combination(2) {|combination| p combination } + * * Output: + * * [0, 0] * [0, 1] * [0, 2] @@ -7146,14 +7460,17 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj) * If +n+ is zero, calls the block once with an empty \Array. * * If +n+ is negative, does not call the block: + * * a.repeated_combination(-1) {|combination| fail 'Cannot happen' } * * Returns a new \Enumerator if no block given: + * * a = [0, 1, 2] * a.repeated_combination(2) # => # * * Using Enumerators, it's convenient to show the combinations and counts * for some values of +n+: + * * e = a.repeated_combination(0) * e.size # => 1 * e.to_a # => [[]] @@ -7163,6 +7480,7 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj) * e = a.repeated_combination(2) * e.size # => 6 * e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]] + * */ static VALUE @@ -7206,12 +7524,14 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) * array.product(*other_arrays) {|combination| ... } -> self * * Computes and returns or yields all combinations of elements from all the Arrays, - * including both +self+ and +other_arrays+. + * including both +self+ and +other_arrays+: + * * - The number of combinations is the product of the sizes of all the arrays, * including both +self+ and +other_arrays+. * - The order of the returned combinations is indeterminate. * * When no block is given, returns the combinations as an \Array of Arrays: + * * a = [0, 1, 2] * a1 = [3, 4] * a2 = [5, 6] @@ -7226,11 +7546,15 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) * * If no argument is given, returns an \Array of 1-element Arrays, * each containing an element of +self+: + * * a.product # => [[0], [1], [2]] * * When a block is given, yields each combination as an \Array; returns +self+: + * * a.product(a1) {|combination| p combination } + * * Output: + * * [0, 3] * [0, 4] * [1, 3] @@ -7239,14 +7563,19 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) * [2, 4] * * If any argument is an empty \Array, does not call the block: + * * a.product(a1, a2, []) {|combination| fail 'Cannot happen' } * * If no argument is given, yields each element of +self+ as a 1-element \Array: + * * a.product {|combination| p combination } + * * Output: + * * [0] * [1] * [2] + * */ static VALUE @@ -7346,11 +7675,13 @@ done: * does not modify +self+. * * Examples: + * * a = [0, 1, 2, 3, 4, 5] * a.take(1) # => [0] * a.take(2) # => [0, 1] * a.take(50) # => [0, 1, 2, 3, 4, 5] * a # => [0, 1, 2, 3, 4, 5] + * */ static VALUE @@ -7374,13 +7705,16 @@ rb_ary_take(VALUE obj, VALUE n) * With a block given, calls the block with each successive element of +self+; * stops if the block returns +false+ or +nil+; * returns a new \Array containing those elements for which the block returned a truthy value: + * * a = [0, 1, 2, 3, 4, 5] * a.take_while {|element| element < 3 } # => [0, 1, 2] * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5] * a # => [0, 1, 2, 3, 4, 5] * * With no block given, returns a new \Enumerator: + * * [0, 1].take_while # => # + * */ static VALUE @@ -7404,10 +7738,12 @@ rb_ary_take_while(VALUE ary) * does not modify +self+. * * Examples: + * * a = [0, 1, 2, 3, 4, 5] * a.drop(0) # => [0, 1, 2, 3, 4, 5] * a.drop(1) # => [1, 2, 3, 4, 5] * a.drop(2) # => [2, 3, 4, 5] + * */ static VALUE @@ -7435,11 +7771,14 @@ rb_ary_drop(VALUE ary, VALUE n) * With a block given, calls the block with each successive element of +self+; * stops if the block returns +false+ or +nil+; * returns a new \Array _omitting_ those elements for which the block returned a truthy value: + * * a = [0, 1, 2, 3, 4, 5] * a.drop_while {|element| element < 3 } # => [3, 4, 5] * * With no block given, returns a new \Enumerator: + * * [0, 1].drop_while # => # => # + * */ static VALUE @@ -7464,17 +7803,20 @@ rb_ary_drop_while(VALUE ary) * * With no block given and no argument, returns +true+ if +self+ has any truthy element, * +false+ otherwise: + * * [nil, 0, false].any? # => true * [nil, false].any? # => false * [].any? # => false * * With a block given and no argument, calls the block with each element in +self+; * returns +true+ if the block returns any truthy value, +false+ otherwise: + * * [0, 1, 2].any? {|element| element > 1 } # => true * [0, 1, 2].any? {|element| element > 2 } # => false * * If argument +obj+ is given, returns +true+ if +obj+.=== any element, * +false+ otherwise: + * * ['food', 'drink'].any?(/foo/) # => true * ['food', 'drink'].any?(/bar/) # => false * [].any?(/foo/) # => false @@ -7522,16 +7864,19 @@ rb_ary_any_p(int argc, VALUE *argv, VALUE ary) * * With no block given and no argument, returns +true+ if +self+ contains only truthy elements, * +false+ otherwise: + * * [0, 1, :foo].all? # => true * [0, nil, 2].all? # => false * [].all? # => true * * With a block given and no argument, calls the block with each element in +self+; * returns +true+ if the block returns only truthy values, +false+ otherwise: + * * [0, 1, 2].all? { |element| element < 3 } # => true * [0, 1, 2].all? { |element| element < 2 } # => false * * If argument +obj+ is given, returns +true+ if obj.=== every element, +false+ otherwise: + * * ['food', 'fool', 'foot'].all?(/foo/) # => true * ['food', 'drink'].all?(/bar/) # => false * [].all?(/foo/) # => true @@ -7579,16 +7924,19 @@ rb_ary_all_p(int argc, VALUE *argv, VALUE ary) * * With no block given and no argument, returns +true+ if +self+ has no truthy elements, * +false+ otherwise: + * * [nil, false].none? # => true * [nil, 0, false].none? # => false * [].none? # => true * * With a block given and no argument, calls the block with each element in +self+; * returns +true+ if the block returns no truthy value, +false+ otherwise: + * * [0, 1, 2].none? {|element| element > 3 } # => true * [0, 1, 2].none? {|element| element > 1 } # => false * * If argument +obj+ is given, returns +true+ if obj.=== no element, +false+ otherwise: + * * ['food', 'drink'].none?(/bar/) # => true * ['food', 'drink'].none?(/foo/) # => false * [].none?(/foo/) # => true @@ -7636,6 +7984,7 @@ rb_ary_none_p(int argc, VALUE *argv, VALUE ary) * * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element, * +false+ otherwise: + * * [nil, 0].one? # => true * [0, 0].one? # => false * [nil, nil].one? # => false @@ -7643,12 +7992,14 @@ rb_ary_none_p(int argc, VALUE *argv, VALUE ary) * * With a block given and no argument, calls the block with each element in +self+; * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise: + * * [0, 1, 2].one? {|element| element > 0 } # => false * [0, 1, 2].one? {|element| element > 1 } # => true * [0, 1, 2].one? {|element| element > 2 } # => false * * If argument +obj+ is given, returns +true+ if obj.=== exactly one element, * +false+ otherwise: + * * [0, 1, 2].one?(0) # => true * [0, 0, 1].one?(0) # => false * [1, 1, 2].one?(0) # => false @@ -7707,11 +8058,13 @@ rb_ary_one_p(int argc, VALUE *argv, VALUE ary) * See {Dig Methods}[rdoc-ref:dig_methods.rdoc]. * * Examples: + * * a = [:foo, [:bar, :baz, [:bat, :bam]]] * a.dig(1) # => [:bar, :baz, [:bat, :bam]] * a.dig(1, 2) # => [:bat, :bam] * a.dig(1, 2, 0) # => :bat * a.dig(1, 2, 3) # => nil + * */ static VALUE @@ -7744,31 +8097,38 @@ finish_exact_sum(long n, VALUE r, VALUE v, int z) * array.sum(init = 0) {|element| ... } -> object * * When no block is given, returns the object equivalent to: + * * sum = init * array.each {|element| sum += element } * sum + * * For example, [e1, e2, e3].sum returns init + e1 + e2 + e3. * * Examples: + * * a = [0, 1, 2, 3] * a.sum # => 6 * a.sum(100) # => 106 * * The elements need not be numeric, but must be +-compatible * with each other and with +init+: + * * a = ['abc', 'def', 'ghi'] * a.sum('jkl') # => "jklabcdefghi" * * When a block is given, it is called with each element * and the block's return value (instead of the element itself) is used as the addend: + * * a = ['zero', 1, :two] * s = a.sum('Coerced and concatenated: ') {|element| element.to_s } * s # => "Coerced and concatenated: zero1two" * * Notes: + * * - Array#join and Array#flatten may be faster than Array#sum * for an \Array of Strings or an \Array of Arrays. * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+. + * */ static VALUE -- cgit v1.2.3