Funzioni della matrice

Questa pagina tratta delle classi Nette\Utils\Arrays, ArrayHash e ArrayList, relative agli array.

Installazione:

composer require nette/utils

Array

Nette\Utils\Arrays è una classe statica che contiene una manciata di pratiche funzioni per gli array. Il suo equivalente per gli iteratori è Nette\Utils\Iterables.

Gli esempi seguenti presuppongono che sia definito il seguente alias di classe:

use Nette\Utils\Arrays;

associate(array $array, mixed $path): array|\stdClass

La funzione trasforma in modo flessibile l'oggetto $array in un array associativo o in oggetti secondo il percorso specificato $path. Il percorso può essere una stringa o un array. È costituito dai nomi delle chiavi dell'array di input e da operatori come ‘[]’, ‘->’, ‘=’ e ‘|’. Lancia Nette\InvalidArgumentException se il percorso non è valido.

// Conversione in un array associativo con una chiave semplice
$arr = [
    ['name' => 'John', 'age' => 11],
    ['name' => 'Mary', 'age' => null],
    //...
];
$result = Arrays::associate($arr, 'name');
// $result = ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]

// assegnare valori da una chiave a un'altra utilizzando l'operatore =
$result = Arrays::associate($arr, 'name=age'); // o ['name', '=', 'age']
// $result = ['John' => 11, 'Mary' => null, ...]

// creare un oggetto utilizzando l'operatore ->
$result = Arrays::associate($arr, '->name'); // o ['->', 'name']
// $result = (object) ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]

// combinando le chiavi con l'operatore |
$result = Arrays::associate($arr, 'name|age'); // oppure ['name', '|', 'age']
// $result: ['John' => ['name' => 'John', 'age' => 11], 'Paul' => ['name' => 'Paul', 'age' => 44]]

// aggiungere a un array usando []
$result = Arrays::associate($arr, 'name[]'); // oppure ['name', '[]']
// $result: ['John' => [['name' => 'John', 'age' => 22], ['name' => 'John', 'age' => 11]]]

contains(array $array, $value): bool

Verifica la presenza di un valore in un array. Utilizza un confronto rigoroso (===)

Arrays::contains([1, 2, 3], 1);    // true
Arrays::contains(['1', false], 1); // false

every(array $array, callable $predicate): bool

Verifica se tutti gli elementi dell'array superano il test implementato dalla funzione fornita, che ha la firma function ($value, $key, array $array): bool.

$array = [1, 30, 39, 29, 10, 13];
$isBelowThreshold = fn($value) => $value < 40;
$res = Arrays::every($array, $isBelowThreshold); // true

Vedere some().

filter(array $array, callable $predicate): array

Restituisce un nuovo array contenente tutte le coppie chiave-valore corrispondenti al dato $predicate. Il callback ha la firma function ($value, int|string $key, array $array): bool.

Arrays::filter(
	['a' => 1, 'b' => 2, 'c' => 3],
	fn($v) => $v < 3,
);
// ['a' => 1, 'b' => 2]

first(array $array, ?callable $predicate=null, ?callable $else=null): mixed

Restituisce il primo elemento (che corrisponde al predicato specificato, se dato). Se non esiste un elemento, restituisce il risultato dell'invocazione di $else o null.
$predicate ha la firma function ($value, int|string $key, array $array): bool.

Non modifica il puntatore interno, a differenza di reset(). I parametri $predicate e $else esistono dalla versione 4.0.4.

Arrays::first([1, 2, 3]);                   // 1
Arrays::first([1, 2, 3], fn($v) => $v > 2); // 3
Arrays::first([]);                          // null
Arrays::first([], else: fn() => false);     // false

Vedere last().

firstKey(array $array, ?callable $predicate=null): int|string|null

Restituisce la chiave del primo elemento (che corrisponde al predicato specificato, se dato) o null se non esiste un elemento. $predicate ha la firma function ($value, int|string $key, array $array): bool.

Arrays::firstKey([1, 2, 3]);                   // 0
Arrays::firstKey([1, 2, 3], fn($v) => $v > 2); // 2
Arrays::firstKey(['a' => 1, 'b' => 2]);        // 'a'
Arrays::firstKey([]);                          // null

Vedere lastKey().

flatten(array $array, bool $preserveKeys=false): array

Trasforma un array multidimensionale in un array piatto.

$array = Arrays::flatten([1, 2, [3, 4, [5, 6]]]);
// $array = [1, 2, 3, 4, 5, 6];

get(array $array, string|int|array $key, mixed $default=null): mixed

Restituisce $array[$key] item. Se non esiste, viene lanciato Nette\InvalidArgumentException, a meno che non venga impostato un valore predefinito come terzo parametro.

// se $array['foo'] non esiste, lancia un'eccezione
$value = Arrays::get($array, 'foo');

// se $array['foo'] non esiste, restituisce 'bar'
$value = Arrays::get($array, 'foo', 'bar');

L'argomento $key può anche essere un array.

$array = ['color' => ['favorite' => 'red'], 5];

