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']

mapWithKeys (array $array, callable $transformer): array

Erzeugt ein neues Array durch Umwandlung der Werte und Schlüssel des ursprünglichen Arrays. Die Funktion $transformer hat die Signatur function ($value, $key, array $array): ?array{$newValue, $newKey}. Wenn $transformer null zurückgibt, wird das Element übersprungen. Bei beibehaltenen Elementen wird das erste Element des zurückgegebenen Arrays als neuer Schlüssel und das zweite Element als neuer Wert verwendet.

$array = ['a' => 1, 'b' => 2, 'c' => 3];
$result = Arrays::mapWithKeys($array, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']

Diese Methode ist in Situationen nützlich, in denen Sie die Struktur eines Arrays (Schlüssel und Werte gleichzeitig) ändern oder Elemente während der Transformation filtern müssen (indem Sie für unerwünschte Elemente null zurückgeben).

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