zicht / itertools
A collection of functions that mirror the Python itertools library
Installs: 26 645
Dependents: 2
Suggesters: 0
Security: 0
Stars: 10
Watchers: 7
Forks: 1
Open Issues: 5
Requires
- php: ^7.4 || ^8.0
Requires (Dev)
- doctrine/collections: ^1.3
- phpunit/phpunit: ^9
- rregeer/phpunit-coverage-check: ^0.1
- twig/twig: ^2.0 || ^3.0
- zicht/standards-php: ^4.0
- dev-release/3.x
- dev-release/2.x
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.15.0
- 2.14.0
- 2.13.0
- 2.12.3
- 2.12.2
- 2.12.1
- 2.12.0
- 2.11.0
- 2.10.14
- 2.10.13
- 2.10.12
- 2.10.11
- 2.10.10
- 2.10.9
- 2.10.8
- 2.10.7
- 2.10.6
- 2.10.5
- 2.10.4
- 2.10.3
- 2.10.2
- 2.10.1
- 2.10.0
- 2.10.0-rc.3
- 2.10.0-rc.2
- 2.10.0-rc.1
- 2.9.0
- 2.8.26
- 2.8.25
- 2.8.24
- 2.8.23
- 2.8.22-rc.1
- 2.8.21
- 2.8.20
- 2.8.19
- 2.8.18
- 2.8.17
- 2.8.16
- 2.8.15
- 2.8.14
- 2.8.13
- 2.8.12
- 2.8.11
- 2.8.10
- 2.8.9
- 2.8.8
- 2.8.7
- 2.8.6
- 2.8.5
- 2.8.4
- 2.8.3
- 2.8.2
- 2.8.1
- 2.8.0
- 2.7.1
- 2.7.0
- 2.6.0
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.1
- 2.3.1-rc.5
- 2.3.1-rc.4
- 2.3.1-rc.3
- 2.3.1-rc.2
- 2.3.1-rc.1
- 2.3.0
- 2.3.0-beta.3
- 2.3.0-beta.2
- 2.3.0-beta.1
- 2.2.0-beta.1
- 2.1.0-beta.3
- 2.1.0-beta.2
- 2.1.0-beta.1
- 2.0.0-beta.2
- 2.0.0-beta.1
- 1.5.0
- 1.5.0-beta.5
- 1.5.0-beta.4
- 1.5.0-beta.3
- 1.5.0-beta.2
- 1.5.0-beta.1
- 1.4.3
- 1.4.2
- 1.4.1
- 1.4.1-rc.2
- 1.4.1-rc.1
- 1.4.0
- 1.4.0-rc.2
- 1.4.0-rc.1
- 1.3.0
- 1.2.0
- 1.2.0-beta.1
- 1.1.0
- 1.1.0-beta.1
- 1.0.0-beta.1
- 1.0.0-alpha.2
- 1.0.0-alpha.1
This package is auto-updated.
Last update: 2024-11-08 10:33:52 UTC
README
Zicht Iterator Tools Library
The Iterator Tools, or itertools for short, are a collection of convenience tools to handle sequences of data such as arrays, iterators, and strings. Some of the naming and API is based on the Python itertools.
Common operations include:
- mapping:
map
andmapBy
- filtering:
filter
,difference
- sorting:
sorted
- grouping:
groupBy
- reducing:
accumulate
,collapse
, andreduce
Usage
In order to use the available itertools filters/functions via Twig, simply add this service definition in your config/services.yaml
Zicht\Itertools\twig\Extension: tags: ['twig.extension']
Scripts
- unit test:
composer test
- lint test:
composer lint
Example data
The examples below will use the following data to illustrate how various Iterator tools work:
$words = ['Useful', 'Goonies', 'oven', 'Bland', 'notorious']; $numbers = [1, 3, 2, 5, 4]; $vehicles = [ [ 'id' => 1, 'type' => 'car', 'wheels' => 4, 'colors' => ['red', 'green', 'blue'], 'is_cool' => false, 'price' => 20000, ], [ 'id' => 2, 'type' => 'bike', 'wheels' => 2, 'colors' => ['red', 'green', 'blue'], 'is_cool' => false, 'price' => 600, ], [ 'id' => 5, 'type' => 'unicicle', 'wheels' => 1, 'colors' => ['red'], 'is_cool' => true, 'price' => 150, ], [ 'id' => 9, 'type' => 'car', 'wheels' => 8, 'colors' => ['blue'], 'is_cool' => true, 'price' => 100000, ], ];
Examples
With the example data above, this is how you could use itertools to get all unique colors of the cars in alphabetical order:
use Zicht\Itertools\util\Filters; use function Zicht\Itertools\iterable; $vehicles = iterable($vehicles) ->filter(Filters::equals('car', 'type')) // {[vehicle...], [vehicle...]} ->map('colors') // {0: ['red', 'green', 'blue'], 1: ['blue']} ->collapse() // {0: 'red', 1: 'green', 2: 'blue', 3: 'blue'} ->unique() // {0: 'red', 1: 'green', 2: 'blue'} ->sorted(); // {2: 'blue', 1: 'green', 0: 'red'}
You can achieve the same in Twig:
{% for vehicle_color in vehicles |it.filter(it.filters.equals('car', 'type')) |it.map('colors') |it.collapse |it.unique |it.sorted %} {{ vehicle_color }} {% endfor %}
Getter strategy
Many itertools can be passed a $strategy
parameter. This parameter
is used to obtain a value from the elements in the collection. The
$strategy
can be one of three things:
-
null, in which case the element itself is returned. For example:
use function Zicht\Itertools\iterable; $result = iterable($words)->map(null); var_dump($result); // {0: 'Useful', 1: 'Goonies', 2: 'oven', 3: 'Bland', 4: 'notorious'}
Or in Twig:
{{ dump(word|it.map) }}
-
a closure, in which case the closure is called with the element value and key as parameters to be used to compute a return value. For example:
use function Zicht\Itertools\iterable; $getDouble = fn($value, $key) => 2 * $value; $result = iterable($numbers)->map($getDouble); var_dump($result); // {0: 2, 1: 6, 2: 4, 3: 10, 4: 8}
Or in Twig:
{{ dump(numbers|it.map(num => 2 * num)) }}
-
a string, in which case this string is used to create a closure that tries to find public properties, methods, or array indexes. For example:
use function Zicht\Itertools\iterable; $result = iterable($vehicles)->map('type'); var_dump($result); // {0: 'car', 1: 'bike', 2: 'unicicle', 3: 'car'}
Or in Twig:
{{ dump(word|it.map) }}
The string can consist of multiple dot separated words, allowing access to nested properties, methods, and array indexes.
If one of the words in the string can not be resolved into an existing property, method, or array index, the value
null
will be returned. For example:use function Zicht\Itertools\iterable; $result = iterable($vehicles)->map('colors.2'); var_dump($result); // {0: 'blue', 1: 'blue', 2: null, 3: null}
Or in Twig:
{{ dump(vehicles|it.map('colors.2')) }}
Fluent interface
One way to use the Iterator Tools is to convert the array, Iterator,
string, etc into an IterableIterator
. This class provides a fluent
interface to all of the common operations. For example:
use function Zicht\Itertools\iterable; $result = iterable($vehicles)->filter('is_cool')->mapBy('id')->map('type'); var_dump($result); // {5: 'unicicle', 9: 'car'}
Or in Twig:
{{ dump(vehicles|it.filter('is_cool').mapBy('id').map('type')) }}
Mapping
Mapping converts one collection into another collection of equal
length. Using map
allows manipulation of the elements while mapBy
allows manipulation of the collection keys.
For example, we can use a closure to create a title for each element
in $vehicles
:
use function Zicht\Itertools\iterable; $getTitle = fn($value, $key) => sprintf('%s with %s wheels', $value['type'], $value['wheels']); $titles = iterable($vehicles)->map($getTitle); var_dump($titles); // {0: 'car with 4 wheels', ..., 3: 'car with 8 wheels'}
Using the string getter strategy we can easily get
the types for each element in $vehicles
mapped by the vehicle
identifiers. For example:
use function Zicht\Itertools\iterable; $types = iterable($vehicles)->mapBy('id')->map('type'); var_dump($types); // {1: 'car', 2: 'bike', 5: 'unicicle', 9: 'car'}
Or in Twig:
{{ dump(vehicles|it.mapBy('id').map('type')) }}
There are several common mapping closures available
in mappings.php. Calling these
functions returns a closure that can be passed to map
and mapBy
.
For example:
use Zicht\Itertools\util\Mappings; use function Zicht\Itertools\iterable; $lengths = iterable($words)->map(Mappings::length()); var_dump($lengths); // {0: 6, 1: 3, 2: 4, 3: 5, 4: 9}
Or in Twig:
{{ dump(words|it.map(it.mappings.length)) }}
Filtering
Filtering converts one collection into another, possibly shorter,
collection. Using filter
each element in the collection is
evaluated, the elements that are considered empty
will be rejected,
while the elements that are not empty
will be allowd to pass through
the filter.
For example, we can use a closure to determine if an element is
expensive, the filter
will then only allow the expensive elements
through:
use function Zicht\Itertools\iterable; $isExpensive = fn($value, $key) => $value['price'] >= 10000; $expensiveTypes = iterable($vehicles)->filter($isExpensive)->map('type'); var_dump($expensiveTypes); // {1: 'car', 9: 'car'}
Or in Twig:
{{ dump(vehicles|it.filter(vehicle => vehicle.price >= 10000).map('type')) }}
Using the string getter strategy we can get only
the $vehicles
that are considered to be cool. For example:
use function Zicht\Itertools\iterable; $coolVehicleTypes = iterable($vehicles)->filter('is_cool')->map('type'); var_dump($coolVehicleTypes); // {5: 'unicicle', 9: 'car'}
Or in Twig:
{{ dump(vehicles|it.filter('is_cool').map('type')) }}
There are several common filter closures available
in filters.php. Calling these
function returns a closure that can be passed to filter
. For
example:
use Zicht\Itertools\util\Filters; use function Zicht\Itertools\iterable; $movieWords = iterable($words)->filter(Filters::in(['Shining', 'My little pony', 'Goonies'])); var_dump($movieWords); // {1: 'Goonies'}
Or in Twig:
{{ dump(words|it.filter(it.filters.in(['Shining', "My little pony', 'Goonies'])) }}
Sorting
sorted
converts one collection into another collection of equal size
but with the elements possibly reordered.
For example, using the null
getter strategy,
which is the default, we will sort using the element values in
ascending order:
use function Zicht\Itertools\iterable; $ordered = iterable($numbers)->sorted(); var_dump($ordered); // {0: 1, 2: 2, 1: 3, 4: 4, 3: 5}
Or in Twig:
{{ dump(numbers|it.sorted }}
The sorting algorithm will preserve the keys and is guaranteed to be stable. I.e. when elements are sorted using the same value, then the sorted order is guaranteed to be the same as the order of the input elements. This is contrary to the standard PHP sorting functions.
Using the closure getter strategy the returned value is used to determine the order. The closure is called exactly once per element, and the resulting values must be comparable. For example:
use function Zicht\Itertools\iterable; $getLower = fn($value, $key) => strtolower($value); $ordered = iterable($words)->sorted($getLower); var_dump($ordered); // {3: 'Bland', 1: 'Goonies', 2: 'oven', 0: 'Useful', 4: 'notorious'};
The mappings.php provides a mapping closure which returns a random number. This can be used to sort a collection in a random order. For example:
use Zicht\Itertools\util\Mappings; use function Zicht\Itertools\iterable; $randomized = iterable($words)->sorted(Mappings::random()); var_dump($randomized); // {... randomly ordere words ...}
Or in Twig:
{{ dump(words|it.sorted(it.mappings.random)) }}
Grouping
groupBy
converts one collection into one or more collections that
group the elements together on a specific criteria.
For example, using the string getter strategy we
can group all the $vehicles
of the same type together:
use function Zicht\Itertools\iterable; $vehiclesByType = iterable($vehicles)->groupBy('type'); var_dump($vehiclesByType); // {'bike': {1: [...]}, 'car': {0: [...], 3: [...]} 'unicicle': {2: [...]}}
Or in Twig:
{{ dump(vehicles|it.groupBy('type')) }}
Not that the original keys of the vehicles are still part of the
resulting groups, and the elements within each group keep the order
that they had in the input, i.e. it uses the stable sorting provided
by sorted
.
Reducing
reduce
converts a collection into a single value by calling a
closure of two arguments cumulatively to the elements in the
collection, from left to right.
For example, without any arguments reduce
will add all elements of
the collection together:
use function Zicht\Itertools\iterable; $sum = iterable($numbers)->reduce(); var_dump($sum); // 15
Or in Twig:
{{ dump(numbers|it.reduce) }}
In the above example, the default closure that is used looks like this:
public static function add($a, $b): \Closure { return $a + $b; }
Given that $numbers
consists of the elements {1, 3, 2, 5, 4}, the
add
closure is called four times:
$sum = Reductions::add(Reductions::add(Reductions::add(Reductions::add((1, 3), 2), 5), 4)); var_dump($sum); // 15
There are several common reduction closures available
in reductions.php. Calling
these functions returns a closure that can be passed to reduction
.
For example:
use Zicht\Itertools\util\Reductions; use function Zicht\Itertools\iterable; $scentence = iterable($words)->reduce(Reductions::join(' - ')); var_dump($scentence); // 'Useful - Goonies - oven - Bland - notorious'
Or in Twig:
{{ dump(words|it.reduce(it.reductions.join(' - ')) }}
Another common reduction is chaining multiple lists together into one list.
We call this process collapse. This process can also be achieved using reduce
and chain
together, however, because it is used frequently the collapse
helper
makes its usage easier, for example:
use function Zicht\Itertools\iterable; $flat = iterable([['one', 'two'], ['three']])->collapse(); var_dump($flat); // {0: 'one', 1: 'two', 0: 'three'}
Or in Twig:
{% set data = [['one', 'two'], ['three']] %} {{ dump(data|it.collapse) }}
Maintainer(s)
- Boudewijn Schoon boudewijn@zicht.nl
- Virginia Meijer virginia@zicht.nl