Trabalhando com iteradores

**************************

.[perex]{data-version:4.0.4}

[api:Nette\Utils\Iterables] é uma classe estática com funções para trabalhar com iteradores. Seu equivalente para arrays é [Nette\Utils\Arrays|arrays].

Instalação:

```shell

composer require nette/utils

```

Todos os exemplos assumem que um alias foi criado:

```php

use Nette\Utils\Iterables;

```

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

----------------------------------------------------

Procura o valor especificado no iterador. Usa comparação estrita (`===`) para verificar a 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

```

Este método é útil quando você precisa descobrir rapidamente se um valor específico está no iterador sem ter que percorrer todos os elementos manualmente.

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

-----------------------------------------------------

Procura a chave especificada no iterador. Usa comparação estrita (`===`) para verificar a 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

```

Este método é útil para verificar se todos os elementos em uma coleção satisfazem uma determinada condição, por exemplo, se todos os números são menores que um determinado valor.

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

--------------------------------------------------------------------

Cria um novo iterador que contém apenas 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 utiliza um gerador, o que significa que a filtragem ocorre gradualmente ao percorrer o resultado. Isso é eficiente em termos de memória e permite processar coleções muito grandes. Se você não percorrer todos os elementos do iterador resultante, economizará poder de processamento, 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 especificado, retorna o primeiro elemento que satisfaz a condição dada. A função `$predicate` tem a assinatura `function ($value, $key, iterable $iterable): bool`. Se nenhum elemento correspondente for encontrado, a função `$else` é chamada (se especificada) e seu resultado é retornado. Se `$else` não for especificado, retorna `null`.

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

```

Este método é útil quando você precisa obter rapidamente o primeiro elemento de uma coleção ou o primeiro elemento que satisfaz uma determinada condição, sem ter que percorrer toda a coleção manualmente.

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

----------------------------------------------------------------------------------------------

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

```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 utiliza um gerador, o que significa que a transformação ocorre gradualmente ao percorrer o resultado. Isso é eficiente em termos de memória e permite processar coleções muito grandes. Se você não percorrer todos os elementos do iterador resultante, economizará poder de processamento, 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 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 é ignorado. Para os elementos mantidos, o primeiro elemento do array retornado é 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 `map()`, este método utiliza um gerador para processamento gradual e trabalho eficiente com a memória. Isso permite trabalhar com grandes coleções e economizar poder de processamento ao percorrer parcialmente o resultado.

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

--------------------------------------------------------

Cria um invólucro em torno do 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 percorrer novamente a fonte de dados original.

```php

$iterator = /* dados que não podem ser iterados mais de uma vez */;

$memoized = Iterables::memoize($iterator);

// Agora você pode iterar $memoized várias vezes sem perder dados

```

Este método é útil em situações em que você precisa percorrer o mesmo conjunto de dados várias vezes, mas o iterador original não permite iteração repetida ou a passagem repetida seria cara (por exemplo, ao 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

```

Este método é útil para verificar rapidamente se existe pelo menos um elemento na coleção que satisfaz uma determinada condição, por exemplo, se a coleção contém pelo menos um número par.

Veja [#every()].

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

--------------------------------------------------

Converte qualquer objeto iterável (array, Traversable) em um Iterator. Se a entrada já for um Iterator, retorna-o sem alterações.

```php

$array = [1, 2, 3];

$iterator = Iterables::toIterator($array);

// Agora você tem um Iterator em vez de um array

```

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