geco

$3


!NODE VERSION



> __Geco__, a __CAT__ (Constant Amortized Time) __recursive generator*__ for
> __k-combinations__ chosen from a given set S of __n__ elements, with and
> without __replacement__.

> It is __extremely memory efficient__ and __very fast__, it generates all the k-combinations in
> a set of __n elements__, using a __single sequence of n bits__, only __1 bit__
> per element.

> It is also able to generate all the __k-combinations__ of a given __multiset__,
> aka __compositions with restricted parts__, of which, __combinations with repetition__
> are the general case (without limits on possible repetitions).

> __NOTE__: It generates combinations in __Colexicographic Order__.

$3

- __Install__
- __Run Tests__
- __Run Benchmarks__
- __Properties__
- __cnt__
- __gen__
- __get__
- __get_bm__
- __mget__
- __Events__
- __Examples__
- __Simple Example__
- __Cards Example__
- __Cartesian Product__
- __52-Card Deck Example__
- __Simple Multiset Example__
- __Multiset Example__
- __Multiset Fixed Repetitions Example__
- __7-card Poker Boards Example__
- __5 different cards Poker Boards Example__
- __MIT License__

------------------------------------------------------------------------------

$3

``bash
$ npm install geco [-g]
`

> __require__:

`javascript
const Geco = require( 'geco' );
`

$3

> __to run all test files, install devDependencies:__

`bash
$ cd geco/
# install or update devDependencies
$ npm install
# run tests
$ npm test
`

> __to execute a single test file simply do__:

`bash
$ node test/file-name.js
`

$3

`bash
$ cd geco/
$ npm run bench
`

> __to execute a single bench file, simply do__:

`bash
$ node bench/file-name.js
`

> __output example and running time__:

`bash
- generate all boards of 5 cards from a deck of 52, without repetition/replacement

- the 52-card deck is:
A♠ K♠ Q♠ J♠ T♠ 9♠ 8♠ 7♠ 6♠ 5♠ 4♠ 3♠ 2♠
A♣ K♣ Q♣ J♣ T♣ 9♣ 8♣ 7♣ 6♣ 5♣ 4♣ 3♣ 2♣
A♦ K♦ Q♦ J♦ T♦ 9♦ 8♦ 7♦ 6♦ 5♦ 4♦ 3♦ 2♦
A♥ K♥ Q♥ J♥ T♥ 9♥ 8♥ 7♥ 6♥ 5♥ 4♥ 3♥ 2♥

- generating 5-combinations..

....

- total: 2598960 combinations
- rate: 621760 comb/sec
- time: 4.18 secs

- generating all 7-combinations (133784560)..

....

- total: 133784580 combinations
- rate: 580687 comb/sec
- time: 230.39 secs

`

$3

> Arguments between [ ] are optional.

| name | description |
|:--------------------------|:-----------------------------------------------------------------------|
| __cnt__ | count the number of k-combinations of n elements, without repetition |
| __gen__ | get a generator to produce combinations of k elements from a given set, without repetition|
| __get__ | iterate on k-combinations of n elements, without replacement, represented as buffers |
| __get_bm__ | iterate on k-combinations of n elements, without replacement, represented as bitmaps |
| __mget__ | iterate on k-combinations from a mulitiset of v different types, represented as buffers |


#### Geco.cnt
> ##### get the total number of k-combinations from n elements, without replacement
`javascript
'cnt' : function ( Number n, Number k ) : Number
`

#### Geco.gen
> ##### iterate on all k-combination of a given set, without replacement
`javascript
/*
* get a generator for iterating on all combinations of k elements,
* chosen from the first n items of the given set. Optionally, it
* may uses also a bitmap, for generating combinations.
*
* NOTE: it consumes only n bytes in memory to generate all
* combinations, instead, with bitmap, it uses only n bits.
*/
'gen' : function *( Number n, Number k, Array set [, Boolean bitmap ] ) : GeneratorFunction
`

#### Geco.get
> ##### iterate on all k-combinations of n elements, without replacement, represented as buffers
`javascript
/*
* the iterator's value is a Buffer with k bytes set to 1.
* Every 1 (a byte) represents a chosen element for the current combination.
*/
'get' : function ( Number n, Number k ) : GeneratorFunction
`

#### Geco.get_bm
> ##### iterate on all k-combinations of n elements, without replacement, represented as bitmaps (Toni)
`javascript
/*
* the iterator's value is a bitmap with k bits set to 1.
* Every 1 (a bit) represents a chosen element for the current combination.
*
* NOTE: to check if the element at index i has been chosen use bitmap.chk( i ).
*/
'get_bm' : function ( Number n, Number k ) : GeneratorFunction
`

#### Geco.mget
> ##### iterate on k-combinations of a mulitiset of v different types, with replacement
`javascript
/*
* aka compositions with restricted parts, repeated elements are allowed within
* certain limits.
*
* NOTE: when all specified repetitions are (>)= v, it simply generates all the
* combinations with repetition. ( n + r − 1 )! / r!( n − 1 )!
*
* the iterator's value is a Buffer representing the number of elements chosen
* for every type/value, according to the limit imposed by the repetition buffer.
*
* NOTE: the repetitions buffer should contain the nummber of max allowable
* repetitions for every type/value. If the max repetitions for a chosen type
* are > 256 you should use 2 byte per type (16 bits numbers), in the same
* manner, if repetitions > 65536 you should use 4 bytes per type (32 bits).
* The buffer returned by the iterator should be read coherently to the number
* of bytes used for every type in the repetition buffer (1,2 or 4 bytes).
*/
'mget' : function ( Number k, Number v, Buffer | Number repetitions ) : GeneratorFunction
``

$3

> - __Simple Example__
> - __Cards Example__
> - __Cartesian Product__
> - __52-Card Deck Example__
> - __Simple Multiset Example__
> - __Multiset Example__
> - __Multiset Fixed Repetitions Example__
> - __7-card Poker Boards Example__
> - __5 different cards Poker Boards Example__

> See __examples__.

$3

> Copyright (c) 2018-present < Guglielmo Ferri : 44gatti@gmail.com >

> Permission is hereby granted, free of charge, to any person obtaining
> a copy of this software and associated documentation files (the
> 'Software'), to deal in the Software without restriction, including
> without limitation the rights to use, copy, modify, merge, publish,
> distribute, sublicense, and/or sell copies of the Software, and to
> permit persons to whom the Software is furnished to do so, subject to
> the following conditions:

> __The above copyright notice and this permission notice shall be
> included in all copies or substantial portions of the Software.__

> THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.