Description

The splice() function adds elements to an array much like push() and unshift() do. The difference is that you can insert elements anywhere in the array that you'd like. The push() method only lets you add elements to the bottom of an array, and unshift() only lets you add them to the top.

Give it a try using this example. Notice the array displayed in the textarea in the top right. Add some new items, separated with commas, in the first textbox on the left. Now, pick a place to insert them by placing an index number in the second box. Click the button to update the array.

Say you wanted to add "elephants" and "shrimp" to the array and have them display right after "cats". Type "elephants,cats" (without quotes) in the first textbox. The index for "cats" is [1], so we'd have to add our new items at [2] to have them display right after "cats". So enter a 2 in the second box. Play around with this until you get the idea of the effect.

To add items to an array, we'll use the following syntax for splice():

array_name.splice(starting_index_number,0, item1,item2,item3...);

It's important to notice the 0 as the value in the range positon. This number normally tells splice() how many array elements to remove beginning at the "starting_index_number". In the case of adding new elements, we don't want to remove anything, so this number is set to 0. By using zero, nothing will be removed, only added.

The values for "item1", etc. will be added to the array in the order in which they are coded in the splice() statement. The first item will be placed at the "starting_index_number" positon in the array. Subsequent items will be placed directly after the first item in order. The portion of the old array that began with the starting index will be placed beneath the new items.

All indexing and the array's length value are automatically updated. Ain't it great.

The Code

Here's the code for the function that inserts elements into the array:

function add_items(){

var index_value = document.form1.index1.value;

var list = document.form1.new_stuff.value;

dynamic_array.splice(index_value,0,list);

load_array();
}//ends remove_items function

The first two statements assign the values from the boxes to variables. The variable "index_value" holds the index number from the second box. The "list" variable holds the string of new items including the important commas.

The part in red is the splice(). The first value is the index number. This is where we want the new stuff to begin. The next part is the 0 we discussed previously. We don't want anything removed, so we set the range to 0.

Finally, the variable "list" adds your new stuff with commas already included to finish the statement. The last line leads to another function that updates the display.

Walking Through The Function

Let's see what happens in the function when we add "elephants" and "shrimp" to the array and have them display immedately after "cats". To do this we must enter an index number of 2, as well as entering "elephants,shrimp" in the first box.

When we click the button, the "add_items()" function is run. The index number - 2 - is assigned to the "index_value" variable. The string "elephants,shrimp" - with the comma - is assigned to the "list" variable.

Now we come to the splice() statement. It searches for index number 2. It has nothing to remove because of the zero in the range positon in the statement. So, it adds "elephant" to the dynamic_array[2] position. Then it continues by adding shrimp to dynamic_array[3]. It then updates all array index numbers and the "array.length". All done.

Summary & Exercises

In this tutorial, we learned how to insert new elements anywhere in an array by using the splice() method. Unlike unshift() and push(), splice() can add new elements anywhere in the array.

You must set an index number to tell splice() where to begin adding the new elements. Remember that the index number of elements begins at 0. You will also want to take care to avoid gaps in the array indexing by making sure this number is no greater than the array's length.

When you only want to add to an array, set the range (second number in splice()'s parentheses) to 0. The range tells splice() how many elements to remove beginning with the index indicated by the first number in the parentheses.

After the range is set to 0, you can add as many items to the list as you want. Just remember to separate them with commas. Otherwise, they'll appear as a single big string assinged to one position in the array.

The splice() method can mimic the push() method by using "array_name.length" (without quotes) as the index:

array_name.splice(array_name.length,0,item1,item2...);

The above sets the initial index number to one more than the last element's index number. You remember how that works, don't you? The length count begins at 1 and the index count begins at zero. Therefore, "array_name.length" is always 1 more than the index number of the last element.

The splice() method can also mimic the unshift() method by using 0 as the initial index number:

array_name.splice(0,0,item1,item2...);

The above would add the list of items to the top of the array. You should be able to figure out how to mimic the pop() and shift() methods by adjusting the range number as described in the previous tutorial.

To Next Advanced JavaScript Lesson

Back To Advanced JavaScript Index