Array.prototype.unshift()

  • Revision slug: JavaScript/Reference/Global_Objects/Array/unshift
  • Revision title: Array unshift method
  • Revision id: 26339
  • Created:
  • Creator: evilpie
  • Is current revision? No
  • Comment 1 words added, 5 words removed

Revision Content

Summary

Adds one or more elements to the beginning of an array and returns the new length of the array.

Method of Array
Implemented in JavaScript 1.2
ECMAScript Edition ECMAScript 3rd Edition

Syntax

arrayName.unshift(element1, ..., elementN)

Parameters

element1, ..., elementN
The elements to add to the front of the array.

Description

The unshift method inserts the given values to the beginning of an array-like object.

unshift is intentionally generic; this method can be called or applied to objects resembling arrays. Objects which do not contain a length property reflecting the last in a series of consecutive, zero-based numerical properties may not behave in any meaningful manner.

Examples

Example: Adding elements to an array

The following code displays the myFish array before and after adding elements to it.

// assumes a println function exists
myFish = ["angel", "clown"];
println("myFish before: " + myFish);
unshifted = myFish.unshift("drum", "lion");
println("myFish after: " + myFish);
println("New length: " + unshifted);

This example displays the following:

myFish before: ["angel", "clown"]
myFish after: ["drum", "lion", "angel", "clown"]
New length: 4

See Also

{{ languages( { "fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array/unshift", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array/unshift", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array/unshift" } ) }}

Revision Source

<h3 name="Summary">Summary</h3>
<p>Adds one or more elements to the beginning of an array and returns the new length of the array.</p>
<table class="standard-table"> <thead> <tr> <th class="header" colspan="2">Method of <a href="/en/JavaScript/Reference/Global_Objects/Array"><code>Array</code></a></th> </tr> </thead> <tbody> <tr> <td>Implemented in</td> <td>JavaScript 1.2</td> </tr> <tr> <td>ECMAScript Edition</td> <td>ECMAScript 3rd Edition</td> </tr> </tbody>
</table> <h3 name="Syntax">Syntax</h3>
<p><code><em>arrayName</em>.unshift(<em>element1</em>, ..., <em>elementN</em>) </code></p>
<h3 name="Parameters">Parameters</h3>
<dl> <dt><code>element1, ..., element<em>N</em></code></dt> <dd>The elements to add to the front of the array.</dd>
</dl>
<h3 name="Description">Description</h3>
<p>The <code>unshift</code> method inserts the given values to the beginning of an array-like object.</p>
<p><code>unshift</code> is intentionally generic; this method can be <a href="/en/JavaScript/Reference/Global_Objects/Function/call" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Function/call">called</a> or <a href="/en/JavaScript/Reference/Global_Objects/Function/apply" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Function/apply">applied</a> to objects resembling arrays. Objects which do not contain a <code>length</code> property reflecting the last in a series of consecutive, zero-based numerical properties may not behave in any meaningful manner.</p>
<h3 name="Examples">Examples</h3>
<h4 name="Example:_Adding_elements_to_an_array">Example: Adding elements to an array</h4>
<p>The following code displays the <code>myFish</code> array before and after adding elements to it.</p>
<pre class="eval">// assumes a println function exists
myFish = ["angel", "clown"];
println("myFish before: " + myFish);
unshifted = myFish.unshift("drum", "lion");
println("myFish after: " + myFish);
println("New length: " + unshifted);
</pre>
<p>This example displays the following:</p>
<pre class="eval">myFish before: ["angel", "clown"]
myFish after: ["drum", "lion", "angel", "clown"]
New length: 4
</pre>
<h3 name="See_Also">See Also</h3>
<ul> <li><a href="/en/JavaScript/Reference/Global_Objects/Array/pop" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array/pop">pop</a></li> <li><a href="/en/JavaScript/Reference/Global_Objects/Array/push" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array/push">push</a></li> <li><a href="/en/JavaScript/Reference/Global_Objects/Array/shift" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array/shift">shift</a></li>
</ul>
<p>{{ languages( { "fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array/unshift", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array/unshift", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array/unshift" } ) }}</p>
Revert to this revision