mozilla

Revision 313655 of Array.prototype.push()

  • Revision slug: JavaScript/Reference/Global_Objects/Array/push
  • Revision title: Array#push
  • Revision id: 313655
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

Revision Content

Summary

Mutates an array by appending the given elements and returning the new length of the array.

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

Syntax

array.push(element1, ..., elementN)

Parameters

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

Returns

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

Description

The push method is useful for easily appending values to an array.

push is intentionally generic. This method can be called or applied to objects resembling arrays. The push method relies on a length property to determine where to start inserting the given values. If the length property cannot be converted into a number, the index used is 0. This includes the possibility of length being nonexistent, in which case length will also be created.

The only native, array-like objects are strings, although they are not suitable in applications of this method, as strings are immutable.

Examples

Example: Adding elements to an array

The following code creates the sports array containing two elements, then appends two elements to it. After the code executes, sports contains 4 elements: "soccer", "baseball", "football" and "swimming".

var sports = ["soccer", "baseball"];
sports.push("football", "swimming");

See Also

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Mutates an array by appending the given elements and returning 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 id="Syntax" name="Syntax">Syntax</h2>
<p><code><em>array</em>.push(<em>element1</em>, ..., <em>elementN</em>)</code></p>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>element1, ..., element<em>N</em></code></dt>
  <dd>
    The elements to add to the end of the array.</dd>
</dl>
<h2 id="Returns">Returns</h2>
<p>The new <code><a href="/en/JavaScript/Reference/Global_Objects/Array/length" title="en/JavaScript/Reference/Global_Objects/Array/length">length</a></code> property of the object upon which the method was called.</p>
<h2 id="Description" name="Description">Description</h2>
<p>The <code>push</code> method is useful for easily appending values to an array.</p>
<p><code>push</code> is intentionally generic. This method can be <a href="/en/JavaScript/Reference/Global_Objects/Function/call" title="en/JavaScript/Reference/Global_Objects/Function/call">called</a> or <a href="/en/JavaScript/Reference/Global_Objects/Function/apply" title="en/JavaScript/Reference/Global_Objects/Function/apply">applied</a> to objects resembling arrays. The <code>push</code> method relies on a <code>length</code> property to determine where to start inserting the given values. If the <code>length</code> property cannot be converted into a number, the index used is 0. This includes the possibility of <code>length</code> being nonexistent, in which case <code>length</code> will also be created.</p>
<p>The only native, array-like objects are <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/String" title="En/Core_JavaScript_1.5_Reference/Global_Objects/String">strings</a>, although they are not suitable in applications of this method, as strings are immutable.</p>
<h2 id="Examples" name="Examples">Examples</h2>
<h3 id="Example:_Adding_elements_to_an_array" name="Example:_Adding_elements_to_an_array">Example: Adding elements to an array</h3>
<p>The following code creates the <code>sports</code> array containing two elements, then appends two elements to it. After the code executes, <code>sports</code> contains 4 elements: "soccer", "baseball", "football" and "swimming".</p>
<pre class="brush: js">
var sports = ["soccer", "baseball"];
sports.push("football", "swimming");
</pre>
<h2 id="See_Also" name="See_Also">See Also</h2>
<ul>
  <li><a href="/en/JavaScript/Reference/Global_Objects/Array/pop" title="en/JavaScript/Reference/Global_Objects/Array/pop">pop</a></li>
  <li><a href="/en/JavaScript/Reference/Global_Objects/Array/shift" title="en/JavaScript/Reference/Global_Objects/Array/shift">shift</a></li>
  <li><a href="/en/JavaScript/Reference/Global_Objects/Array/unshift" title="en/JavaScript/Reference/Global_Objects/Array/unshift">unshift</a></li>
  <li><a href="/en/JavaScript/Reference/Global_Objects/Array/concat" title="en/JavaScript/Reference/Global_Objects/Array/concat">concat</a></li>
</ul>

<!--languages({
"fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array/push",
})-->
Revert to this revision