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.
Prerequisites
This tutorial assumes that you're familiar with:
Syntaxarray.splice(start, numElementsToDelete, item1, item2, …itemN)
Parameters
array.splice(start, numElementsToDelete, item1, item2, …itemN)
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.
ExamplesIn Apps Script, you can only run functions. So you have to copy and paste each of the code snippets below into a function before you run them.
I recommend creating separate functions to try out each of the examples below. Also, don't forget to give each of these functions a unique name.
Example 1: Removing the first element from an array.
In Apps Script, you can only run functions. So you have to copy and paste each of the code snippets below into a function before you run them.
I recommend creating separate functions to try out each of the examples below. Also, don't forget to give each of these functions a unique name.
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 arrayExample 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 elementExample 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 arrayExample 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.