Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Function Reference : Array Functions : array_unshift

array_unshift

Prepend one or more elements to the beginning of an array (PHP 4, PHP 5)
int array_unshift ( array &array, mixed var [, mixed ...] )

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 touched.

Returns the new number of elements in the array.

Example288.array_unshift() example

<?php
$queue
= array("orange", "banana");
array_unshift($queue, "apple", "raspberry");
print_r($queue);
?>

The above example will output:

Array
(
[
0] => apple
[1] => raspberry
[2] => orange
[3] => banana
) ?>


See also array_shift(), array_push(), and array_pop().

Related Examples ( Source code ) » array_unshift


Code Examples / Notes » array_unshift

sergei

You can preserve keys and unshift an array with numerical indexes in a really simple way if you'll do the following:
$someArray=array(224=>'someword1', 228=>'someword2', 102=>'someword3', 544=>'someword3',95=>'someword4');
$someArray=array(100=>'Test Element 1 ',255=>'Test Element 2')+$someArray;
now the array looks as follows:
array(
100=>'Test Element 1 ',
255=>'Test Element 2'
224=>'someword1',
228=>'someword2',
102=>'someword3',
544=>'someword3',
95=>'someword4'
);


amschroeder

This becomes a nice little problem if you index your arrays out of order (while manually sorting).  For example:
$recordMonths[3] = '8/%/2006';
$recordMonths[4] = '7/%/2004';
$recordMonths[0] = '3/%/2007';
$recordMonths[1] = '2/%/2007';
$recordMonths[5] = '12/%/2000';
$recordMonths[6] = '11/%/2000';
$recordMonths[7] = '10/%/2000';
$recordMonths[2] = '1/%/2007';
for($i = 0; $i < count($recordMonths); $i++)
{
$singleMonth = $recordMonths[$i];
echo "singleMonth: $singleMonth <br />";
}
array_unshift($recordMonths,'%');
for($i = 0; $i < count($recordMonths); $i++)
{
$singleMonth = $recordMonths[$i];
echo "singleMonth: $singleMonth <br />";
}
Produces:
singleMonth: 3/%/2007
singleMonth: 2/%/2007
singleMonth: 1/%/2007
singleMonth: 8/%/2006
singleMonth: 7/%/2004
singleMonth: 12/%/2000
singleMonth: 11/%/2000
singleMonth: 10/%/2000
singleMonth: %
singleMonth: 8/%/2006
singleMonth: 7/%/2004
singleMonth: 3/%/2007
singleMonth: 2/%/2007
singleMonth: 12/%/2000
singleMonth: 11/%/2000
singleMonth: 10/%/2000
singleMonth: 1/%/2007
It reindexes them based on the order they were created.  It seems like if an array has all numeric indexes, then it should reindex them based on the order of their index.  Just my opinion...


matt

The behaviour of unshift nearly caught me out.
Not only is the item added at the start of the list but the list is re-indexed too.
<?php
$a = array(5=>"five", 6 =>"six", 20 => "twenty");
while(list($key, $value) = each($a))
echo "k: $key v: $value
\n";
echo "
\n";
array_unshift($a, "zero");
while(list($key, $value) = each($a))
echo "k: $key v: $value
\n";
?>
k: 5 v: five
k: 6 v: six
k: 20 v: twenty
k: 0 v: zero
k: 1 v: five
k: 2 v: six
k: 3 v: twenty


lagroue

Last version of PHP deprecated unshifting of a reference.
You can use this function instead :
<?php
function array_unshift1 (& $ioArray, $iValueWrappedInAnArray) {
$lNewArray = false;
foreach (array_keys ($ioArray) as $lKey)
$lNewArray[$lKey+1] = & $ioArray[$lKey];
$ioArray = array (& $iValueWrappedInAnArray[0]);
if ($lNewArray)
foreach (array_keys ($lNewArray) as $lKey)
$ioArray[] = & $lNewArray[$lKey];
return count($ioArray);
}
// before last PHP (now generates a deprecation warning)
array_unshift ($a, &$v);
// since last PHP (caution, there is a wrapping array !!)
array_unshift1 ($a, array (&$v));
?>


sahn

If you need to prepend something to the array without the keys being reindexed and/or need to prepend a key value pair, you can use this short function:
<?php
function array_unshift_assoc(&$arr, $key, $val)
{
   $arr = array_reverse($arr, true);
   $arr[$key] = $val;
   $arr = array_reverse($arr, true);
   return count($arr);
}
?>


chris dot nothxspam dot given

