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