Adding and removing items

Four methods add and remove items at the ends of an array: push() adds items at the end and pop() removes the last one, unshift() adds items at the front and shift() removes the first one. splice() works anywhere: one call can insert, delete or replace items at any index. All five change the array they are called on, and they return different things: push() and unshift() return the new length, pop() and shift() the item they removed, and splice() an array of the items it deleted. Mixing those up is a classic bug. This lesson runs each method, shows the copying versions that leave the original alone, toSpliced() and slice(), and measures why a long queue should never be emptied with shift().

push, pop, shift and unshift

A queue at a ticket window is an array where people join at the back and leave from the front:

// The queue at a station's ticket window: people join at the back with push() and the window serves the front
// with shift(). Each method changes the array and returns something different.
const queue = ['Asha', 'Ravi'];

console.log('push returns the new length:', queue.push('Meena'));
console.log('push can add several:', queue.push('Kiran', 'Arjun'), queue);

console.log('shift returns who was served:', queue.shift(), queue);
console.log('pop returns who left the back:', queue.pop(), queue);
console.log('unshift returns the new length:', queue.unshift('Divya'), queue);

const nobody = [];
console.log('pop and shift on an empty array:', nobody.pop(), nobody.shift(), nobody.length);

push returns the new length: 3
push can add several: 5 [ 'Asha', 'Ravi', 'Meena', 'Kiran', 'Arjun' ]
shift returns who was served: Asha [ 'Ravi', 'Meena', 'Kiran', 'Arjun' ]
pop returns who left the back: Arjun [ 'Ravi', 'Meena', 'Kiran' ]
unshift returns the new length: 4 [ 'Divya', 'Ravi', 'Meena', 'Kiran' ]
pop and shift on an empty array: undefined undefined 0

• push(item) adds at the end and returns the new length, 3. It takes any number of items, push('Kiran', 'Arjun'), and adds them in that order.
• shift() removes the first item and returns it: the window serves Asha, and everyone else moves up one place.
• pop() removes the last item and returns it, here Arjun, who gave up waiting.
• unshift(item) adds at the front and returns the new length. Like push(), it takes several items and keeps their order.
• On an empty array, pop() and shift() return undefined and change nothing, so a loop such as while (queue.length > 0) is the safe way to empty a queue whose items may themselves be undefined.

The two ends are not equal. At the back, push() and pop() touch one slot and leave every other item where it was. At the front, every other item gets a new index: after shift(), Ravi moves from index 1 to index 0, Meena from 2 to 1, and so on down the queue. For a few hundred items you will never notice; a later section of this lesson measures what it costs for a long queue.

What each method returns

All four methods return something useful, but never the array itself, and that trips people up when they try to chain calls or keep the result:

// push() returns a number, not the array, so its result cannot stand in for the array.
const cart = ['rice'];
const result = cart.push('tea');
console.log('result:', result, typeof result);

try {
  cart.push('salt').push('oil');
} catch (error) {
  console.log(error.name, 'from chaining push(); cart is now', cart);
}

// splice() returns what it removed, not what is left.
const playlist = ['intro', 'song 1', 'ad', 'song 2'];
const removed = playlist.splice(2, 1);
console.log('splice returned', removed, 'and the playlist is', playlist);

result: 2 number
TypeError from chaining push(); cart is now [ 'rice', 'tea', 'salt' ]
splice returned [ 'ad' ] and the playlist is [ 'intro', 'song 1', 'song 2' ]

cart.push('tea') returns 2, the new length, so result is a number. That is also why cart.push('salt').push('oil') fails: the first call returns 3, and a number has no push() method, so the second call throws a TypeError. Note that the first push() already ran, so 'salt' is in the cart even though the line failed. Call the methods one per line instead.

splice() returns the items it removed, in an array of their own, even when it removes only one: ['ad'], not 'ad'. Code such as const remaining = playlist.splice(2, 1) reads as if it kept what is left, but remaining holds the advert and playlist holds the songs. When you want the removed item itself, take it out of that array: const [removed] = playlist.splice(2, 1).

splice(): insert, delete or replace anywhere

splice(start, deleteCount, ...items) goes to index start, deletes deleteCount items there and inserts items in their place, all in one call. Its two numbers cover every edit of a list:

// A bus route as an array of stops, changed in place with splice() and copied with toSpliced().
const route = ['Depot', 'Market', 'School', 'Hospital', 'Station'];

