Add _.sample.

Former-commit-id: 00e27cca2a65e1310b26904173ffec18aa484e48

lodash.js

@@ -3815,6 +3815,37 @@
       });
     }
 
+    /**
+     * Retrieves a random element or `n` random elements from a collection.
+     *
+     * @static
+     * @memberOf _
+     * @category Collections
+     * @param {Array|Object|String} collection The collection to sample.
+     * @returns {Array} Returns the random sample(s) of `collection`.
+     * @example
+     *
+     * _.sample([1, 2, 3, 4]);
+     * // => 2
+     *
+     * _.sample([1, 2, 3, 4], 2);
+     * // => [3, 1]
+     */
+    function sample(collection, n, guard) {
+      if (!isArray(collection)) {
+        collection = toArray(collection);
+      }
+      var index = -1,
+          maxIndex = collection.length - 1;
+
+      if (n == null || guard) {
+        return collection[random(maxIndex)];
+      }
+      var result = shuffle(collection);
+      result.length = nativeMin(nativeMax(0, n), result.length);
+      return result;
+    }
+
     /**
      * Creates an array of shuffled values, using a version of the Fisher-Yates
      * shuffle. See http://en.wikipedia.org/wiki/Fisher-Yates_shuffle.
@@ -3835,7 +3866,7 @@
           result = Array(typeof length == 'number' ? length : 0);
 
       forEach(collection, function(value) {
-        var rand = floor(nativeRandom() * (++index + 1));
+        var rand = random(++index);
         result[index] = result[rand];
         result[rand] = value;
       });
@@ -4177,11 +4208,10 @@
     }
 
     /**
-     * Gets the first element of an array. If a number `n` is provided the first
-     * `n` elements of the array are returned. If a callback is provided elements
-     * at the beginning of the array are returned as long as the callback returns
-     * truthy. The callback is bound to `thisArg` and invoked with three arguments;
-     * (value, index, array).
+     * Gets the first element or first `n` elements of an array. If a callback
+     * is provided elements at the beginning of the array are returned as long
+     * as the callback returns truthy. The callback is bound to `thisArg` and
+     * invoked with three arguments; (value, index, array).
      *
      * If a property name is provided for `callback` the created "_.pluck" style
      * callback will return the property value of the given element.
@@ -4344,11 +4374,10 @@
     }
 
     /**
-     * Gets all but the last element of an array. If a number `n` is provided
-     * the last `n` elements are excluded from the result. If a callback is
-     * provided elements at the end of the array are excluded from the result
-     * as long as the callback returns truthy. The callback is bound to `thisArg`
-     * and invoked with three arguments; (value, index, array).
+     * Gets all but the last element or last `n` elements of an array. If a
+     * callback is provided elements at the end of the array are excluded from
+     * the result as long as the callback returns truthy. The callback is bound
+     * to `thisArg` and invoked with three arguments; (value, index, array).
      *
      * If a property name is provided for `callback` the created "_.pluck" style
      * callback will return the property value of the given element.
@@ -4478,12 +4507,10 @@
     }
 
     /**
-     * Gets the last element of an array. If a number `n` is provided the last
-     * `n` elements of the array are returned. If a callback is provided elements
-     * at the end of the array are returned as long as the callback returns truthy.
-     * The callback is bound to `thisArg` and invoked with three arguments;
-     * (value, index, array).
-     *
+     * Gets the last element or last `n` elements of an array. If a callback is
+     * provided elements at the end of the array are returned as long as the
+     * callback returns truthy. The callback is bound to `thisArg` and invoked
+     * with three arguments; (value, index, array).
      *
      * If a property name is provided for `callback` the created "_.pluck" style
      * callback will return the property value of the given element.
@@ -4727,12 +4754,11 @@
     }
 
     /**
-     * The opposite of `_.initial` this method gets all but the first value of
-     * an array. If a number `n` is provided the first `n` values are excluded
-     * from the result. If a callback function is provided elements at the beginning
-     * of the array are excluded from the result as long as the callback returns
-     * truthy. The callback is bound to `thisArg` and invoked with three
-     * arguments; (value, index, array).
+     * The opposite of `_.initial` this method gets all but the first element or
+     * first `n` elements of an array. If a callback function is provided elements
+     * at the beginning of the array are excluded from the result as long as the
+     * callback returns truthy. The callback is bound to `thisArg` and invoked
+     * with three arguments; (value, index, array).
      *
      * If a property name is provided for `callback` the created "_.pluck" style
      * callback will return the property value of the given element.
@@ -6429,18 +6455,20 @@
     // add functions capable of returning wrapped and unwrapped values when chaining
     lodash.first = first;
     lodash.last = last;
+    lodash.sample = sample;
 
     // add aliases
     lodash.take = first;
     lodash.head = first;
 
     forOwn(lodash, function(func, methodName) {
+      var callbackable = methodName !== 'sample';
       if (!lodash.prototype[methodName]) {
-        lodash.prototype[methodName]= function(callback, thisArg) {
+        lodash.prototype[methodName]= function(n, guard) {
           var chainAll = this.__chain__,
-              result = func(this.__wrapped__, callback, thisArg);
+              result = func(this.__wrapped__, n, guard);
 
-          return !chainAll && (callback == null || (thisArg && typeof callback != 'function'))
+          return !chainAll && (n == null || (guard && !(callbackable && typeof n == 'function')))
             ? result
             : new lodashWrapper(result, chainAll);
         };