From 84546e802e1e2efadf2e59be1e9ff1b6220a9e72 Mon Sep 17 00:00:00 2001 From: Pol Dellaiera Date: Mon, 3 Apr 2017 22:25:45 +0200 Subject: [PATCH] #6: Update the README file. --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 84 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index b40a589..403a45d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,88 @@ ## PHPermutations [![Build Status](https://travis-ci.org/drupol/phpermutations.svg?branch=master)](https://travis-ci.org/drupol/phpermutations) [![Code Coverage](https://scrutinizer-ci.com/g/drupol/phpermutations/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/drupol/phpermutations/?branch=master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/drupol/phpermutations/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/drupol/phpermutations/?branch=master) [![Dependency Status](https://www.versioneye.com/user/projects/5870ade140543803e80abb5b/badge.svg?style=flat-square)](https://www.versioneye.com/user/projects/5870ade140543803e80abb5b) -PHP iterators and generators to generate combinations and permutations in an efficient way. +PHP Iterators and Generators to generate combinations and permutations in an efficient way. At first the library was created to only generate permutations and combinations. + In the end, I added other Iterators and Generators like: * Fibonacci numbers, * Perfect numbers, * Prime numbers, * Product of numbers, -* ... more to come. +* Rotation of an array, +* Cycling through an array, +* Permutations, +* Combinations, + +## Introduction + +I've always been fascinated by numbers and everything around them... in other words, mathematics. + +The library has been written first for being used in [PHPartition](https://github.com/drupol/phpartition), then it has +been extended here and there. + +Its main use is for generating Permutations and Combinations without running out of memory, thanks to +[PHP Generators](https://secure.php.net/manual/en/language.generators.overview.php) and +and [Iterators](https://secure.php.net/manual/en/class.iterator.php). + +The difference with other combinatorics library is that you can use an extra parameter 'length', that allows you to +compute Permutations and Combinations of a particular size. +The other notable difference is that your input arrays may contains any type of object (integers, arrays, strings or +objects), the library will still continue to work without any trouble. + +## Requirements + +* PHP >= 5.6, +* (optional) [PHPUnit](https://phpunit.de/) to run tests. + +## How to use + +Include this library in your project by doing: + +`composer require drupol/phpermutations` + +Let's say you want to find all the permutations of the list of number [1, 2, 3, 4, 5] having a length of 3: + +```php +// Create the object +$permutations = new \drupol\phpermutations\Generators\Permutations([1,2,3,4,5], 3); + +// Use a foreach loop. +foreach ($permutations->generator() as $permutation) {// do stuff} + +// Or get the whole array at once. +$permutations->toArray(); +``` + +Most of the components always has the same arguments except for very few of them. + +As the documentation per component is not written yet, I advise you to +[check the tests](https://github.com/drupol/phpermutations/tree/master/tests/src) to see how to use them. + +## Combinations + +> In mathematics, a combination is a way of selecting items from a collection, such that (unlike permutations) the order +> of selection does not matter. +> -- [_Wikipedia_](https://en.wikipedia.org/wiki/Combination) + +In one sentence: _When the order doesn't matter, it is a Combination._ + +## Examples + +Let's say we have a group of fruits: + +`$list = ['Apple', 'Pear', 'Banana', 'Orange']` + +and we want to find the combinations of length: `3`, the result will be: + +`['Apple', 'Pear', 'Banana']` + +`['Apple', 'Pear', 'Orange']` + +`['Apple', 'Banana', 'Orange']` + +`['Pear', 'Banana', 'Orange']` ## Permutations @@ -76,35 +149,16 @@ and we want to find the permutations of length: `3`, the result will be: `['Orange', 'Banana', 'Pear']` -## Combinations - -> In mathematics, a combination is a way of selecting items from a collection, such that (unlike permutations) the order -> of selection does not matter. -> -- [_Wikipedia_](https://en.wikipedia.org/wiki/Combination) - -In one sentence: _When the order doesn't matter, it is a Combination._ - -## Examples - -Let's say we have a group of fruits +The permutations of length 3 of the array [1, 2, 3, 4, 5] are, _please hold on tight_, the sum of all the permutations +of each combinations having a length of 3 of that array. -`$list = ['Apple', 'Pear', 'Banana', 'Orange']` +## Tests -and we want to find the combinations of length: `3`, the result will be: +Each Generators and Iterators are tested using the same values as input. I try to be as much complete as possible with +the [tests](https://github.com/drupol/phpermutations/tree/master/tests/fixtures). +Every time the sources are modified, [Travis](https://travis-ci.org/drupol/phpermutations), the continuous integration +service, tests the code against those tests, this way you are aware if the changes that you are introducing are valid. -`['Apple', 'Pear', 'Banana']` - -`['Apple', 'Pear', 'Orange']` - -`['Apple', 'Banana', 'Orange']` +# Contributing -`['Pear', 'Banana', 'Orange']` - -## Inspired by - -* Many stackoverflow posts. - -## Requirements - -* PHP >= 5.6, -* (optional) [PHPUnit](https://phpunit.de/) to run tests. +Feel free to contribute to this library by sending Github pull requests. I'm quite reactive :-)