console.log('insert:', route.splice(2, 0, 'Library'), route);
console.log('delete:', route.splice(3, 1), route);
console.log('replace:', route.splice(-1, 1, 'Central'), route);
console.log('to the end:', route.splice(3), route);

const plan = ['Depot', 'Market', 'School'];
console.log('toSpliced:', plan.toSpliced(1, 1, 'Mall', 'Park'), plan);
console.log('slice:', plan.slice(1), plan.slice(0, -1), plan);

insert: [] [ 'Depot', 'Market', 'Library', 'School', 'Hospital', 'Station' ]
delete: [ 'School' ] [ 'Depot', 'Market', 'Library', 'Hospital', 'Station' ]
replace: [ 'Station' ] [ 'Depot', 'Market', 'Library', 'Hospital', 'Central' ]
to the end: [ 'Hospital', 'Central' ] [ 'Depot', 'Market', 'Library' ]
toSpliced: [ 'Depot', 'Mall', 'Park', 'School' ] [ 'Depot', 'Market', 'School' ]
slice: [ 'Market', 'School' ] [ 'Depot', 'Market' ] [ 'Depot', 'Market', 'School' ]

• Insert: a deleteCount of 0 deletes nothing, so route.splice(2, 0, 'Library') puts the new stop at index 2 and moves the rest up. It returns [], because nothing was removed.
• Delete: route.splice(3, 1) removes one item at index 3 and returns it inside an array.
• Replace: delete and insert together. A negative start counts from the end, so splice(-1, 1, 'Central') replaces the last stop.
• Delete to the end: with no deleteCount, splice(3) removes everything from index 3 on.

toSpliced(), added in ECMAScript 2023, takes the same arguments and returns a new array with the edit made, leaving the original untouched: plan still has its three stops afterwards. slice(start, end) is the other copying method: it returns the items from start up to, but not including, end, and a negative number counts from the end, so plan.slice(0, -1) is everything but the last item.

splice, toSpliced or slice?

The names look alike, and the difference that matters is whether the array changes:

toSpliced() sits between the two: it takes the arguments of splice() and, like slice(), returns a new array and leaves the original as it was, so it is the choice for an edit when other code also holds the array.

Changing an array in place is quick and fine when only one piece of code uses it. When other code holds the same array, such as the state of a user interface or an argument a function was given, an edit in place changes their data behind their back. Copying methods keep every other holder’s view as it was:

Emptying a long queue with shift()

The specification defines shift() as copying every remaining item one index down and then shortening the array by one. Emptying a queue of n items that way could move about n × n ÷ 2 items in total. This program measures it, against a head index: a number that remembers where the front of the queue is, so that serving a job only reads queue[head] and adds one to head:

// Emptying a queue of n jobs from the front: shift() on every turn, against a head index that moves along the
// array. The queues grow with push(), as real queues do. Times are in milliseconds; the head index is timed three
// times and the fastest run is shown, because it is too quick to time once.
function makeQueue(n) {
  const queue = [];
  for (let i = 0; i < n; i++) queue.push(`job ${i}`);
  return queue;
}

function drainWithShift(queue) {
  let served = 0;
  while (queue.length > 0) {
    if (queue.shift() !== undefined) served++;
  }
  return served;
}

function drainWithHead(queue) {
  let served = 0;
  let head = 0;
  while (head < queue.length) {
    if (queue[head] !== undefined) served++;
    head++;
  }
  return served;
}

function time(drain, n, runs) {
  let best = Infinity;
  for (let run = 0; run < runs; run++) {
    const queue = makeQueue(n);
    const start = performance.now();
    if (drain(queue) !== n) throw new Error('a job was lost');
    best = Math.min(best, performance.now() - start);
  }
  return best;
}

console.log('     items      shift()   head index');
for (const n of [10_000, 15_000, 20_000, 40_000, 80_000]) {
  const shift = time(drainWithShift, n, 1).toFixed(1).padStart(8);
  const head = time(drainWithHead, n, 3).toFixed(2).padStart(7);
  console.log(`${n.toLocaleString('en-US').padStart(10)}  ${shift} ms  ${head} ms`);
}

     items      shift()   head index
    10,000       2.2 ms     0.07 ms
    15,000       0.7 ms     0.02 ms
    20,000      52.2 ms     0.01 ms
    40,000     219.2 ms     0.03 ms
    80,000     854.7 ms     0.06 ms