$value = Arrays::get($array, ['color', 'favorite']);
// returns 'red'

getRef(array &$array, string|int|array $key): mixed

Ottiene il riferimento al dato $array[$key]. Se l'indice non esiste, ne viene creato uno nuovo con il valore null.

$valueRef = & Arrays::getRef($array, 'foo');
// restituisce il riferimento a $array['foo'].

Funziona con gli array multidimensionali e con get().

$value = & Arrays::get($array, ['colore', 'preferito']);
// restituisce il riferimento $array['colore']['preferito']

grep(array $array, string $pattern, bool $invert=false): array

Restituisce solo gli elementi dell'array che corrispondono a un'espressione regolare $pattern. Se $invert è true, restituisce gli elementi che non corrispondono. Un errore di compilazione o di esecuzione della Regex lancia Nette\RegexpException.

$filteredArray = Arrays::grep($array, '~^\d+$~');
// restituisce solo elementi numerici

insertAfter(array &$array, string|int|null $key, array $inserted): void

Inserisce il contenuto dell'array $inserted nell'array $array immediatamente dopo $key. Se $key è null (o non esiste), viene inserito alla fine.

$array = ['first' => 10, 'second' => 20];
Arrays::insertAfter($array, 'first', ['hello' => 'world']);
// $array = ['first' => 10, 'hello' => 'world', 'second' => 20];

insertBefore(array &$array, string|int|null $key, array $inserted): void

Inserisce il contenuto della matrice $inserted in $array prima di $key. Se $key è null (o non esiste), viene inserito all'inizio.

$array = ['first' => 10, 'second' => 20];
Arrays::insertBefore($array, 'first', ['hello' => 'world']);
// $array = ['hello' => 'world', 'first' => 10, 'second' => 20];

invoke(iterable $callbacks, …$args): array

Invoca tutti i callback e restituisce un array di risultati.

$callbacks = [
	'+' => fn($a, $b) => $a + $b,
	'*' => fn($a, $b) => $a * $b,
];

$array = Arrays::invoke($callbacks, 5, 11);
// $array = ['+' => 16, '*' => 55];

invokeMethod(iterable $objects, string $method, …$args): array

Invoca il metodo su ogni oggetto di un array e restituisce un array di risultati.

$objects = ['a' => $obj1, 'b' => $obj2];

$array = Arrays::invokeMethod($objects, 'foo', 1, 2);
// $array = ['a' => $obj1->foo(1, 2), 'b' => $obj2->foo(1, 2)];

isList(array $array): bool

Verifica se l'array è indicizzato in ordine crescente di chiavi numeriche a partire da zero, ovvero un elenco.

Arrays::isList(['a', 'b', 'c']); // true
Arrays::isList([4 => 1, 2, 3]); // false
Arrays::isList(['a' => 1, 'b' => 2]); // false

last(array $array, ?callable $predicate=null, ?callable $else=null): mixed

Restituisce l'ultimo elemento (che corrisponde al predicato specificato, se dato). Se non esiste un elemento, restituisce il risultato dell'invocazione di $else o null.
$predicate ha la firma function ($value, int|string $key, array $array): bool.

Non modifica il puntatore interno, a differenza di end(). I parametri $predicate e $else esistono dalla versione 4.0.4.

Arrays::last([1, 2, 3]);                   // 3
Arrays::last([1, 2, 3], fn($v) => $v < 3); // 2
Arrays::last([]);                          // null
Arrays::last([], else: fn() => false);     // false

Vedere prima().

lastKey(array $array, ?callable $predicate=null): int|string|null

Restituisce la chiave dell'ultimo elemento (che corrisponde al predicato specificato, se dato) o null se non esiste un elemento. $predicate ha la firma function ($value, int|string $key, array $array): bool.

Arrays::lastKey([1, 2, 3]);                    // 2
Arrays::lastKey([1, 2, 3], fn($v) => $v < 3);  // 1
Arrays::lastKey(['a' => 1, 'b' => 2]);         // 'b'
Arrays::lastKey([]);                           // null

Vedere firstKey().

map(array $array, callable $transformer): array

Richiama $transformer su tutti gli elementi dell'array e restituisce l'array dei valori di ritorno. Il callback ha la firma function ($value, $key, array $array): bool.

$array = ['foo', 'bar', 'baz'];
$res = Arrays::map($array, fn($value) => $value . $value);
// $res = ['foofoo', 'barbar', 'bazbaz']

mergeTree(array $array1, array $array2): array

Unisce ricorsivamente due campi. È utile, ad esempio, per unire strutture ad albero. Si comporta come l'operatore `+' per gli array, cioè aggiunge una coppia chiave/valore dal secondo array al primo e mantiene il valore dal primo array nel caso di una collisione di chiavi.

$array1 = ['colore' => ['preferito' => 'rosso'], 5];
$array2 = [10, 'colore' => ['preferito' => 'verde', 'blu']];

$array = Arrays::mergeTree($array1, $array2);
// $array = ['colore' => ['preferito' => 'rosso', 'blu'], 5];

