[DOC] Tweaks to Array#combination (#11440)

This commit is contained in:
Burdette Lamar 2024-08-24 20:22:33 -05:00 committed by GitHub
parent 620ce3807b
commit 76e0ea28ea
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
Notes: git 2024-08-25 01:22:51 +00:00
Merged-By: peterzhu2118 <peter@peterzhu.ca>

55
array.c
View File

@ -7103,56 +7103,45 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj)
/* /*
* call-seq: * call-seq:
* array.combination(n) {|element| ... } -> self * combination(n) {|element| ... } -> self
* array.combination(n) -> new_enumerator * combination(n) -> new_enumerator
* *
* Calls the block, if given, with combinations of elements of +self+; * When a block and a positive
* returns +self+. The order of combinations is indeterminate. * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
* argument +n+ (<tt>0 < n <= self.size</tt>)
* are given, calls the block with all +n+-tuple combinations of +self+;
* returns +self+:
* *
* When a block and an in-range positive Integer argument +n+ (<tt>0 < n <= self.size</tt>) * a = %w[a b c] # => ["a", "b", "c"]
* are given, calls the block with all +n+-tuple combinations of +self+. * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
*
* Example:
*
* a = [0, 1, 2]
* a.combination(2) {|combination| p combination }
* *
* Output: * Output:
* *
* [0, 1] * ["a", "b"]
* [0, 2] * ["a", "c"]
* [1, 2] * ["b", "c"]
* *
* Another example: * The order of the yielded combinations is not guaranteed.
* *
* a = [0, 1, 2] * When +n+ is zero, calls the block once with a new empty array:
* a.combination(3) {|combination| p combination }
* *
* Output: * a.combination(0) {|combination| p combination }
* * [].combination(0) {|combination| p combination }
* [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: * Output:
* *
* [] * []
* []
* *
* When +n+ is out of range (negative or larger than <tt>self.size</tt>), * When +n+ is negative or larger than +self.size+ and +self+ is non-empty,
* does not call the block: * does not call the block:
* *
* a = [0, 1, 2] * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
* a.combination(-1) {|combination| fail 'Cannot happen' } * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
* a.combination(4) {|combination| fail 'Cannot happen' }
* *
* Returns a new Enumerator if no block given: * With no block given, returns a new Enumerator.
*
* a = [0, 1, 2]
* a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
* *
* Related: Array#permutation.
*/ */
static VALUE static VALUE