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.
Les exemples suivants supposent que l'alias de classe suivant est défini :
use Nette\Utils\Arrays;
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(iterable $array, callable $callback): 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().
first(array $array): mixed
Retourne le premier élément du tableau ou null si le tableau est vide. Elle ne modifie pas le pointeur interne contrairement
à reset()
.
Arrays::first([1, 2, 3]); // 1
Arrays::first([]); // null
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): mixed
Retourne le dernier élément du tableau ou null si le tableau est vide. Elle ne modifie pas le pointeur interne contrairement
à end()
.
Arrays::last([1, 2, 3]); // 3
Arrays::last([]); // null
map(iterable $array, callable $callback): array
Appelle $callback
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']
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(iterable $array, callable $callback): 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(iterable $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.
Vous pouvez itérer sur un objet comme vous le feriez sur un tableau, même avec une référence :
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()
:
$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
:
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 :
unset($list[1]);
// ArrayList(0 => 'a', 1 => 'c')
Vous pouvez ajouter un nouvel élément au début en utilisant prepend()
:
$list->prepend('d');
// ArrayList(0 => 'd', 1 => 'a', 2 => 'c')