diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2021-09-28 11:38:35 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-09-28 11:38:35 -0500 |
commit | 1e10099e0919eda9464ef454b4920213eca658f3 (patch) | |
tree | 68a9eac321a6ad8441223c6714a83bb4cba0d66b /enum.c | |
parent | 545e01645f7350c255f79b90f184a1317d3d55fb (diff) |
Enhanced RDoc for Enumerable (#4906)
Treats:
#partition
#group_by
#tally
#first
#sort
#sort_by
#all?
#any?
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'enum.c')
-rw-r--r-- | enum.c | 264 |
1 files changed, 176 insertions, 88 deletions
@@ -1066,16 +1066,29 @@ partition_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, arys)) /* * call-seq: - * enum.partition { |obj| block } -> [ true_array, false_array ] - * enum.partition -> an_enumerator + * partition {|element| ... } -> [true_array, false_array] + * partition -> enumerator * - * Returns two arrays, the first containing the elements of - * <i>enum</i> for which the block evaluates to true, the second - * containing the rest. + * With a block given, returns an array of two arrays: * - * If no block is given, an enumerator is returned instead. + * - The first having those elements for which the block returns a truthy value. + * - The other having all other elements. + * + * Examples: + * + * p = (1..4).partition {|i| i.even? } + * p # => [[2, 4], [1, 3]] + * p = ('a'..'d').partition {|c| c < 'c' } + * p # => [["a", "b"], ["c", "d"]] + * h = {foo: 0, bar: 1, baz: 2, bat: 3} + * p = h.partition {|key, value| key.start_with?('b') } + * p # => [[[:bar, 1], [:baz, 2], [:bat, 3]], [[:foo, 0]]] + * p = h.partition {|key, value| value < 2 } + * p # => [[[:foo, 0], [:bar, 1]], [[:baz, 2], [:bat, 3]]] + * + * With no block given, returns an Enumerator. * - * (1..6).partition { |v| v.even? } #=> [[2, 4, 6], [1, 3, 5]] + * Related: Enumerable#group_by. * */ @@ -1114,16 +1127,23 @@ group_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) /* * call-seq: - * enum.group_by { |obj| block } -> a_hash - * enum.group_by -> an_enumerator + * group_by {|element| ... } -> hash + * group_by -> enumerator * - * Groups the collection by result of the block. Returns a hash where the - * keys are the evaluated result from the block and the values are - * arrays of elements in the collection that correspond to the key. + * With a block given returns a hash: * - * If no block is given an enumerator is returned. + * - Each key is a return value from the block. + * - Each value is an array of those elements for which the block returned that key. * - * (1..6).group_by { |i| i%3 } #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]} + * Examples: + * + * g = (1..6).group_by {|i| i%3 } + * g # => {1=>[1, 4], 2=>[2, 5], 0=>[3, 6]} + * h = {foo: 0, bar: 1, baz: 0, bat: 1} + * g = h.group_by {|key, value| value } + * g # => {0=>[[:foo, 0], [:baz, 0]], 1=>[[:bar, 1], [:bat, 1]]} + * + * With no block given, returns an Enumerator. * */ @@ -1173,18 +1193,30 @@ tally_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) /* * call-seq: - * enum.tally -> a_hash - * enum.tally(a_hash) -> a_hash + * tally -> new_hash + * tally(hash) -> hash + * + * Returns a hash containing the counts of equal elements: + * + * - Each key is an element of +self+. + * - Each value is the number elements equal to that key. * - * Tallies the collection, i.e., counts the occurrences of each element. - * Returns a hash with the elements of the collection as keys and the - * corresponding counts as values. + * With no argument: * - * ["a", "b", "c", "b"].tally #=> {"a"=>1, "b"=>2, "c"=>1} + * %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3} + * + * With a hash argument, that hash is used for the tally (instead of a new hash), + * and is returned; + * this may be useful for accumulating tallies across multiple enumerables: + * + * hash = {} + * hash = %w[a c d b c a].tally(hash) + * hash # => {"a"=>2, "c"=>2, "d"=>1, "b"=>1} + * hash = %w[b a z].tally(hash) + * hash # => {"a"=>3, "c"=>2, "d"=>1, "b"=>2, "z"=>1} + * hash = %w[b a m].tally(hash) + * hash # => {"a"=>4, "c"=>2, "d"=>1, "b"=>3, "z"=>1, "m"=> 1} * - * If a hash is given, the number of occurrences is added to each value - * in the hash, and the hash is returned. The value corresponding to - * each element must be an integer. */ static VALUE @@ -1219,18 +1251,26 @@ static VALUE enum_take(VALUE obj, VALUE n); /* * call-seq: - * enum.first -> obj or nil - * enum.first(n) -> an_array + * first -> element or nil + * first(n) -> array + * + * Returns the first element or elements. + * + * With no argument, returns the first element, or +nil+ if there is none: * - * Returns the first element, or the first +n+ elements, of the enumerable. - * If the enumerable is empty, the first form returns <code>nil</code>, and the - * second form returns an empty array. + * (1..4).first # => 1 + * %w[a b c].first # => "a" + * {foo: 1, bar: 1, baz: 2}.first # => [:foo, 1] + * [].first # => nil * - * %w[foo bar baz].first #=> "foo" - * %w[foo bar baz].first(2) #=> ["foo", "bar"] - * %w[foo bar baz].first(10) #=> ["foo", "bar", "baz"] - * [].first #=> nil - * [].first(10) #=> [] + * With integer argument +n+, returns an array + * containing the first +n+ elements that exist: + * + * (1..4).first(2) # => [1, 2] + * %w[a b c d].first(3) # => ["a", "b", "c"] + * %w[a b c d].first(50) # => ["a", "b", "c", "d"] + * {foo: 1, bar: 1, baz: 2}.first(2) # => [[:foo, 1], [:bar, 1]] + * [].first(2) # => [] * */ @@ -1249,28 +1289,35 @@ enum_first(int argc, VALUE *argv, VALUE obj) } } - /* * call-seq: - * enum.sort -> array - * enum.sort { |a, b| block } -> array + * sort -> array + * sort {|a, b| ... } -> array + * + * Returns an array containing the sorted elements of +self+. + * The ordering of equal elements is indeterminate and may be unstable. + * + * With no block given, the sort compares + * using the items' own method <tt><=></tt>: * - * Returns an array containing the items in <i>enum</i> sorted. + * %w[b c a d].sort # => ["a", "b", "c", "d"] + * {foo: 0, bar: 1, baz: 2}.sort # => [[:bar, 1], [:baz, 2], [:foo, 0]] * - * Comparisons for the sort will be done using the items' own - * <code><=></code> operator or using an optional code block. + * With a block given, comparisons in the block determine the ordering. + * The block is called with two elements +a+ and +b+, and must return: * - * The block must implement a comparison between +a+ and +b+ and return - * an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+ - * are equivalent, or an integer greater than 0 when +a+ follows +b+. + * - A negative integer if <tt>a < b</tt>. + * - Zero if <tt>a == b</tt>. + * - A positive integer if <tt>a > b</tt>. * - * The result is not guaranteed to be stable. When the comparison of two - * elements returns +0+, the order of the elements is unpredictable. + * Examples: * - * %w(rhea kea flea).sort #=> ["flea", "kea", "rhea"] - * (1..10).sort { |a, b| b <=> a } #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1] + * a = %w[b c a d] + * a.sort {|a, b| b <=> a } # => ["d", "c", "b", "a"] + * h = {foo: 0, bar: 1, baz: 2} + * h.sort {|a, b| b <=> a } # => [[:foo, 0], [:baz, 2], [:bar, 1]] * - * See also Enumerable#sort_by. It implements a Schwartzian transform + * See also #sort_by. It implements a Schwartzian transform * which is useful when key computation or comparison is expensive. */ @@ -1335,19 +1382,23 @@ sort_by_cmp(const void *ap, const void *bp, void *data) /* * call-seq: - * enum.sort_by { |obj| block } -> array - * enum.sort_by -> an_enumerator + * sort_by {|element| ... } -> array + * sort_by -> enumerator * - * Sorts <i>enum</i> using a set of keys generated by mapping the - * values in <i>enum</i> through the given block. + * With a block given, returns an array of elements of +self+, + * sorted according to the value returned by the block for each element. + * The ordering of equal elements is indeterminate and may be unstable. * - * The result is not guaranteed to be stable. When two keys are equal, - * the order of the corresponding elements is unpredictable. + * Examples: * - * If no block is given, an enumerator is returned instead. + * a = %w[xx xxx x xxxx] + * a.sort_by {|s| s.size } # => ["x", "xx", "xxx", "xxxx"] + * a.sort_by {|s| -s.size } # => ["xxxx", "xxx", "xx", "x"] + * h = {foo: 2, bar: 1, baz: 0} + * h.sort_by{|key, value| value } # => [[:baz, 0], [:bar, 1], [:foo, 2]] + * h.sort_by{|key, value| key } # => [[:bar, 1], [:baz, 0], [:foo, 2]] * - * %w{apple pear fig}.sort_by { |word| word.length } - * #=> ["fig", "pear", "apple"] + * With no block given, returns an Enumerator. * * The current implementation of #sort_by generates an array of * tuples containing the original collection element and the mapped @@ -1505,25 +1556,44 @@ DEFINE_ENUMFUNCS(all) /* * call-seq: - * enum.all? [{ |obj| block } ] -> true or false - * enum.all?(pattern) -> true or false + * all? -> true or false + * all?(pattern) -> true or false + * all? {|element| ... } -> true or false * - * Passes each element of the collection to the given block. The method - * returns <code>true</code> if the block never returns - * <code>false</code> or <code>nil</code>. If the block is not given, - * Ruby adds an implicit block of <code>{ |obj| obj }</code> which will - * cause #all? to return +true+ when none of the collection members are - * +false+ or +nil+. + * Returns whether every element meets a given criterion. * - * If instead a pattern is supplied, the method returns whether - * <code>pattern === element</code> for every collection member. + * With no argument and no block, + * returns whether every element is truthy: + * + * (1..4).all? # => true + * %w[a b c d].all? # => true + * [1, 2, nil].all? # => false + * ['a','b', false].all? # => false + * [].all? # => true + * + * With argument +pattern+ and no block, + * returns whether for each element +element+, + * <tt>pattern === element</tt>: + * + * (1..4).all?(Integer) # => true + * (1..4).all?(Numeric) # => true + * (1..4).all?(Float) # => false + * %w[bar baz bat bam].all?(/ba/) # => true + * %w[bar baz bat bam].all?(/bar/) # => false + * %w[bar baz bat bam].all?('ba') # => false + * {foo: 0, bar: 1, baz: 2}.all?(Array) # => true + * {foo: 0, bar: 1, baz: 2}.all?(Hash) # => false + * [].all?(Integer) # => true + * + * With a block given, returns whether the block returns a truthy value + * for every element: + * + * (1..4).all? {|element| element < 5 } # => true + * (1..4).all? {|element| element < 4 } # => false + * {foo: 0, bar: 1, baz: 2}.all? {|key, value| value < 3 } # => true + * {foo: 0, bar: 1, baz: 2}.all? {|key, value| value < 2 } # => false * - * %w[ant bear cat].all? { |word| word.length >= 3 } #=> true - * %w[ant bear cat].all? { |word| word.length >= 4 } #=> false - * %w[ant bear cat].all?(/t/) #=> false - * [1, 2i, 3.14].all?(Numeric) #=> true - * [nil, true, 99].all? #=> false - * [].all? #=> true + * Related: #any?. * */ @@ -1547,26 +1617,44 @@ DEFINE_ENUMFUNCS(any) /* * call-seq: - * enum.any? [{ |obj| block }] -> true or false - * enum.any?(pattern) -> true or false + * any? -> true or false + * any?(pattern) -> true or false + * any? {|element| ... } -> true or false * - * Passes each element of the collection to the given block. The method - * returns <code>true</code> if the block ever returns a value other - * than <code>false</code> or <code>nil</code>. If the block is not - * given, Ruby adds an implicit block of <code>{ |obj| obj }</code> that - * will cause #any? to return +true+ if at least one of the collection - * members is not +false+ or +nil+. + * Returns whether any element meets a given criterion. * - * If instead a pattern is supplied, the method returns whether - * <code>pattern === element</code> for any collection member. + * With no argument and no block, + * returns whether any element is truthy: + * + * (1..4).any? # => true + * %w[a b c d].any? # => true + * [1, false, nil].any? # => true + * [].any? # => false + * + * With argument +pattern+ and no block, + * returns whether for any element +element+, + * <tt>pattern === element</tt>: + * + * [nil, false, 0].any?(Integer) # => true + * [nil, false, 0].any?(Numeric) # => true + * [nil, false, 0].any?(Float) # => false + * %w[bar baz bat bam].any?(/m/) # => true + * %w[bar baz bat bam].any?(/foo/) # => false + * %w[bar baz bat bam].any?('ba') # => false + * {foo: 0, bar: 1, baz: 2}.any?(Array) # => true + * {foo: 0, bar: 1, baz: 2}.any?(Hash) # => false + * [].any?(Integer) # => false + * + * With a block given, returns whether the block returns a truthy value + * for any element: + * + * (1..4).any? {|element| element < 2 } # => true + * (1..4).any? {|element| element < 1 } # => false + * {foo: 0, bar: 1, baz: 2}.any? {|key, value| value < 1 } # => true + * {foo: 0, bar: 1, baz: 2}.any? {|key, value| value < 0 } # => false * - * %w[ant bear cat].any? { |word| word.length >= 3 } #=> true - * %w[ant bear cat].any? { |word| word.length >= 4 } #=> true - * %w[ant bear cat].any?(/d/) #=> false - * [nil, true, 99].any?(Integer) #=> true - * [nil, true, 99].any? #=> true - * [].any? #=> false * + * Related: #all? */ static VALUE |