docs(orderBy): Clarify behavior of default comparator #15304
Conversation
Documentation updates to clarify default sort behavior. See angular#15293 for more information
| ### Filters (`orderBy`) | ||
|
|
||
| - due to [a097aa95](https://github.com/angular/angular.js/commit/a097aa95b7c78beab6d1b7d521c25f7d9d7843d9), | ||
| the default orderBy comparator sorts null values (strings, objects, etc.) as if they were the string `'null'`: |
There was a problem hiding this comment.
Null values can't be strings, objects etc. A null value is just null :)
There was a problem hiding this comment.
Hm...actually things are a little more complicated: #15293 (comment)
For this breaking change note, you need to mention the change introduced in a097aa9.
For the docs, you need to mention the current situation, as introduced in 48e1f56.
| the default orderBy comparator sorts null values (strings, objects, etc.) as if they were the string `'null'`: | ||
| a null string will be sorted as if it started with the letter N. To sort nonexistent items to the last (or first, | ||
| if sort order is reversed) positions in the sort results, the sort predicate should use the empty string instead | ||
| of null. Similarly, predicate values that are `undefined` will be sorted as if they were strings starting with |
There was a problem hiding this comment.
I don't think this applies to undefined. The change only affects null afaict.
| @@ -86,6 +86,9 @@ | |||
| * | |||
| * **Note:** If you notice numbers not being sorted as expected, make sure they are actually being | |||
| * saved as numbers and not strings. | |||
| * **Note:** If null or undefined values are not being sorted as expected, convert them to the empty | |||
There was a problem hiding this comment.
What this note should mention is that null is treated as the string 'null' while sorting. There doesn't need to be a special mention about undefined, since it follows the algorithm described above.
I would also refrain from suggesting any work arounds, because there are different ones available, each with its pros and cons (e.g. use an extra predicate to separate null from non-null value, convert null to an empty string or undefined, use a custom comparator etc).
There was a problem hiding this comment.
I've changed as suggested.
| @@ -86,6 +86,8 @@ | |||
| * | |||
| * **Note:** If you notice numbers not being sorted as expected, make sure they are actually being | |||
| * saved as numbers and not strings. | |||
| * **Note:** If null values are not being sorted as expected it may be due to rule number | |||
| * 1 above which sorts `null` as the string `'null'`. | |||
There was a problem hiding this comment.
No, it is not related to rule number 1. Normally, the type of null is object. But we sort it as if it's type were string.
I would write something like:
Note: Normally the type of
nullisobject. When applying the above algorithm,nullvalues are converted to the string'null'(and thus have a type ofstring).
|
I've made additional wording updates. I really do want to try and keep something in the wording indicating the effect (unexpected sort order), not just the fact that nulls are converted to strings. |
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Document how `orderBy`'s default comparator handles `null` values. Fixes angular#15293 Closes angular#15304
Documentation updates to clarify default sort behavior. See
#15293 for more information
(These changes are slightly different than the ones in #15302, since I started from master rather than 1.3.x docs)