This operates very like the Array.push() method except that items are added to the front of the stack rather than the end of the stack. The items are also pushed in reverse order if several are presented at once. That is to say, the order or presentation is preserved within the array.

When the push is completed, the item at the front of the array is returned.

The number of items that were added increases the array length.

If arrays are presented, they will be pushed on as they are and not flattened. When they are subsequently removed from the stack, they will still be arrays.

This method modifies the array in place.

The result of this method is the new length of the receiving array after the pushed item has been concatenated onto its tail.

Example code:

   // Create an array and test the Array.unshift() method

   myArray = new Array("AAA", "BBB", "CCC");

   document.write("Array<BR>")

   displayArrayAsTable(myArray);

   document.write("Array.unshift()<BR>")

   document.write(myArray.unshift("XXX"))

   document.write("<BR><BR>")

   document.write("Array after unshift('XXX') call<BR>")

   displayArrayAsTable(myArray);

   

   // Display an array in a table

   function displayArrayAsTable(anArray)

   {

      myLength = anArray.length;

      document.write("<TABLE BORDER=1>");

      for(myIndex = 0; myIndex < myLength; myIndex++)

      {

         document.write("<TR><TD>");

         document.write(myIndex);

         document.write("</TD><TD>");

         document.write(anArray[myIndex]);

         document.write("</TD></TR>");

      }

      document.write("</TABLE><BR><BR>")

   }

Cross-references:

ECMA 262 edition 3 - section - 15.4.4.13