<commit_before>[![Build Status](https://scrutinizer-ci.com/g/zicht/itertools/badges/build.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/build-status/master)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/zicht/itertools/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/?branch=master) 
[![Code Coverage](https://scrutinizer-ci.com/g/zicht/itertools/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/?branch=master)

# 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](#mapping): `map` and `mapBy`
- [filtering](#filtering): `filter`, `difference`
- [sorting](#sorting): `sorted`
- [grouping](#grouping): `groupBy`
- [reducing](#reducing): `accumulate`, `collapse`, and `reduce`

## Usage
In order to use the available  itertools filters/functions via Twig, simply add this service definition in your `services.xml`
```php
<service id="zicht_itertools_twig_extension" class="Zicht\Itertools\twig\Extension">
    <tag name="twig.extension"/>
</service>

```
## 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:

```php
$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,
    ],
];

```
<commit_msg>Add Twig example to the readme<commit_after>[![Build Status](https://scrutinizer-ci.com/g/zicht/itertools/badges/build.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/build-status/master)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/zicht/itertools/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/?branch=master) 
[![Code Coverage](https://scrutinizer-ci.com/g/zicht/itertools/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/zicht/itertools/?branch=master)

# 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.

[Examples](#examples)

Common operations include:
- [mapping](#mapping): `map` and `mapBy`
- [filtering](#filtering): `filter`, `difference`
- [sorting](#sorting): `sorted`
- [grouping](#grouping): `groupBy`
- [reducing](#reducing): `accumulate`, `collapse`, and `reduce`

## Usage
In order to use the available  itertools filters/functions via Twig, simply add this service definition in your `services.xml`
```php
<service id="zicht_itertools_twig_extension" class="Zicht\Itertools\twig\Extension">
    <tag name="twig.extension"/>
</service>
```

## 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:

```php
$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:

```php
use function Zicht\Itertools\iterable;
use function Zicht\Itertools\filters\equals;

$vehicles = iterable($vehicles)
    ->filter(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:
```twig
{% for vehicle_color in vehicles
    |filter(filtering('equals', 'car', 'type'))
    |map('colors')
    |collapse
    |unique
    |sorted
%}
    {{ vehicle_color }}
{% endfor %}
```


{'fraction_non_alphanumeric': 0.18927911275415896, 'fraction_numerical': 0.013308687615526803, 'mean_word_length': 3.1273836765827614, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 62, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6010694', 'n_tokens_mistral': 2007, 'n_tokens_neox': 1864, 'n_words': 462}