Fonctions des tableaux

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

Installation :

composer require nette/utils

Matrices

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.

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

use Nette\Utils\Arrays;

associate (array $array, mixed $path): array|\stdClass

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.

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

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

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

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

// 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

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

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

every (array $array, callable $predicate): bool

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.

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

Voir some().

filter (array $array, callable $predicate): array

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.

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

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.

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().

firstKey (array $array, ?callable $predicate=null): int|string|null

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.

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().

flatten (array $array, bool $preserveKeys=false): array

Transforme un tableau multidimensionnel en tableau plat.

$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

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.

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

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

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

getRef (array &$array, string|int|array $key): mixed

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

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

Fonctionne avec les tableaux multidimensionnels ainsi qu'avec get().

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

grep (array $array, string $pattern, bool $invert=false): array

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.

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

insertAfter (array &$array, string|int|null $key, array $inserted): void

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.

$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

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.

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

invoke (iterable $callbacks, …$args): array

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

$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

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

$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

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.

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

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.

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().

lastKey (array $array, ?callable $predicate=null): int|string|null

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.

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().

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

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.

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

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

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.

$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

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.

$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

Normalise le tableau en tableau associatif. Remplacez les clés numériques par leurs valeurs, la nouvelle valeur sera $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

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.

$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

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

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

getKeyOffset (array $array, string|int $key): ?int

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

$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

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.

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

Voir every().

toKey (mixed $key): string|int

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

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

toObject (iterable $array, object $object): object

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

$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

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

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

ArrayHash

L'objet 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 :

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

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():

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

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

La transformation est récursive :

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

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

Transformer en retour au tableau :

$array = (array) $hash;

ArrayList

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

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