Array Functions

This page is about the Nette\Utils\Arrays, ArrayHash and ArrayList classes, which are related to arrays.

Installation:

composer require nette/utils

Arrays

Nette\Utils\Arrays is a static class, which contains a handful of handy array functions.

Following examples assume the following class alias is defined:

use Nette\Utils\Arrays;

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

Transforms multidimensional array to flat array.

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

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

Returns $array[$key] item. If it does not exist, Nette\InvalidArgumentException is thrown, unless a default value is set as third argument.

// if $array['foo'] does not exist, throws an exception
$value = Arrays::get($array, 'foo');

// if $array['foo'] does not exist, returns 'bar'
$value = Arrays::get($array, 'foo', 'bar');

Argument $key may as well be an array.

$array = array('color' => array('favorite' => 'red'), 5);

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

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

Gets reference to given $array[$key]. If the index does not exist, new one is created with value NULL.

$valueRef = & Arrays::getRef($array, 'foo');
// returns $array['foo'] reference

Works with multidimensional arrays as well as get().

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

grep(array $array, string $pattern, int $flags=NULL): array

Returns only those array items, which matches a regular expression $pattern. Regex compilation or runtime error throw Nette\RegexpException.

$filteredArray = Arrays::grep($array, '~^\d+$~');
// returns only numerical items

Value PREG_GREP_INVERT may be set as $flags, which inverts the selection.

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

Inserts the contents of the $inserted array into the $array immediately after the $key. If the key does not exist, it is inserted at the end.

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

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

Inserts the contents of the $inserted array into the $array before the $key. If the key does not exist, it is inserted at the beginning.

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

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

Recursively merges two fields. It is useful, for example, for merging tree structures. It behaves as the + operator for array, ie. it adds a key/value pair from the second array to the first one and retains the value from the first array in the case of a key collision.

$array1 = array('color' => array('favorite' => 'red'), 5);
$array2 = array(10, 'color' => array('favorite' => 'green', 'blue'));

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

Values from the second array are always appended to the first. The disappearance of the value 10 from the second array may seem a bit confusing. It should be noted that this value as well as the value 5 in the first array have the same numeric key 0, so in the resulting field there is only an element from the first array.

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

Renames a key.

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

searchKey(array $array, string|int $key)

Returns zero-indexed position of given array key. Returns FALSE if key is not found.

$array = array('first' => 10, 'second' => 20);
$position = Arrays::searchKey($array, 'first'); // returns 0
$position = Arrays::searchKey($array, 'second'); // returns 1
$position = Arrays::searchKey($array, 'not-exists'); // returns NULL

ArrayHash

Object Nette\Utils\ArrayHash is the descendant of generic class stdClass and extends it to the ability to treat it as an array, for example, accessing members using square brackets:

$hash = new Nette\Utils\ArrayHash;
$hash['foo'] = 123;
$hash->bar = 456; // also works object notation
$hash->foo; // 123

You can use count() and iterate over the object, as in the case of the array:

count($hash); // 2

foreach ($hash as $key => $value) ...

Existing arrays can be transformed to ArrayHash using from():

$array = array('foo' => 123, 'bar' => 456);

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

The transformation is recursive:

$array = array('foo' => 123, 'inner' => array('a' => 'b'));

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

It can be avoided by the second parameter:

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

Transform back to the array:

$array = (array) $hash;

ArrayList

Nette\Utils\ArrayList represents a linear array where the indexes are only integers ascending from 0.

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

Over the object you can iterate or call count(), as in the case of an array.

Accessing keys beyond the allowed values throws an exception Nette\OutOfRangeException:

echo $list[-1]; // throws Nette\OutOfRangeException
unset($list[30]); // throws Nette\OutOfRangeException

Removing the key will result in renumbering the elements:

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