Funcții de matrice

Această pagină se referă la clasele Nette\Utils\Arrays, ArrayHash și ArrayList, care sunt legate de array-uri.

Instalare:

composer require nette/utils

Array-uri

Nette\Utils\Arrays este o clasă statică, care conține o serie de funcții practice de matrice. Echivalentul său pentru iteratori este Nette\Utils\Iterables.

Exemplele următoare presupun că este definit următorul alias de clasă:

use Nette\Utils\Arrays;

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

Funcția transformă în mod flexibil $array într-o matrice asociativă sau obiecte în funcție de calea specificată $path. Calea poate fi un șir de caractere sau o matrice. Aceasta constă din numele cheilor din tabloul de intrare și operatori precum “[]”, “->”, “=” și “|”. Se aruncă Nette\InvalidArgumentException în cazul în care calea nu este validă.

// conversia într-un tablou asociativ utilizând o cheie simplă
$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]]

// atribuirea de valori de la o cheie la alta cu ajutorul operatorului =.
$result = Arrays::associate($arr, 'name=age'); // sau ['name', '=', 'age']
// $result = ['John' => 11, 'Mary' => null, ...]

// crearea unui obiect cu ajutorul operatorului ->
$result = Arrays::associate($arr, '->name'); // sau ['->', 'name']
// $result = (object) ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]

// combinarea cheilor cu ajutorul operatorului |
$result = Arrays::associate($arr, 'name|age'); // sau ['name', '|', 'age']
// $result: ['John' => ['name' => 'John', 'age' => 11], 'Paul' => ['name' => 'Paul', 'age' => 44]]

// adăugarea la un array folosind []
$result = Arrays::associate($arr, 'name[]'); // sau ['name', '[]']
// $result: ['John' => [['name' => 'John', 'age' => 22], ['name' => 'John', 'age' => 11]]]

contains (array $array, $value): bool

Testează un tablou pentru prezența unei valori. Utilizează o comparație strictă (===)

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

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

Testează dacă toate elementele din matrice trec testul implementat de funcția furnizată, care are semnătura function ($value, $key, array $array): bool.

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

A se vedea some().

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

Returnează o nouă matrice care conține toate perechile cheie-valoare care corespund cu $predicate. Callback-ul are semnătura 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

Returnează primul element (care corespunde predicatului specificat, dacă este dat). Dacă nu există un astfel de element, se returnează rezultatul invocării $else sau null.
$predicate are semnătura function ($value, int|string $key, array $array): bool.

Nu modifică pointerul intern, spre deosebire de reset(). Parametrii $predicate și $else există începând cu versiunea 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

A se vedea last().

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

Returnează cheia primului element (care corespunde predicatului specificat, dacă este dat) sau nulă dacă nu există un astfel de element. $predicate are semnătura 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

A se vedea lastKey().

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

Transformă matricea multidimensională în matrice plată.

$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

Returnează $array[$key] item. Dacă nu există, se aruncă Nette\InvalidArgumentException, cu excepția cazului în care se stabilește o valoare implicită ca al treilea argument.

// dacă $array['foo'] nu există, se aruncă o excepție
$value = Arrays::get($array, 'foo');

// dacă $array['foo'] nu există, se returnează 'bar'.
$value = Arrays::get($array, 'foo', 'bar');

Argumentul $key poate fi la fel de bine o matrice.

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

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

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

Obține o referință la $array[$key]. Dacă indexul nu există, se creează unul nou cu valoarea null.

$valueRef = & Arrays::getRef($array, 'foo');
// returnează referința $array['foo']

Funcționează cu array-uri multidimensionale, precum și cu get().

$value = & Arrays::get($array, ['color', 'favorite']);
// returnează referința $array['color']['favorite']].

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

Returnează numai acele elemente din matrice care corespund unei expresii regulate $pattern. Dacă $invert este true, returnează elementele care nu se potrivesc. O eroare de compilare sau de execuție a expresiei regizorale aruncă Nette\RegexpException.

$filteredArray = Arrays::grep($array, '~^\d+$~');
// returnează numai elemente numerice

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

Introduce conținutul matricei $inserted în $array imediat după $key. Dacă $key este null (sau nu există), se introduce la sfârșit.

$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

Introduce conținutul tabloului $inserted în $array înainte de $key. Dacă $key este null (sau nu există), se introduce la început.

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

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

Invocă toate callback-urile și returnează matricea de rezultate.

$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

Invocă metoda pe fiecare obiect dintr-un tablou și returnează un tablou de rezultate.

$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

