array_unshift

Prepend one or more elements to the beginning of an array

&reftitle.description; `int` `array_unshift` `array` `array` `mixed` `values`

`array_unshift` prepends passed elements to the front of the `array`. Note that the list of elements is prepended as a whole, so that the prepended elements stay in the same order. All numerical array keys will be modified to start counting from zero while literal keys won't be changed.

¬e.reset-index;
&reftitle.parameters;

`array`

- The input array.

`values`

- The values to prepend.

&reftitle.returnvalues;

Returns the new number of elements in the `array`.

&reftitle.changelog;

&Version; | &Description;
7.3.0 | This function can now be called with only one parameter. Formerly, at least two parameters have been required.

&reftitle.examples;

### `array_unshift` example

    <?php
    $queue = [
        "orange",
        "banana"
    ];

    array_unshift($queue, "apple", "raspberry");
    var_dump($queue);
    ?>

&example.outputs;

    array(4) {
      [0] =>
      string(5) "apple"
      [1] =>
      string(9) "raspberry"
      [2] =>
      string(6) "orange"
      [3] =>
      string(6) "banana"
    }

### Usage with associative arrays

If one associative array is prepended to another associative array, the prepended array is numerically indexed into the former array.

    <?php
    $foods = [
        'apples' => [
            'McIntosh' => 'red',
            'Granny Smith' => 'green',
        ],
        'oranges' => [
            'Navel' => 'orange',
            'Valencia' => 'orange',
        ],
    ];
    $vegetables = [
        'lettuce' => [
            'Iceberg' => 'green',
            'Butterhead' => 'green',
        ],
        'carrots' => [
            'Deep Purple Hybrid' => 'purple',
            'Imperator' => 'orange',
        ],
        'cucumber' => [
            'Kirby' => 'green',
            'Gherkin' => 'green',
        ],
    ];

    array_unshift($foods, $vegetables);
    var_dump($foods);

&example.outputs;

    array(3) {
      [0] =>
      array(3) {
        'lettuce' =>
        array(2) {
          'Iceberg' =>
          string(5) "green"
          'Butterhead' =>
          string(5) "green"
        }
        'carrots' =>
        array(2) {
          'Deep Purple Hybrid' =>
          string(6) "purple"
          'Imperator' =>
          string(6) "orange"
        }
        'cucumber' =>
        array(2) {
          'Kirby' =>
          string(5) "green"
          'Gherkin' =>
          string(5) "green"
        }
      }
      'apples' =>
      array(2) {
        'McIntosh' =>
        string(3) "red"
        'Granny Smith' =>
        string(5) "green"
      }
      'oranges' =>
      array(2) {
        'Navel' =>
        string(6) "orange"
        'Valencia' =>
        string(6) "orange"
      }
    }

&reftitle.seealso;

- `array_merge`
- `array_shift`
- `array_push`
- `array_pop`