mozilla

Revision 474443 of Spread operator

  • Revision slug: Web/JavaScript/Reference/Spread_operator
  • Revision title: Spread operator
  • Revision id: 474443
  • Created:
  • Creator: kscarfone
  • Is current revision? No
  • Comment Editorial review

Revision Content

{{Harmony()}}

Summary

The spread operator allows an expression to be expanded in places where multiple arguments (for function calls) or multiple elements (for array literals) are expected.

Syntax

function calls:

f(...iterableObj);

array literals:

[...iterableObj, 4, 5, 6]

Examples

A better apply

Example: it is common to use Function.prototype.apply in cases where you want to use an array as arguments to a function.

function f(x, y, z) { }
var args = [0, 1, 2];
f.apply(null, args);

With ES6 spread you can now write the above as:

function f(x, y, z) { }
var args = [0, 1, 2];
f(...args);

Any argument in the argument list can use the spread syntax and it can be used multiple times.

function f(v, w, x, y, z) { }
var args = [0, 1];
f(-1, ...args, 2, ...[3]);

A more powerful array literal

Example: Today if you have an array and want to create a new array with the existing one being part of it, the array literal syntax is no longer sufficient and you have to fall back to imperative code, using a combination of push, splice, concat, etc. With spread syntax this becomes much more succinct:

var parts = ['shoulder', 'knees'];
var lyrics = ['head', ...parts, 'and', 'toes'];

Just like with spread for argument lists ... can be used anywhere in the array literal and it can be used multiple times.

Apply for new

Example: In ES5 it is not possible to compose new with apply (in ES5 terms apply does a [[Call]] and not a [[Construct]]). In ES6 the spread syntax naturally supports this:

var dataFields = readDateFields(database);
var d = new Date(...dateFields);

A better push

Example: push is often used to push an array to the end of an existing array. In ES5 this is often done as:

var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
// Append all items from arr2 onto arr1
Array.prototype.push.apply(arr1, arr2);

In ES6 with spread this becomes:

var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
arr1.push(...arr2);

Specifications

Specification Status Comment
{{SpecName('Harmony')}} {{Spec2('Harmony')}}
  • 12.1.4 Array Initialiser
  • 12.2.5 Argument Lists

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Spread operation in array literals {{ CompatNo() }} {{ CompatGeckoDesktop("16") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Spread operation in function calls {{ CompatNo() }} {{ CompatGeckoDesktop("27") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Spread operation in array literals {{ CompatNo() }} {{ CompatGeckoMobile("16") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Spread operation in function calls {{ CompatNo() }} {{ CompatGeckoMobile("27") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

See also

Revision Source

<p name="Summary">{{Harmony()}}</p>
<h2 id="Summary" name="Summary">Summary</h2>
<p>The spread operator allows an expression to be expanded in places where multiple arguments (for function calls) or multiple elements (for array literals) are expected.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<p>function calls:</p>
<pre class="brush: js">
f(...iterableObj);
</pre>
<p>array literals:</p>
<pre class="brush: js">
[...iterableObj, 4, 5, 6]</pre>
<h2 id="Example" name="Example">Examples</h2>
<h3 id="A_better_apply">A better apply</h3>
<p><strong>Example:</strong> it is common to use <code>Function.prototype.apply</code> in cases where you want to use an array as arguments to a function.</p>
<pre class="brush: js">
function f(x, y, z) { }
var args = [0, 1, 2];
f.apply(null, args);</pre>
<p>With ES6 spread you can now write the above as:</p>
<pre class="brush: js">
function f(x, y, z) { }
var args = [0, 1, 2];
f(...args);</pre>
<p>Any argument in the argument list can use the spread syntax and it can be used multiple times.</p>
<pre class="brush: js">
function f(v, w, x, y, z) { }
var args = [0, 1];
f(-1, ...args, 2, ...[3]);</pre>
<h3 id="A_more_powerful_array_literal">A more powerful array literal</h3>
<p><strong>Example:</strong> Today if you have an array and want to create a new array with the existing one being part of it, the array literal syntax is no longer sufficient and you have to fall back to imperative code, using a combination of <code>push</code>, <code>splice</code>, <code>concat</code>, etc. With spread syntax this becomes much more succinct:</p>
<pre class="brush: js">
var parts = ['shoulder', 'knees'];
var lyrics = ['head', ...parts, 'and', 'toes'];</pre>
<p>Just like with spread for argument lists <code>...</code> can be used anywhere in the array literal and it can be used multiple times.</p>
<h3 id="Apply_for_new">Apply for new</h3>
<p><strong>Example:</strong> In ES5 it is not possible to compose <code>new</code> with <code>apply</code> (in ES5 terms <code>apply</code> does a <code>[[Call]]</code> and not a <code>[[Construct]]</code>). In ES6 the spread syntax naturally supports this:</p>
<pre class="brush: js">
var dataFields = readDateFields(database);
var d = new Date(...dateFields);</pre>
<h3 id="A_better_push">A better push</h3>
<p><strong>Example:</strong> <code>push</code> is often used to push an array to the end of an existing array. In ES5 this is often done as:</p>
<pre class="brush: js">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
// Append all items from arr2 onto arr1
Array.prototype.push.apply(arr1, arr2);</pre>
<p>In ES6 with spread this becomes:</p>
<pre class="brush: js">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
arr1.push(...arr2);</pre>
<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{SpecName('Harmony')}}</td>
      <td>{{Spec2('Harmony')}}</td>
      <td>
        <ul>
          <li>12.1.4 Array Initialiser</li>
          <li>12.2.5 Argument Lists</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<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 (WebKit)</th>
      </tr>
      <tr>
        <td>Spread operation in array literals</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoDesktop("16") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
      <tr>
        <td>Spread operation in function calls</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoDesktop("27") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Spread operation in array literals</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoMobile("16") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
      <tr>
        <td>Spread operation in function calls</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoMobile("27") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="../Reference/rest_parameters" title="rest parameters">Rest parameters</a></li>
</ul>
Revert to this revision