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)

Returns -1 if a is less than b, or 1 if a is greater than b, or 0. This is the comparator function for natural order, and can be used in conjunction with the built-in array sort method to arrange elements in ascending order:

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

Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic (alphabetical), not natural! This can lead to bugs when sorting an array of numbers.

# d3.descending(a, b)

Returns -1 if a is greater than b, or 1 if a is less than b, or 0. This is the comparator function for reverse natural order, and can be used in conjunction with the built-in array sort method to arrange elements in descending order:

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

Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic (alphabetical), not natural! This can lead to bugs when sorting an array of numbers.

# d3.min(array[, function])

Returns the minimum value in the given array. If the array is empty, returns undefined. An optional accessor function may be specified, which is equivalent to calling array.map(function) before computing the minimum value. Unlike the built-in Math.min, this method ignores any values that cannot be coerced to a number, such as NaN or undefined. Thus, when computing the domain of a scale from data, only the defined region of the data is considered, rather than applying a degenerate domain.

# d3.max(array[, function])

Returns the maximum value in the given array. If the array is empty, returns undefined. An optional accessor function may be specified, which is equivalent to calling array.map(function) before computing the maximum value. Unlike the built-in Math.max, this method ignores any values that cannot be coerced to a number, such as NaN or undefined. Thus, when computing the domain of a scale from data, only the defined region of the data is considered, rather than applying a degenerate domain.

Associative Arrays

# d3.keys(object)

Returns an array containing the property names of the specified object (an associative array). The order of the returned array is not defined, though it will be consistent with your browser's iteration order when using a for…in loop.

# d3.values(object)

Returns an array containing the property values of the specified object (an associative array). The order of the returned array is not defined, though it will be consistent with your browser's iteration order when using a for…in loop.

# d3.entries(object)

Returns an array containing the property keys and values of the specified object (an associative array). Each entry is an object with a key and value attribute, such as {key: "foo", value: 42}. The order of the returned array is not defined, though it will be consistent with your browser's iteration order when using a for…in loop.

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)