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.