Funções de iterador
Nette\Utils\Iterables é uma classe estática com funções para trabalhar com iteradores. Sua contraparte para matrizes é Nette\Utils\Arrays.
Instalação:
composer require nette/utils
Todos os exemplos pressupõem que o alias a seguir foi criado:
use Nette\Utils\Iterables;
contains (iterable $iterable, $value): bool
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.
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
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.
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0); // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4); // false
every (iterable $iterable, callable $predicate): bool
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.
$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
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.
$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
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.
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
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.
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
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.
$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
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.
$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
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.
$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
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.
$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().
toIterator (iterable $iterable): Iterator
Converte qualquer objeto iterável (matriz, Traversable) em um Iterator. Se a entrada já for um Iterator, ela será retornada inalterada.
$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.
