Funcții de matrice
******************

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


Instalare:

```shell
composer require nette/utils
```


Array-uri .[#toc-arrays]
========================

[api: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 |iterables].

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

```php
use Nette\Utils\Arrays;
```


associate(array $array, mixed $path): array|\stdClass .[method]
---------------------------------------------------------------

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ă.

```php
// 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]]
```

```php
// 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, ...]
```

```php
// 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]]
```

```php
// 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]]
```

```php
// 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 .[method]
----------------------------------------------

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

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


every(array $array, callable $predicate): bool .[method]
--------------------------------------------------------

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

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

A se vedea [some() |#some()].


filter(array $array, callable $predicate): array .[method]{data-version:4.0.4}
------------------------------------------------------------------------------

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

```php
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 .[method]
-------------------------------------------------------------------------------------

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.

```php
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() |#last()].


firstKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
------------------------------------------------------------------------------------------------

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

```php
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() |#lastKey()].


flatten(array $array, bool $preserveKeys=false): array .[method]
----------------------------------------------------------------

Transformă matricea multidimensională în matrice plată.

```php
$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 .[method]
-------------------------------------------------------------------------------

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.

```php
// 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.

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

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


getRef(array &$array, string|int|array $key): mixed .[method]
-------------------------------------------------------------

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

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

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

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


grep(array $array, string $pattern, bool $invert=false): array .[method]
------------------------------------------------------------------------

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

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


insertAfter(array &$array, string|int|null $key, array $inserted): void .[method]
---------------------------------------------------------------------------------

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

```php
$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 .[method]
----------------------------------------------------------------------------------

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

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


invoke(iterable $callbacks, ...$args): array .[method]
------------------------------------------------------

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

```php
$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 .[method]
--------------------------------------------------------------------------

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

```php
$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 .[method]
------------------------------------

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

```php
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 .[method]
------------------------------------------------------------------------------------

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.

```php
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() |#first()].


lastKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
-----------------------------------------------------------------------------------------------

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

```php
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() |#firstKey()].


map(array $array, callable $transformer): array .[method]
---------------------------------------------------------

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

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


mapWithKeys(array $array, callable $transformer): array .[method]
-----------------------------------------------------------------

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.

```php
$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 .[method]
--------------------------------------------------------

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.

```php
$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 .[method]
---------------------------------------------------------------

Normalizează matricea în matrice asociativă. Înlocuiește cheile numerice cu valorile lor, noua valoare va fi `$filling`.

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

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


pick(array &$array, string|int $key, ?mixed $default=null): mixed .[method]
---------------------------------------------------------------------------

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.

```php
$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 .[method]
--------------------------------------------------------------------------------

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

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


getKeyOffset(array $array, string|int $key): ?int .[method]
-----------------------------------------------------------

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

```php
$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 .[method]
-------------------------------------------------------

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

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

A se vedea [every() |#every()].


toKey(mixed $key): string|int .[method]
---------------------------------------

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

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


toObject(iterable $array, object $object): object .[method]
-----------------------------------------------------------

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

```php
$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 .[method]
-------------------------------------------------------------------------

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

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


ArrayHash .[#toc-arrayhash]
===========================

Obiectul [api: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:

```php
$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ță:

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

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

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

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

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

Transformarea este recursivă:

```php
$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:

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

Transformă înapoi în matrice:

```php
$array = (array) $hash;
```


ArrayList .[#toc-arraylist]
===========================

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

```php
$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.

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

```php
foreach ($list as $key => $value) {
	// ...
}

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

Rețelele existente pot fi transformate în `ArrayList` utilizând `from()`:

```php
$array = ['foo', 'bar'];
$list = Nette\Utils\ArrayList::from($array);
```

Accesarea cheilor dincolo de valorile permise aruncă o excepție `Nette\OutOfRangeException`:

```php
echo $list[-1]; // aruncă Nette\OutOutOfRangeException
unset($list[30]); // aruncă Nette\OutOfRangeException
```

Eliminarea cheii va duce la renumerotarea elementelor:

```php
unset($list[1]);
// ArrayList(0 => 'a', 1 => 'c')
```

Puteți adăuga un nou element la început folosind `prepend()`:

```php
$list->prepend('d');
// ArrayList(0 => 'd', 1 => 'a', 2 => 'c')
```