If you need to change the name of a key without changing its position in the array this function may be useful.
<?php
function array_key_change($Old, $New, $In, $NewVal=NULL) {
       $Temp = array();
       while(isset($Temp[$Old]) == false) {
               list($k, $v) = each($In);
               $Temp[$k] = $v;
               unset($In[$k]);
       }
       if($NewVal == NULL) {
               $NewVal = $Temp[$Old];
       }
       unset($Temp[$Old]);
       $Temp = array_reverse($Temp);
       $In = array_merge(array($New=>$NewVal), $In);
       while(list($k,$v) = each($Temp)) {
               $In = array_merge(array($k=>$v), $In);
       }
       return($In);
}
?>


jrh_at_geodata.soton.ac.uk

I have found array_unshift is a function that should be avoided when unshifting lots of data in large arrays.
In a recent script I wrote, it took approx. 24 seconds to unshift 3500 timestamps to an array, a work around could be to use array_reverse and array_push. Array_push is much faster due to the indexing.


john brooking

I had a need tonight to convert a numeric array from 1-based to 0-based, and found that the following worked just fine due to the "side effect" of renumbering:
  array_unshift( $myArray, array_shift( $myArray ));


07-nov-2005 07:38

function multi_array_search($search_value, $the_array)
{
  if (is_array($the_array))
  {
      foreach ($the_array as $key => $value)
      {
          $result = multi_array_search($search_value, $value);
          if (is_array($result))
          {
              $return = $result;
              array_unshift($return, $key);
              return $return;
          }
          elseif ($result == true)
          {
              $return[] = $key;
              return $return;
          }
      }
      return false;
  }
  else
  {
      if ($search_value == $the_array)
      {
          return true;
      }
      else return false;
  }
}


php

even simpler unshifting of a reference !
<?php
/**
* @return int
* @param $array array
* @param $value mixed
* @desc Prepend a reference to an element to the beginning of an array. Renumbers numeric keys, so $value is always inserted to $array[0]
*/
function array_unshift_ref(&$array, &$value)
{
  $return = array_unshift($array,'');
  $array[0] =& $value;
  return $return;
}
?>


rsmith_nospam_

array_merge() will also reindex (see array_merge() manual entry), but the '+' operator won't, so...
<?php
$arrayone=array("newkey"=>"newvalue") + $arrayone;
?>
does the job.


robert dot wills

Actually this problem with the keys getting reindexed only happens when the keys are numerical:
<?php
$a = array("f"=>"five", "s" =>"six", "t" =>
       "twenty");
print_r($a);
echo "\n";
foreach($a as $key=>$val)
{
   echo "k: $key v: $val \n";
}
array_unshift($a, "zero");
print_r($a);
echo "\n";
foreach($a as $key=>$val)
{
   echo "k: $key v: $val \n";
}
?>
Array
(
   [f] => five
   [s] => six
   [t] => twenty
)
k: f v: five
k: s v: six
k: t v: twenty
Array
(
   [0] => zero
   [f] => five
   [s] => six
   [t] => twenty
)
k: 0 v: zero
k: f v: five
k: s v: six
k: t v: twenty


timhyde

A simpler way to implement an array_unshift with key=>value pairs (i.e. similar to the example using array_reverse above) is to use array_merge.  i.e.
<?php
$arrayone=array_merge(array("newkey"=>"newvalue"),$arrayone);
?>
Obviously you need to take care when adding numeric or duplicate keys.


mightye

@John Brooking:
Better performing would most likely be array_values($input)


Change Language


Follow Navioo On Twitter
array_change_key_case
array_chunk
array_combine
array_count_values
array_diff_assoc
array_diff_key
array_diff_uassoc
array_diff_ukey
array_diff
array_fill_keys
array_fill
array_filter
array_flip
array_intersect_assoc
array_intersect_key
array_intersect_uassoc
array_intersect_ukey
array_intersect
array_key_exists
array_keys
array_map
array_merge_recursive
array_merge
array_multisort
array_pad
array_pop
array_product
array_push
array_rand
array_reduce
array_reverse
array_search
array_shift
array_slice
array_splice
array_sum
array_udiff_assoc
array_udiff_uassoc
array_udiff
array_uintersect_assoc
array_uintersect_uassoc
array_uintersect
array_unique
array_unshift
array_values
array_walk_recursive
array_walk
array
arsort
asort
compact
count
current
each
end
extract
in_array
key
krsort
ksort
list
natcasesort
natsort
next
pos
prev
range
reset
rsort
shuffle
sizeof
sort
uasort
uksort
usort
eXTReMe Tracker