diff --git a/index.html b/index.html index e785d72eb..53c76fe8c 100644 --- a/index.html +++ b/index.html @@ -382,6 +382,12 @@ +
+ + Notes + +
+
Change Log @@ -734,6 +740,8 @@

Collection Functions (Arrays or Objects)

criterion by which the value is ranked. -Infinity is returned if list is empty, so an
isEmpty guard may be required. Non-numerical values in list will be ignored. + This function uses operator < + (note).

 var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
@@ -749,6 +757,8 @@ 

Collection Functions (Arrays or Objects)

criterion by which the value is ranked. Infinity is returned if list is empty, so an isEmpty guard may be required. Non-numerical values in list will be ignored. + This function uses operator < + (note).

 var numbers = [10, 5, 100, 2, 1000];
@@ -762,7 +772,8 @@ 

Collection Functions (Arrays or Objects)

Returns a (stably) sorted copy of list, ranked in ascending order by the results of running each value through iteratee. iteratee may also be the string name of the property to sort by (eg. - length). + length). This function uses operator < + (note).

 _.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
@@ -1091,7 +1102,9 @@ 

Array Functions

large array, and you know that the array is already sorted, pass true for isSorted to use a faster binary search ... or, pass a number as the third argument in order to look for the first matching value in the - array after the given index. + array after the given index. If isSorted is true, + this function uses operator < + (note).

 _.indexOf([1, 2, 3], 2);
@@ -1117,7 +1130,9 @@ 

Array Functions

should be inserted into the array in order to maintain the array's sorted order. If an iteratee function is provided, it will be used to compute the sort ranking of each value, including the value you pass. - The iteratee may also be the string name of the property to sort by (eg. length). + The iteratee may also be the string name of the property to sort by + (eg. length). This function uses operator < + (note).

 _.sortedIndex([10, 20, 30, 40, 50], 35);
@@ -2417,6 +2432,50 @@ 
         collection of functional helpers for Python, partially inspired by Underscore.
       

+

Notes

+ +

+ On the use of < in Underscore +
+ Underscore functions that depend on ordering, such as + _.sortBy and + _.sortedIndex, use + JavaScript’s built-in + relational operators, + specifically the “less than” operator <. It is + important to understand that these operators are only meaningful for + numbers and strings. You can throw any value to them, but JavaScript + will convert the operands to string or number first before performing + the actual comparison. If you pass an operand that + cannot be meaningfully converted to string or number, it ends up being + NaN by default. This value is unsortable. +

+

+ Ideally, the values that you are sorting should either be all + (meaningfully convertible to) strings or all (meaningfully convertible + to) numbers. If this is not the case, you have two options: +

    +
  • + _.filter out all unsortable values + first. +
  • +
  • + Pick a target type, i.e., either string or number, and pass an + iteratee to your Underscore + function that will convert its argument to a sensible instance of + the target type. For example, if you have an array of numbers that + you want to sort and that may occasionally contain null or + undefined, you can control whether you want to sort these + before or after all numbers by passing an iteratee to + _.sortBy that returns -Infinity or + +Infinity for such values, respectively. Or maybe you want + to treat them as zeros; it is up to you. The same iteratee + can also be passed to other Underscore functions to ensure that the + behavior is consistent. +
  • +
+

+

Change Log