mozilla

Revision 238159 of Array.prototype.unshift()

  • Revision slug: JavaScript/Reference/Global_Objects/Array/unshift
  • Revision title: Array unshift method
  • Revision id: 238159
  • Created:
  • Creator: zirak
  • Is current revision? No
  • Comment 70 words added, 96 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.

Returns

The new length property of the object upon which the method was called.

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

var arr = [1, 2];

arr.unshift(0); //result of call is 3, the new array length
//arr is [0, 1, 2]

arr.unshift(-2, -1); // = 5
//arr is [-2, -1, 0, 1, 2]

arr.unshift( [-3] );
//arr is [[-3], -2, -1, 0, 1, 2]

See Also

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

Revision Source

<h2 name="Summary">Summary</h2>
<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" title="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>
<h2 name="Syntax">Syntax</h2>
<p><code><em>arrayName</em>.unshift(<em>element1</em>, ..., <em>elementN</em>) </code></p>
<h2 name="Parameters">Parameters</h2>
<dl> <dt><code>element1, ..., element<em>N</em></code></dt> <dd>The elements to add to the front of the array.</dd>
</dl>
<h2 name="Parameters">Returns</h2>
<p>The new <code><a href="length" rel="internal" title="en/JavaScript/Reference/Global_Objects/Array/length">length</a></code> property of the object upon which the method was called.</p>
<dl>
</dl>
<h2 name="Description">Description</h2>
<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>
<h2 name="Examples">Examples</h2>
<h3 name="Example:_Adding_elements_to_an_array">Example: Adding elements to an array</h3>
<pre class="script-jem">var arr = [1, 2];

arr.unshift(0); //result of call is 3, the new array length
//arr is [0, 1, 2]

arr.unshift(-2, -1); // = 5
//arr is [-2, -1, 0, 1, 2]

arr.unshift( [-3] );
//arr is [[-3], -2, -1, 0, 1, 2]</pre>
<h2 name="See_Also">See Also</h2>
<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/JavaScript/Reference/Global_Objects/Array/unshift", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array/unshift" } ) }}</p>
Revert to this revision