Array-Funktionen
Diese Seite befasst sich mit den Klassen Nette\Utils\Arrays, ArrayHash und ArrayList, die mit Arrays zu tun haben.
Installation:
composer require nette/utils
Arrays
Nette\Utils\Arrays ist eine statische Klasse, die eine Handvoll praktischer Array-Funktionen enthält. Ihre Entsprechung für Iteratoren ist Nette\Utils\Iterables.
Die folgenden Beispiele setzen voraus, dass der folgende Klassenalias definiert ist:
use Nette\Utils\Arrays;
associate(array $array, mixed $path): array|\stdClass
Die Funktion wandelt die $array flexibel in ein assoziatives Array oder Objekte entsprechend dem angegebenen Pfad
$path um. Der Pfad kann eine Zeichenkette oder ein Array sein. Er besteht aus den Namen der Schlüssel im
Eingabe-Array und Operatoren wie ‘[]’, ‘->’, ‘=’ und ‘|’. Wirft Nette\InvalidArgumentException,
wenn der Pfad ungültig ist.
// Umwandlung in ein assoziatives Array unter Verwendung eines einfachen Schlüssels
$arr = [
['name' => 'John', 'age' => 11],
['name' => 'Mary', 'age' => null],
//...
];
$result = Arrays::associate($arr, 'name');
// $result = ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]
// Zuweisung von Werten von einem Schlüssel zu einem anderen mit dem Operator =
$result = Arrays::associate($arr, 'name=age'); // oder ['name', '=', 'age']
// $result = ['John' => 11, 'Mary' => null, ...]
// Erstellen eines Objekts mit dem ->-Operator
$result = Arrays::associate($arr, '->name'); // oder ['->', 'name']
// $result = (object) ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]
// Schlüssel mit dem Operator | kombinieren
$result = Arrays::associate($arr, 'name|age'); // oder ['name', '|', 'age']
// $result: ['John' => ['name' => 'John', 'age' => 11], 'Paul' => ['name' => 'Paul', 'age' => 44]]
// Hinzufügen zu einem Array mit []
$result = Arrays::associate($arr, 'name[]'); // oder ['name', '[]']
// $result: ['John' => [['name' => 'John', 'age' => 22], ['name' => 'John', 'age' => 11]]]
contains(array $array, $value): bool
Prüft ein Array auf das Vorhandensein eines Wertes. Verwendet einen strengen Vergleich (===)
Arrays::contains([1, 2, 3], 1); // true
Arrays::contains(['1', false], 1); // false
every(array $array, callable $predicate): bool
Prüft, ob alle Elemente im Array den Test bestehen, der von der angegebenen Funktion mit der Signatur
function ($value, $key, array $array): bool implementiert wird.
$array = [1, 30, 39, 29, 10, 13];
$isBelowThreshold = fn($value) => $value < 40;
$res = Arrays::every($array, $isBelowThreshold); // true
Siehe some().
filter(array $array, callable $predicate): array
Gibt ein neues Array zurück, das alle Schlüssel-Wert-Paare enthält, die mit dem angegebenen $predicate
übereinstimmen. Der Callback hat die Signatur function ($value, int|string $key, array $array): bool.
Arrays::filter(
['a' => 1, 'b' => 2, 'c' => 3],
fn($v) => $v < 3,
);
// ['a' => 1, 'b' => 2]
first(array $array, ?callable $predicate=null, ?callable $else=null): mixed
Gibt das erste Element zurück (das dem angegebenen Prädikat entspricht, falls angegeben). Wenn es kein solches Element gibt,
wird das Ergebnis des Aufrufs von $else oder null zurückgegeben.
$predicate hat die Signatur function ($value, int|string $key, array $array): bool.
Im Gegensatz zu reset() wird der interne Zeiger nicht verändert. Die Parameter $predicate und
$else gibt es seit Version 4.0.4.
Arrays::first([1, 2, 3]); // 1
Arrays::first([1, 2, 3], fn($v) => $v > 2); // 3
Arrays::first([]); // null
Arrays::first([], else: fn() => false); // false
Siehe last().
firstKey(array $array, ?callable $predicate=null): int|string|null
Gibt den Schlüssel des ersten Elements zurück (das mit dem angegebenen Prädikat übereinstimmt, falls gegeben) oder null,
wenn es kein solches Element gibt. $predicate hat die Signatur
function ($value, int|string $key, array $array): bool.
Arrays::firstKey([1, 2, 3]); // 0
Arrays::firstKey([1, 2, 3], fn($v) => $v > 2); // 2
Arrays::firstKey(['a' => 1, 'b' => 2]); // 'a'
Arrays::firstKey([]); // null
Siehe lastKey().
flatten(array $array, bool $preserveKeys=false): array
Wandelt ein mehrdimensionales Array in ein flaches Array um.
$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
Gibt $array[$key] Element. Wenn es nicht existiert, wird Nette\InvalidArgumentException ausgelöst,
es sei denn, ein Standardwert wird als drittes Argument angegeben.
// wenn $array['foo'] nicht existiert, wird eine Ausnahme ausgelöst
$value = Arrays::get($array, 'foo');
// wenn $array['foo'] nicht existiert, gibt 'bar' zurück
$value = Arrays::get($array, 'foo', 'bar');
Das Argument $key kann ebenso gut ein Array sein.
$array = ['color' => ['favorite' => 'red'], 5];
$value = Arrays::get($array, ['color', 'favorite']);
// returns 'red'
getRef(array &$array, string|int|array $key): mixed
Ruft eine Referenz auf die angegebene $array[$key]. Wenn der Index nicht existiert, wird ein neuer Index mit dem
Wert null erstellt.
$valueRef = & Arrays::getRef($array, 'foo');
// returns $array['foo'] reference
Funktioniert sowohl mit mehrdimensionalen Arrays als auch mit get().
$value = & Arrays::get($array, ['color', 'favorite']);
// returns $array['color']['favorite'] reference
grep(array $array, string $pattern, bool $invert=false): array
Gibt nur die Array-Elemente zurück, die einem regulären Ausdruck $pattern entsprechen. Wenn $invert
gleich true ist, werden Elemente zurückgegeben, die nicht übereinstimmen. Ein Regex-Kompilierungs- oder
Laufzeitfehler führt zu Nette\RegexpException.
$filteredArray = Arrays::grep($array, '~^\d+$~');
// gibt nur numerische Elemente zurück
insertAfter(array &$array, string|int|null $key, array $inserted): void
Fügt den Inhalt des Arrays $inserted in $array unmittelbar nach $key ein. Wenn
$key null ist (oder nicht existiert), wird es am Ende eingefügt.
$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
Fügt den Inhalt des Arrays $inserted in $array vor $key ein. Wenn $key
gleich null ist (oder nicht existiert), wird er am Anfang eingefügt.
$array = ['first' => 10, 'second' => 20];
Arrays::insertBefore($array, 'first', ['hello' => 'world']);
// $array = ['hello' => 'world', 'first' => 10, 'second' => 20];
invoke(iterable $callbacks, …$args): array
Ruft alle Callbacks auf und gibt ein Array mit den Ergebnissen zurück.
$callbacks = [
'+' => fn($a, $b) => $a + $b,
'*' => fn($a, $b) => $a * $b,
];
$array = Arrays::invoke($callbacks, 5, 11);
// $array = ['+' => 16, '*' => 55];
invokeMethod(iterable $objects, string $method, …$args): array
Ruft die Methode für jedes Objekt in einem Array auf und gibt ein Array mit Ergebnissen zurück.
$objects = ['a' => $obj1, 'b' => $obj2];
$array = Arrays::invokeMethod($objects, 'foo', 1, 2);
// $array = ['a' => $obj1->foo(1, 2), 'b' => $obj2->foo(1, 2)];
isList(array $array): bool
Prüft, ob das Array in aufsteigender Reihenfolge der numerischen Schlüssel von Null an indiziert ist, d.h. eine Liste.
Arrays::isList(['a', 'b', 'c']); // true
Arrays::isList([4 => 1, 2, 3]); // false
Arrays::isList(['a' => 1, 'b' => 2]); // false
last(array $array, ?callable $predicate=null, ?callable $else=null): mixed
Gibt das letzte Element zurück (das dem angegebenen Prädikat entspricht, falls angegeben). Wenn es kein solches Element gibt,
wird das Ergebnis des Aufrufs von $else oder null zurückgegeben.
$predicate hat die Signatur function ($value, int|string $key, array $array): bool.
Im Gegensatz zu end() wird der interne Zeiger nicht verändert. Die Parameter $predicate und
$else gibt es seit Version 4.0.4.
Arrays::last([1, 2, 3]); // 3
Arrays::last([1, 2, 3], fn($v) => $v < 3); // 2
Arrays::last([]); // null
Arrays::last([], else: fn() => false); // false
Siehe first().
lastKey(array $array, ?callable $predicate=null): int|string|null
Gibt den Schlüssel des letzten Elements zurück (das mit dem angegebenen Prädikat übereinstimmt, falls angegeben) oder null,
wenn es kein solches Element gibt. $predicate hat die Signatur
function ($value, int|string $key, array $array): bool.
Arrays::lastKey([1, 2, 3]); // 2
Arrays::lastKey([1, 2, 3], fn($v) => $v < 3); // 1
Arrays::lastKey(['a' => 1, 'b' => 2]); // 'b'
Arrays::lastKey([]); // null
Siehe firstKey().
map(array $array, callable $transformer): array
Ruft $transformer für alle Elemente im Array auf und gibt das Array der Rückgabewerte zurück. Der Callback hat
die Signatur function ($value, $key, array $array): bool.
$array = ['foo', 'bar', 'baz'];
$res = Arrays::map($array, fn($value) => $value . $value);
// $res = ['foofoo', 'barbar', 'bazbaz']
mergeTree(array $array1, array $array2): array
Führt zwei Felder rekursiv zusammen. Er ist z.B. nützlich, um Baumstrukturen zusammenzuführen. Er verhält sich wie der
+-Operator für Array, d.h. er fügt ein Schlüssel/Wert-Paar aus dem zweiten Array zum ersten hinzu und behält den
Wert aus dem ersten Array im Falle einer Schlüsselkollision bei.
$array1 = ['color' => ['favorite' => 'red'], 5];
$array2 = [10, 'color' => ['favorite' => 'green', 'blue']];
$array = Arrays::mergeTree($array1, $array2);
// $array = ['color' => ['favorite' => 'red', 'blue'], 5];
Werte aus dem zweiten Array werden immer an das erste angehängt. Das Verschwinden des Wertes 10 aus dem zweiten
Array mag ein wenig verwirrend erscheinen. Es sollte beachtet werden, dass dieser Wert sowie der Wert 5 in the first
array have the same numeric key 0, also im resultierenden Feld nur ein Element aus dem ersten Array
vorhanden ist.
normalize(array $array, string $filling=null): array
Normalisiert ein Array zu einem assoziativen Array. Ersetzen Sie numerische Schlüssel durch ihre Werte, der neue Wert wird
$filling sein.
$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
Liefert und entfernt den Wert eines Elements aus einem Array. Wenn es nicht existiert, wird eine Exception geworfen oder
$default zurückgegeben, falls angegeben.
$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): bool
Benennt einen Schlüssel um. Gibt true zurück, wenn der Schlüssel im Array gefunden wurde.
$array = ['first' => 10, 'second' => 20];
Arrays::renameKey($array, 'first', 'renamed');
// $array = ['renamed' => 10, 'second' => 20];
getKeyOffset(array $array, string|int $key): ?int
Gibt die null-indizierte Position des angegebenen Array-Schlüssels zurück. Gibt null zurück, wenn der
Schlüssel nicht gefunden wird.
$array = ['first' => 10, 'second' => 20];
$position = Arrays::getKeyOffset($array, 'first'); // returns 0
$position = Arrays::getKeyOffset($array, 'second'); // returns 1
$position = Arrays::getKeyOffset($array, 'not-exists'); // returns null
some(array $array, callable $predicate): bool
Prüft, ob mindestens ein Element im Array den Test besteht, der durch den angegebenen Callback mit der Signatur
function ($value, $key, array $array): bool implementiert wird.
$array = [1, 2, 3, 4];
$isEven = fn($value) => $value % 2 === 0;
$res = Arrays::some($array, $isEven); // true
Siehe every().
toKey(mixed $key): string|int
Konvertiert einen Wert in einen Array-Schlüssel, der entweder eine Ganzzahl oder eine Zeichenkette ist.
Arrays::toKey('1'); // 1
Arrays::toKey('01'); // '01'
toObject(iterable $array, object $object): object
Kopiert die Elemente des Arrays $array in das Objekt $object und gibt es dann zurück.
$obj = new stdClass;
$array = ['foo' => 1, 'bar' => 2];
Arrays::toObject($array, $obj); // it sets $obj->foo = 1; $obj->bar = 2;
wrap(array $array, string
$prefix='', string $suffix=''): array
Jedes Element des Arrays wird in einen String umgewandelt und mit $prefix und $suffix
umschlossen.
$array = Arrays::wrap(['a' => 'red', 'b' => 'green'], '<<', '>>');
// $array = ['a' => '<<red>>', 'b' => '<<green>>'];
ArrayHash
Das Objekt Nette\Utils\ArrayHash ist ein Nachkomme der generischen Klasse stdClass und erweitert diese um die Möglichkeit, sie als Array zu behandeln, z. B. den Zugriff auf Mitglieder mit eckigen Klammern:
$hash = new Nette\Utils\ArrayHash;
$hash['foo'] = 123;
$hash->bar = 456; // funktioniert auch in Objektnotation
$hash->foo; // 123
Sie können die Funktion count($hash) verwenden, um die Anzahl der Elemente zu ermitteln.
Sie können über ein Objekt wie über ein Array iterieren, sogar mit einer Referenz:
foreach ($hash as $key => $value) {
// ...
}
foreach ($hash as $key => &$value) {
$value = 'new value';
}
Vorhandene Arrays können mit from() in ArrayHash umgewandelt werden:
$array = ['foo' => 123, 'bar' => 456];
$hash = Nette\Utils\ArrayHash::from($array);
$hash->foo; // 123
$hash->bar; // 456
Die Umwandlung ist rekursiv:
$array = ['foo' => 123, 'inner' => ['a' => 'b']];
$hash = Nette\Utils\ArrayHash::from($array);
$hash->inner; // Objekt ArrayHash
$hash->inner->a; // 'b'
$hash['inner']['a']; // 'b'
Sie kann durch den zweiten Parameter vermieden werden:
$hash = Nette\Utils\ArrayHash::from($array, false);
$hash->inner; // array
Zurück in das Array transformieren:
$array = (array) $hash;
ArrayList
Nette\Utils\ArrayList stellt ein lineares Array dar, bei dem die Indizes nur ganze Zahlen sind, die von 0 an aufsteigen.
$list = new Nette\Utils\ArrayList;
$list[] = 'a';
$list[] = 'b';
$list[] = 'c';
// ArrayList(0 => 'a', 1 => 'b', 2 => 'c')
count($list); // 3
Sie können die Funktion count($list) verwenden, um die Anzahl der Elemente zu ermitteln.
Sie können über ein Objekt wie über ein Array iterieren, sogar mit einem Verweis:
foreach ($list as $key => $value) {
// ...
}
foreach ($list as $key => &$value) {
$value = 'neuer Wert';
}
Vorhandene Arrays können mit from() in ArrayList umgewandelt werden:
$array = ['foo', 'bar'];
$list = Nette\Utils\ArrayList::from($array);
Der Zugriff auf Schlüssel, die über die zulässigen Werte hinausgehen, führt zu einer Ausnahme
Nette\OutOfRangeException:
echo $list[-1]; // throws Nette\OutOfRangeException
unset($list[30]); // throws Nette\OutOfRangeException
Das Entfernen des Schlüssels führt zu einer Neunummerierung der Elemente:
unset($list[1]);
// ArrayList(0 => 'a', 1 => 'c')
Mit prepend() können Sie ein neues Element an den Anfang setzen:
$list->prepend('d');
// ArrayList(0 => 'd', 1 => 'a', 2 => 'c')
