|
| 1 | +# OrderBy Filter |
| 2 | + |
| 3 | +## Description |
| 4 | + |
| 5 | +Returns an array containing the items from the specified `collection`, ordered |
| 6 | +by a `comparator` function based on the values computed using the `expression` |
| 7 | +predicate. |
| 8 | + |
| 9 | +For example, `[{id: 'foo'}, {id: 'bar'}] | orderBy:'id'` would result in |
| 10 | +`[{id: 'bar'}, {id: 'foo'}]`. |
| 11 | + |
| 12 | +The `collection` can be an Array or array-like object (e.g., NodeList, jQuery |
| 13 | +object, TypedArray, String, etc). |
| 14 | + |
| 15 | +The `expression` can be a single predicate or a list of predicates, each serving |
| 16 | +as a tie-breaker for the preceding one. The `expression` is evaluated against |
| 17 | +each item and the output is used for comparing with other items. |
| 18 | + |
| 19 | +You can change the sorting order by setting `reverse` to `true`. By default, |
| 20 | +items are sorted in ascending order. |
| 21 | + |
| 22 | +The comparison is done using the `comparator` function. If none is specified, a |
| 23 | +default, built-in comparator is used (see below for details - in a nutshell, it |
| 24 | +compares numbers numerically and strings alphabetically). |
| 25 | + |
| 26 | +### Under the Hood |
| 27 | + |
| 28 | +Ordering the specified `collection` happens in two phases: |
| 29 | + |
| 30 | +1. All items are passed through the predicate (or predicates), and the returned |
| 31 | + values are saved along with their type (`string`, `number`, etc). For |
| 32 | + example, an item `{label: 'foo'}`, passed through a predicate that extracts |
| 33 | + the value of the `label` property, would be transformed to: |
| 34 | + ```javascript |
| 35 | + { |
| 36 | + value: 'foo', |
| 37 | + type: 'string', |
| 38 | + index: ... |
| 39 | + } |
| 40 | + ``` |
| 41 | + |
| 42 | +Note: null values use 'null' as their type. 2. The comparator function is used |
| 43 | +to sort the items, based on the derived values, types, and indices. |
| 44 | + |
| 45 | +If you use a custom comparator, it will be called with pairs of objects of the |
| 46 | +form {value: ..., type: '...', index: ...} and is expected to return 0 if the |
| 47 | +objects are equal (as far as the comparator is concerned), -1 if the 1st one |
| 48 | +should be ranked higher than the second, or 1 otherwise. |
| 49 | + |
| 50 | +To ensure that the sorting will be deterministic across platforms, if none of |
| 51 | +the specified predicates can distinguish between two items, orderBy will |
| 52 | +automatically introduce a dummy predicate that returns the item's index as |
| 53 | +value. (If you are using a custom comparator, make sure it can handle this |
| 54 | +predicate as well.) |
| 55 | + |
| 56 | +If a custom comparator still can't distinguish between two items, then they will |
| 57 | +be sorted based on their index using the built-in comparator. |
| 58 | + |
| 59 | +Finally, in an attempt to simplify things, if a predicate returns an object as |
| 60 | +the extracted value for an item, orderBy will try to convert that object to a |
| 61 | +primitive value before passing it to the comparator. The following rules govern |
| 62 | +the conversion: |
| 63 | + |
| 64 | +If the object has a valueOf() method that returns a primitive, its return value |
| 65 | +will be used instead. (If the object has a valueOf() method that returns another |
| 66 | +object, then the returned object will be used in subsequent steps.) If the |
| 67 | +object has a custom toString() method (i.e., not the one inherited from Object) |
| 68 | +that returns a primitive, its return value will be used instead. (If the object |
| 69 | +has a toString() method that returns another object, then the returned object |
| 70 | +will be used in subsequent steps.) No conversion; the object itself is used. The |
| 71 | +Default Comparator The default, built-in comparator should be sufficient for |
| 72 | +most use cases. In short, it compares numbers numerically, strings |
| 73 | +alphabetically (and case-insensitively), for objects falls back to using their |
| 74 | +index in the original collection, sorts values of different types by type, and |
| 75 | +puts undefined and null values at the end of the sorted list. |
| 76 | + |
| 77 | +More specifically, it follows these steps to determine the relative order of |
| 78 | +items: |
| 79 | + |
| 80 | +If the compared values are of different types: If one of the values is |
| 81 | +undefined, consider it "greater than" the other. Else if one of the values is |
| 82 | +null, consider it "greater than" the other. Else compare the types themselves |
| 83 | +alphabetically. If both values are of type string, compare them alphabetically |
| 84 | +in a case- and locale-insensitive way. If both values are objects, compare their |
| 85 | +indices instead. Otherwise, return: 0, if the values are equal (by strict |
| 86 | +equality comparison, i.e., using ===). -1, if the 1st value is "less than" the |
| 87 | +2nd value (compared using the < operator). 1, otherwise. Note: If you notice |
| 88 | +numbers not being sorted as expected, make sure they are actually being saved as |
| 89 | +numbers and not strings. Note: For the purpose of sorting, null and undefined |
| 90 | +are considered "greater than" any other value (with undefined "greater than" |
| 91 | +null). This effectively means that null and undefined values end up at the end |
| 92 | +of a list sorted in ascending order. Note: null values use 'null' as their type |
| 93 | +to be able to distinguish them from objects. |
| 94 | + |
| 95 | +Parameters collection {Array|ArrayLike}: The collection (array or array-like |
| 96 | +object) to sort. |
| 97 | + |
| 98 | +expression {(Function|string|Array.<Function|string>)=}: A predicate (or list of |
| 99 | +predicates) to be used by the comparator to determine the order of elements. |
| 100 | + |
| 101 | +Can be one of: |
| 102 | + |
| 103 | +Function: A getter function. This function will be called with each item as an |
| 104 | +argument and the return value will be used for sorting. string: An AngularTS |
| 105 | +expression. This expression will be evaluated against each item and the result |
| 106 | +will be used for sorting. For example, use 'label' to sort by a property called |
| 107 | +label or 'label.substring(0, 3)' to sort by the first 3 characters of the label |
| 108 | +property. (The result of a constant expression is interpreted as a property name |
| 109 | +to be used for comparison. For example, use '"special name"' (note the extra |
| 110 | +pair of quotes) to sort by a property called special name.) An expression can be |
| 111 | +optionally prefixed with + or - to control the sorting direction, ascending or |
| 112 | +descending. For example, '+label' or '-label'. If no property is provided, |
| 113 | +(e.g., '+' or '-'), the collection element itself is used in comparisons. Array: |
| 114 | +An array of function and/or string predicates. If a predicate cannot determine |
| 115 | +the relative order of two items, the next predicate is used as a tie-breaker. |
| 116 | +Note: If the predicate is missing or empty, then it defaults to '+'. |
| 117 | + |
| 118 | +reverse {boolean=}: If true, reverse the sorting order. |
| 119 | + |
| 120 | +comparator {(Function)=}: The comparator function used to determine the relative |
| 121 | +order of value pairs. If omitted, the built-in comparator will be used. |
| 122 | + |
| 123 | +Returns {Array}: The sorted array. |
0 commit comments