Trabajar con iteradores
***********************
.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] es una clase estática con funciones para trabajar con iteradores. Su equivalente para los arrays es [Nette\Utils\Arrays|arrays].
Instalación:
```shell
composer require nette/utils
```
Todos los ejemplos suponen que está creado el siguiente alias:
```php
use Nette\Utils\Iterables;
```
contains(iterable $iterable, $value): bool .[method]
----------------------------------------------------
Busca un valor dado dentro de un iterador. Usa comparación estricta (`===`) para comprobar la coincidencia. Devuelve `true` si encuentra el valor, y `false` en caso contrario.
```php
Iterables::contains(new ArrayIterator([1, 2, 3]), 1); // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1'); // false
```
Este método resulta útil cuando necesita saber rápidamente si un valor concreto está en un iterador, sin recorrer manualmente todos los elementos.
containsKey(iterable $iterable, $key): bool .[method]
-----------------------------------------------------
Busca una clave dada dentro de un iterador. Usa comparación estricta (`===`) para comprobar la coincidencia. Devuelve `true` si encuentra la clave, y `false` en caso contrario.
```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]
--------------------------------------------------------------
Comprueba si todos los elementos del iterador cumplen la condición definida en `$predicate`. El callback `$predicate` tiene la firma `function ($value, $key, iterable $iterable): bool` y debe devolver `true` para todos los elementos para que el método `every()` devuelva `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 resulta útil para verificar que todos los elementos de una colección cumplen cierta condición, por ejemplo, si todos los números son menores que un valor dado.
filter(iterable $iterable, callable $predicate): Generator .[method]
--------------------------------------------------------------------
Crea un iterador nuevo que contiene solo aquellos elementos del original que cumplen la condición definida en `$predicate`. El callback `$predicate` tiene la firma `function ($value, $key, iterable $iterable): bool` y debe devolver `true` para los elementos que deban conservarse.
```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
// 1, 2
```
El método usa un generador, lo que significa que el filtrado se produce de forma incremental a medida que recorre el resultado. Esto es eficiente en memoria y permite procesar colecciones muy grandes. Si no recorre todos los elementos del iterador resultante, ahorra capacidad de cálculo, porque no se procesan todos los elementos del iterador original.
first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
-------------------------------------------------------------------------------------------
Devuelve el primer elemento del iterador. Si se indica `$predicate`, devuelve el primer elemento que cumple la condición. El callback `$predicate` tiene la firma `function ($value, $key, iterable $iterable): bool`. Si no se encuentra ningún elemento que encaje, se llama al callback `$else` (si se ha indicado) y se devuelve su resultado. Si no se indica `$else`, se devuelve `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 resulta útil cuando necesita obtener rápidamente el primer elemento de una colección, o el primero que cumple una condición concreta, sin recorrer manualmente toda la colección.
firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
----------------------------------------------------------------------------------------------
Devuelve la clave del primer elemento del iterador. Si se indica `$predicate`, devuelve la clave del primer elemento que cumple la condición. El callback `$predicate` tiene la firma `function ($value, $key, iterable $iterable): bool`. Si no se encuentra ningún elemento que encaje, se llama al callback `$else` (si se ha indicado) y se devuelve su resultado. Si no se indica `$else`, se devuelve `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]
-------------------------------------------------------------------
Crea un iterador nuevo aplicando el callback `$transformer` a cada elemento del iterador original. El callback `$transformer` tiene la firma `function ($value, $key, iterable $iterable): mixed` y su valor de retorno se usa como nuevo valor del elemento.
```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::map($iterator, fn($v) => $v * 2);
// 2, 4, 6
```
El método usa un generador, lo que significa que la transformación se produce de forma incremental a medida que recorre el resultado. Esto es eficiente en memoria y permite procesar colecciones muy grandes. Si no recorre todos los elementos del iterador resultante, ahorra capacidad de cálculo, porque no se procesan todos los elementos del iterador original.
mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
---------------------------------------------------------------------------
Crea un iterador nuevo transformando los valores y las claves del original. El callback `$transformer` tiene la firma `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Si `$transformer` devuelve `null`, el elemento se salta. En los elementos conservados, el primer elemento del array devuelto se usa como nueva clave y el segundo, como nuevo 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']
```
Igual que `map()`, este método usa un generador para el procesamiento incremental y la eficiencia en memoria. Esto permite trabajar con colecciones grandes y ahorrar capacidad de cálculo cuando solo se recorre parcialmente el resultado.
memoize(iterable $iterable): IteratorAggregate .[method]
--------------------------------------------------------
Crea un envoltorio alrededor de un iterador que guarda en caché sus claves y valores durante la iteración. Esto permite iterar repetidamente sobre los datos sin tener que recorrer de nuevo el origen original.
```php
$iterator = /* ... */; // datos que no se pueden recorrer varias veces
$memoized = Iterables::memoize($iterator);
// Ahora puede recorrer $memoized varias veces sin perder datos
```
Este método resulta útil cuando necesita iterar varias veces sobre el mismo conjunto de datos, pero el iterador original no permite repetir la iteración o volver a recorrerlo sería costoso (por ejemplo, leer datos de una base de datos o de un archivo).
repeatable(callable $factory): IteratorAggregate .[method]{data-version:4.0.10}
-------------------------------------------------------------------------------
Permite iterar repetidamente sobre objetos que de otro modo no lo admiten, normalmente los [generadores de PHP |https://www.php.net/manual/en/language.generators.overview.php]. El método `repeatable()` resuelve el problema con elegancia: en lugar de pasar el propio iterador, se pasa una función que lo crea. Esa factory se llama después automáticamente en cada bucle de iteración.
```php
// Un generador estándar que no se puede recorrer dos veces
$generator = function () {
yield 'A';
yield 'B';
};
$iterator = Iterables::repeatable($generator);
foreach ($iterator as $v) echo $v; // Imprime: AB
foreach ($iterator as $v) echo $v; // Imprime: AB (el generador se ejecutó de nuevo)
```
Este método es una alternativa a [#memoize()] en situaciones donde trabaja con **grandes cantidades de datos**, ya que `repeatable()` no cachea los datos, sino que los genera de nuevo en cada iteración.
some(iterable $iterable, callable $predicate): bool .[method]
-------------------------------------------------------------
Comprueba si al menos un elemento del iterador cumple la condición definida en `$predicate`. El callback `$predicate` tiene la firma `function ($value, $key, iterable $iterable): bool` y debe devolver `true` para al menos un elemento para que el método `some()` devuelva `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 resulta útil para verificar rápidamente si al menos un elemento de una colección cumple cierta condición, por ejemplo, si la colección contiene al menos un número par.
Vea [#every()].
toIterator(iterable $iterable): Iterator .[method]
--------------------------------------------------
Convierte cualquier objeto iterable (array, Traversable) en un Iterator. Si la entrada ya es un Iterator, se devuelve sin cambios.
```php
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Ahora tiene un Iterator en lugar de un array
```
Este método resulta útil cuando necesita asegurarse de disponer de un Iterator, sea cual sea el tipo de datos de entrada. Puede venir bien al crear funciones que trabajan con distintos tipos de datos iterables.
Trabajar con iteradores
Nette\Utils\Iterables es una clase estática con
funciones para trabajar con iteradores. Su equivalente para los arrays es Nette\Utils\Arrays.
Instalación:
composer require nette/utils
Todos los ejemplos suponen que está creado el siguiente alias:
use Nette\Utils\Iterables;
contains (iterable $iterable, $value): bool
Busca un valor dado dentro de un iterador. Usa comparación estricta (===) para comprobar la coincidencia.
Devuelve true si encuentra el valor, y false en caso contrario.
Iterables::contains(new ArrayIterator([1, 2, 3]), 1); // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1'); // false
Este método resulta útil cuando necesita saber rápidamente si un valor concreto está en un iterador, sin recorrer
manualmente todos los elementos.
containsKey (iterable $iterable,
$key): bool
Busca una clave dada dentro de un iterador. Usa comparación estricta (===) para comprobar la coincidencia.
Devuelve true si encuentra la clave, y false en caso contrario.
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0); // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4); // false
every (iterable $iterable, callable
$predicate): bool
Comprueba si todos los elementos del iterador cumplen la condición definida en $predicate. El callback
$predicate tiene la firma function ($value, $key, iterable $iterable): bool y debe devolver
true para todos los elementos para que el método every() devuelva true.
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isBelowThreshold = fn($value) => $value < 40;
$res = Iterables::every($iterator, $isBelowThreshold); // true
Este método resulta útil para verificar que todos los elementos de una colección cumplen cierta condición, por ejemplo, si
todos los números son menores que un valor dado.
filter (iterable $iterable, callable
$predicate): Generator
Crea un iterador nuevo que contiene solo aquellos elementos del original que cumplen la condición definida en
$predicate. El callback $predicate tiene la firma
function ($value, $key, iterable $iterable): bool y debe devolver true para los elementos que deban
conservarse.
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
// 1, 2
El método usa un generador, lo que significa que el filtrado se produce de forma incremental a medida que recorre el
resultado. Esto es eficiente en memoria y permite procesar colecciones muy grandes. Si no recorre todos los elementos del iterador
resultante, ahorra capacidad de cálculo, porque no se procesan todos los elementos del iterador original.
first (iterable $iterable, ?callable
$predicate=null, ?callable $else=null): mixed
Devuelve el primer elemento del iterador. Si se indica $predicate, devuelve el primer elemento que cumple la
condición. El callback $predicate tiene la firma function ($value, $key, iterable $iterable): bool. Si
no se encuentra ningún elemento que encaje, se llama al callback $else (si se ha indicado) y se devuelve su
resultado. Si no se indica $else, se devuelve null.
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 resulta útil cuando necesita obtener rápidamente el primer elemento de una colección, o el primero que cumple
una condición concreta, sin recorrer manualmente toda la colección.
firstKey (iterable $iterable, ?callable
$predicate=null, ?callable $else=null): mixed
Devuelve la clave del primer elemento del iterador. Si se indica $predicate, devuelve la clave del primer elemento
que cumple la condición. El callback $predicate tiene la firma
function ($value, $key, iterable $iterable): bool. Si no se encuentra ningún elemento que encaje, se llama al
callback $else (si se ha indicado) y se devuelve su resultado. Si no se indica $else, se
devuelve null.
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
Crea un iterador nuevo aplicando el callback $transformer a cada elemento del iterador original. El callback
$transformer tiene la firma function ($value, $key, iterable $iterable): mixed y su valor de retorno se
usa como nuevo valor del elemento.
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::map($iterator, fn($v) => $v * 2);
// 2, 4, 6
El método usa un generador, lo que significa que la transformación se produce de forma incremental a medida que recorre el
resultado. Esto es eficiente en memoria y permite procesar colecciones muy grandes. Si no recorre todos los elementos del iterador
resultante, ahorra capacidad de cálculo, porque no se procesan todos los elementos del iterador original.
mapWithKeys (iterable $iterable, callable
$transformer): Generator
Crea un iterador nuevo transformando los valores y las claves del original. El callback $transformer tiene la
firma function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Si $transformer devuelve
null, el elemento se salta. En los elementos conservados, el primer elemento del array devuelto se usa como nueva
clave y el segundo, como nuevo valor.
$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']
Igual que map(), este método usa un generador para el procesamiento incremental y la eficiencia en memoria. Esto
permite trabajar con colecciones grandes y ahorrar capacidad de cálculo cuando solo se recorre parcialmente el resultado.
memoize (iterable $iterable): IteratorAggregate
Crea un envoltorio alrededor de un iterador que guarda en caché sus claves y valores durante la iteración. Esto permite
iterar repetidamente sobre los datos sin tener que recorrer de nuevo el origen original.
$iterator = /* ... */; // datos que no se pueden recorrer varias veces
$memoized = Iterables::memoize($iterator);
// Ahora puede recorrer $memoized varias veces sin perder datos
Este método resulta útil cuando necesita iterar varias veces sobre el mismo conjunto de datos, pero el iterador original no
permite repetir la iteración o volver a recorrerlo sería costoso (por ejemplo, leer datos de una base de datos o de un
archivo).
repeatable (callable
$factory): IteratorAggregate
Permite iterar repetidamente sobre objetos que de otro modo no lo admiten, normalmente los generadores de PHP. El método repeatable()
resuelve el problema con elegancia: en lugar de pasar el propio iterador, se pasa una función que lo crea. Esa factory se llama
después automáticamente en cada bucle de iteración.
// Un generador estándar que no se puede recorrer dos veces
$generator = function () {
yield 'A';
yield 'B';
};
$iterator = Iterables::repeatable($generator);
foreach ($iterator as $v) echo $v; // Imprime: AB
foreach ($iterator as $v) echo $v; // Imprime: AB (el generador se ejecutó de nuevo)
Este método es una alternativa a memoize() en situaciones donde trabaja con grandes cantidades
de datos, ya que repeatable() no cachea los datos, sino que los genera de nuevo en cada iteración.
some (iterable $iterable, callable
$predicate): bool
Comprueba si al menos un elemento del iterador cumple la condición definida en $predicate. El callback
$predicate tiene la firma function ($value, $key, iterable $iterable): bool y debe devolver
true para al menos un elemento para que el método some() devuelva true.
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isEven = fn($value) => $value % 2 === 0;
$res = Iterables::some($iterator, $isEven); // true
Este método resulta útil para verificar rápidamente si al menos un elemento de una colección cumple cierta condición, por
ejemplo, si la colección contiene al menos un número par.
Vea every().
toIterator (iterable $iterable): Iterator
Convierte cualquier objeto iterable (array, Traversable) en un Iterator. Si la entrada ya es un Iterator, se devuelve sin
cambios.
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Ahora tiene un Iterator en lugar de un array
Este método resulta útil cuando necesita asegurarse de disponer de un Iterator, sea cual sea el tipo de datos de entrada.
Puede venir bien al crear funciones que trabajan con distintos tipos de datos iterables.