array_unshift()

Ищете мощную функцию для добавления новых элементов в начало array в PHP? Обратите внимание на функцию array_unshift(). С её помощью можно легко добавить один или несколько элементов в начало array, автоматически переиндексируя числовые ключи и смещая существующие элементы на более высокие позиции.

Что такое array_unshift()?

Функция array_unshift() — это встроенная функция PHP, которая добавляет один или несколько элементов в начало array. Она не заменяет существующие элементы — она смещает их на более высокие позиции индекса, освобождая место для новых. Можно считать её зеркальным отражением array_push(), которая добавляет элементы в конец.

Синтаксис

array_unshift(array &$array, mixed ...$values): int

• $array — array, в начало которого добавляются элементы. Передаётся по ссылке, поэтому исходная переменная изменяется на месте.
• $values — одно или несколько значений, добавляемых в начало. Указанные слева направо, они появляются в том же порядке в начале array.

Функция возвращает новое количество элементов в array (целое число), а не сам array.

Простой пример

Мы добавляем "orange" и "lemon" в начало $fruits. Числовые ключи переиндексируются автоматически, начиная с 0, а возвращаемое значение 5 — это новое количество элементов. Вывод:

5
Array
(
    [0] => orange
    [1] => lemon
    [2] => apple
    [3] => banana
    [4] => cherry
)

Как обрабатываются ключи

Это наиболее распространённый источник неожиданных результатов. array_unshift() по-разному обрабатывает числовые и string ключи:

• Числовые ключи сбрасываются. Все существующие целочисленные ключи перенумеровываются начиная с 0. Любые пользовательские целочисленные ключи теряются.
• String (ассоциативные) ключи сохраняются. Только вновь добавленные элементы получают числовые ключи (0, 1, …); существующие string ключи сохраняют свои имена.

<?php

$data = array("name" => "Alice", 10 => "ten", 20 => "twenty");
array_unshift($data, "first");
print_r($data);

?>

Вывод — обратите внимание, что "name" сохраняется, а 10 и 20 становятся 1 и 2:

Array
(
    [0] => first
    [name] => Alice
    [1] => ten
    [2] => twenty
)

Когда использовать

• При построении очереди или списка, где новые элементы должны быть в начале (сначала самые свежие).
• При добавлении заголовочной строки или значения по умолчанию перед существующими данными.
• Для отмены действия array_shift(), которая удаляет первый элемент.

Замечание о производительности: поскольку каждый существующий элемент должен быть переиндексирован и смещён, array_unshift() имеет сложность O(n) — медленнее, чем array_push() с её O(1). Для очень больших array в горячем цикле предпочтительнее добавлять элементы в конец и один раз перевернуть array в конце, или использовать структуру данных наподобие SplDoublyLinkedList.

Связанные функции

• array_push() — добавить элементы в конец array.
• array_shift() — удалить первый элемент.
• array_splice() — вставить или удалить элементы в любой позиции.
• array_merge() — объединить два или более array.

Практика