Array.prototype.unshift()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/Array/unshift
  • Revision title: Array.unshift
  • Revision id: 417527
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment Moved From JavaScript/Reference/Global_Objects/Array/unshift to Web/JavaScript/Reference/Global_Objects/Array/unshift

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

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

Revision Source

<h2 id="Summary" 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-US/docs/JavaScript/Reference/Global_Objects/Array" title="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 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
<code><em>arrayName</em>.unshift(<em>element1</em>, ..., <em>elementN</em>) </code></pre>
<h3 id="Parameters" 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 id="Returns">Returns</h3>
<p>The new <code><a href="length" rel="internal" title="JavaScript/Reference/Global_Objects/Array/length">length</a></code> property of the object upon which the method was called.</p>
<dl>
</dl>
<h2 id="Description" 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-US/docs/JavaScript/Reference/Global_Objects/Function/call" title="JavaScript/Reference/Global_Objects/Function/call">called</a> or <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function/apply" title="JavaScript/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 id="Examples" name="Examples">Examples</h2>
<pre class="brush:js">
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 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array/pop" title="JavaScript/Reference/Global_Objects/Array/pop">pop</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array/push" title="JavaScript/Reference/Global_Objects/Array/push">push</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array/shift" title="JavaScript/Reference/Global_Objects/Array/shift">shift</a></li>
</ul>
<!-- languages({
"fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array/unshift"
}) -->
Revert to this revision