Arrays

API Reference

When using D3—and doing data visualization in general—you tend to do a lot of array manipulation. That's because D3's canonical representation of data is an array. Some common forms of array manipulation include taking a contiguous slice (subset) of an array, filtering an array using a predicate function, and mapping an array to a parallel set of values using a transform function. Before looking at the set of utilities that D3 provides for arrays, you should familiarize yourself with the powerful array methods built-in to JavaScript.

This includes mutator methods that modify the array:

• array.reverse - Reverse the order of the elements of the array.
• array.shift - Remove the first element from the array.
• array.sort - Sort the elements of the array.
• array.splice - Add or remove elements from the array.
• array.unshift - Add one or more elements to the front of the array.

There are also accessor methods that return some representation of the array:

• array.concat - Join the array with other array(s) or value(s).
• array.join - Join all elements of the array into a string.
• array.slice - Extract a section of the array.
• array.indexOf - Find the first occurrence of a value within the array.
• array.lastIndexOf - Find the last occurrence of a value within the array.

And finally, iteration methods that apply functions to elements in the array:

• array.filter - Create a new array with only the elements for which a predicate is true.
• array.forEach - Call a function for each element in the array.
• array.every - See if every element in the array satisfies a predicate.
• array.map - Create a new array with the result of a function of every element in the array.
• array.some - See if at least one element in the array satisfies a predicate.
• array.reduce - Apply a function to reduce the array to a single value (from left-to-right).
• array.reduceRight - Apply a function to reduce the array to a single value (from right-to-left).

Ordering

# d3.ascending(a, b)

The comparator function for natural order:

function(a, b) {
  return a < b ? -1 : a > b ? 1 : 0;
}

This comparator can be used in conjunction with the built-in array sort method to sort elements by their natural order, ascending. Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic (alphabetical), not natural!

# d3.descending(a, b)

The comparator function for reverse natural order:

function(a, b) {
  return b < a ? -1 : b > a ? 1 : 0;
}

This comparator can be used in conjunction with the built-in array sort method to sort elements by their natural order, descending. Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic, not natural!

# d3.min(array[, function])

# d3.max(array[, function])

Associative Arrays

# d3.keys(object)

# d3.values(object)

# d3.entries(object)

Array Operators

# d3.split(array[, function])

# d3.merge(arrays)

# d3.range([start, ]stop[, step])

Nest

# d3.nest()

# nest.key(function)

# nest.sortKeys(comparator)

# nest.sortValues(comparator)

# nest.rollup(function)

# nest.map(array)

# nest.entries(array)