Use the _.iteratee convention in _.collate (#135)

Author: jgonggrijp

docs/underscore.array.builders.js.md

@@ -112,9 +112,9 @@ Signature: `_.collate(toSort:array, customOrder:array)`
     //=> ['tall', 'tall', 'medium', 'medium', 'short', 'short']
 ```
 
-You can provide a third argument to `_.collate` to influence how array elements are evaluated while sorting.
+You can provide a third argument to `_.collate` to influence how array elements are evaluated while sorting. This argument will be passed through `_.iteratee()` in order to obtain a function that returns the sorting value.
 
-If the third argument is a string, `_.collate` will look for a property with that name on each array element, and that value will be used for sorting.
+For example, if the third argument is a string, `_.collate` will look for a property with that name on each array element, and that value will be used for sorting.
 
 Signature: `_collate(toSort:array, customOrder:array, sortKey:string)`
 
@@ -125,7 +125,7 @@ Signature: `_collate(toSort:array, customOrder:array, sortKey:string)`
     //=> [ {name:'Arnold', height:'tall'}, {name:'Danny', height:'short'} ];
 ```
 
-You may also pass a function as the third argument; it will be executed once for each item (with the original list as `this`, and the item as its argument), with its return used as the item's sort value.
+You may also directly pass a function as the third argument; it will be executed once for each item (with the original list as `this`, and the item as its argument), with its return used as the item's sort value.
 
 Signature: `_collate(toSort:array, customOrder:array, sortKey:function)`
 

underscore.array.builders.js

@@ -189,27 +189,17 @@
 
     // Returns copy or array sorted according to arbitrary ordering
     // order must be an array of values; defines the custom sort
-    // key must be one of: missing/null, a string, or a function;
+    // key must be a valid argument to _.iteratee
     collate: function(array, order, key) {
       if (typeof array.length != "number") throw new TypeError("expected an array-like first argument");
       if (typeof order.length != "number") throw new TypeError("expected an array-like second argument");
 
       var original = slice.call(array);
       var valA, valB;
+      var cb = _.iteratee(key);
       return sort.call(original, function (a, b) {
-        if(_.isFunction(key)) {
-          valA = key.call(original, a);
-          valB = key.call(original, b);
-        } else if(existy(key)) {
-          valA = a[key];
-          valB = b[key];
-        } else {
-          valA = a;
-          valB = b;
-        }
-
-        var rankA = _.indexOf(order, valA);
-        var rankB = _.indexOf(order, valB);
+        var rankA = _.indexOf(order, cb(a));
+        var rankB = _.indexOf(order, cb(b));
 
         if(rankA === -1) return 1;
         if(rankB === -1) return -1;