Verifică dacă matricea este indexată în ordinea crescătoare a cheilor numerice de la zero, adică o listă.

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

Returnează ultimul element (care corespunde predicatului specificat, dacă este dat). Dacă nu există un astfel de element, se returnează rezultatul invocării $else sau null.
$predicate are semnătura function ($value, int|string $key, array $array): bool.

Nu modifică pointerul intern, spre deosebire de end(). Parametrii $predicate și $else există începând cu versiunea 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

A se vedea first().

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

Returnează cheia ultimului element (care corespunde predicatului specificat, dacă este dat) sau nulă dacă nu există un astfel de element. $predicate are semnătura 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

A se vedea firstKey().

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

Solicită $transformer pentru toate elementele din matrice și returnează matricea de valori de returnare. Callback-ul are semnătura function ($value, $key, array $array): bool.

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

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

Creează un nou array prin transformarea valorilor și a cheilor array-ului original. Funcția $transformer are semnătura function ($value, $key, array $array): ?array{$newValue, $newKey}. Dacă $transformer returnează null, elementul este ignorat. Pentru elementele păstrate, primul element al matricei returnate este utilizat ca nouă cheie, iar al doilea element ca nouă valoare.

$array = ['a' => 1, 'b' => 2, 'c' => 3];
$result = Arrays::mapWithKeys($array, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']

Această metodă este utilă în situațiile în care trebuie să modificați structura unui array (atât cheile, cât și valorile simultan) sau să filtrați elementele în timpul transformării (returnând null pentru elementele nedorite).

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

Fuzionează recurent două câmpuri. Este util, de exemplu, pentru fuzionarea structurilor arborescente. Se comportă ca operatorul + pentru array, adică adaugă o pereche cheie/valoare din al doilea array la primul array și păstrează valoarea din primul array în cazul unei coliziuni de chei.

$array1 = ['color' => ['favorite' => 'red'], 5];
$array2 = [10, 'color' => ['favorite' => 'green', 'blue']];

$array = Arrays::mergeTree($array1, $array2);
// $array = ['color' => ['favorite' => 'red', 'blue'], 5];

Valorile din al doilea tablou sunt întotdeauna adăugate la primul. Dispariția valorii 10 din cel de-al doilea tablou poate părea puțin confuză. Trebuie remarcat faptul că această valoare, precum și valoarea 5 in the first array have the same numeric key 0, astfel încât în câmpul rezultat există doar un element din prima matrice.

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

Normalizează matricea în matrice asociativă. Înlocuiește cheile numerice cu valorile lor, noua valoare va fi $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

Returnează și elimină valoarea unui element dintr-un tablou. Dacă acesta nu există, se aruncă o excepție sau se returnează $default, dacă este furnizat.

$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');
// aruncă Nette\InvalidArgumentException

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

Redenumește o cheie. Returnează true dacă cheia a fost găsită în matrice.

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

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

Returnează poziția indexată cu zero a cheii date în matrice. În cazul în care cheia nu este găsită, se returnează null.

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

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

Testează dacă cel puțin un element din matrice trece testul implementat de callback-ul furnizat cu semnătura function ($value, $key, array $array): bool.

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

A se vedea every().

toKey (mixed $key): string|int

Convertește o valoare într-o cheie de matrice, care este fie un număr întreg, fie un șir de caractere.

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

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

Copiază elementele din tabloul $array în obiectul $object și apoi îl returnează.

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

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

Transformă fiecare element al tabloului în șir de caractere și îl închide cu $prefix și $suffix.

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

ArrayHash

Obiectul Nette\Utils\ArrayHash este descendentul clasei generice stdClass și o extinde cu posibilitatea de a o trata ca pe o matrice, de exemplu, accesând membrii folosind paranteze pătrate:

$hash = new Nette\Utils\ArrayHash;
$hash['foo'] = 123;
$hash->bar = 456; // de asemenea, funcționează notația obiect
$hash->foo; // 123

Puteți utiliza funcția count($hash) pentru a obține numărul de elemente.

Puteți itera peste un obiect la fel ca peste o matrice, chiar și cu o referință:

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

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

Array-urile existente pot fi transformate în ArrayHash folosind from():

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

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

Transformarea este recursivă:

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

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

Ea poate fi evitată cu ajutorul celui de-al doilea parametru:

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

Transformă înapoi în matrice:

$array = (array) $hash;

ArrayList

Nette\Utils\ArrayList reprezintă o matrice liniară în care indicii sunt numai numere întregi care cresc de la 0.

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

Puteți utiliza funcția count($list) pentru a obține numărul de elemente.