The Array method splice() in Apps Script

The Array method splice() is used to change an array by removing elements from it and/or adding elements to it.

Syntax

array.splice(start, numElementsToDelete, item1, item2, …itemN)

Parameters

start (required):

• The array index at which to splice the array.

• If this value is greater than the length of the array, it will be set to the length of the array.

• If it is negative, the starting position is determined by starting at the end of the array and moving towards the beginning of the array. This will be clear from the examples below.

numElementsToDelete (optional):

• The number of elements to delete beginning at the starting point specified using the start parameter.

• If this value is 0 or negative, no elements will be deleted.

• If this value is not specified or if it is greater than the number of elements after the start position, then all elements beyond the start position will be deleted.

item1, item2, …itemN (optional):

• One or more values to insert into the array.

Return value

An array containing deleted values is returned by the splice() function. If no elements are deleted then the return value will be an empty array.

Examples

Example 1: Removing the first element from an array.

In the code below, colors.splice(0,1) removes the first element ("red") from the array colors. An array containing this removed element is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(0,1);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[blue, green, black, orange, purple]

[red]

Example 2: Removing the second element from an array

In the code below, colors.splice(1,1) removes the second element ("blue") from the array colors. An array containing this removed element is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(1,1);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, green, black, orange, purple]

[blue]

Example 3: Removing the second element from an array

In the code below, colors.splice(1,0) does not change the array at all since it removes 0 elements from the array. An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(1,0);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange, purple]

[]

Example 4: Removing the last element from an array

In the code below, colors.splice(-1,1) removes the last element ("purple") from the array colors. An array containing this removed element is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(-1,1);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange]

[purple]

Example 5: Removing two elements from an array

Example 5.1

In the code below, colors.splice(1,2) removes two elements starting from the 2nd position from the array colors. An array containing these removed elements is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(1,2);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, black, orange, purple]

[blue, green]

Example 5.2

In the code below, colors.splice(-3,2) removes two elements starting from the 3rd last position ("black") in the array colors. An array containing these removed elements is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(-3,2);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, purple]

[black, orange]

Example 6: Removing all elements from an array

In the code below, colors.splice(0) removes all elements from the array colors because numElementsToDelete (the second argument) was not specified. An array containing these removed elements is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(0);
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[]

[red, blue, green, black, orange, purple]

Example 7: Replacing an element with another element

Example 7.1

In the code below, colors.splice(0,1,"gray") replaces the first element in the array colors with the value "gray". An array containing the removed element (i.e., the first element) is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(0,1,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[gray, blue, green, black, orange, purple]

[red]

Example 7.2

In the code below, colors.splice(-1,1,"gray") replaces the last element in the array colors with the value "gray". An array containing the removed element (i.e., the last element) is returned.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(-1,1,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange, gray]

[purple]

Example 8: Inserting an element into an array

Example 8.1

In the code below, colors.splice(0,0,"gray") inserts the value "gray" in the first position of the array colors. An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(0,0,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[gray, red, blue, green, black, orange, purple]

[]

Example 8.2

In the code below, colors.splice(-1,0,"gray") inserts the value "gray" into the penultimate position of the array colors (i.e., between "orange" and "purple"). An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(-1,0,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange, gray, purple]

[]

Example 8.3

In the code below, colors.splice(colors.length,0,"gray") inserts the value "gray" into the last position of the array colors. An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(colors.length,0,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange, purple, gray]

[]

Example 8.4

In the code below, colors.splice(1,0,"gray") inserts the value "gray" into the second position of the array colors. An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(1,0,"gray");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, gray, blue, green, black, orange, purple]

[]

Example 9: Inserting multiple elements into an array

In the code below, colors.splice(-1,0,"gray", "yellow") inserts the values "gray" and "yellow" just before the last element of the array colors. An empty array is returned since no elements were removed.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors);
var del = colors.splice(-1,0,"gray", "yellow");
Logger.log(colors);
Logger.log(del);

Output

[red, blue, green, black, orange, purple]

[red, blue, green, black, orange, gray, yellow, purple]

[]

Conclusion

In this tutorial, you learned how to use the splice() method to add elements to and/or remove elements from an array.