Praca z tablicami
Ta strona poświęcona jest klasom Nette\Utils\Arrays, ArrayHash i ArrayList, które dotyczą tablic.
Instalacja:
Arrays
Nette\Utils\Arrays to statyczna klasa zawierająca przydatne funkcje do pracy z tablicami. Jej odpowiednikiem dla iteratorów jest Nette\Utils\Iterables.
Poniższe przykłady zakładają utworzony alias:
associate(array $array, mixed $path): array|\stdClass
Funkcja elastycznie przekształca tablicę $array
w tablicę asocjacyjną lub obiekty zgodnie z podaną
ścieżką $path
. Ścieżka może być ciągiem znaków lub tablicą. Składa się z nazw kluczy tablicy wejściowej
oraz operatorów takich jak ‚[]‘, ‚->‘, ‚=‘, i ‚|‘. Rzuca Nette\InvalidArgumentException
w
przypadku, gdy ścieżka jest nieprawidłowa.
contains(array $array, $value): bool
Sprawdza tablicę pod kątem obecności wartości. Używa ścisłego porównania (===
).
every(array $array, callable $predicate): bool
Sprawdza, czy wszystkie elementy w tablicy przechodzą test zaimplementowany w $predicate
o sygnaturze
function ($value, $key, array $array): bool
.
Zobacz some().
filter(array $array, callable $predicate): array
Zwraca nową tablicę zawierającą wszystkie pary klucz-wartość pasujące do podanego predykatu. Callback ma sygnaturę
function ($value, int|string $key, array $array): bool
.
first(array $array, ?callable $predicate=null, ?callable $else=null): mixed
Zwraca pierwszy element (pasujący do predykatu, jeśli jest podany). Jeśli taki element nie istnieje, zwraca wynik wywołania
$else
lub null. Parametr $predicate
ma sygnaturę
function ($value, int|string $key, array $array): bool
.
Nie zmienia wewnętrznego wskaźnika w przeciwieństwie do reset()
. Parametry $predicate
i
$else
istnieją od wersji 4.0.4.
Zobacz last().
firstKey(array $array, ?callable $predicate=null): int|string|null
Zwraca klucz pierwszego elementu (pasującego do predykatu, jeśli jest podany) lub null, jeśli taki element nie istnieje.
Predykat $predicate
ma sygnaturę function ($value, int|string $key, array $array): bool
.
Zobacz lastKey().
flatten(array $array, bool $preserveKeys=false): array
Spłaszcza wielopoziomową tablicę do płaskiej.
get(array $array, string|int|array $key, ?mixed $default=null): mixed
Zwraca element $array[$key]
. Jeśli nie istnieje, rzuca wyjątek Nette\InvalidArgumentException
lub,
jeśli podano trzeci parametr $default
, zwraca go.
Kluczem $key
może być również tablica.
getRef(array &$array, string|int|array $key): mixed
Pobiera referencję do określonego elementu tablicy. Jeśli element nie istnieje, zostanie utworzony z wartością null.
Podobnie jak funkcja get(), potrafi pracować z tablicami wielowymiarowymi.
grep(array $array, string $pattern, bool $invert=false): array
Zwraca tylko te elementy tablicy, których wartość pasuje do wyrażenia regularnego $pattern
. Jeśli
$invert
jest true
, zwraca elementy, które nie pasują. Błąd podczas kompilacji lub przetwarzania
wyrażenia rzuca wyjątek Nette\RegexpException
.
insertAfter(array &$array, string|int|null $key, array $inserted): void
Wstawia zawartość tablicy $inserted
do tablicy $array
tuż za elementem o kluczu
$key
. Jeśli $key
jest null
(lub nie ma go w tablicy), wstawia na koniec.
insertBefore(array &$array, string|int|null $key, array $inserted): void
Wstawia zawartość tablicy $inserted
do tablicy $array
przed elementem o kluczu $key
.
Jeśli $key
jest null
(lub nie ma go w tablicy), wstawia na początek.
invoke(iterable $callbacks, …$args): array
Wywołuje wszystkie callbacki i zwraca tablicę wyników.
invokeMethod(iterable $objects, string $method, …$args): array
Wywołuje metodę na każdym obiekcie w tablicy i zwraca tablicę wyników.
isList(array $array): bool
Sprawdza, czy tablica jest indeksowana według rosnącej serii kluczy numerycznych od zera, a.k.a lista.
last(array $array, ?callable $predicate=null, ?callable $else=null): mixed
Zwraca ostatni element (pasujący do predykatu, jeśli jest podany). Jeśli taki element nie istnieje, zwraca wynik wywołania
$else
lub null. Parametr $predicate
ma sygnaturę
function ($value, int|string $key, array $array): bool
.
Nie zmienia wewnętrznego wskaźnika w przeciwieństwie do end()
. Parametry $predicate
i
$else
istnieją od wersji 4.0.4.
Zobacz first().
lastKey(array $array, ?callable $predicate=null): int|string|null
Zwraca klucz ostatniego elementu (pasującego do predykatu, jeśli jest podany) lub null, jeśli taki element nie istnieje.
Predykat $predicate
ma sygnaturę function ($value, int|string $key, array $array): bool
.
Zobacz firstKey().
map(array $array, callable $transformer): array
Wywołuje $transformer
na wszystkich elementach w tablicy i zwraca tablicę zwróconych wartości. Callback ma
sygnaturę function ($value, $key, array $array): mixed
.
mapWithKeys(array $array, callable $transformer): array
Tworzy nową tablicę przez transformację wartości i kluczy oryginalnej tablicy. Funkcja $transformer
ma
sygnaturę function ($value, $key, array $array): ?array{$newKey, $newValue}
. Jeśli $transformer
zwróci null
, element jest pomijany. Dla zachowanych elementów pierwszy element zwróconej tablicy jest używany
jako nowy klucz, a drugi element jako nowa wartość.
Ta metoda jest przydatna w sytuacjach, gdy potrzebujesz zmienić strukturę tablicy (klucze i wartości jednocześnie) lub filtrować elementy podczas transformacji (zwracając null dla niechcianych elementów).
mergeTree(array $array1, array $array2): array
Rekurencyjnie łączy dwie tablice. Przydaje się na przykład do łączenia struktur drzewiastych. Podczas łączenia kieruje
się tymi samymi zasadami co operator +
zastosowany do tablic, tj. do pierwszej tablicy dodaje pary klucz/wartość
z drugiej tablicy, a w przypadku kolizji kluczy pozostawia wartość z pierwszej tablicy.
Wartości z drugiej tablicy są zawsze dodawane na koniec pierwszej. Trochę mylące może wydawać się zniknięcie wartości
10
z drugiej tablicy. Należy zdać sobie sprawę, że ta wartość, podobnie jak wartość 5
w
pierwszej tablicy, mają przypisany ten sam klucz numeryczny 0
, dlatego w wynikowej tablicy znajduje się tylko
element z pierwszej tablicy.
normalize(array $array, ?string $filling=null): array
Normalizuje tablicę do tablicy asocjacyjnej. Klucze numeryczne zastępuje ich wartościami, nową wartością będzie
$filling
.
pick(array &$array, string|int $key, ?mixed $default=null): mixed
Zwraca i usuwa wartość elementu z tablicy. Jeśli nie istnieje, rzuca wyjątek lub zwraca wartość $default
,
jeśli jest podana.
renameKey(array &$array, string|int $oldKey, string|int $newKey): bool
Zmienia nazwę klucza w tablicy. Zwraca true
, jeśli klucz został znaleziony w tablicy.
getKeyOffset(array $array, string|int $key): ?int
Zwraca pozycję danego klucza w tablicy. Pozycja jest numerowana od 0. W przypadku, gdy klucz nie zostanie znaleziony, funkcja
zwróci null
.
some(array $array, callable $predicate): bool
Sprawdza, czy przynajmniej jeden element w tablicy przechodzi test zaimplementowany w $predicate
o sygnaturze
function ($value, $key, array $array): bool
.
Zobacz every().
toKey(mixed $key): string|int
Konwertuje wartość na klucz tablicy, który jest albo liczbą całkowitą, albo ciągiem znaków.
toObject(iterable $array, object $object): object
Kopiuje elementy tablicy $array
do obiektu $object
, który następnie zwraca.
wrap(array $array, string
$prefix=''
, string $suffix=''
): array
Każdy element w tablicy rzutuje na ciąg znaków i otacza prefiksem $prefix
oraz sufiksem
$suffix
.
ArrayHash
Obiekt Nette\Utils\ArrayHash jest potomkiem generycznej klasy stdClass i rozszerza ją o możliwość traktowania go jak tablicy, czyli na przykład dostępu do elementów za pomocą nawiasów kwadratowych:
Można używać funkcji count($hash)
do sprawdzania liczby elementów.
Nad obiektem można iterować tak samo jak w przypadku tablicy, również z referencją:
Istniejącą tablicę możemy przekształcić na ArrayHash
za pomocą metody from()
:
Konwersja jest rekurencyjna:
Można temu zapobiec drugim parametrem:
Transformacja z powrotem na tablicę:
ArrayList
Nette\Utils\ArrayList reprezentuje tablicę liniową, gdzie indeksy są wyłącznie liczbami całkowitymi rosnącymi od 0.
Istniejącą tablicę możemy przekształcić na ArrayList
za pomocą metody from()
:
Można używać funkcji count($list)
do sprawdzania liczby elementów.
Nad obiektem można iterować tak samo jak w przypadku tablicy, również z referencją:
Dostęp do kluczy spoza dozwolonych wartości rzuca wyjątek Nette\OutOfRangeException
:
Usunięcie klucza powoduje przenumerowanie elementów:
Nowy element można dodać na początek za pomocą metody prepend()
: