Introduction

Array.prototype.splice() is a JavaScript Array method that is used to remove, replace or insert items starting at a chosen index. It is also an effective tool for adding items to the end of an array.

Array.prototype.splice() is a sparsely used but powerful JavaScript method for manipulating arrays in place. This means, we are mutating the actual array, not a copy of it. JavaScript splice() is useful for wiping all items after n number of initial items. It is handy for removing a number of intermediary items starting at an indicated index. It is especially needed for inserting items when we want to replace items or overload an array besides replacement. JavaScript splice() offers an alternative to Array.prototype.push() for growing the tail of the array as well.

Unlike several other Array methods, JavaScript slice() does not have a String equivalent.

In this post, we play around to illustrate various use cases of JavaScript splice() with trivial examples. We start with the method signature for Array.prototype.splice(), its possible parameters (startIndex, deleteCount, items) and what they represent. We then go ahead and see examples of using combinations of passed arguments to manipulate an array.

In particular, we observe how to wipe out items from a certain index onward. We also go through examples of replacing existing items with new ones. We explore how to insert items in the case of overloaded replacement and injection. We also figure out splice() way of adding items to the tail of the array.

Towards the end, we touch base on the nuances of the values passed as startIndex and learn how JavaScript splice() behaves when startIndex argument is negative or greater than the array length.

JavaScript Splice

When called by an array, JavaScript splice() takes three possible arguments: startIndex, deleteCount and items list. Of these three types of arguments, startIndex indicates a zero-based index at which mutation kicks off. deleteCount denotes the number of items to be deleted and items is a possibly infinite list of items to be inserted.

JS Array.prototype.splice() Method Signature

Possible call signatures for JavaScript splice() are:

splice()
splice(startIndex)
splice(startIndex, deleteCount, item1)
splice(startIndex, deleteCount, item1, item2, /*...*/, itemN)

None of the arguments for Array.prototype.splice() are required. However, when we want to mutate the caller array, we have to pass the startIndex as a minimum. Passing deleteCount depends on whether we want to delete any item/s or not. And passing the items list depends on whether/what we want to insert or add to the array. It is also possible to pass all arguments at the same time. In the coming sections, we consider most of the cases.

JS splice() Result / Return Value

As we'll start seeing next, splice() mutates the original array and returns an array containing removed items.

JS Array.prototype.splice() without Arguments

Although, JavaScript splice() attempts to mutate the caller array, the returned value is an array of removed items. We can get a hint of the return value when an array calls it without passing any argument:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Return value
console.log(mnemonic.splice()); // []

console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

As we can see, splice() without argument returns an empty array []. And as we'll see it become clearer in the next section, it is an array of removed items. In the case above, since no item is being removed, it is empty.

Notice that, although splice() is geared to remove items, it did not mutate the caller above, since we have not passed startIndex.

Wiping All After n Items - JavaScript splice() with Only startIndex

When we pass startIndex, we should expect the caller array to mutate.

With only startIndex passed to JavaScript splice(), all items including the one at and after startIndex are removed:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Return value
console.log(mnemonic.splice(4)); // ["And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

// Caller array
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys"]

We can clearly see from this example that the returned array now has items including the one at startIndex (4) till the end removed. In other words, they were wiped out and the items upto startIndex are remaining in the original array.

It is important to notice that removal begins at startIndex included. This gives rise to a noticeable pattern where the zero based startIndex actually corresponds to first n items remaining in the caller array, i.e. n = startIndex:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Wiping all after first 4 items
console.log(mnemonic.splice(4)); // ["And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys"]

// Wiping all after first 2 items
console.log(mnemonic.splice(2)); // ["Cats", "Monkeys"]
console.log(mnemonic); // ["Please", "Send"]

// Wiping all items
console.log(mnemonic.splice(0)); // ["Please", "Send"]
console.log(mnemonic); // []

In the above examples, for each of the values passed as startIndex, we want that number of items to remain at the head of the original array. With mnemonic.splice(0), we are emptying the original array.

Deleting Intermediary Items with JS Array.prototype.splice()

We can remove intermediary items from an array by passing deleteCount as the second argument. This removes the indicated number of items beginning at startIndex:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 2)); // ["And", "Zebras"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

In the above call, we are passing 2 as deleteCount. Deleting starts at startIndex and ends at the index where deleteCount is achieved. Notice, removal slides the items after deleteCount to the left.

Replacing Items with JS Array.prototype.splice()

We can replace removed items with new ones by passing in items as a list after the second argument. All items passed are added to startIndex onwards:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 0, "Ants", "Zebus")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
console.log(mnemonic.splice(4, 2)); // ["Ants", "Zebus"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

