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;

every(array $array, callable $callback)bool

Tests whether all elements in the array pass the test implemented by the provided function, which has the signature function ($value, $key, array $array): bool.

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

See some().

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

Transforms multidimensional array to flat array.

$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

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 = ['color' => ['favorite' => 'red'], 5];

$value = Arrays::get($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, ['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 throws 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|null $key, array $inserted)void

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

$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

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

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

isList(array $array): bool

Checks if the array is indexed in ascending order of numeric keys from zero, a.k.a list.

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

map(array $array, callable $callback)array

Calls $callback on all elements in the array and returns the array of return values. The callback has the signature function ($value, $key, array $array): bool.

$array = ['foo', 'bar', 'baz'];
$res = Arrays::map($array, function ($value) { return $value . $value; });
// $res = ['foofoo', 'barbar', 'bazbaz']

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 = ['color' => ['favorite' => 'red'], 5];
$array2 = [10, 'color' => ['favorite' => 'green', 'blue']];

$array = Arrays::mergeTree($array1, $array2);
// $array = ['color' => ['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.

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

Normalizes array to associative array. Replace numeric keys with their values, the new value will be $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

Returns and removes the value of an item from an array. If it does not exist, it throws an exception, or returns $default, if provided.

$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)void

Renames a key.

$array = ['first' => 10, 'second' => 20];
Arrays::renameKey($array, 'first', 'renamed');
// $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 = ['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

Since version 3 it will return null instead of false.

some(array $array, callable $callback)bool

Tests whether at least one element in the array passes the test implemented by the provided callback with signature function ($value, $key, array $array): bool.

$array = [1, 2, 3, 4];
$isEven = function ($value) { return $value % 2 === 0; };
$res = Arrays::some($array, $isEven); // true

See every().

ArrayHash

Object Nette\Utils\ArrayHash is the descendant of an anonymous 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 = ['foo' => 123, 'bar' => 456];

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

The transformation is recursive:

$array = ['foo' => 123, 'inner' => ['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')

You can add a new element to the beginning using prepend():

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