diff --git a/README.md b/README.md index 24255fd..b97e2b5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![PHP](https://img.shields.io/badge/PHP-%3E=7.0-green.svg?style=flat)](http://docs.php.net/manual/en/migration70.new-features.php) +[![PHP](https://img.shields.io/badge/PHP-%3E=7.1-green.svg?style=flat)](http://docs.php.net/manual/en/migration71.new-features.php) [![Total Downloads](https://poser.pugx.org/seboettg/collection/downloads)](https://packagist.org/packages/seboettg/collection/stats) [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/seboettg/Collection/blob/master/LICENSE) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/seboettg/Collection/badges/quality-score.png?b=version-2.0)](https://scrutinizer-ci.com/g/seboettg/Collection/?branch=master) @@ -10,6 +10,9 @@ Collection is a set of useful wrapper classes for arrays, similar to Java Collection. +## Versions +Since [Version 2.1](https://github.com/seboettg/Collection/releases/tag/v2.1.0) you need PHP 7.1 to use Collection library. Previous versions are running from PHP 5.6 upwards. + ### ArrayList, Stack, Queue ### The current version comes with a [ArrayList](#arraylist), a [Stack](#stack), and a [Queue](#queue). These classes can be used as wrapper instead using simple arrays. This approach guarantees consistently object-oriented handling for collection-like data-structures. @@ -25,6 +28,8 @@ ArrayList is powerful alternative with a lot of of features: Take also a look to the UML [class diagram](#class-diagram). + + # Installing Collection ## The recommended way to install Collection is through @@ -203,7 +208,7 @@ class Element implements Comparable public function getAttribute2() { return $this->attribute2; } //compareTo function - public function compareTo(Comparable $b) + public function compareTo(Comparable $b): int { return strcmp($this->attribute1, $b->getAttribute1()); } @@ -221,7 +226,7 @@ use Seboettg\Collection\Comparable\Comparable; class Attribute1Comparator extends Comparator { - public function compare(Comparable $a, Comparable $b) + public function compare(Comparable $a, Comparable $b): int { if ($this->sortingOrder === Comparator::ORDER_ASC) { return $a->compareTo($b); @@ -266,7 +271,7 @@ use Vendor\App\Model\Element; //Define a custom Comparator class MyCustomOrderComparator extends Comparator { - public function compare(Comparable $a, Comparable $b) + public function compare(Comparable $a, Comparable $b): int { return (array_search($a->getAttribute1(), $this->customOrder) >= array_search($b->getAttribute1(), $this->customOrder)) ? 1 : -1; } diff --git a/composer.json b/composer.json index 92fe852..22a88bf 100644 --- a/composer.json +++ b/composer.json @@ -31,7 +31,7 @@ "psr-4": {"Seboettg\\Collection\\Test\\": "tests/"} }, "require": { - "php": ">=7.0" + "php": ">=7.1" }, "require-dev": { "phpunit/phpunit": "6.5.*", diff --git a/src/ArrayList.php b/src/ArrayList.php index 85d977f..9c43d72 100644 --- a/src/ArrayList.php +++ b/src/ArrayList.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/ArrayList/ArrayAccessTrait.php b/src/ArrayList/ArrayAccessTrait.php index d0061ba..964bc10 100644 --- a/src/ArrayList/ArrayAccessTrait.php +++ b/src/ArrayList/ArrayAccessTrait.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/ArrayList/ArrayListInterface.php b/src/ArrayList/ArrayListInterface.php index bf489d5..5588230 100644 --- a/src/ArrayList/ArrayListInterface.php +++ b/src/ArrayList/ArrayListInterface.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -37,7 +38,7 @@ public function get($key); * @param $element * @return ArrayListInterface */ - public function set($key, $element); + public function set($key, $element): ArrayListInterface; /** * Returns the value of the array element that's currently being pointed to by the @@ -69,17 +70,17 @@ public function prev(); /** * @param array $array - * @return mixed + * @return ArrayListInterface */ - public function replace(array $array); + public function replace(array $array): ArrayListInterface; /** * Appends the passed element to the end of this list. * * @param $element - * @return $this + * @return ArrayListInterface */ - public function append($element); + public function append($element): ArrayListInterface; /** * Inserts the specified element at the specified position in this list. If another element already exist at the @@ -88,17 +89,17 @@ public function append($element); * * @param $key * @param $element - * @return $this + * @return ArrayListInterface */ - public function add($key, $element); + public function add($key, $element): ArrayListInterface; /** * Removes the element at the specified position in this list. * * @param $key - * @return $this + * @return ArrayListInterface */ - public function remove($key); + public function remove($key): ArrayListInterface; /** * Returns true if an element exists on the specified position. @@ -106,15 +107,15 @@ public function remove($key); * @param mixed $key * @return bool */ - public function hasKey($key); + public function hasKey($key): bool; /** * Returns true if the passed element already exists in this list, otherwise false. * * @param string $element - * @return mixed + * @return bool */ - public function hasElement($element); + public function hasElement($element): bool; /** * Returns the first element in this list @@ -128,11 +129,59 @@ public function first(); */ public function last(); + /** + * alias of replace function + * @param array $array + * @return ArrayListInterface + */ + public function setArray(array $array): ArrayListInterface; + + /** + * flush array list + * + * @return ArrayListInterface + */ + public function clear(): ArrayListInterface; + + /** + * Shuffles this list (randomizes the order of the elements in). It uses the PHP function shuffle + * @see http://php.net/manual/en/function.shuffle.php + * @return ArrayListInterface + */ + public function shuffle(): ArrayListInterface; + + /** + * returns a clone of this ArrayList, filtered by the given closure function + * @param callable $filterFunction + * @return ArrayListInterface + */ + public function filter(callable $filterFunction): ArrayListInterface; + + /** + * returns a clone of this ArrayList, filtered by the given array keys + * @param array $keys + * @return ArrayListInterface + */ + public function filterByKeys(array $keys): ArrayListInterface; + /** * Merges the elements of the passed list together with this list so that the values of the passed list are appended * to the end of the this list * @param ArrayListInterface $list * @return void */ - public function merge(ArrayListInterface $list); + public function merge(ArrayListInterface $list): void; + + /** + * returns a new ArrayList containing all the elements of this ArrayList after applying the callback function to each one. + * @param callable $mapFunction + * @return ArrayListInterface + */ + public function map(callable $mapFunction): ArrayListInterface; + + /** + * Returns a new ArrayList containing an one-dimensional array of all elements of this ArrayList. Keys are going lost. + * @return ArrayListInterface + */ + public function flatten(): ArrayListInterface; } diff --git a/src/ArrayList/ArrayListTrait.php b/src/ArrayList/ArrayListTrait.php index fc48896..f062052 100644 --- a/src/ArrayList/ArrayListTrait.php +++ b/src/ArrayList/ArrayListTrait.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -10,8 +11,6 @@ namespace Seboettg\Collection\ArrayList; -use closure; - /** * Trait ArrayListTrait * @package Seboettg\Collection @@ -25,9 +24,9 @@ trait ArrayListTrait /** * flush array list * - * @return $this + * @return ArrayListInterface|ArrayListTrait */ - public function clear() + public function clear(): ArrayListInterface { $this->array = []; return $this; @@ -66,27 +65,32 @@ public function prev() } /** - * {@inheritdoc} + * @param $key + * @param $element + * @return ArrayListInterface|ArrayListTrait */ - public function set($key, $element) + public function set($key, $element): ArrayListInterface { $this->array[$key] = $element; return $this; } /** - * {@inheritdoc} + * @param $element + * @return ArrayListInterface|ArrayListTrait */ - public function append($element) + public function append($element): ArrayListInterface { $this->array[] = $element; return $this; } /** - * {@inheritdoc} + * @param $key + * @param $element + * @return ArrayListInterface|ArrayListTrait */ - public function add($key, $element) + public function add($key, $element): ArrayListInterface { if (!array_key_exists($key, $this->array)) { @@ -101,9 +105,10 @@ public function add($key, $element) } /** - * {@inheritdoc} + * @param $key + * @return ArrayListInterface|ArrayListTrait */ - public function remove($key) + public function remove($key): ArrayListInterface { unset($this->array[$key]); return $this; @@ -112,7 +117,7 @@ public function remove($key) /** * {@inheritdoc} */ - public function hasKey($key) + public function hasKey($key): bool { return array_key_exists($key, $this->array); } @@ -120,7 +125,7 @@ public function hasKey($key) /** * {@inheritdoc} */ - public function hasElement($value) + public function hasElement($value): bool { $result = array_search($value, $this->array, true); return ($result !== false); @@ -150,7 +155,7 @@ public function last() /** * {@inheritDoc} */ - public function toArray() + public function toArray(): array { return $this->array; } @@ -160,7 +165,7 @@ public function toArray() * @see http://php.net/manual/en/function.shuffle.php * @return ArrayListInterface|ArrayListTrait */ - public function shuffle() + public function shuffle(): ArrayListInterface { shuffle($this->array); return $this; @@ -168,28 +173,30 @@ public function shuffle() /** * returns a clone of this ArrayList, filtered by the given closure function - * @param closure $closure + * @param callable $filterFunction * @return ArrayListInterface|ArrayListTrait */ - public function filter(closure $closure) + public function filter(callable $filterFunction): ArrayListInterface { $newInstance = new self(); - $newInstance->setArray(array_filter($this->array, $closure)); + $newInstance->setArray(array_filter($this->array, $filterFunction)); return $newInstance; } /** - * {@inheritdoc} + * @param array $array + * @return ArrayListInterface|ArrayListTrait */ - public function setArray(array $array) + public function setArray(array $array): ArrayListInterface { return $this->replace($array); } /** - * {@inheritdoc} + * @param array $data + * @return ArrayListInterface|ArrayListTrait */ - public function replace(array $data) + public function replace(array $data): ArrayListInterface { $this->array = $data; return $this; @@ -200,7 +207,7 @@ public function replace(array $data) * @param array $keys * @return ArrayListInterface|ArrayListTrait */ - public function filterByKeys(array $keys) + public function filterByKeys(array $keys): ArrayListInterface { $newInstance = new self(); $newInstance->setArray(array_filter($this->array, function ($key) use ($keys) { @@ -211,10 +218,10 @@ public function filterByKeys(array $keys) /** * returns a new ArrayList containing all the elements of this ArrayList after applying the callback function to each one. - * @param closure $mapFunction + * @param callable $mapFunction * @return ArrayListInterface|ArrayListTrait */ - public function map(closure $mapFunction) + public function map(callable $mapFunction): ArrayListInterface { $newInstance = new self(); $newInstance->setArray(array_map($mapFunction, $this->array)); @@ -225,7 +232,7 @@ public function map(closure $mapFunction) * Returns a new ArrayList containing an one-dimensional array of all elements of this ArrayList. Keys are going lost. * @return ArrayListInterface|ArrayListTrait */ - public function flatten() + public function flatten(): ArrayListInterface { $flattenedArray = []; array_walk_recursive($this->array, function ($item) use (&$flattenedArray) { @@ -237,12 +244,10 @@ public function flatten() } /** - * Merges the elements of the passed list together with this list so that the values of the passed list are appended - * to the end of the this list + * @inheritDoc * @param ArrayListInterface $list - * @return void */ - public function merge(ArrayListInterface $list) + public function merge(ArrayListInterface $list): void { $this->array = array_merge($this->array, $list->toArray()); } diff --git a/src/ArrayList/ToArrayInterface.php b/src/ArrayList/ToArrayInterface.php index 9081e74..0a6dd8c 100644 --- a/src/ArrayList/ToArrayInterface.php +++ b/src/ArrayList/ToArrayInterface.php @@ -25,5 +25,5 @@ interface ToArrayInterface * * @return array */ - public function toArray(); + public function toArray(): array; } diff --git a/src/CollectionInterface.php b/src/CollectionInterface.php index b7785a5..9731e15 100644 --- a/src/CollectionInterface.php +++ b/src/CollectionInterface.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/Collections.php b/src/Collections.php index 639a0d0..1f1d136 100644 --- a/src/Collections.php +++ b/src/Collections.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -10,9 +11,9 @@ namespace Seboettg\Collection; +use Seboettg\Collection\ArrayList\ArrayListInterface; use Seboettg\Collection\Comparable\Comparator; - /** * Class Collections * @package Seboettg\Collection @@ -25,11 +26,11 @@ class Collections * Sorts the specified list according to the order induced by the specified comparator. All elements in the list * must be mutually comparable. * - * @param ArrayList $list + * @param ArrayListInterface $list * @param Comparator $comparator - * @return ArrayList + * @return ArrayListInterface */ - public static function sort(ArrayList &$list, Comparator $comparator) + public static function sort(ArrayListInterface $list, Comparator $comparator): ArrayListInterface { $array = $list->toArray(); usort($array, [$comparator, "compare"]); diff --git a/src/Comparable/Comparable.php b/src/Comparable/Comparable.php index be938ce..587b213 100644 --- a/src/Comparable/Comparable.php +++ b/src/Comparable/Comparable.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -30,5 +31,5 @@ interface Comparable * @param Comparable $b * @return int */ - public function compareTo(Comparable $b); + public function compareTo(Comparable $b): int; } diff --git a/src/Comparable/Comparator.php b/src/Comparable/Comparator.php index 356bf71..d0d19e8 100644 --- a/src/Comparable/Comparator.php +++ b/src/Comparable/Comparator.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -69,5 +70,5 @@ public function __construct($sortingOrder = self::ORDER_ASC, $customOrder = null * @param Comparable $b * @return int */ - public abstract function compare(Comparable $a, Comparable $b); + public abstract function compare(Comparable $a, Comparable $b): int; } diff --git a/src/Queue.php b/src/Queue.php index 3af8112..337e71b 100644 --- a/src/Queue.php +++ b/src/Queue.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/Queue/QueueInterface.php b/src/Queue/QueueInterface.php index f012c60..bfd1d54 100644 --- a/src/Queue/QueueInterface.php +++ b/src/Queue/QueueInterface.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/Queue/QueueTrait.php b/src/Queue/QueueTrait.php index 1209c38..90c0fd1 100644 --- a/src/Queue/QueueTrait.php +++ b/src/Queue/QueueTrait.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/Stack.php b/src/Stack.php index 4431387..d3e6713 100644 --- a/src/Stack.php +++ b/src/Stack.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the @@ -20,7 +21,6 @@ */ class Stack implements StackInterface { - use StackTrait; /** diff --git a/src/Stack/StackInterface.php b/src/Stack/StackInterface.php index 79dc185..a41c735 100644 --- a/src/Stack/StackInterface.php +++ b/src/Stack/StackInterface.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/src/Stack/StackTrait.php b/src/Stack/StackTrait.php index 7470468..dc24abd 100644 --- a/src/Stack/StackTrait.php +++ b/src/Stack/StackTrait.php @@ -1,4 +1,5 @@ * You may use, distribute and modify this code under the diff --git a/tests/ArrayListTest.php b/tests/ArrayListTest.php index 5c5cafd..a304481 100644 --- a/tests/ArrayListTest.php +++ b/tests/ArrayListTest.php @@ -1,5 +1,4 @@ * You may use, distribute and modify this code under the @@ -11,6 +10,7 @@ namespace Seboettg\Collection\Test; +use Exception; use PHPUnit\Framework\TestCase; use Seboettg\Collection\ArrayList; use Seboettg\Collection\Collections; @@ -139,7 +139,7 @@ public function testShuffle() ->append(new Element("z", "zz")); Collections::sort($this->numeratedArrayList, new class extends Comparator{ - public function compare(Comparable $a, Comparable $b) { + public function compare(Comparable $a, Comparable $b): int { return $a->compareTo($b); } }); @@ -190,6 +190,9 @@ public function testHasValue() $this->assertTrue($list->hasElement("a")); } + /** + * @throws Exception + */ public function testGetIterator() { $it = $this->numeratedArrayList->getIterator(); @@ -382,7 +385,7 @@ public function setAttr2(string $attr2) * @param Comparable $b * @return int */ - public function compareTo(Comparable $b) + public function compareTo(Comparable $b): int { /** @var Element $b */ return strcmp($this->attr1, $b->getAttr1()); diff --git a/tests/CollectionsTest.php b/tests/CollectionsTest.php index 51ad04b..287733a 100644 --- a/tests/CollectionsTest.php +++ b/tests/CollectionsTest.php @@ -73,7 +73,7 @@ class MyAscendingComparator extends Comparator * @param Comparable $b * @return int */ - public function compare(Comparable $a, Comparable $b) + public function compare(Comparable $a, Comparable $b): int { return $a->compareTo($b); } @@ -89,7 +89,7 @@ class MyDescendingComparator extends Comparator * @param Comparable $b * @return int */ - public function compare(Comparable $a, Comparable $b) + public function compare(Comparable $a, Comparable $b): int { return $b->compareTo($a); } @@ -106,7 +106,7 @@ class MyCustomOrderComparator extends Comparator * @param Comparable $b * @return int */ - public function compare(Comparable $a, Comparable $b) + public function compare(Comparable $a, Comparable $b): int { /** * @var Element $a