Array.prototype.splice()

  • Revision slug: JavaScript/Reference/Global_Objects/Array/splice
  • Revision title: Array splice method
  • Revision id: 26354
  • Created:
  • Creator: Yuichirou
  • Is current revision? No
  • Comment +ja

Revision Content

Summary

Changes the content of an array, adding new elements while removing old elements.

Method of Array
Implemented in: JavaScript 1.2, NES 3.0

JavaScript 1.3: returns an array containing the removed elements.

ECMA Version: ECMA-262 Edition 3

Syntax

splice(index, howMany, {{mediawiki.external('<i>element1</i>')}}{{mediawiki.external(', ..., <i>elementN</i>')}})

Parameters

index 
Index at which to start changing the array.
howMany 
An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element.
element1, ..., elementN 
The elements to add to the array. If you don't specify any elements, splice simply removes elements from the array.

Description

If you specify a different number of elements to insert than the number you're removing, the array will have a different length at the end of the call.

The splice method returns an array containing the removed elements. If only one element is removed, an array of one element is returned.

Backward Compatibility

JavaScript 1.2

The splice method returns the element removed, if only one element is removed (howMany parameter is 1); otherwise, the method returns an array containing the removed elements.

Examples

Example: Using splice

The following script illustrate the use of splice:

<SCRIPT LANGUAGE="JavaScript1.2">

myFish = ["angel", "clown", "mandarin", "surgeon"];
document.writeln("myFish: " + myFish + "<BR>");

removed = myFish.splice(2, 0, "drum");
document.writeln("After adding 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");

removed = myFish.splice(3, 1)
document.writeln("After removing 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");

removed = myFish.splice(2, 1, "trumpet")
document.writeln("After replacing 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");

removed = myFish.splice(0, 2, "parrot", "anemone", "blue")
document.writeln("After replacing 2: " + myFish);
document.writeln("removed is: " + removed);

</SCRIPT>

This script displays:

myFish: ["angel", "clown", "mandarin", "surgeon"]

After adding 1: ["angel", "clown", "drum", "mandarin", "surgeon"]
removed is: undefined

After removing 1: ["angel", "clown", "drum", "surgeon"]
removed is: mandarin

After replacing 1: ["angel", "clown", "trumpet", "surgeon"]
removed is: drum

After replacing 2: ["parrot", "anemone", "blue", "trumpet", "surgeon"]
removed is: ["angel", "clown"]
{{ wiki.languages( { "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array/splice" } ) }}

Revision Source

<p>
</p>
<h3 name="Summary"> Summary </h3>
<p>Changes the content of an array, adding new elements while removing old elements.
</p>
<table class="fullwidth-table">
<tbody><tr>
<td class="header" colspan="2">Method of <a href="en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></td>
</tr>
<tr>
<td>Implemented in:</td>
<td>JavaScript 1.2, NES 3.0
<p>JavaScript 1.3: returns an array containing the removed elements.
</p>
</td>
</tr>
<tr>
<td>ECMA Version:</td>
<td>ECMA-262 Edition 3</td>
</tr>
</tbody></table>
<h3 name="Syntax"> Syntax </h3>
<p><code>
splice(<i>index</i>, <i>howMany</i>, {{mediawiki.external('&lt;i&gt;element1&lt;/i&gt;')}}{{mediawiki.external(', ..., &lt;i&gt;elementN&lt;/i&gt;')}})
</code>
</p>
<h3 name="Parameters"> Parameters </h3>
<dl><dt> <code>index</code> </dt><dd> Index at which to start changing the array.
</dd></dl>
<dl><dt> <code>howMany</code> </dt><dd> An integer indicating the number of old array elements to remove. If <code>howMany</code> is 0, no elements are removed. In this case, you should specify at least one new element.
</dd></dl>
<dl><dt> <code>element1, ..., element<i>N</i></code> </dt><dd> The elements to add to the array. If you don't specify any elements, <code>splice</code> simply removes elements from the array.
</dd></dl>
<h3 name="Description"> Description </h3>
<p>If you specify a different number of elements to insert than the number you're removing, the array will have a different length at the end of the call.
</p><p>The <code>splice</code> method returns an array containing the removed elements. If only one element is removed, an array of one element is returned.
</p>
<h3 name="Backward_Compatibility"> Backward Compatibility </h3>
<h4 name="JavaScript_1.2"> JavaScript 1.2 </h4>
<p>The <code>splice</code> method returns the element removed, if only one element is removed (<code>howMany</code> parameter is 1); otherwise, the method returns an array containing the removed elements.
</p>
<h3 name="Examples"> Examples </h3>
<h4 name="Example:_Using_splice"> Example: Using <code>splice</code> </h4>
<p>The following script illustrate the use of splice:
</p>
<pre>&lt;SCRIPT LANGUAGE="JavaScript1.2"&gt;

myFish = ["angel", "clown", "mandarin", "surgeon"];
document.writeln("myFish: " + myFish + "&lt;BR&gt;");

removed = myFish.splice(2, 0, "drum");
document.writeln("After adding 1: " + myFish);
document.writeln("removed is: " + removed + "&lt;BR&gt;");

removed = myFish.splice(3, 1)
document.writeln("After removing 1: " + myFish);
document.writeln("removed is: " + removed + "&lt;BR&gt;");

removed = myFish.splice(2, 1, "trumpet")
document.writeln("After replacing 1: " + myFish);
document.writeln("removed is: " + removed + "&lt;BR&gt;");

removed = myFish.splice(0, 2, "parrot", "anemone", "blue")
document.writeln("After replacing 2: " + myFish);
document.writeln("removed is: " + removed);

&lt;/SCRIPT&gt;
</pre>
<p>This script displays:
</p>
<pre>myFish: ["angel", "clown", "mandarin", "surgeon"]

After adding 1: ["angel", "clown", "drum", "mandarin", "surgeon"]
removed is: undefined

After removing 1: ["angel", "clown", "drum", "surgeon"]
removed is: mandarin

After replacing 1: ["angel", "clown", "trumpet", "surgeon"]
removed is: drum

After replacing 2: ["parrot", "anemone", "blue", "trumpet", "surgeon"]
removed is: ["angel", "clown"]
</pre>
{{ wiki.languages( { "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array/splice" } ) }}
Revert to this revision