30:[] 2e:{"title":"d3.ascending, d3.descending","cells":[{"id":285,"value":"# d3.ascending, d3.descending\n\n[d3.ascending](https://d3js.org/d3-array/sort#ascending) returns the natural order of a given value *a* relative to a given value *b*. By *order*, we mean whether *a* should be before or after *b*, and by *natural*, we mean the order defined by the operators `<` and `>`, which compare not only [ordinal numbers](https://en.wikipedia.org/wiki/Ordinal_number), but also booleans, strings and certain objects (such as dates). [d3.descending](https://d3js.org/d3-array/sort#descending) returns the *reverse* natural order: d3.descending(*a*, *b*) is equivalent to d3.ascending(*b*, *a*).","pinned":false,"hidden":false,"mode":"md"},{"id":704,"value":"Order is represented by:\n\n* a positive value if *a* is before *b*,\n* a negative value if *a* is after *b*,\n* zero if *a* is equivalent to *b*, or\n* `NaN` if the relative order is unknown.\n\nAnyhow, we can now confirm that 5 is, in fact, greater than 4:","pinned":false,"hidden":false,"mode":"md"},{"id":260,"value":"d3.ascending(5, 4)","pinned":true,"hidden":false,"mode":"ojs"},{"id":469,"value":"5 > 4","pinned":true,"hidden":false,"mode":"ojs"},{"id":356,"value":"And likewise that Alice appears before Bob in alphabetical order:","pinned":false,"hidden":false,"mode":"md"},{"id":359,"value":"d3.ascending(\"Alice\", \"Bob\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":472,"value":"\"Alice\" < \"Bob\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":423,"value":"But why use d3.ascending when you can use `<` and `>` directly? The answer is that d3.ascending is a *comparator*—a special type of function used by various algorithms that manipulate ordinal values, such as [*array*.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), [d3.bisect](https://d3js.org/d3-array/bisect), and [d3.quickselect](https://d3js.org/d3-array/sort#quickselect). While you’ll often implement comparators by hand, standard comparators are convenient to use directly or to derive a custom order.\n\nFor example, to sort an array of numbers:","pinned":false,"hidden":false,"mode":"md"},{"id":20,"value":"[3, 2, 5, 4, 1].sort(d3.ascending)","pinned":true,"hidden":false,"mode":"ojs"},{"id":25,"value":"Or some words:","pinned":false,"hidden":false,"mode":"md"},{"id":59,"value":"\"The quick brown fox jumps over the lazy dog\".split(/\\s/).sort(d3.ascending)","pinned":true,"hidden":false,"mode":"ojs"},{"id":509,"value":"Couldn’t we just use *array*.sort directly, with no comparator? In some cases, like the array of strings above, it works. But consider what happens when we use *array*.sort on an array of numbers:","pinned":false,"hidden":false,"mode":"md"},{"id":513,"value":"[1, 2, 10].sort() // 🌶 Yikes!","pinned":true,"hidden":false,"mode":"ojs"},{"id":949,"value":"The behavior is quite surprising: instead of comparing the numeric values to return them in the natural order, *array*.sort coerces them to strings and uses *lexicographic* (case-sensitive alphabetical) order! Using d3.ascending guarantees that the numeric order is preserved:","pinned":false,"hidden":false,"mode":"md"},{"id":958,"value":"[1, 2, 10].sort(d3.ascending)","pinned":true,"hidden":false,"mode":"ojs"},{"id":557,"value":"Here’s the by-hand equivalent for ordering numbers, for comparison:","pinned":false,"hidden":false,"mode":"md"},{"id":561,"value":"[1, 2, 10].sort((a, b) => a - b)","pinned":true,"hidden":false,"mode":"ojs"},{"id":564,"value":"But d3.ascending is more accurate, say if you’re working with large numbers where subtracting values can introduce floating point error. And d3.ascending works with any naturally orderable type.","pinned":false,"hidden":false,"mode":"md"},{"id":71,"value":"## Custom comparators\n\nTabular data, such as from a CSV file, is often represented as an array of objects. Although these objects have no *natural* order, you can define a custom order by writing a comparator. Use d3.ascending to derive your custom order from a natural order, say of a specific column.","pinned":false,"hidden":false,"mode":"md"},{"id":77,"value":"foods = [\n {item: \"Soup\", votes: 4, emoji: \"🍜\"},\n {item: \"Cake\", votes: 5, emoji: \"🍰\"},\n {item: \"Cabbage\", votes: 1, emoji: \"🥬\"},\n {item: \"Ice Cream\", votes: 4, emoji: \"🍦\"}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":619,"value":"sortedFoods = foods.slice().sort((a, b) => d3.descending(a.votes, b.votes))","pinned":true,"hidden":false,"mode":"ojs"},{"id":86,"value":"The foods in descending order of votes are: ${sortedFoods.map(d => d.emoji).join(\", \")}. People like cake!\n\nSimilarly, you can implement a custom order based on multiple columns (multiple properties) by composing them with the `||` operator. The first comparator that returns a truthy (non-zero, non-`NaN`) value is used. For example, you might sort people alphabetically by last name and then first name.","pinned":false,"hidden":false,"mode":"md"},{"id":641,"value":"people = [\n {first: \"Barry\", last: \"Gibb\"},\n {first: \"Robin\", last: \"Gibb\"},\n {first: \"Vince\", last: \"Melouney\"},\n {first: \"Maurice\", last: \"Gibb\"},\n {first: \"Colin\", last: \"Petersen\"}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":643,"value":"people.slice().sort((a, b) => d3.ascending(a.last, b.last) || d3.ascending(a.first, b.first))","pinned":true,"hidden":false,"mode":"ojs"},{"id":167,"value":"Likewise, you can order using a derived column—a property that you compute on-the-fly, as needed—rather than some preexisting column in your data. For example, if you want case-insensitive sorting of strings, you can downcase words before comparing them with d3.ascending.","pinned":false,"hidden":false,"mode":"md"},{"id":174,"value":"\"The quick brown fox jumps over the lazy dog\".split(/\\s/).sort((a, b) => d3.ascending(a.toLowerCase(), b.toLowerCase()))","pinned":true,"hidden":false,"mode":"ojs"},{"id":184,"value":"It may be more efficient to materialize the derived column rather than doing it lazily inside your comparator. For example when sorting, your comparator may be called ${tex`O(n \\log n)`} times, but if you materialize greedily you’ll only derive ${tex`O(n)`} values.","pinned":false,"hidden":false,"mode":"md"},{"id":598,"value":"## Naturally-orderable objects\n\nCertain objects in JavaScript can be ordered using the comparison operators, and by extension d3.ascending and d3.descending. Dates, for example:","pinned":false,"hidden":false,"mode":"md"},{"id":762,"value":"before = new Date(2018, 0, 1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":763,"value":"after = new Date(2019, 0, 1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":766,"value":"before < after","pinned":true,"hidden":false,"mode":"ojs"},{"id":772,"value":"d3.ascending(before, after)","pinned":true,"hidden":false,"mode":"ojs"},{"id":774,"value":"d3.descending(before, after)","pinned":true,"hidden":false,"mode":"ojs"},{"id":414,"value":"What’s special about dates? They merely implement [*object*.valueOf](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf) which allows operators to coerce them to a primitive value (a number) prior to comparison. To demonstrate, here the coercion is explicit:","pinned":false,"hidden":false,"mode":"md"},{"id":785,"value":"before.valueOf()","pinned":true,"hidden":false,"mode":"ojs"},{"id":787,"value":"+before","pinned":true,"hidden":false,"mode":"ojs"},{"id":792,"value":"+before < +after","pinned":true,"hidden":false,"mode":"ojs"},{"id":794,"value":"Implement *object*.valueOf if you want your objects to be naturally ordered, too.","pinned":false,"hidden":false,"mode":"md"},{"id":798,"value":"class Color {\n constructor(r, g, b) {\n this.r = r & 0xff;\n this.g = g & 0xff;\n this.b = b & 0xff;\n }\n valueOf() {\n return (this.r << 16) | (this.g << 8) | this.b;\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":799,"value":"steelblue = new Color(70, 130, 180)","pinned":true,"hidden":false,"mode":"ojs"},{"id":801,"value":"coral = new Color(255, 127, 80)","pinned":true,"hidden":false,"mode":"ojs"},{"id":803,"value":"steelblue < coral","pinned":true,"hidden":false,"mode":"ojs"},{"id":893,"value":"d3.ascending(steelblue, coral)","pinned":true,"hidden":false,"mode":"ojs"},{"id":344,"value":"Object equality, as defined by JavaScript’s `===` operator, has a somewhat surprising relationship with order as determined by `<`, `>`, `<=` and `>=`. Say you have two Dates that represent the same moment in time:","pinned":false,"hidden":false,"mode":"md"},{"id":369,"value":"date1 = new Date(2018, 0, 1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":371,"value":"date2 = new Date(2018, 0, 1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":373,"value":"Because these are different instances, they are not equal:","pinned":false,"hidden":false,"mode":"md"},{"id":376,"value":"date1 === date2","pinned":true,"hidden":false,"mode":"ojs"},{"id":378,"value":"Yet they have equivalent order:","pinned":false,"hidden":false,"mode":"md"},{"id":388,"value":"d3.ascending(date1, date2)","pinned":true,"hidden":false,"mode":"ojs"},{"id":386,"value":"[date1 <= date2, date1 >= date2]","pinned":true,"hidden":false,"mode":"ojs"},{"id":730,"value":"The primitives returned by *object*.valueOf *are* equal even though the objects themselves are not; the strict equality operator, unlike the comparison operators, does not coerce objects to primitives. (The loose equality operator, `==`, [may coerce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness), but not when both values are objects.)","pinned":false,"hidden":false,"mode":"md"},{"id":381,"value":"## Stable sorting\n\nIn modern JavaScript, *array*.sort is stable, meaning that if your comparator returns zero (or `NaN`) for the given *a* and *b*, *array*.sort will preserve the existing relative order of *a* and *b* in the array. This means, for example, that you can sort an array using multiple comparators (and have predictable results).\n\nHere’s an alternative method of sorting tabular data by multiple columns. The lowest-priority column goes first, and the highest-priority column goes last.","pinned":false,"hidden":false,"mode":"md"},{"id":834,"value":"people.slice()\n .sort((a, b) => d3.ascending(a.first, b.first))\n .sort((a, b) => d3.ascending(a.last, b.last))","pinned":true,"hidden":false,"mode":"ojs"},{"id":838,"value":"Multi-pass sorting is typically slower than single-pass sorting with a compound comparator (a comparator that compares multiple columns directly), since it involves more comparisons, but it can be convenient.","pinned":false,"hidden":false,"mode":"md"},{"id":141,"value":"## Gotchas!\n\nWhile natural order is well-defined for two values of the same type, such as two numbers or two strings, it’s not well-defined for two values of *different* types. When the comparison fails, the comparison operator will return false, while d3.ascending and d3.descending will return `NaN`.","pinned":false,"hidden":false,"mode":"md"},{"id":866,"value":"\"a\" < 3","pinned":true,"hidden":false,"mode":"ojs"},{"id":868,"value":"\"a\" > 3","pinned":true,"hidden":false,"mode":"ojs"},{"id":910,"value":"d3.ascending(\"a\", 3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":912,"value":"Even more confusing, if the string can be coerced to a number, then comparing the string and number can succeed.","pinned":false,"hidden":false,"mode":"md"},{"id":915,"value":"\"10\" > 3","pinned":true,"hidden":false,"mode":"ojs"},{"id":918,"value":"d3.ascending(\"10\", 3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":920,"value":"Sorting mixed types by natural order will have undefined behavior.","pinned":false,"hidden":false,"mode":"md"},{"id":135,"value":"[3, 2, \"a\", 4, 1].sort(d3.ascending) // 🌶 Yikes!","pinned":true,"hidden":false,"mode":"ojs"},{"id":152,"value":"Natural order may also give unexpected results if you thought your values were one type (say numbers), but were in fact another type (say strings). If you’re working with an untyped data format, such as CSV, coerce your data to the expected type as early as possible, say using [d3.autoType](https://d3js.org/d3-dsv#autoType).","pinned":false,"hidden":false,"mode":"md"},{"id":61,"value":"[\"100\", \"67\", \"103\", \"245\"].sort(d3.ascending) // 🧐","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}