I valori del secondo array vengono sempre aggiunti al primo. La scomparsa del valore 10 dal secondo array può sembrare un po' confusa. Va notato che questo valore, così come il valore 5 in the first array have the same numeric key 0, quindi nel campo risultante c'è solo un elemento del primo array.

normalize(array $array, string $filling=null): array

Normalizza l'array in un array associativo. Sostituisce le chiavi numeriche con i loro valori, il nuovo valore sarà $filling.

$array = Arrays::normalize([1 => 'first', 'a' => 'second']);
// $array = ['first' => null, 'a' => 'second'];

$array = Arrays::normalize([1 => 'first', 'a' => 'second'], 'foobar');
// $array = ['first' => 'foobar', 'a' => 'second'];

pick(array &$array, string|int $key, mixed $default=null): mixed

Restituisce e rimuove il valore di un elemento da un array. Se non esiste, lancia un'eccezione o restituisce $default, se fornito.

$array = [1 => 'foo', null => 'bar'];
$a = Arrays::pick($array, null);
// $a = 'bar'
$b = Arrays::pick($array, 'not-exists', 'foobar');
// $b = 'foobar'
$c = Arrays::pick($array, 'not-exists');
// throws Nette\InvalidArgumentException

renameKey(array &$array, string|int $oldKey, string|int $newKey): bool

Rinomina una chiave. Restituisce true se la chiave è stata trovata nell'array.

$array = ['first' => 10, 'second' => 20];
Arrays::renameKey($array, 'first', 'renamed');
// $array = ['renamed' => 10, 'second' => 20];

getKeyOffset(array $array, string|int $key): ?int

Restituisce la posizione a indice zero della chiave dell'array dato. Restituisce null se la chiave non viene trovata.

$array = ['first' => 10, 'second' => 20];
$position = Arrays::getKeyOffset($array, 'first'); // restituisce 0
$position = Arrays::getKeyOffset($array, 'second'); // restituisce 1
$position = Arrays::getKeyOffset($array, 'not-exists'); // restituisce null

some(array $array, callable $predicate): bool

Verifica se almeno un elemento dell'array supera il test implementato dal callback fornito con la firma function ($value, $key, array $array): bool.

$array = [1, 2, 3, 4];
$isEven = fn($value) => $value % 2 === 0;
$res = Arrays::some($array, $isEven); // true

Vedere every().

toKey(mixed $key): string|int

Converte un valore in una chiave di array, che può essere un intero o una stringa.

Arrays::toKey('1');  // 1
Arrays::toKey('01'); // '01'

toObject(iterable $array, object $object): object

Copia gli elementi dell'array $array nell'oggetto $object e lo restituisce.

$obj = new stdClass;
$array = ['foo' => 1, 'bar' => 2];
Arrays::toObject($array, $obj); // imposta $obj->foo = 1; $obj->bar = 2;

wrap(array $array, string $prefix=`''`, string $suffix=`''`): array

Lancia ogni elemento dell'array come stringa e lo racchiude con $prefix e $suffix.

$array = Arrays::wrap(['a' => 'red', 'b' => 'green'], '<<', '>>');
// $array = ['a' => '<<red>>', 'b' => '<<green>>'];

ArrayHash

L'oggetto Nette\Utils\ArrayHash è il discendente della classe generica stdClass e la estende alla possibilità di trattarla come un array, ad esempio accedendo ai membri usando le parentesi quadre:

$hash = new Nette\Utils\ArrayHash;
$hash['foo'] = 123;
$hash->bar = 456; // funziona anche in notazione oggetto
$hash->foo; // 123

È possibile utilizzare la funzione count($hash) per ottenere il numero di elementi.

È possibile iterare su un oggetto come su un array, anche con un riferimento:

foreach ($hash as $key => $value) {
	// ...
}

foreach ($hash as $key => &$value) {
	$value = 'nuovo valore';
}

Gli array esistenti possono essere trasformati in ArrayHash utilizzando from():

$array = ['foo' => 123, 'bar' => 456];

$hash = Nette\Utils\ArrayHash::from($array);
$hash->foo; // 123
$hash->bar; // 456

La trasformazione è ricorsiva:

$array = ['foo' => 123, 'inner' => ['a' => 'b']];

$hash = Nette\Utils\ArrayHash::from($array);
$hash->inner; // oggetto ArrayHash
$hash->inner->a; // 'b'
$hash['inner']['a']; // 'b'

Può essere evitata con il secondo parametro:

$hash = Nette\Utils\ArrayHash::from($array, false);
$hash->inner; // array

Trasformazione in array:

$array = (array) $hash;

ArrayList

Nette\Utils\ArrayList rappresenta un array lineare in cui gli indici sono solo numeri interi ascendenti a partire da 0.

$list = new Nette\Utils\ArrayList;
$list[] = 'a';
$list[] = 'b';
$list[] = 'c';
// ArrayList(0 => 'a', 1 => 'b', 2 => 'c')
count($list); // 3

È possibile utilizzare la funzione count($list) per ottenere il numero di elementi.