// Items removed first and then added
console.log(mnemonic.splice(4, 2, "Alpacas", "Zorillas"));
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Alpacas", "Zorillas", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

Observe above that deletion gains precedence over insertion. It becomes more apparent when deleteCount is positive and items are replaced or added with arguments after . In the above series of mutations,"Ants", "Zebus" first inserted at 4, with 0 items removed first. Then they were removed with 4 as startIndex, 2 as deleteCount and no items replacing them. In the last mutation, further removal of 2 items at index 4 happens, that are replaced subsequently with the new items.

We can actually go further and overload the array by adding more items than removed:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Add more items than removed
console.log(mnemonic.splice(4, 2, "Ants", "Zebus", "Donkeys", "Bears")); // ["And", "Zebras"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "Donkeys", "Bears", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

Notice that because we are replacing or overloading items, the items that come after get displaced towards the right.

Items Injection with Array.prototype.splice()

You might already noticed that, if we want to only inject items at a certain point in the array, we can pass 0 as deleteCount:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "Donkeys", "Bears", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

New items are added starting at startIndex directly because with deleteCount set to 0, so no items are deleted.

Tailgrowing with Array.prototype.splice()

We can add to the tail by using the length of the caller array as startIndex:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(
  mnemonic.splice(mnemonic.length, 0, "Ants", "Zebus", "Donkeys", "Bears")
); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "In", "Large", "Cages", "Make", "Sure", "Padlocked", "Ants", "Zebus", "Donkeys", "Bears"]

Caller length finds the tail for an incoming item as length is greater than the last index in the zero-index based array. Using length like this with splice() is a good occasional alternative to Array.prototype.push().

It important to caution that using -1 as startIndex doesn't add to the tail. That's because for startIndex < 0, mutation starts at startIndex + mnemonic.length. So, the last item always gets displaced as last and we never add to the tail:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(-1, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure" "Ants", "Zebus", "Donkeys", "Bears", "Padlocked"]

A variation of this next.

Inject Items Before Last n Items - JavaScript slice() with Negative startIndex

We can inject new items before last n items by passing in -n as startIndex. This is another example when startIndex < 0:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Inject before last 2 items
console.log(mnemonic.splice(-2, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Ants", "Zebus", "Donkeys", "Bears", "Sure", "Padlocked"]

// Inject before last 4 items
console.log(mnemonic.splice(-4, 0, "Apacas", "Zorillas")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Ants", "Zebus", "Apacas", "Zorillas", "Donkeys", "Bears", "Sure", "Padlocked"]

Again, a negative startIndex brings -n + mnemonic.length to play. So, mutation starts at n items (not indexes) from the end of the array -- keeping last n items intact in the tail.

Nuances of JS Array.prototype.splice()

In this section, let's consider other quirks of using JavaScript slice().

Higher Negatives of startIndex

There is another nuance of using negative startIndex with splice(). For example, when startIndex < -mnemonic.length, it is effectively 0:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(-100, 10, "Ants", "Zebus", "Donkeys", "Bears")); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make"]
console.log(mnemonic); // ["Ants", "Zebus", "Donkeys", "Bears", "Sure", "Padlocked"]

Here, with startIndex value of -100, removal starts at index 0 and first 10 items are removed. The passed items are added after removal at index 0.

Higher startIndex Value

When startIndex is greater than the length of the array, no items is deleted even if deleteCount is passed. Plus all passed items are tucked to the tail:

const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(100, 10, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked", "Ants", "Zebus", "Donkeys", "Bears"]

As we can see, 100 is far greater than mnemonic.length, and we asked for deletion of 10 items somewhere non-existent. So, none is deleted inside the array. And passed items are added to the tail.

Using an arbitrary higher index is, however, not safe for tailgrowing, since it does not always make sure startIndex is greater or equal to caller length.

Summary

In this post, explored various cases and patterns of using JavaScript splice(). We learned that Array.prototype.splice() is an array method and it doesn't have a String equivalent. We also understood that it mutates the original array and returns an array of removed items.

We found out how to wipe out all items after first n items by passing n as the startIndex to splice(). We illustrated how to remove intermediary items by passing deleteCount as the second argument. We also saw how to replace removed items by passing in new items as third argument and onward. We learned how to inject items with 0 passed as deleteCount.

We figured out an alternative to Array.prototype.push() by using Array.prototype.splice() with caller length passed as startIndex. We also discovered the pattern of adding items prior to last n items using -n as the startIndex. In the end, we explored the quirks of using extreme values of startIndex, particularly when it is more negative than -length of the caller array and when it is higher than length.

Author: Abdullah Numan