Array-Funktionen
****************

.[perex]
Diese Seite befasst sich mit den Klassen [Nette\Utils\Arrays |#Arrays], [ArrayHash |#ArrayHash] und [ArrayList |#ArrayList], die mit Arrays zu tun haben.


Installation:

```shell
composer require nette/utils
```


Arrays .[#toc-arrays]
=====================

[api:Nette\Utils\Arrays] ist eine statische Klasse, die eine Handvoll praktischer Array-Funktionen enthält. Ihre Entsprechung für Iteratoren ist [Nette\Utils\Iterables |iterables].

Die folgenden Beispiele setzen voraus, dass der folgende Klassenalias definiert ist:

```php
use Nette\Utils\Arrays;
```


associate(array $array, mixed $path): array|\stdClass .[method]
---------------------------------------------------------------

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.

```php
// 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]]
```

```php
// 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, ...]
```

```php
// 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]]
```

```php
// 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]]
```

```php
// 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 .[method]
----------------------------------------------

Prüft ein Array auf das Vorhandensein eines Wertes. Verwendet einen strengen Vergleich (`===`)

```php
Arrays::contains([1, 2, 3], 1);    // true
Arrays::contains(['1', false], 1); // false
```


every(array $array, callable $predicate): bool .[method]
--------------------------------------------------------

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.

```php
$array = [1, 30, 39, 29, 10, 13];
$isBelowThreshold = fn($value) => $value < 40;
$res = Arrays::every($array, $isBelowThreshold); // true
```

Siehe [some() |#some()].


filter(array $array, callable $predicate): array .[method]{data-version:4.0.4}
------------------------------------------------------------------------------

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`.

```php
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 .[method]
-------------------------------------------------------------------------------------

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.

```php
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() |#last()].


firstKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
------------------------------------------------------------------------------------------------

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`.

```php
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() |#lastKey()].


flatten(array $array, bool $preserveKeys=false): array .[method]
----------------------------------------------------------------

Wandelt ein mehrdimensionales Array in ein flaches Array um.

```php
$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 .[method]
-------------------------------------------------------------------------------

Gibt `$array[$key]` Element. Wenn es nicht existiert, wird `Nette\InvalidArgumentException` ausgelöst, es sei denn, ein Standardwert wird als drittes Argument angegeben.

```php
// 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.

```php
$array = ['color' => ['favorite' => 'red'], 5];

$value = Arrays::get($array, ['color', 'favorite']);
// returns 'red'
```


getRef(array &$array, string|int|array $key): mixed .[method]
-------------------------------------------------------------

Ruft eine Referenz auf die angegebene `$array[$key]`. Wenn der Index nicht existiert, wird ein neuer Index mit dem Wert `null` erstellt.

```php
$valueRef = & Arrays::getRef($array, 'foo');
// returns $array['foo'] reference
```

Funktioniert sowohl mit mehrdimensionalen Arrays als auch mit [get() |#get()].

```php
$value = & Arrays::get($array, ['color', 'favorite']);
// returns $array['color']['favorite'] reference
```


grep(array $array, string $pattern, bool $invert=false): array .[method]
------------------------------------------------------------------------

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`.

```php
$filteredArray = Arrays::grep($array, '~^\d+$~');
// gibt nur numerische Elemente zurück
```


insertAfter(array &$array, string|int|null $key, array $inserted): void .[method]
---------------------------------------------------------------------------------

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.

```php
$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 .[method]
----------------------------------------------------------------------------------

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.

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


invoke(iterable $callbacks, ...$args): array .[method]
------------------------------------------------------

Ruft alle Callbacks auf und gibt ein Array mit den Ergebnissen zurück.

```php
$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 .[method]
--------------------------------------------------------------------------

Ruft die Methode für jedes Objekt in einem Array auf und gibt ein Array mit Ergebnissen zurück.

```php
$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 .[method]
------------------------------------

Prüft, ob das Array in aufsteigender Reihenfolge der numerischen Schlüssel von Null an indiziert ist, d.h. eine Liste.

```php
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 .[method]
------------------------------------------------------------------------------------

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.

```php
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() |#first()].


lastKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
-----------------------------------------------------------------------------------------------

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`.

```php
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() |#firstKey()].


map(array $array, callable $transformer): array .[method]
---------------------------------------------------------

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`.

```php
$array = ['foo', 'bar', 'baz'];
$res = Arrays::map($array, fn($value) => $value . $value);
// $res = ['foofoo', 'barbar', 'bazbaz']
```


mapWithKeys(array $array, callable $transformer): array .[method]
-----------------------------------------------------------------

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.

```php
$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 .[method]
--------------------------------------------------------

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.

```php
$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 .[method]
---------------------------------------------------------------

Normalisiert ein Array zu einem assoziativen Array. Ersetzen Sie numerische Schlüssel durch ihre Werte, der neue Wert wird `$filling` sein.

```php
$array = Arrays::normalize([1 => 'first', 'a' => 'second']);
// $array = ['first' => null, 'a' => 'second'];
```

```php
$array = Arrays::normalize([1 => 'first', 'a' => 'second'], 'foobar');
// $array = ['first' => 'foobar', 'a' => 'second'];
```


pick(array &$array, string|int $key, ?mixed $default=null): mixed .[method]
---------------------------------------------------------------------------

Liefert und entfernt den Wert eines Elements aus einem Array. Wenn es nicht existiert, wird eine Exception geworfen oder `$default` zurückgegeben, falls angegeben.

```php
$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 .[method]
--------------------------------------------------------------------------------

Benennt einen Schlüssel um. Gibt `true` zurück, wenn der Schlüssel im Array gefunden wurde.

```php
$array = ['first' => 10, 'second' => 20];
Arrays::renameKey($array, 'first', 'renamed');
// $array = ['renamed' => 10, 'second' => 20];
```


getKeyOffset(array $array, string|int $key): ?int .[method]
-----------------------------------------------------------

Gibt die null-indizierte Position des angegebenen Array-Schlüssels zurück. Gibt `null` zurück, wenn der Schlüssel nicht gefunden wird.

```php
$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 .[method]
-------------------------------------------------------

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.

```php
$array = [1, 2, 3, 4];
$isEven = fn($value) => $value % 2 === 0;
$res = Arrays::some($array, $isEven); // true
```

Siehe [every() |#every()].


toKey(mixed $key): string|int .[method]
---------------------------------------

Konvertiert einen Wert in einen Array-Schlüssel, der entweder eine Ganzzahl oder eine Zeichenkette ist.

```php
Arrays::toKey('1');  // 1
Arrays::toKey('01'); // '01'
```


toObject(iterable $array, object $object): object .[method]
-----------------------------------------------------------

Kopiert die Elemente des Arrays `$array` in das Objekt `$object` und gibt es dann zurück.

```php
$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 .[method]
-------------------------------------------------------------------------

Jedes Element des Arrays wird in einen String umgewandelt und mit `$prefix` und `$suffix` umschlossen.

```php
$array = Arrays::wrap(['a' => 'red', 'b' => 'green'], '<<', '>>');
// $array = ['a' => '<<red>>', 'b' => '<<green>>'];
```


ArrayHash .[#toc-arrayhash]
===========================

Das Objekt [api: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:

```php
$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:

```php
foreach ($hash as $key => $value) {
	// ...
}

foreach ($hash as $key => &$value) {
	$value = 'new value';
}
```

Vorhandene Arrays können mit `from()` in `ArrayHash` umgewandelt werden:

```php
$array = ['foo' => 123, 'bar' => 456];

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

Die Umwandlung ist rekursiv:

```php
$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:

```php
$hash = Nette\Utils\ArrayHash::from($array, false);
$hash->inner; // array
```

Zurück in das Array transformieren:

```php
$array = (array) $hash;
```


ArrayList .[#toc-arraylist]
===========================

[api:Nette\Utils\ArrayList] stellt ein lineares Array dar, bei dem die Indizes nur ganze Zahlen sind, die von 0 an aufsteigen.

```php
$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:

```php
foreach ($list as $key => $value) {
	// ...
}

foreach ($list as $key => &$value) {
	$value = 'neuer Wert';
}
```

Vorhandene Arrays können mit `from()` in `ArrayList` umgewandelt werden:

```php
$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`:

```php
echo $list[-1]; // throws Nette\OutOfRangeException
unset($list[30]); // throws Nette\OutOfRangeException
```

Das Entfernen des Schlüssels führt zu einer Neunummerierung der Elemente:

```php
unset($list[1]);
// ArrayList(0 => 'a', 1 => 'c')
```

Mit `prepend()` können Sie ein neues Element an den Anfang setzen:

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