A D3 generator for comparator functions. It can be used to easily sort arrays of objects by one or multiple dimensions.

If you want to sort by a single dimension, you end up writing comparators like function cmp(a, b) { return a.value - b.value; } or function cmp(a, b) { return d3.ascending(a.value, b.value); }. For sorting by two or more dimensions it gets ugly pretty fast. d3.comparator provides a simple API for generating those comparators.

d3.comparator()

Constructs a new comparator with the default return value 0. I.e. using it will not change sort order.

comparator(a, b)

The comparator can be used with the array sort method.

comparator.dimension(cmp, [accessor])

Adds a dimension to the comparator. The return value of accessor will be compared with cmp (which has to be a comparator function itself, e.g. d3.ascending). If accessor isn't specified, an identity function function(d) { return d; } is used.

Dimensions are compared in order. As soon as cmp returns something other than 0, subsequent dimensions are ignored.

Example using a single dimension:

var cmp = d3.comparator().dimension(d3.ascending, function(d) { return d.value; });

Example using two dimensions, roughly equivalent to SQL ORDER BY year DESC, value ASC:

var cmp = d3.comparator()
  .dimension(d3.descending, function(d) { return d.year; })
  .dimension(d3.ascending, function(d) { return d.value; });

Note: These are just comparator functions. To acually sort an array use

someArray.sort(cmp);

Jeremy Stucki, Interactive Things

BSD, see LICENSE.txt