mozilla

Revision 515705 of Array.prototype.unshift()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/Array/unshift
  • Revision title: Array.prototype.unshift()
  • Revision id: 515705
  • Created:
  • Creator: netinept
  • Is current revision? No
  • Comment

Revision Content

{{JSRef("Global_Objects", "Array")}}

Summary

The unshift() method adds one or more elements to the beginning of an array and returns the new length of the array.

Syntax

arr.unshift(element1, ..., elementN) 

Parameters

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

Returns

The new {{jsxref("Array.length", "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 {{jsxref("Function.call", "called")}} or {{jsxref("Function.apply", "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]

Specifications

Specification Status Comment
ECMAScript 3rd Edition Standard Initial definition.
Implemented in JavaScript 1.2
{{SpecName('ES5.1', '#sec-15.4.4.13', 'Array.prototype.unshift')}} {{Spec2('ES5.1')}}  
{{SpecName('ES6', '#sec-array.prototype.unshift', 'Array.prototype.unshift')}} {{Spec2('ES6')}}  

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 1.0 {{CompatGeckoDesktop("1.7")}} 5.5 {{CompatVersionUnknown}} {{CompatVersionUnknown}}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}}

See also

  • {{jsxref("Array.prototype.push()")}}
  • {{jsxref("Array.prototype.pop()")}}
  • {{jsxref("Array.prototype.shift()")}}

Revision Source

<div>
 {{JSRef("Global_Objects", "Array")}}</div>
<h2 id="Summary" name="Summary">Summary</h2>
<p>The <code><strong>unshift()</strong></code> method adds one or more elements to the beginning of an array and returns the new length of the array.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
<code><em>arr</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 {{jsxref("Array.length", "length")}} 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 {{jsxref("Function.call", "called")}} or {{jsxref("Function.apply", "applied")}} 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="Specifications">Specifications</h2>
<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>ECMAScript 3rd Edition</td>
   <td>Standard</td>
   <td>Initial definition.<br />
    Implemented in JavaScript 1.2</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.4.4.13', 'Array.prototype.unshift')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-array.prototype.unshift', 'Array.prototype.unshift')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
 {{CompatibilityTable}}</div>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>1.0</td>
    <td>{{CompatGeckoDesktop("1.7")}}</td>
    <td>5.5</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Chrome for Android</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>IE Mobile</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
   </tr>
  </tbody>
 </table>
</div>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
 <li>{{jsxref("Array.prototype.push()")}}</li>
 <li>{{jsxref("Array.prototype.pop()")}}</li>
 <li>{{jsxref("Array.prototype.shift()")}}</li>
</ul>
<!-- languages({
"fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array/unshift"
}) -->
Revert to this revision