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 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 = 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')