{"id":17771392,"url":"https://github.com/rootslab/geco","last_synced_at":"2025-03-15T16:31:01.689Z","repository":{"id":57245661,"uuid":"119282579","full_name":"rootslab/geco","owner":"rootslab","description":" Geco, a (Constant Amortized Time) recursive generator* for k-combinations, chosen from a given set S of n elements.","archived":false,"fork":false,"pushed_at":"2018-02-06T19:15:44.000Z","size":72,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-25T08:49:45.939Z","etag":null,"topics":["cat","colex","colexicographic-order","combinations","combinations-with-repetition","combinatorics","compositions","generators","k-combinations","multiset-combinations","nodejs","poker","recursive-js-generator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rootslab.png","metadata":{"files":{"readme":"Readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-28T17:46:30.000Z","updated_at":"2024-09-07T20:37:47.000Z","dependencies_parsed_at":"2022-08-24T16:10:46.622Z","dependency_job_id":null,"html_url":"https://github.com/rootslab/geco","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fgeco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fgeco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fgeco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fgeco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootslab","download_url":"https://codeload.github.com/rootslab/geco/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221585901,"owners_count":16847847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cat","colex","colexicographic-order","combinations","combinations-with-repetition","combinatorics","compositions","generators","k-combinations","multiset-combinations","nodejs","poker","recursive-js-generator"],"created_at":"2024-10-26T21:32:35.780Z","updated_at":"2025-03-15T16:31:01.683Z","avatar_url":"https://github.com/rootslab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Geco\n\n[![NPM VERSION](http://img.shields.io/npm/v/geco.svg?style=flat)](https://www.npmjs.org/package/geco)\n[![CODACY BADGE](https://img.shields.io/codacy/b18ed7d95b0a4707a0ff7b88b30d3def.svg?style=flat)](https://www.codacy.com/public/44gatti/geco)\n[![CODECLIMATE-TEST-COVERAGE](https://img.shields.io/codeclimate/c/rootslab/geco.svg?style=flat)](https://codeclimate.com/github/rootslab/geco)\n[![LICENSE](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/rootslab/geco#mit-license)\n\n![NODE VERSION](https://img.shields.io/node/v/geco.svg)\n[![TRAVIS CI BUILD](http://img.shields.io/travis/rootslab/geco.svg?style=flat)](http://travis-ci.org/rootslab/geco)\n[![BUILD STATUS](http://img.shields.io/david/rootslab/geco.svg?style=flat)](https://david-dm.org/rootslab/geco)\n[![DEVDEPENDENCY STATUS](http://img.shields.io/david/dev/rootslab/geco.svg?style=flat)](https://david-dm.org/rootslab/geco#info=devDependencies)\n\n[![NPM MONTHLY](http://img.shields.io/npm/dm/geco.svg?style=flat)](http://npm-stat.com/charts.html?package=geco)\n[![NPM YEARLY](https://img.shields.io/npm/dy/geco.svg)](http://npm-stat.com/charts.html?package=geco)\n[![NPM TOTAL](https://img.shields.io/npm/dt/geco.svg)](http://npm-stat.com/charts.html?package=geco)\n\n[![NPM GRAPH](https://nodei.co/npm/geco.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/geco/)\n\n\u003e __Geco__, a __CAT__ (Constant Amortized Time) __recursive generator*__ for \n\u003e __k-combinations__ chosen from a given set S of __n__ elements, with and\n\u003e without __replacement__.\n\n\u003e It is __extremely memory efficient__ and __very fast__, it generates all the k-combinations in\n\u003e a set of __n elements__, using a __single sequence of n bits__, only __1 bit__\n\u003e per element.\n\n\u003e It is also able to generate all the __k-combinations__ of a given __multiset__,\n\u003e aka __compositions with restricted parts__, of which, __combinations with repetition__\n\u003e are the general case (without limits on possible repetitions).\n\n\n\u003e __NOTE__: It generates combinations in __[Colexicographic Order](https://en.wikipedia.org/wiki/Lexicographical_order#Colexicographic_order)__.\n\n\n### Table of Contents\n\n- __[Install](#install)__\n- __[Run Tests](#run-tests)__\n- __[Run Benchmarks](#run-benchmarks)__\n- __[Properties](#properties)__\n    - __[cnt](#gecocnt)__\n    - __[gen](#gecogen)__\n    - __[get](#gecoget)__\n    - __[get_bm](#gecoget_bm)__\n    - __[mget](#gecomget)__\n- __[Events](#events)__\n- __[Examples](#examples)__\n  - __[Simple Example](#examples)__\n  - __[Cards Example](#examples)__\n  - __[Cartesian Product](#examples)__\n  - __[52-Card Deck Example](#examples)__\n  - __[Simple Multiset Example](#examples)__\n  - __[Multiset Example](#examples)__\n  - __[Multiset Fixed Repetitions Example](#examples)__\n  - __[7-card Poker Boards Example](#examples)__\n  - __[5 different cards Poker Boards Example](#examples)__\n - __[MIT License](#mit-license)__\n\n------------------------------------------------------------------------------\n\n### Install\n\n```bash\n$ npm install geco [-g]\n```\n\n\u003e __require__:\n\n```javascript\nconst Geco  = require( 'geco' );\n```\n\n### Run Tests\n\n\u003e __to run all test files, install devDependencies:__\n\n```bash\n $ cd geco/\n # install or update devDependencies\n $ npm install \n # run tests\n $ npm test\n```\n\n\u003e __to execute a single test file simply do__:\n\n```bash\n $ node test/file-name.js\n```\n\n### Run Benchmarks\n\n```bash\n$ cd geco/\n$ npm run bench\n```\n\n\u003e __to execute a single bench file, simply do__:\n\n```bash\n $ node bench/file-name.js\n```\n\n\u003e __output example and running time__:\n\n```bash\n- generate all boards of 5 cards from a deck of 52, without repetition/replacement\n\n- the 52-card deck is:\n  A♠ K♠ Q♠ J♠ T♠ 9♠ 8♠ 7♠ 6♠ 5♠ 4♠ 3♠ 2♠ \n  A♣ K♣ Q♣ J♣ T♣ 9♣ 8♣ 7♣ 6♣ 5♣ 4♣ 3♣ 2♣ \n  A♦ K♦ Q♦ J♦ T♦ 9♦ 8♦ 7♦ 6♦ 5♦ 4♦ 3♦ 2♦ \n  A♥ K♥ Q♥ J♥ T♥ 9♥ 8♥ 7♥ 6♥ 5♥ 4♥ 3♥ 2♥\n\n- generating 5-combinations..\n\n....\n\n- total: 2598960 combinations\n- rate:  621760 comb/sec\n- time:  4.18 secs\n\n- generating all 7-combinations (133784560)..\n\n....\n\n- total: 133784580 combinations\n- rate:  580687 comb/sec\n- time:  230.39 secs\n\n```\n\n### Methods\n\n\u003e Arguments between [ ] are optional.\n\n|             name          |                             description                                |\n|:--------------------------|:-----------------------------------------------------------------------|\n| __[cnt](#gecocount)__     | `count the number of k-combinations of n elements, without repetition` |\n| __[gen](#gecogen)__       | `get a generator to produce combinations of k elements from a given set, without repetition`|\n| __[get](#gecoget)__       | `iterate on k-combinations of n elements, without replacement, represented as buffers` |\n| __[get_bm](#gecoget_bm)__ | `iterate on k-combinations of n elements, without replacement, represented as bitmaps` |\n| __[mget](#gecomget)__     | `iterate on k-combinations from a mulitiset of v different types, represented as buffers` |\n\n\n#### Geco.cnt\n\u003e ##### get the total number of k-combinations from n elements, without replacement\n```javascript\n'cnt' : function ( Number n, Number k ) : Number\n```\n\n#### Geco.gen\n\u003e ##### iterate on all k-combination of a given set, without replacement\n```javascript\n/*\n * get a generator for iterating on all combinations of k elements,\n * chosen from the first n items of the given set. Optionally, it\n * may uses also a bitmap, for generating combinations.\n *\n * NOTE: it consumes only n bytes in memory to generate all\n * combinations, instead, with bitmap, it uses only n bits.\n */\n'gen' : function *( Number n, Number k, Array set [, Boolean bitmap ] ) : GeneratorFunction\n```\n\n#### Geco.get\n\u003e ##### iterate on all k-combinations of n elements, without replacement, represented as buffers\n```javascript\n/*\n * the iterator's value is a Buffer with k bytes set to 1.\n * Every 1 (a byte) represents a chosen element for the current combination.\n */\n'get' : function ( Number n, Number k ) : GeneratorFunction\n```\n\n#### Geco.get_bm\n\u003e ##### iterate on all k-combinations of n elements, without replacement, represented as bitmaps  ([Toni](https://github.com/rootslab/toni))\n```javascript\n/*\n * the iterator's value is a bitmap with k bits set to 1.\n * Every 1 (a bit) represents a chosen element for the current combination.\n *\n * NOTE: to check if the element at index i has been chosen use bitmap.chk( i ).\n */\n'get_bm' : function ( Number n, Number k ) : GeneratorFunction\n```\n\n#### Geco.mget\n\u003e ##### iterate on k-combinations of a mulitiset of v different types, with replacement\n```javascript\n/*\n * aka compositions with restricted parts, repeated elements are allowed within\n * certain limits.\n *\n * NOTE: when all specified repetitions are (\u003e)= v, it simply generates all the\n * combinations with repetition. ( n + r − 1 )! / r!( n − 1 )!\n *\n * the iterator's value is a Buffer representing the number of elements chosen\n * for every type/value, according to the limit imposed by the repetition buffer.\n *\n * NOTE: the repetitions buffer should contain the nummber of max allowable\n * repetitions for every type/value. If the max repetitions for a chosen type\n * are \u003e 256 you should use 2 byte per type (16 bits numbers), in the same\n * manner, if repetitions \u003e 65536 you should use 4 bytes per type (32 bits).\n * The buffer returned by the iterator should be read coherently to the number\n * of bytes used for every type in the repetition buffer (1,2 or 4 bytes).\n */\n'mget' : function ( Number k, Number v, Buffer | Number repetitions ) : GeneratorFunction\n```\n\n\n### Examples\n\n \u003e - __[Simple Example](example/next-example.js)__\n \u003e - __[Cards Example](example/cards-example.js)__\n \u003e - __[Cartesian Product](example/cartesian-product-example.js)__\n \u003e - __[52-Card Deck Example](example/deck-example.js)__\n \u003e - __[Simple Multiset Example](example/multi-simple-example.js)__\n \u003e - __[Multiset Example](example/multi-example.js)__\n \u003e - __[Multiset Fixed Repetitions Example](example/multi-fixed-integer-example.js)__\n \u003e - __[7-card Poker Boards Example](example/multi-7-cards-example.js)__\n \u003e - __[5 different cards Poker Boards Example](example/multi-5-cards-example.js)__\n\n\u003e See __[examples](example/)__.\n\n\n### MIT License\n\n\u003e Copyright (c) 2018-present \u0026lt; Guglielmo Ferri : 44gatti@gmail.com \u0026gt;\n\n\u003e Permission is hereby granted, free of charge, to any person obtaining\n\u003e a copy of this software and associated documentation files (the\n\u003e 'Software'), to deal in the Software without restriction, including\n\u003e without limitation the rights to use, copy, modify, merge, publish,\n\u003e distribute, sublicense, and/or sell copies of the Software, and to\n\u003e permit persons to whom the Software is furnished to do so, subject to\n\u003e the following conditions:\n\n\u003e __The above copyright notice and this permission notice shall be\n\u003e included in all copies or substantial portions of the Software.__\n\n\u003e THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\n\u003e EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n\u003e MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\n\u003e IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\n\u003e CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\n\u003e TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\n\u003e SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fgeco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootslab%2Fgeco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fgeco/lists"}