Bump to v3.0.0.

collection/sample.js

@@ -0,0 +1,39 @@
+define(['../internal/baseRandom', '../internal/isIterateeCall', './shuffle', '../internal/toIterable'], function(baseRandom, isIterateeCall, shuffle, toIterable) {
+
+  /** Used as a safe reference for `undefined` in pre-ES5 environments. */
+  var undefined;
+
+  /* Native method references for those with the same name as other `lodash` methods. */
+  var nativeMin = Math.min;
+
+  /**
+   * Gets a random element or `n` random elements from a collection.
+   *
+   * @static
+   * @memberOf _
+   * @category Collection
+   * @param {Array|Object|string} collection The collection to sample.
+   * @param {number} [n] The number of elements to sample.
+   * @param- {Object} [guard] Enables use as a callback for functions like `_.map`.
+   * @returns {*} Returns the random sample(s).
+   * @example
+   *
+   * _.sample([1, 2, 3, 4]);
+   * // => 2
+   *
+   * _.sample([1, 2, 3, 4], 2);
+   * // => [3, 1]
+   */
+  function sample(collection, n, guard) {
+    if (guard ? isIterateeCall(collection, n, guard) : n == null) {
+      collection = toIterable(collection);
+      var length = collection.length;
+      return length > 0 ? collection[baseRandom(0, length - 1)] : undefined;
+    }
+    var result = shuffle(collection);
+    result.length = nativeMin(n < 0 ? 0 : (+n || 0), result.length);
+    return result;
+  }
+
+  return sample;
+});