Fonctions des tableaux
**********************

.[perex]
Cette page concerne les classes [Nette\Utils\Arrays |#Arrays], [ArrayHash |#ArrayHash] et [ArrayList |#ArrayList], qui sont liées aux tableaux.


Installation :

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


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

[api:Nette\Utils\Arrays] est une classe statique qui contient une poignée de fonctions pratiques pour les tableaux. Son équivalent pour les itérateurs est [Nette\Utils\Iterables |iterables].

Les exemples suivants supposent que l'alias de classe suivant est défini :

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


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

La fonction transforme de manière flexible le fichier `$array` en un tableau associatif ou en objets selon le chemin spécifié `$path`. Le chemin peut être une chaîne ou un tableau. Il se compose des noms des clés du tableau d'entrée et d'opérateurs tels que "[]", "->", "=" et "|". Lance `Nette\InvalidArgumentException` si le chemin n'est pas valide.

```php
// conversion en tableau associatif à l'aide d'une simple clé
$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
// l'affectation de valeurs d'une clé à une autre à l'aide de l'opérateur =.
$result = Arrays::associate($arr, 'name=age'); // ou ['name', '=', 'age']
// $result = ['John' => 11, 'Mary' => null, ...]
```

```php
// création d'un objet à l'aide de l'opérateur ->
$result = Arrays::associate($arr, '->name'); // ou ['->', 'name']
// $result = (object) ['John' => ['name' => 'John', 'age' => 11], 'Mary' => ['name' => 'Mary', 'age' => null]]
```

```php
// combiner des clés à l'aide de l'opérateur |
$result = Arrays::associate($arr, 'name|age'); // ou ['name', '|', 'age']
// $result: ['John' => ['name' => 'John', 'age' => 11], 'Paul' => ['name' => 'Paul', 'age' => 44]]
```

```php
// ajouter à un tableau en utilisant []
$result = Arrays::associate($arr, 'name[]'); // ou ['name', '[]']
// $result: ['John' => [['name' => 'John', 'age' => 22], ['name' => 'John', 'age' => 11]]]
```


contains(array $array, $value): bool .[method]
----------------------------------------------

Teste un tableau pour vérifier la présence d'une valeur. Utilise une comparaison stricte (`===`)

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


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

Teste si tous les éléments du tableau passent le test implémenté par la fonction fournie, qui a la signature `function ($value, $key, array $array): bool`.

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

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


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

Renvoie un nouveau tableau contenant toutes les paires clé-valeur correspondant à l'adresse `$predicate`. Le rappel a la signature `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]
-------------------------------------------------------------------------------------

Renvoie le premier élément (correspondant au prédicat spécifié s'il est donné). S'il n'y a pas d'élément de ce type, il renvoie le résultat de l'invocation de `$else` ou null.
Le site `$predicate` a la signature `function ($value, int|string $key, array $array): bool`.

Il ne modifie pas le pointeur interne, contrairement à `reset()`. Les paramètres `$predicate` et `$else` existent depuis la 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
```

Voir [last() |#last()].


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

Renvoie la clé du premier élément (correspondant au prédicat spécifié s'il est donné) ou null s'il n'y a pas d'élément de ce type. La signature de `$predicate` est `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
```

Voir [lastKey() |#lastKey()].


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

Transforme un tableau multidimensionnel en tableau plat.

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

Retourne `$array[$key]` item. S'il n'existe pas, `Nette\InvalidArgumentException` est lancé, sauf si une valeur par défaut est définie comme troisième argument.

```php
// si $array['foo'] n'existe pas, lance une exception
$value = Arrays::get($array, 'foo');

// si $array['foo'] n'existe pas, retourne 'bar'.
$value = Arrays::get($array, 'foo', 'bar');
```

L'argument `$key` peut aussi bien être un tableau.

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

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


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

Obtient une référence à l'objet `$array[$key]`. Si l'index n'existe pas, un nouvel index est créé avec la valeur `null`.

```php
$valueRef = & Arrays::getRef($array, 'foo');
// renvoie une référence à $array['foo'].
```

Fonctionne avec les tableaux multidimensionnels ainsi qu'avec [get() |#get()].

```php
$value = & Arrays::get($array, ['color', 'favorite']);
// renvoie la référence $array['color']['favorite'].
```


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

Renvoie uniquement les éléments du tableau qui correspondent à l'expression régulière `$pattern`. Si `$invert` est `true`, il renvoie les éléments qui ne correspondent pas. Une erreur de compilation ou d'exécution de l'expression régulière entraîne le lancement de `Nette\RegexpException`.

```php
$filteredArray = Arrays::grep($array, '~^\d+$~');
// renvoie uniquement les éléments numériques
```


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

Insère le contenu du tableau `$inserted` dans le tableau `$array` immédiatement après le tableau `$key`. Si `$key` est `null` (ou n'existe pas), il est inséré à la fin.

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

Insère le contenu du tableau `$inserted` dans le fichier `$array` avant le fichier `$key`. Si `$key` est `null` (ou n'existe pas), il est inséré au début.

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

Appelle tous les callbacks et renvoie un tableau de résultats.

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

Appelle la méthode sur chaque objet d'un tableau et renvoie un tableau de résultats.

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

Vérifie si le tableau est indexé dans l'ordre croissant des clés numériques à partir de zéro, c'est-à-dire une 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]
------------------------------------------------------------------------------------

Renvoie le dernier élément (correspondant au prédicat spécifié, le cas échéant). S'il n'existe pas d'élément de ce type, il renvoie le résultat de l'invocation de `$else` ou null.
Le site `$predicate` a la signature `function ($value, int|string $key, array $array): bool`.

Il ne modifie pas le pointeur interne, contrairement à `end()`. Les paramètres `$predicate` et `$else` existent depuis la 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
```

Voir [first() |#first()].


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

Renvoie la clé du dernier élément (correspondant au prédicat spécifié s'il est donné) ou null s'il n'y a pas d'élément de ce type. La signature de `$predicate` est `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
```

Voir [firstKey() |#firstKey()].


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

Appelle `$transformer` sur tous les éléments du tableau et renvoie le tableau des valeurs de retour. Le callback a la signature `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]
-----------------------------------------------------------------

Crée un nouveau tableau en transformant les valeurs et les clés du tableau original. La fonction `$transformer` a pour signature `function ($value, $key, array $array): ?array{$newValue, $newKey}`. Si `$transformer` renvoie `null`, l'élément est ignoré. Pour les éléments conservés, le premier élément du tableau retourné est utilisé comme nouvelle clé et le deuxième élément comme nouvelle valeur.

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

Cette méthode est utile dans les situations où vous devez modifier la structure d'un tableau (à la fois les clés et les valeurs) ou filtrer les éléments au cours de la transformation (en renvoyant null pour les éléments non souhaités).


mergeTree(array $array1, array $array2): array .[method]
--------------------------------------------------------

Fusionne récursivement deux champs. Il est utile, par exemple, pour fusionner des structures arborescentes. Il se comporte comme l'opérateur `+` pour les tableaux, c'est-à-dire qu'il ajoute une paire clé/valeur du second tableau au premier et conserve la valeur du premier tableau en cas de collision de clés.

```php
$array1 = ['color' => ['favorite' => 'red'], 5];
$array2 = [10, 'color' => ['favorite' => 'green', 'blue']];

$array = Arrays::mergeTree($array1, $array2);
// $array = ['color' => ['favorite' => 'red', 'blue'], 5];
```

Les valeurs du deuxième tableau sont toujours ajoutées au premier. La disparition de la valeur `10` du deuxième tableau peut sembler un peu déroutante. Il convient de noter que cette valeur, ainsi que la valeur `5` in the first array have the same numeric key `0`, font que dans le champ résultant, il n'y a qu'un élément du premier tableau.


normalize(array $array, ?string $filling=null): array .[method]
---------------------------------------------------------------

Normalise le tableau en tableau associatif. Remplacez les clés numériques par leurs valeurs, la nouvelle valeur sera `$filling`.

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

Renvoie et supprime la valeur d'un élément d'un tableau. S'il n'existe pas, il lève une exception, ou renvoie `$default`, s'il est fourni.

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

Renomme une clé. Retourne `true` si la clé a été trouvée dans le tableau.

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


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

Renvoie la position indexée zéro de la clé du tableau donné. Retourne `null` si la clé n'est pas trouvée.

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

Teste si au moins un élément du tableau passe le test implémenté par la callback fournie avec la signature `function ($value, $key, array $array): bool`.

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

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


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

Convertit une valeur en une clé de tableau, qui est soit un entier, soit une chaîne de caractères.

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


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

Copie les éléments du tableau `$array` dans l'objet `$object`, puis le renvoie.

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

Il transforme chaque élément du tableau en chaîne de caractères et l'entoure de `$prefix` et `$suffix`.

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


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

L'objet [api:Nette\Utils\ArrayHash] est le descendant de la classe générique stdClass et l'étend à la possibilité de le traiter comme un tableau, par exemple en accédant aux membres à l'aide de crochets :

```php
$hash = new Nette\Utils\ArrayHash;
$hash['foo'] = 123;
$hash->bar = 456; // also works object notation
$hash->foo; // 123
```

Vous pouvez utiliser la fonction `count($hash)` pour obtenir le nombre d'éléments.

Vous pouvez itérer sur un objet comme vous le feriez sur un tableau, même avec une référence :

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

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

Les tableaux existants peuvent être transformés en `ArrayHash` en utilisant `from()`:

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

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

La transformation est récursive :

```php
$array = ['foo' => 123, 'inner' => ['a' => 'b']];

$hash = Nette\Utils\ArrayHash::from($array);
$hash->inner; // object ArrayHash
$hash->inner->a; // 'b'
$hash['inner']['a']; // 'b'
```

Elle peut être évitée par le deuxième paramètre :

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

Transformer en retour au tableau :

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


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

[api:Nette\Utils\ArrayList] représente un tableau linéaire où les index sont uniquement des entiers croissants à partir de 0.

```php
$list = new Nette\Utils\ArrayList;
$list[] = 'a';
$list[] = 'b';
$list[] = 'c';
// ArrayList(0 => 'a', 1 => 'b', 2 => 'c')
count($list); // 3
```

Vous pouvez utiliser la fonction `count($list)` pour obtenir le nombre d'éléments.

Vous pouvez itérer sur un objet comme vous le feriez sur un tableau, même avec une référence :

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

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

Les tableaux existants peuvent être transformés en `ArrayList` en utilisant `from()`:

```php
$array = ['foo', 'bar'];
$list = Nette\Utils\ArrayList::from($array);
```

L'accès aux clés au-delà des valeurs autorisées déclenche une exception `Nette\OutOfRangeException`:

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

La suppression de la clé entraîne la renumérotation des éléments :

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

Vous pouvez ajouter un nouvel élément au début en utilisant `prepend()`:

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