Up to 15,000 jobs, shift() emptied the queue in a millisecond or two. At 20,000 it took tens of milliseconds, and each doubling after that made it about four times slower, roughly a second at 80,000, while the head index stayed under a tenth of a millisecond at every size. The sudden jump between 15,000 and 20,000 comes from V8, the engine inside Node.js and Chrome. For an array of a few thousand items V8 usually avoids the copy: it moves the point where the array’s storage starts by one slot. Its source code says that this trick does not work for objects in its large-object space, and an array’s storage goes there once it needs more than 128 KiB, which is about 16,000 slots of 8 bytes. A queue that grew with push() has reserved spare slots as it grew, so it crosses that line a little sooner. Above it, every shift() really does copy every item that is left.

unshift() has the same problem in the other direction, and on every call: it moves every item up to make room at the front. Arrays therefore make good stacks, where items come and go at the end, and poor long-lived queues, which take their items from the front. For a queue, keep a head index as the program does, and when the served part grows large, drop it in one go with queue.splice(0, head) and set head back to 0; the data structures module builds a proper queue class.

Exercises

// The list helpers of lesson javascript/adding-and-removing-items.

export function moveItem(list, from, to) {
  // Moves the item, but changes the list it was given, and accepts any index.
  const [item] = list.splice(from, 1);
  list.splice(to, 0, item);
  return list;
}

export function removeAll(list, value) {
  // Skips the second of two neighbours that match: after a splice(), the next item moves into index i.
  let removed = 0;
  for (let i = 0; i < list.length; i++) {
    if (list[i] === value) {
      list.splice(i, 1);
      removed++;
    }
  }
  return removed;
}

import { test, assert } from 'mysmartcopilot:test';
import { moveItem, removeAll } from './listops.mjs';

test('moves an item forward', () => {
  assert.deepEqual(moveItem(['a', 'b', 'c', 'd'], 0, 2), ['b', 'c', 'a', 'd']);
});

test('moves an item back', () => {
  assert.deepEqual(moveItem(['a', 'b', 'c', 'd'], 3, 1), ['a', 'd', 'b', 'c']);
});

test('returns a new array and leaves the list as it was', () => {
  const list = ['a', 'b', 'c'];
  const moved = moveItem(list, 0, 2);
  assert.deepEqual(moved, ['b', 'c', 'a']);
  assert.deepEqual(list, ['a', 'b', 'c']);
});

test('negative indexes count from the end; outside the list is a RangeError', () => {
  assert.deepEqual(moveItem(['a', 'b', 'c'], -1, 0), ['c', 'a', 'b']);
  assert.deepEqual(moveItem(['a', 'b', 'c'], 0, -1), ['b', 'c', 'a']);
  assert.throws(() => moveItem(['a', 'b'], 2, 0), RangeError);
  assert.throws(() => moveItem(['a', 'b'], 0, -3), RangeError);
});

test('removeAll removes neighbours that match, in place', () => {
  const tags = ['x', 'x', 'y', 'x'];
  assert.equal(removeAll(tags, 'x'), 3);
  assert.deepEqual(tags, ['y']);
});

test('removeAll returns 0 and changes nothing when no item matches', () => {
  const ids = [1, 2, 3];
  assert.equal(removeAll(ids, 9), 0);
  assert.deepEqual(ids, [1, 2, 3]);
});

Interview questions

Fresher · What is the difference between slice() and splice() in JavaScript?

slice(start, end) copies a part of an array into a new array, from start up to but not including end, and never changes the original. splice(start, deleteCount, ...items) changes the array itself: it deletes deleteCount items at start, inserts any items there, and returns the deleted items in a new array. So the second argument means “where to stop” for slice() and “how many to delete” for splice(). Both accept a negative start, which counts from the end. Use slice() to take a part without side effects, splice() to edit a list in place, and toSpliced(), from ECMAScript 2023, when you want the edit made on a copy.

Key takeaways

• push() and pop() work at the end, unshift() and shift() at the front, and splice() anywhere. All five change the array.
• push() and unshift() return the new length; pop() and shift() return the item they removed, or undefined for an empty array; splice() returns the removed items in an array.
• None of them returns the array, so do not chain them: list.push(a).push(b) throws a TypeError.
• splice(i, 0, x) inserts, splice(i, n) deletes, splice(i, n, x) replaces and splice(i) deletes to the end.
• toSpliced() and slice() return new arrays and leave the original alone: use them when other code holds the array.
• shift() and unshift() move every other item. For a long queue, read with a head index instead: in the run above, 80,000 jobs took roughly a second with shift() and well under a millisecond with the index.