summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2020-07-29 17:25:24 -0500
committerGitHub <noreply@github.com>2020-07-29 18:25:24 -0400
commit35e5b8fb82ffd09ea34af88834588aa078ee9db3 (patch)
tree3ca0f31622baad1d708d236c07dd322ffa8230eb
parent28cd254b498e34b3fb205cfb116bff3f946d2fdc (diff)
Enhanced RDoc for Array (#3372)
Notes
Notes: Merged-By: marcandre <github@marc-andre.ca>
-rw-r--r--array.c222
1 files changed, 142 insertions, 80 deletions
diff --git a/array.c b/array.c
index 8c14d5b..345ee32 100644
--- a/array.c
+++ b/array.c
@@ -6706,31 +6706,41 @@ push_value(st_data_t key, st_data_t val, st_data_t ary)
/*
* call-seq:
- * ary.uniq! -> ary or nil
- * ary.uniq! {|item| ...} -> ary or nil
+ * array.uniq! -> self or nil
+ * array.uniq! {|element| ... } -> self or nil
*
- * Removes duplicate elements from +self+.
+ * Removes duplicate elements from +self+, the first occurrence always being retained;
+ * returns +self+ if any elements removed, +nil+ otherwise.
*
- * If a block is given, it will use the return value of the block for
- * comparison.
+ * ---
*
- * It compares values using their #hash and #eql? methods for efficiency.
+ * With no block given, identifies and removes elements using method <tt>eql?</tt>
+ * to compare.
*
- * +self+ is traversed in order, and the first occurrence is kept.
+ * Returns +self+ if any elements removed:
+ * a = [0, 0, 1, 1, 2, 2]
+ * a1 = a.uniq!
+ * a1 # => [0, 1, 2]
+ * a1.equal?(a) # => true # Returned self
*
- * Returns +nil+ if no changes are made (that is, no duplicates are found).
+ * Returns +nil+ if no elements removed:
+ * [0, 1, 2].uniq! # => nil
*
- * a = [ "a", "a", "b", "b", "c" ]
- * a.uniq! # => ["a", "b", "c"]
+ * ---
*
- * b = [ "a", "b", "c" ]
- * b.uniq! # => nil
+ * With a block given, calls the block for each element;
+ * identifies (using method <tt>eql?</tt>) and removes
+ * elements for which the block returns duplicate values.
*
- * c = [["student","sam"], ["student","george"], ["teacher","matz"]]
- * c.uniq! {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]]
+ * Returns +self+ if any elements removed:
+ * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
+ * a1 = a.uniq! {|element| element.size }
+ * a1 # => ['a', 'aa', 'aaa']
+ * a1.equal?(a) # => true # Returned self
*
+ * Returns +nil+ if no elements removed:
+ * a.uniq! {|element| element.size } # => nil
*/
-
static VALUE
rb_ary_uniq_bang(VALUE ary)
{
@@ -6764,23 +6774,22 @@ rb_ary_uniq_bang(VALUE ary)
/*
* call-seq:
- * ary.uniq -> new_ary
- * ary.uniq {|item| ...} -> new_ary
- *
- * Returns a new array by removing duplicate values in +self+.
- *
- * If a block is given, it will use the return value of the block for comparison.
- *
- * It compares values using their #hash and #eql? methods for efficiency.
- *
- * +self+ is traversed in order, and the first occurrence is kept.
- *
- * a = [ "a", "a", "b", "b", "c" ]
- * a.uniq # => ["a", "b", "c"]
- *
- * b = [["student","sam"], ["student","george"], ["teacher","matz"]]
- * b.uniq {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]]
- *
+ * array.uniq -> new_array
+ * array.uniq {|element| ... } -> new_array
+ *
+ * Returns a new \Array containing those elements from +self+ that are not duplicates,
+ * the first occurrence always being retained.
+ *
+ * With no block given, identifies and omits duplicates using method <tt>eql?</tt>
+ * 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 <tt>eql?</tt>) 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
@@ -6810,14 +6819,17 @@ rb_ary_uniq(VALUE ary)
/*
* call-seq:
- * ary.compact! -> ary or nil
+ * array.compact! -> self or nil
*
- * Removes +nil+ elements from the array.
+ * Removes all +nil+ elements from +self+.
*
- * Returns +nil+ if no changes were made, otherwise returns the array.
+ * Returns +self+ if any elements removed:
+ * a = [nil, 0, nil, 1, nil, 2, nil]
+ * a1 = a.compact! # => [0, 1, 2]
+ * a1.equal?(a) # => true # Returned self
*
- * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
- * [ "a", "b", "c" ].compact! #=> nil
+ * Returns +nil+ if no elements removed:
+ * [0, 1, 2].compact! # => nil
*/
static VALUE
@@ -6845,12 +6857,11 @@ rb_ary_compact_bang(VALUE ary)
/*
* call-seq:
- * ary.compact -> new_ary
- *
- * Returns a copy of +self+ with all +nil+ elements removed.
+ * array.compact -> new_array
*
- * [ "a", nil, "b", nil, "c", nil ].compact
- * #=> [ "a", "b", "c" ]
+ * Returns a new \Array containing all non-+nil+ elements from +self+:
+ * a = [nil, 0, nil, 1, nil, 2, nil]
+ * a.compact # => [0, 1, 2]
*/
static VALUE
@@ -6863,23 +6874,26 @@ rb_ary_compact(VALUE ary)
/*
* call-seq:
- * ary.count -> int
- * ary.count(obj) -> int
- * ary.count {|item| block} -> int
+ * array.count -> an_integer
+ * array.count(obj) -> an_integer
+ * array.count {|element| ... } -> an_integer
*
- * Returns the number of elements.
+ * Returns a count of specified elements.
*
- * If an argument is given, counts the number of elements which equal +obj+
- * using <code>==</code>.
+ * With no argument and no block, returns the count of all elements:
+ * [0, 1, 2].count # => 3
+ * [].count # => 0
*
- * If a block is given, counts the number of elements for which the block
- * returns a true value.
+ * With argument +obj+, returns the count of elements <tt>eql?</tt> to +obj+:
+ * [0, 1, 2, 0].count(0) # => 2
+ * [0, 1, 2].count(3) # => 0
*
- * ary = [1, 2, 4, 2]
- * ary.count #=> 4
- * ary.count(2) #=> 2
- * ary.count {|x| x%2 == 0} #=> 3
+ * 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 <tt>eql?</tt> to +obj+:
*/
static VALUE
@@ -6998,22 +7012,47 @@ flatten(VALUE ary, int level)
/*
* call-seq:
- * ary.flatten! -> ary or nil
- * ary.flatten!(level) -> ary or nil
+ * array.flatten! -> self or nil
+ * array.flatten!(level) -> self or nil
*
- * Flattens +self+ in place.
+ * Replaces each nested \Array in +self+ with the elements from that \Array;
+ * returns +self+ if any changes, +nil+ otherwise.
+ *
+ * Argument +level+, if given, must be an
+ * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
+ *
+ * With non-negative argument +level+, flattens recursively through +level+ levels:
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a1 = a.flatten!(1)
+ * a1 # => [0, 1, [2, 3], 4, 5]
+ * a1.equal?(a) # => true # Returned self
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
+ * [0, 1, 2].flatten!(1) # => nil
+ *
+ * With no 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
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
+ * [0, 1, 2].flatten!(-1) # => nil
*
- * Returns +nil+ if no modifications were made (i.e., the array contains no
- * subarrays.)
+ * ---
*
- * The optional +level+ argument determines the level of recursion to flatten.
+ * Raises an exception if +level+ is not an Integer-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Integer):
+ * [].flatten!(:foo)
*
- * a = [ 1, 2, [3, [4, 5] ] ]
- * a.flatten! #=> [1, 2, 3, 4, 5]
- * a.flatten! #=> nil
- * a #=> [1, 2, 3, 4, 5]
- * a = [ 1, 2, [3, [4, 5] ] ]
- * a.flatten!(1) #=> [1, 2, 3, [4, 5]]
+ * Raises an exception if +self+ contains a circular reference:
+ * a = []
+ * a.push([a, a])
+ * # Raises ArgumentError (tried to flatten recursive array):
+ * a.flatten!
*/
static VALUE
@@ -7040,24 +7079,47 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
/*
* call-seq:
- * ary.flatten -> new_ary
- * ary.flatten(level) -> new_ary
+ * array.flatten -> new_array
+ * array.flatten(level) -> new_array
+ *
+ * Returns a new \Array that is a recursive flattening of +self+:
+ * - Each non-Array element is unchanged.
+ * - Each \Array is replaced by its individual elements.
+ *
+ * Argument +level+, if given, must be
+ * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
*
- * Returns a new array that is a one-dimensional flattening of +self+
- * (recursively).
+ * With non-negative 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 ]
+ * a.flatten(1) # => [0, 1, [2, 3], 4, 5]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten(2) # => [0, 1, 2, 3, 4, 5]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten(3) # => [0, 1, 2, 3, 4, 5]
+ *
+ * With no 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]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
+ * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ * a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
+ * [0, 1, 2].flatten(-1) # => [0, 1, 2]
*
- * That is, for every element that is an array, extract its elements into
- * the new array.
+ * ---
*
- * The optional +level+ argument determines the level of recursion to
- * flatten.
+ * Raises an exception if +level+ is not an Integer-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Integer):
+ * [].flatten(:foo)
*
- * s = [ 1, 2, 3 ] #=> [1, 2, 3]
- * t = [ 4, 5, 6, [7, 8] ] #=> [4, 5, 6, [7, 8]]
- * a = [ s, t, 9, 10 ] #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
- * a.flatten #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
- * a = [ 1, 2, [3, [4, 5] ] ]
- * a.flatten(1) #=> [1, 2, 3, [4, 5]]
+ * Raises an exception if +self+ contains a circular reference:
+ * a = []
+ * a.push([a, a])
+ * # Raises ArgumentError (tried to flatten recursive array):
+ * a.flatten
*/
static VALUE