summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdetteLamar <burdettelamar@yahoo.com>2020-07-23 15:06:14 -0500
committerJeremy Evans <code@jeremyevans.net>2020-07-28 12:01:46 -0700
commite1b6e1d12607ee25a11feb7fcbe81ca1bc4b8cad (patch)
tree5d0f83143664f97ffc88c9d3336ec11346cbb372
parent946cd6c5348d7dd12ecc41e79c3ca9803d2ca7f0 (diff)
Enhanced RDoc for Array [ci skip]
-rw-r--r--array.c336
1 files changed, 240 insertions, 96 deletions
diff --git a/array.c b/array.c
index ed1850356b..8c14d5b7ce 100644
--- a/array.c
+++ b/array.c
@@ -5412,7 +5412,7 @@ ary_append(VALUE x, VALUE y)
*
* Returns +self+ unmodified if no arguments given:
* a = [0, 1]
- * a.concat
+ * a.concat(*[])
* a # => [0, 1]
*
* ---
@@ -5920,23 +5920,24 @@ ary_recycle_hash(VALUE hash)
/*
* call-seq:
- * ary - other_ary -> new_ary
+ * array - other_array -> new_array
*
- * Array Difference
- *
- * Returns a new array that is a copy of the original array, removing all
- * occurrences of any item that also appear in +other_ary+. The order is
- * preserved from the original array.
- *
- * It compares elements using their #hash and #eql? methods for efficiency.
+ * Argument +other_array+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
*
- * [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ]
+ * Returns a new \Array containing only those elements from +array+
+ * that are not found in +other_array+;
+ * items are compared using <tt>eql?</tt>;
+ * 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]
*
- * Note that while 1 and 2 were only present once in the array argument, and
- * were present twice in the receiver array, all occurrences of each Integer are
- * removed in the returned array.
+ * ---
*
- * If you need set-like behavior, see the library class Set.
+ * Raises an exception if +other_array+ is not an Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [] - :foo
*
* See also Array#difference.
*/
@@ -5971,29 +5972,29 @@ rb_ary_diff(VALUE ary1, VALUE ary2)
/*
* call-seq:
- * ary.difference(other_ary1, other_ary2, ...) -> new_ary
- *
- * Array Difference
- *
- * Returns a new array that is a copy of the original array, removing all
- * occurrences of any item that also appear in +other_ary+. The order is
- * preserved from the original array.
+ * array.difference(*other_arrays) -> new_array
*
- * It compares elements using their #hash and #eql? methods for efficiency.
- *
- * [ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ]) #=> [ 3, 3, 5 ]
+ * Each argument in +other_arrays+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
*
- * Note that while 1 and 2 were only present once in the array argument, and
- * were present twice in the receiver array, all occurrences of each Integer are
- * removed in the returned array.
+ * Returns a new \Array containing only those elements from +self+
+ * that are not found in any of the +other_arrays+;
+ * items are compared using <tt>eql?</tt>; 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]
*
- * Multiple array arguments can be supplied and all occurrences of any element
- * in those supplied arrays that match the receiver will be removed from the
- * returned array.
+ * Returns a copy of +self+ if no arguments given:
+ * a0 = [0, 1]
+ * a1 = a0.difference(*[])
+ * a1 # => [0, 1]
+ * a1.equal?(a0) # => false
*
- * [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ]) #=> [ :s, "yep" ]
+ * ---
*
- * If you need set-like behavior, see the library class Set.
+ * Raises an exception if any of +other_arrays+ is not an Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [].difference(:foo)
*
* See also Array#-.
*/
@@ -6037,17 +6038,26 @@ rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary)
/*
* call-seq:
- * ary & other_ary -> new_ary
+ * array & other_array -> new_array
+ *
+ * Argument +other_array+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
*
- * Set Intersection --- Returns a new array containing unique elements common to the
- * two arrays. The order is preserved from the original array.
+ * Returns a new \Array containing each element found in both +array+ and +other_array+;
+ * duplicates are omitted; items are compared using <tt>eql?</tt>:
+ * [0, 1, 2, 3] & [1, 2] # => [1, 2]
+ * [0, 1, 0, 1] & [0, 1] # => [0, 1]
*
- * It compares elements using their #hash and #eql? methods for efficiency.
+ * Preserves order from +array+:
+ * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
*
- * [ 1, 1, 3, 5 ] & [ 3, 2, 1 ] #=> [ 1, 3 ]
- * [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ] #=> [ 'a', 'b' ]
+ * ---
*
- * See also Array#uniq.
+ * Raises an exception if +other_array+ is not an Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [] & :foo
+ *
+ * See also Array#intersection.
*/
@@ -6088,17 +6098,31 @@ rb_ary_and(VALUE ary1, VALUE ary2)
/*
* call-seq:
- * ary.intersection(other_ary1, other_ary2, ...) -> new_ary
+ * array.intersection(*other_arrays) -> new_array
*
- * Set Intersection --- Returns a new array containing unique elements common
- * to +self+ and <code>other_ary</code>s. Order is preserved from the original
- * array.
+ * Each object in +other_arrays+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
+ *
+ * Returns a new \Array containing each element found both in +self+
+ * and in all of the given +other_arrays+;
+ * duplicates are omitted; items are compared using <tt>eql?</tt>:
+ * [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]
*
- * It compares elements using their #hash and #eql? methods for efficiency.
+ * Returns a copy of +self+ if no arguments given:
+ * a0 = [0, 1]
+ * a1 = a0.intersection(*[])
+ * a1 # => [0, 1]
+ * a1.equal?(a0) # => false
+ *
+ * ---
*
- * [ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ]) # => [ 1, 3 ]
- * [ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ]) # => [ "b" ]
- * [ "a" ].intersection #=> [ "a" ]
+ * Raises an exception if any of the given +other_arrays+ is not an Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [].intersection([0, 1], :foo)
*
* See also Array#&.
*/
@@ -6149,15 +6173,23 @@ rb_ary_union_hash(VALUE hash, VALUE ary2)
/*
* call-seq:
- * ary | other_ary -> new_ary
+ * array | other_array -> new_array
*
- * Set Union --- Returns a new array by joining +ary+ with +other_ary+,
- * excluding any duplicates and preserving the order from the given arrays.
+ * Argument +other_array+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
*
- * It compares elements using their #hash and #eql? methods for efficiency.
+ * Returns the union of +array+ and +other_array+;
+ * duplicates are removed; order is preserved;
+ * items are compared using <tt>eql?</tt>:
+ * [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]
+ *
+ * ---
*
- * [ "a", "b", "c" ] | [ "c", "d", "a" ] #=> [ "a", "b", "c", "d" ]
- * [ "c", "d", "a" ] | [ "a", "b", "c" ] #=> [ "c", "d", "a", "b" ]
+ * Raises an exception if +other_array+ is not an Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [] | :foo
*
* See also Array#union.
*/
@@ -6185,16 +6217,28 @@ rb_ary_or(VALUE ary1, VALUE ary2)
/*
* call-seq:
- * ary.union(other_ary1, other_ary2, ...) -> new_ary
+ * array.union(*other_arrays) -> new_array
+ *
+ * Each object in +other_arrays+ must be an
+ * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects].
*
- * Set Union --- Returns a new array by joining <code>other_ary</code>s with +self+,
- * excluding any duplicates and preserving the order from the given arrays.
+ * Returns a new \Array that is the union of +self+ and all given +other_arrays+;
+ * duplicates are removed; order is preserved; items are compared using <tt>eql?</tt>:
+ * [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]
*
- * It compares elements using their #hash and #eql? methods for efficiency.
+ * Returns a copy of +self+ if no arguments given:
+ * a0 = [0, 1]
+ * a1 = a0.union(*[])
+ * a1 # => [0, 1]
+ * a1.equal?(a0) # => false
*
- * [ "a", "b", "c" ].union( [ "c", "d", "a" ] ) #=> [ "a", "b", "c", "d" ]
- * [ "a" ].union( ["e", "b"], ["a", "c", "b"] ) #=> [ "a", "e", "b", "c" ]
- * [ "a" ].union #=> [ "a" ]
+ * ---
+ *
+ * Raises an exception if any argument is not an \Array-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Array):
+ * [].union([], :foo)
*
* See also Array#|.
*/
@@ -6320,25 +6364,64 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax)
/*
* call-seq:
- * ary.max -> obj
- * ary.max {|a, b| block} -> obj
- * ary.max(n) -> array
- * ary.max(n) {|a, b| block} -> array
+ * array.max -> element
+ * array.max {|a, b| ... } -> element
+ * array.max(n) -> new_array
+ * array.max(n) {|a, b| ... } -> new_array
*
- * Returns the object in _ary_ with the maximum value. The
- * first form assumes all objects implement <code><=></code>;
- * the second uses the block to return <em>a <=> b</em>.
+ * Returns one of the following:
+ * - The maximum-valued element from +self+.
+ * - A new \Array of maximum-valued elements selected from +self+.
*
- * ary = %w(albatross dog horse)
- * ary.max #=> "horse"
- * ary.max {|a, b| a.length <=> b.length} #=> "albatross"
+ * Argument +n+, if given, must be an
+ * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects],
+ * and must be non-negative.
*
- * If the +n+ argument is given, maximum +n+ elements are returned
- * as an array.
+ * ---
*
- * ary = %w[albatross dog horse]
- * ary.max(2) #=> ["horse", "dog"]
- * ary.max(2) {|a, b| a.length <=> b.length } #=> ["albatross", "horse"]
+ * When no block is given, each element in +self+ must respond to method <tt><=></tt>
+ * with an \Integer-convertible object.
+ *
+ * With no argument and no block, returns the element in +self+
+ * having the maximum value per method <tt><=></tt>:
+ * [0, 1, 2].max # => 2
+ *
+ * With an argument +n+ and no block, returns a new \Array with at most +n+ elements,
+ * in descending order per method <tt><=></tt>:
+ * [0, 1, 2, 3].max(3) # => [3, 2, 1]
+ * [0, 1, 2, 3].max(6) # => [3, 2, 1]
+ * [0, 1, 2, 3].max(0) # => []
+ *
+ * ---
+ *
+ * When a block is given, the block must return an Integer-convertible object.
+ *
+ * With a block and no argument, calls the block <tt>self.size-1</tt> 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"]
+ * ['0', '00', '000'].max(0) {|a, b| a.size <=> b.size } # => []
+ *
+ * ---
+ *
+ * Raises an exception on encountering elements that are not comparable:
+ * # Raises ArgumentError (comparison of Symbol with 1 failed):
+ * [0, 1, :foo].max
+ *
+ * Raises an exception if argument +n+ is not an Integer-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Integer):
+ * [0, 1].max(:foo)
+ *
+ * Raises an exception if argument +n+ is negative:
+ * # Raises ArgumentError (negative size (-1)):
+ * [0, 1].max(-1)
+ *
+ * Raises an exception if the block returns an object that is not an Integer-convertible object:
+ * # Raises ArgumentError (comparison of Symbol with 0 failed):
+ * [0, 1, 2].max {|a, b| :foo }
*/
static VALUE
rb_ary_max(int argc, VALUE *argv, VALUE ary)
@@ -6472,25 +6555,65 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin)
/*
* call-seq:
- * ary.min -> obj
- * ary.min {| a,b | block } -> obj
- * ary.min(n) -> array
- * ary.min(n) {| a,b | block } -> array
+ * array.min -> element
+ * array.min { |a, b| ... } -> element
+ * array.min(n) -> new_array
+ * ary.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+.
+ *
+ * Argument +n+, if given, must be an
+ * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects],
+ * and must be non-negative.
+ *
+ * ---
*
- * Returns the object in _ary_ with the minimum value. The
- * first form assumes all objects implement <code><=></code>;
- * the second uses the block to return <em>a <=> b</em>.
+ * When no block is given, each element in +self+ must respond to method <tt><=></tt>
+ * with an \Integer-convertible object.
*
- * ary = %w(albatross dog horse)
- * ary.min #=> "albatross"
- * ary.min {|a, b| a.length <=> b.length} #=> "dog"
+ * With no argument and no block, returns the element in +self+
+ * having the minimum value per method <tt><=></tt>:
+ * [0, 1, 2].min # => 0
*
- * If the +n+ argument is given, minimum +n+ elements are returned
- * as an array.
+ * With an argument +n+ and no block, returns a new \Array with at most +n+ elements,
+ * in ascending order per method <tt><=></tt>:
+ * [0, 1, 2, 3].min(3) # => [0, 1, 2]
+ * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
+ * [0, 1, 2, 3].min(0) # => []
*
- * ary = %w[albatross dog horse]
- * ary.min(2) #=> ["albatross", "dog"]
- * ary.min(2) {|a, b| a.length <=> b.length } #=> ["dog", "horse"]
+ * ---
+ *
+ * When a block is given, the block must return an Integer-convertible object.
+ *
+ * With a block and no argument, calls the block <tt>self.size-1</tt> 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, 1, 2, 3].min(3) # => [0, 1, 2]
+ * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
+ * [0, 1, 2, 3].min(0) # => []
+ *
+ * ---
+ *
+ * Raises an exception on encountering elements that are not comparable:
+ * # Raises ArgumentError (comparison of Symbol with 1 failed):
+ * [0, 1, :foo].min
+ *
+ * Raises an exception if argument +n+ is not an Integer-convertible object:
+ * # Raises TypeError (no implicit conversion of Symbol into Integer):
+ * [0, 1].min(:foo)
+ *
+ * Raises an exception if argument +n+ is negative:
+ * # Raises ArgumentError (negative size (-1)):
+ * [0, 1].min(-1)
+ *
+ * Raises an exception if the block returns an object that is not an Integer-convertible object:
+ * # Raises ArgumentError (comparison of Symbol with 0 failed):
+ * [0, 1, 2].min {|a, b| :foo }
*/
static VALUE
rb_ary_min(int argc, VALUE *argv, VALUE ary)
@@ -6535,14 +6658,35 @@ rb_ary_min(int argc, VALUE *argv, VALUE ary)
/*
* call-seq:
- * ary.minmax -> [obj, obj]
- * ary.minmax {| a,b | block } -> [obj, obj]
+ * array.minmax -> [min_val, max_val]
+ * array.minmax {|a, b| ... } -> [min_val, max_val]
+ *
+ * Returns a new 2-element \Array containing the minimum and maximum values
+ * from +self+, either per method <tt><=></tt> or per a given block:.
+ *
+ * ---
*
- * Returns a two element array which contains the minimum and the
- * maximum value in the array.
+ * When no block is given, each element in +self+ must respond to method <tt><=></tt>
+ * with an \Integer-convertible object;
+ * returns a new 2-element \Array containing the minimum and maximum values
+ * from +self+, per method <tt><=></tt>:
+ * [0, 1, 2].minmax # => [0, 2]
*
- * Can be given an optional block to override the default comparison
- * method <code>a <=> b</code>.
+ * When a block is given, the block must return an Integer-convertible object;
+ * the block is called <tt>self.size-1</tt> 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"]
+ *
+ * ---
+ *
+ * Raises an exception on encountering elements that are not comparable:
+ * # Raises ArgumentError (comparison of Symbol with 1 failed):
+ * [0, 1, :foo].minmax
+ *
+ * Raises an exception if the block returns an object that is not an Integer-convertible object:
+ * # Raises ArgumentError (comparison of Symbol with 0 failed):
+ * [0, 1, 2].minmax {|a, b| :foo }
*/
static VALUE
rb_ary_minmax(VALUE ary)