arrays.texy

Práce s poli - Nette\Utils\Arrays
***********************************

.[perex]
[Nette\Utils\Arrays |api:] je statická třída obsahující užitečné funkce pro práci s poli.


Všechny příklady předpokládají vytvořený alias:

/--php
use Nette\Utils\Arrays;
\--


get($array, $key, $default=NULL) .{toc: get()}
--------------------------------------------

Vrací prvek `$array[$key]`. Pokud neexistuje, vyhodí buď výjimku `Nette\InvalidArgumentException`, nebo je-li uveden třetí parametr `$default`, vrátí ten.

/--php
// pokud $array['foo'] neexistuje, vyhodí výjimku
$value = Arrays::get($array, 'foo');

// pokud $array['foo'] neexistuje, vrátí 'bar'
$value = Arrays::get($array, 'foo', 'bar');
\--

Klíčem `$key` může být i pole.

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

$value = Arrays::get($array, ['color', 'favorite']);
// vrátí 'red'
\--



getRef(&$array, $key) .{toc: getRef()}
------------------------------------

Získá referenci na zadaný prvek pole. Pokud prvek neexistuje, bude vytvořen s hodnotou NULL.

/--php
$valueRef = & Arrays::getRef($array, 'foo');
// vrátí referenci na $array['foo']
\--

Stejně jako funkce [get() | #get()] umí pracovat s vícerozměrnými poli.

/--php
$value = & Arrays::getRef($array, ['color', 'favorite']);
// vrátí referenci na $array['color']['favorite']
\--


grep($array, $pattern, $flags=NULL) .{toc: grep()}
------------------------------------------------

Vrátí pouze ty prvky pole, jejichž hodnota odpovídá regulárnímu výrazu `$pattern`. Chyba při kompilaci nebo zpracování výrazu vyhodí výjimku `Nette\RegexpException`.

/--php
$filteredArray = Arrays::grep($array, '~^\d+$~');
// vrátí pouze prvky pole tvořené číslicemi
\--

Jako příznak `$flags` můžeme uvést konstantu `PREG_GREP_INVERT`, což invertuje výběr.


searchKey($array, $key) .{toc: searchKey()}
-----------------------------------------

Vrátí pozici daného klíče v poli. Pozice je číslována od 0. V případě, že klíč nebude nalezen, vrátí funkce `FALSE`.

/--php
$array = ['first' => 10, 'second' => 20];
$position = Arrays::searchKey($array, 'first'); // vrátí 0
\--



insertAfter(&$array, $key, $inserted) .{toc: insertAfter()}
---------------------------------------------------------

Vloží obsah pole `$inserted` do pole `$array` hned za prvek s klíčem `$key`. Pokud klíč v poli není, vkládá se na konec.

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


insertBefore(&$array, $key, $inserted) .{toc: insertBefore()}
-----------------------------------------------------------

Vloží obsah pole `$inserted` do pole `$array` před prvek s klíčem `$key`. Pokud klíč v poli není, vkládá se na začátek.

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


mergeTree($array1, $array2) .{toc: mergeTree()}
-------------------------------------------

Rekurzivně sloučí dvě pole. Hodí se např. ke slučování stromových struktur. Při slučování se řídí stejnými pravidly jako operátor `+` aplikovaný na pole, tj. k prvnímu poli přidává dvojice klíč/hodnota z druhého pole a v případě kolize klíčů ponechá hodnotu z prvního pole.

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

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

Hodnoty z druhého pole jsou vždy přidány na konec prvního. Jako trošku matoucí se může zdát zmizení hodnoty `10` z druhého pole. Je třeba si uvědomit, že tato hodnota a stejně tak hodnota `5` v poli prvním mají přiřazený stejný numerický klíč `0`, proto ve výsledném poli je jen prvek z prvního pole.


renameKey(&$array, $oldKey, $newKey) .{toc: renameKey()}
------------------------------------------------------

Přejmenuje klíč v poli.

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

{{composer: nette/utils}}