Funções de iterador
*******************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] é uma classe estática com funções para trabalhar com iteradores. Sua contraparte para matrizes é [Nette\Utils\Arrays |arrays].


Instalação:

```shell
composer require nette/utils
```

Todos os exemplos pressupõem que o alias a seguir foi criado:

```php
use Nette\Utils\Iterables;
```


contains(iterable $iterable, $value): bool .[method]
----------------------------------------------------

Procura por um determinado valor em um iterador. Usa comparação rigorosa (`===`) para verificar se há correspondência. Retorna `true` se o valor for encontrado, caso contrário, `false`.

```php
Iterables::contains(new ArrayIterator([1, 2, 3]), 1);    // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1');  // false
```

Esse método é útil quando você precisa determinar rapidamente se um valor específico está presente em um iterador sem iterar manualmente por todos os elementos.


containsKey(iterable $iterable, $key): bool .[method]
-----------------------------------------------------

Procura por uma determinada chave em um iterador. Usa comparação rigorosa (`===`) para verificar se há correspondência. Retorna `true` se a chave for encontrada, caso contrário, `false`.

```php
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false
```


every(iterable $iterable, callable $predicate): bool .[method]
--------------------------------------------------------------

Verifica se todos os elementos do iterador satisfazem a condição definida em `$predicate`. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool` e deve retornar `true` para cada elemento para que o método `every()` retorne `true`.

```php
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isBelowThreshold = fn($value) => $value < 40;
$res = Iterables::every($iterator, $isBelowThreshold); // true
```

Esse método é útil para verificar se todos os elementos de uma coleção atendem a uma determinada condição, como, por exemplo, se todos os números estão abaixo de um valor específico.


filter(iterable $iterable, callable $predicate): Generator .[method]
--------------------------------------------------------------------

Cria um novo iterador que contém somente os elementos do iterador original que satisfazem a condição definida em `$predicate`. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool` e deve retornar `true` para os elementos que devem ser mantidos.

```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
// 1, 2
```

O método usa um gerador, o que significa que a filtragem ocorre de forma incremental durante a iteração. Isso é eficiente em termos de memória e permite lidar com coleções muito grandes. Se você não iterar por todos os elementos do iterador resultante, economizará esforço computacional, pois nem todos os elementos do iterador original serão processados.


first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
-------------------------------------------------------------------------------------------

Retorna o primeiro elemento do iterador. Se `$predicate` for fornecido, ele retornará o primeiro elemento que satisfaz a condição fornecida. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool`. Se nenhum elemento correspondente for encontrado, a função `$else` (se fornecida) será chamada e seu resultado será retornado. Se `$else` não for fornecido, `null` será retornado.

```php
Iterables::first(new ArrayIterator([1, 2, 3]));                   // 1
Iterables::first(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 3
Iterables::first(new ArrayIterator([]));                          // null
Iterables::first(new ArrayIterator([]), else: fn() => false);     // false
```

Esse método é útil quando você precisa recuperar rapidamente o primeiro elemento de uma coleção ou o primeiro elemento que atende a uma determinada condição sem iterar manualmente por toda a coleção.


firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
----------------------------------------------------------------------------------------------

Retorna a chave do primeiro elemento do iterador. Se `$predicate` for fornecido, ele retornará a chave do primeiro elemento que satisfaz a condição fornecida. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool`. Se nenhum elemento correspondente for encontrado, a função `$else` (se fornecida) será chamada e seu resultado será retornado. Se `$else` não for fornecido, `null` será retornado.

```php
Iterables::firstKey(new ArrayIterator([1, 2, 3]));                   // 0
Iterables::firstKey(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 2
Iterables::firstKey(new ArrayIterator(['a' => 1, 'b' => 2]));        // 'a'
Iterables::firstKey(new ArrayIterator([]));                          // null
```


map(iterable $iterable, callable $transformer): Generator .[method]
-------------------------------------------------------------------

Cria um novo iterador aplicando a função `$transformer` a cada elemento do iterador original. A função `$transformer` tem a assinatura `function ($value, $key, iterable $iterable): mixed` e seu valor de retorno é usado como o novo valor do elemento.

```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::map($iterator, fn($v) => $v * 2);
// 2, 4, 6
```

O método usa um gerador, o que significa que a transformação ocorre de forma incremental durante a iteração. Isso é eficiente em termos de memória e permite lidar com coleções muito grandes. Se você não iterar por todos os elementos do iterador resultante, economizará esforço computacional, pois nem todos os elementos do iterador original serão processados.


mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
---------------------------------------------------------------------------

Cria um novo iterador transformando os valores e as chaves do iterador original. A função `$transformer` tem a assinatura `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Se `$transformer` retornar `null`, o elemento será ignorado. Para elementos retidos, o primeiro elemento da matriz retornada é usado como a nova chave e o segundo elemento como o novo valor.

```php
$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']
```

Assim como o `map()`, esse método usa um gerador para processamento incremental e eficiência de memória. Isso permite trabalhar com grandes coleções e economizar esforço computacional ao processar apenas parte do resultado.


memoize(iterable $iterable): IteratorAggregate .[method]
--------------------------------------------------------

Cria um invólucro em torno de um iterador que armazena em cache suas chaves e valores durante a iteração. Isso permite a iteração repetida dos dados sem a necessidade de reprocessar a fonte de dados original.

```php
$iterator = /* data that cannot be iterated multiple times */
$memoized = Iterables::memoize($iterator);
// Now you can iterate $memoized multiple times without data loss
```

Esse método é útil em situações em que você precisa iterar sobre o mesmo conjunto de dados várias vezes, mas o iterador original não oferece suporte à iteração repetida ou a iteração repetida seria dispendiosa (por exemplo, ler dados de um banco de dados ou arquivo).


some(iterable $iterable, callable $predicate): bool .[method]
-------------------------------------------------------------

Verifica se pelo menos um elemento do iterador satisfaz a condição definida em `$predicate`. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool` e deve retornar `true` para pelo menos um elemento para que o método `some()` retorne `true`.

```php
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isEven = fn($value) => $value % 2 === 0;
$res = Iterables::some($iterator, $isEven); // true
```

Esse método é útil para verificar rapidamente se há pelo menos um elemento em uma coleção que atenda a uma determinada condição, como, por exemplo, se a coleção contém pelo menos um número par.

Consulte [every() |#every()].


toIterator(iterable $iterable): Iterator .[method]
--------------------------------------------------

Converte qualquer objeto iterável (matriz, Traversable) em um Iterator. Se a entrada já for um Iterator, ela será retornada inalterada.

```php
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Now you have an Iterator instead of an array
```

Esse método é útil quando você precisa garantir que tem um Iterator, independentemente do tipo de dados de entrada. Isso pode ser útil ao criar funções que funcionam com diferentes tipos de dados iteráveis.