Mirrors/lodash
1
0
Fork 0
mirror of https://github.com/whoisclebs/lodash.git synced 2026-02-09 18:37:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Lots of doc tweaks. [ci skip]

Browse Source
This commit is contained in:
John-David Dalton
2014-03-05 23:25:23 -08:00
parent f630c4ec6c
commit 0392e37eed
1 changed files with 98 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
lodash.js
View File

@@ -258,7 +258,7 @@
* @param {Array} array The array to search. * @param {Array} array The array to search.
* @param {*} value The value to search for. * @param {*} value The value to search for.
* @param {number} [fromIndex=0] The index to search from. * @param {number} [fromIndex=0] The index to search from.
* @returns {number} Returns the index of the matched value or `-1`. * @returns {number} Returns the index of the matched value, else `-1`.
*/ */
function baseIndexOf(array, value, fromIndex) { function baseIndexOf(array, value, fromIndex) {
var index = (fromIndex || 0) - 1, var index = (fromIndex || 0) - 1,
@@ -291,7 +291,7 @@
* *
* @private * @private
* @param {string} value The character to inspect. * @param {string} value The character to inspect.
* @returns {number} Returns the code unit of given character. * @returns {number} Returns the code unit of the given character.
*/ */
function charAtCallback(value) { function charAtCallback(value) {
return value.charCodeAt(0); return value.charCodeAt(0);
@@ -995,7 +995,7 @@
* *
* @private * @private
* @param {Object} data The data object used to populate the text. * @param {Object} data The data object used to populate the text.
* @returns {string} Returns the interpolated text. * @returns {string} Returns the interpolated string.
*/ */
var iteratorTemplate = template( var iteratorTemplate = template(
// assign the `result` variable an initial value // assign the `result` variable an initial value
@@ -1236,7 +1236,7 @@
* @param {*} [func=identity] The value to convert to a callback. * @param {*} [func=identity] The value to convert to a callback.
* @param {*} [thisArg] The `this` binding of the created callback. * @param {*} [thisArg] The `this` binding of the created callback.
* @param {number} [argCount] The number of arguments the callback accepts. * @param {number} [argCount] The number of arguments the callback accepts.
* @returns {Function} Returns a callback function. * @returns {Function} Returns the new function.
*/ */
function baseCreateCallback(func, thisArg, argCount) { function baseCreateCallback(func, thisArg, argCount) {
if (typeof func != 'function') { if (typeof func != 'function') {
@@ -1354,7 +1354,7 @@
* @private * @private
* @param {Array} array The array to process. * @param {Array} array The array to process.
* @param {Array} [values] The array of values to exclude. * @param {Array} [values] The array of values to exclude.
* @returns {Array} Returns a new array of filtered values. * @returns {Array} Returns the new array of filtered values.
*/ */
function baseDifference(array, values) { function baseDifference(array, values) {
var length = array ? array.length : 0; var length = array ? array.length : 0;
@@ -1459,7 +1459,7 @@
* @param {boolean} [isShallow=false] A flag to restrict flattening to a single level. * @param {boolean} [isShallow=false] A flag to restrict flattening to a single level.
* @param {boolean} [isStrict=false] A flag to restrict flattening to arrays and `arguments` objects. * @param {boolean} [isStrict=false] A flag to restrict flattening to arrays and `arguments` objects.
* @param {number} [fromIndex=0] The index to start from. * @param {number} [fromIndex=0] The index to start from.
* @returns {Array} Returns a new flattened array. * @returns {Array} Returns the new flattened array.
*/ */
function baseFlatten(array, isShallow, isStrict, fromIndex) { function baseFlatten(array, isShallow, isStrict, fromIndex) {
var index = (fromIndex || 0) - 1, var index = (fromIndex || 0) - 1,
@@ -1772,7 +1772,7 @@
* @private * @private
* @param {number} min The minimum possible value. * @param {number} min The minimum possible value.
* @param {number} max The maximum possible value. * @param {number} max The maximum possible value.
* @returns {number} Returns a random number. * @returns {number} Returns the random number.
*/ */
function baseRandom(min, max) { function baseRandom(min, max) {
return min + floor(nativeRandom() * (max - min + 1)); return min + floor(nativeRandom() * (max - min + 1));
@@ -1786,7 +1786,7 @@
* @param {Array} array The array to process. * @param {Array} array The array to process.
* @param {boolean} [isSorted=false] A flag to indicate that `array` is sorted. * @param {boolean} [isSorted=false] A flag to indicate that `array` is sorted.
* @param {Function} [callback] The function called per iteration. * @param {Function} [callback] The function called per iteration.
* @returns {Array} Returns a duplicate-value-free array. * @returns {Array} Returns the new duplicate-value-free array.
*/ */
function baseUniq(array, isSorted, callback) { function baseUniq(array, isSorted, callback) {
var length = array ? array.length : 0; var length = array ? array.length : 0;
@@ -1847,7 +1847,7 @@
* @param {Array} partialArg An array of arguments to prepend to those provided. * @param {Array} partialArg An array of arguments to prepend to those provided.
* @param {Array} partialHolders An array of `partialArgs` placeholder indexes. * @param {Array} partialHolders An array of `partialArgs` placeholder indexes.
* @param {Array|Object} args The provided arguments. * @param {Array|Object} args The provided arguments.
* @returns {Array} Returns a new array of composed arguments. * @returns {Array} Returns the new array of composed arguments.
*/ */
function composeArgs(partialArgs, partialHolders, args) { function composeArgs(partialArgs, partialHolders, args) {
var holdersLength = partialHolders.length, var holdersLength = partialHolders.length,
@@ -1877,7 +1877,7 @@
* @param {Array} partialRightArg An array of arguments to append to those provided. * @param {Array} partialRightArg An array of arguments to append to those provided.
* @param {Array} partialHolders An array of `partialRightArgs` placeholder indexes. * @param {Array} partialHolders An array of `partialRightArgs` placeholder indexes.
* @param {Array|Object} args The provided arguments. * @param {Array|Object} args The provided arguments.
* @returns {Array} Returns a new array of composed arguments. * @returns {Array} Returns the new array of composed arguments.
*/ */
function composeArgsRight(partialRightArgs, partialRightHolders, args) { function composeArgsRight(partialRightArgs, partialRightHolders, args) {
var holdersIndex = -1, var holdersIndex = -1,
@@ -1940,7 +1940,7 @@
* *
* @private * @private
* @param {Array} [array=[]] The array to search. * @param {Array} [array=[]] The array to search.
* @returns {Object} Returns the cache object. * @returns {Object} Returns the new cache object.
*/ */
var createCache = Set && function(array) { var createCache = Set && function(array) {
var cache = new Set, var cache = new Set,
@@ -1977,8 +1977,8 @@
} }
/** /**
* Creates a function that, when called, either curries or invokes `func` * Creates a function that either curries or invokes `func` with an optional
* with an optional `this` binding and partially applied arguments. * `this` binding and partially applied arguments.
* *
* @private * @private
* @param {Function|string} func The function or method name to reference. * @param {Function|string} func The function or method name to reference.
@@ -2090,7 +2090,7 @@
* @param {string} [options.init] The string representation of the initial `result` value. * @param {string} [options.init] The string representation of the initial `result` value.
* @param {string} [options.loop] Code to execute in the object loop. * @param {string} [options.loop] Code to execute in the object loop.
* @param {boolean} [options.useHas] Specify using `hasOwnProperty` checks in the object loop. * @param {boolean} [options.useHas] Specify using `hasOwnProperty` checks in the object loop.
* @returns {Function} Returns the compiled function. * @returns {Function} Returns the new function.
*/ */
function createIterator(options) { function createIterator(options) {
options.shadowedProps = shadowedProps; options.shadowedProps = shadowedProps;
@@ -2115,7 +2115,7 @@
* *
* @private * @private
* @param {Array} array The array to inspect. * @param {Array} array The array to inspect.
* @returns {Array} Returns a new array of placeholder indexes. * @returns {Array} Returns the new array of placeholder indexes.
*/ */
function getHolders(array) { function getHolders(array) {
var index = -1, var index = -1,
@@ -2254,13 +2254,13 @@
}); });
/** /**
* A fallback implementation of `Object.keys` which produces an array of the * A fallback implementation of `Object.keys` which creates an array of the
* given object's own enumerable property names. * own enumerable property names of `object`.
* *
* @private * @private
* @type Function * @type Function
* @param {Object} object The object to inspect. * @param {Object} object The object to inspect.
* @returns {Array} Returns an array of property names. * @returns {Array} Returns the array of property names.
*/ */
var shimKeys = createIterator({ var shimKeys = createIterator({
'args': 'object', 'args': 'object',
@@ -2279,7 +2279,7 @@
* @memberOf _ * @memberOf _
* @category Arrays * @category Arrays
* @param {Array} array The array to compact. * @param {Array} array The array to compact.
* @returns {Array} Returns a new array of filtered values. * @returns {Array} Returns the new array of filtered values.
* @example * @example
* *
* _.compact([0, 1, false, 2, '', 3]); * _.compact([0, 1, false, 2, '', 3]);
@@ -2309,7 +2309,7 @@
* @category Arrays * @category Arrays
* @param {Array} array The array to process. * @param {Array} array The array to process.
* @param {...Array} [values] The arrays of values to exclude. * @param {...Array} [values] The arrays of values to exclude.
* @returns {Array} Returns a new array of filtered values. * @returns {Array} Returns the new array of filtered values.
* @example * @example
* *
* _.difference([1, 2, 3], [5, 2, 10]); * _.difference([1, 2, 3], [5, 2, 10]);
@@ -2623,7 +2623,7 @@
* If a property name or object is provided it will be used to create a "_.pluck" * If a property name or object is provided it will be used to create a "_.pluck"
* or "_.where" style callback, respectively. * or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Array} Returns a new flattened array. * @returns {Array} Returns the new flattened array.
* @example * @example
* *
* _.flatten([1, [2], [3, [[4]]]]); * _.flatten([1, [2], [3, [[4]]]]);
@@ -2677,7 +2677,7 @@
* @param {*} value The value to search for. * @param {*} value The value to search for.
* @param {boolean|number} [fromIndex=0] The index to search from or `true` * @param {boolean|number} [fromIndex=0] The index to search from or `true`
* to perform a binary search on a sorted array. * to perform a binary search on a sorted array.
* @returns {number} Returns the index of the matched value or `-1`. * @returns {number} Returns the index of the matched value, else `-1`.
* @example * @example
* *
* _.indexOf([1, 2, 3, 1, 2, 3], 2); * _.indexOf([1, 2, 3, 1, 2, 3], 2);
@@ -2741,7 +2741,7 @@
* @memberOf _ * @memberOf _
* @category Arrays * @category Arrays
* @param {...Array} [array] The arrays to inspect. * @param {...Array} [array] The arrays to inspect.
* @returns {Array} Returns an array of shared values. * @returns {Array} Returns the new array of shared values.
* @example * @example
* *
* _.intersection([1, 2, 3], [5, 2, 1, 4], [2, 1]); * _.intersection([1, 2, 3], [5, 2, 1, 4], [2, 1]);
@@ -2834,7 +2834,7 @@
* @param {Array} array The array to search. * @param {Array} array The array to search.
* @param {*} value The value to search for. * @param {*} value The value to search for.
* @param {number} [fromIndex=array.length-1] The index to search from. * @param {number} [fromIndex=array.length-1] The index to search from.
* @returns {number} Returns the index of the matched value or `-1`. * @returns {number} Returns the index of the matched value, else `-1`.
* @example * @example
* *
* _.lastIndexOf([1, 2, 3, 1, 2, 3], 2); * _.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
@@ -2904,7 +2904,7 @@
* @param {number} [start=0] The start of the range. * @param {number} [start=0] The start of the range.
* @param {number} end The end of the range. * @param {number} end The end of the range.
* @param {number} [step=1] The value to increment or decrement by. * @param {number} [step=1] The value to increment or decrement by.
* @returns {Array} Returns a new range array. * @returns {Array} Returns the new array of numbers.
* @example * @example
* *
* _.range(4); * _.range(4);
@@ -2966,7 +2966,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Array} Returns a new array of removed elements. * @returns {Array} Returns the array of removed elements.
* @example * @example
* *
* var array = [1, 2, 3, 4, 5, 6]; * var array = [1, 2, 3, 4, 5, 6];
@@ -3039,7 +3039,7 @@
* @param {Array} array The array to slice. * @param {Array} array The array to slice.
* @param {number} [start=0] The start index. * @param {number} [start=0] The start index.
* @param {number} [end=array.length] The end index. * @param {number} [end=array.length] The end index.
* @returns {Array} Returns the new array. * @returns {Array} Returns the slice of `array`.
*/ */
function slice(array, start, end) { function slice(array, start, end) {
var index = -1, var index = -1,
@@ -3281,7 +3281,7 @@
* @memberOf _ * @memberOf _
* @category Arrays * @category Arrays
* @param {...Array} [array] The arrays to inspect. * @param {...Array} [array] The arrays to inspect.
* @returns {Array} Returns an array of combined values. * @returns {Array} Returns the new array of combined values.
* @example * @example
* *
* _.union([1, 2, 3], [5, 2, 1, 4], [2, 1]); * _.union([1, 2, 3], [5, 2, 1, 4], [2, 1]);
@@ -3316,7 +3316,7 @@
* If a property name or object is provided it will be used to create a "_.pluck" * If a property name or object is provided it will be used to create a "_.pluck"
* or "_.where" style callback, respectively. * or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Array} Returns a duplicate-value-free array. * @returns {Array} Returns the new duplicate-value-free array.
* @example * @example
* *
* _.uniq([1, 2, 1, 3, 1]); * _.uniq([1, 2, 1, 3, 1]);
@@ -3370,7 +3370,7 @@
* @category Arrays * @category Arrays
* @param {Array} array The array to filter. * @param {Array} array The array to filter.
* @param {...*} [value] The values to exclude. * @param {...*} [value] The values to exclude.
* @returns {Array} Returns a new array of filtered values. * @returns {Array} Returns the new array of filtered values.
* @example * @example
* *
* _.without([1, 2, 1, 0, 3, 1, 4], 0, 1); * _.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
@@ -3389,7 +3389,7 @@
* @memberOf _ * @memberOf _
* @category Arrays * @category Arrays
* @param {...Array} [array] The arrays to inspect. * @param {...Array} [array] The arrays to inspect.
* @returns {Array} Returns an array of values. * @returns {Array} Returns the new array of values.
* @example * @example
* *
* _.xor([1, 2, 3], [5, 2, 1, 4]); * _.xor([1, 2, 3], [5, 2, 1, 4]);
@@ -3424,7 +3424,7 @@
* @alias unzip * @alias unzip
* @category Arrays * @category Arrays
* @param {...Array} [array] The arrays to process. * @param {...Array} [array] The arrays to process.
* @returns {Array} Returns a new array of grouped elements. * @returns {Array} Returns the array of grouped elements.
* @example * @example
* *
* _.zip(['fred', 'barney'], [30, 40], [true, false]); * _.zip(['fred', 'barney'], [30, 40], [true, false]);
@@ -3456,8 +3456,7 @@
* @category Arrays * @category Arrays
* @param {Array} keys The array of keys. * @param {Array} keys The array of keys.
* @param {Array} [values=[]] The array of values. * @param {Array} [values=[]] The array of values.
* @returns {Object} Returns an object composed of the given keys and * @returns {Object} Returns the new object.
* corresponding values.
* @example * @example
* *
* _.zipObject(['fred', 'barney'], [30, 40]); * _.zipObject(['fred', 'barney'], [30, 40]);
@@ -3492,7 +3491,7 @@
* @memberOf _ * @memberOf _
* @category Chaining * @category Chaining
* @param {*} value The value to wrap. * @param {*} value The value to wrap.
* @returns {Object} Returns the wrapper object. * @returns {Object} Returns the new wrapper object.
* @example * @example
* *
* var characters = [ * var characters = [
@@ -3571,12 +3570,12 @@
} }
/** /**
* Produces the `toString` result of the wrapped value. * Produces the result of coercing the wrapped value to a string.
* *
* @name toString * @name toString
* @memberOf _ * @memberOf _
* @category Chaining * @category Chaining
* @returns {string} Returns the string result. * @returns {string} Returns the coerced string value.
* @example * @example
* *
* _([1, 2, 3]).toString(); * _([1, 2, 3]).toString();
@@ -3614,10 +3613,9 @@
* @memberOf _ * @memberOf _
* @category Collections * @category Collections
* @param {Array|Object|string} collection The collection to iterate over. * @param {Array|Object|string} collection The collection to iterate over.
* @param {...(number|number[]|string|string[])} [index] The indexes of `collection` * @param {...(number|number[]|string|string[])} [index] The indexes to retrieve,
* to retrieve, specified as individual indexes or arrays of indexes. * specified as individual indexes or arrays of indexes.
* @returns {Array} Returns a new array of elements corresponding to the * @returns {Array} Returns the array of picked elements.
* provided indexes.
* @example * @example
* *
* _.at(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]); * _.at(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]);
@@ -3824,7 +3822,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Array} Returns a new array of elements that passed the predicate check. * @returns {Array} Returns the new filtered array.
* @example * @example
* *
* var evens = _.filter([1, 2, 3, 4], function(num) { return num % 2 == 0; }); * var evens = _.filter([1, 2, 3, 4], function(num) { return num % 2 == 0; });
@@ -4108,18 +4106,18 @@
* @returns {Object} Returns the composed aggregate object. * @returns {Object} Returns the composed aggregate object.
* @example * @example
* *
* var keys = [ * var keyData = [
* { 'dir': 'left', 'code': 97 }, * { 'dir': 'left', 'code': 97 },
* { 'dir': 'right', 'code': 100 } * { 'dir': 'right', 'code': 100 }
* ]; * ];
* *
* _.indexBy(keys, 'dir'); * _.indexBy(keyData, 'dir');
* // => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } } * // => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }
* *
* _.indexBy(keys, function(key) { return String.fromCharCode(key.code); }); * _.indexBy(keyData, function(object) { return String.fromCharCode(object.code); });
* // => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } } * // => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }
* *
* _.indexBy(keys, function(key) { return this.fromCharCode(key.code); }, String); * _.indexBy(keyData, function(object) { return this.fromCharCode(object.code); }, String);
* // => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } } * // => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }
*/ */
var indexBy = createAggregator(function(result, value, key) { var indexBy = createAggregator(function(result, value, key) {
@@ -4139,7 +4137,7 @@
* @param {Function|string} methodName The name of the method to invoke or * @param {Function|string} methodName The name of the method to invoke or
* the function invoked per iteration. * the function invoked per iteration.
* @param {...*} [args] Arguments to invoke the method with. * @param {...*} [args] Arguments to invoke the method with.
* @returns {Array} Returns a new array of the results of each invoked method. * @returns {Array} Returns the array of results.
* @example * @example
* *
* _.invoke([[5, 1, 7], [3, 2, 1]], 'sort'); * _.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
@@ -4189,7 +4187,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Array} Returns a new array of the results of each `callback` execution. * @returns {Array} Returns the new mapped array.
* @example * @example
* *
* _.map([1, 2, 3], function(num) { return num * 3; }); * _.map([1, 2, 3], function(num) { return num * 3; });
@@ -4396,7 +4394,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Array} Returns a new array of grouped elements. * @returns {Array} Returns the array of grouped elements.
* @example * @example
* *
* _.partition([1, 2, 3], function(num) { return num % 2; }); * _.partition([1, 2, 3], function(num) { return num % 2; });
@@ -4432,7 +4430,7 @@
* @category Collections * @category Collections
* @param {Array|Object|string} collection The collection to iterate over. * @param {Array|Object|string} collection The collection to iterate over.
* @param {string} key The name of the property to pluck. * @param {string} key The name of the property to pluck.
* @returns {Array} Returns a new array of property values. * @returns {Array} Returns the property values.
* @example * @example
* *
* var characters = [ * var characters = [
@@ -4549,7 +4547,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Array} Returns a new array of elements that failed the predicate check. * @returns {Array} Returns the new filtered array.
* @example * @example
* *
* var odds = _.reject([1, 2, 3, 4], function(num) { return num % 2 == 0; }); * var odds = _.reject([1, 2, 3, 4], function(num) { return num % 2 == 0; });
@@ -4584,7 +4582,7 @@
* @param {Array|Object|string} collection The collection to sample. * @param {Array|Object|string} collection The collection to sample.
* @param {number} [n] The number of elements to sample. * @param {number} [n] The number of elements to sample.
* @param- {Object} [guard] Enables use as a callback for functions like `_.map`. * @param- {Object} [guard] Enables use as a callback for functions like `_.map`.
* @returns {*} Returns the random sample(s) of `collection`. * @returns {*} Returns the random sample(s).
* @example * @example
* *
* _.sample([1, 2, 3, 4]); * _.sample([1, 2, 3, 4]);
@@ -4616,7 +4614,7 @@
* @memberOf _ * @memberOf _
* @category Collections * @category Collections
* @param {Array|Object|string} collection The collection to shuffle. * @param {Array|Object|string} collection The collection to shuffle.
* @returns {Array} Returns a new shuffled collection. * @returns {Array} Returns the new shuffled array.
* @example * @example
* *
* _.shuffle([1, 2, 3, 4]); * _.shuffle([1, 2, 3, 4]);
@@ -4749,7 +4747,7 @@
* called per iteration. If a property name or object is provided it will * called per iteration. If a property name or object is provided it will
* be used to create a "_.pluck" or "_.where" style callback, respectively. * be used to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Array} Returns a new array of sorted elements. * @returns {Array} Returns the new sorted array.
* @example * @example
* *
* _.sortBy([1, 2, 3], function(num) { return Math.sin(num); }); * _.sortBy([1, 2, 3], function(num) { return Math.sin(num); });
@@ -4837,7 +4835,7 @@
* @category Collections * @category Collections
* @param {Array|Object|string} collection The collection to iterate over. * @param {Array|Object|string} collection The collection to iterate over.
* @param {Object} source The object of property values to filter by. * @param {Object} source The object of property values to filter by.
* @returns {Array} Returns a new array of elements that have the given properties. * @returns {Array} Returns the new filtered array.
* @example * @example
* *
* var characters = [ * var characters = [
@@ -4891,9 +4889,9 @@
} }
/** /**
* Creates a function that, when called, invokes `func` with the `this` * Creates a function that invokes `func` with the `this` binding of `thisArg`
* binding of `thisArg` and prepends any additional `bind` arguments to those * and prepends any additional `bind` arguments to those provided to the bound
* provided to the bound function. * function.
* *
* Note: Unlike native `Function#bind` this method does not set the `length` * Note: Unlike native `Function#bind` this method does not set the `length`
* property of bound functions. * property of bound functions.
@@ -4967,10 +4965,10 @@
} }
/** /**
* Creates a function that, when called, invokes the method at `object[key]` * Creates a function that invokes the method at `object[key]` and prepends
* and prepends any additional `bindKey` arguments to those provided to the bound * any additional `bindKey` arguments to those provided to the bound function.
* function. This method differs from `_.bind` by allowing bound functions to * This method differs from `_.bind` by allowing bound functions to reference
* reference methods that will be redefined or don't yet exist. * methods that will be redefined or don't yet exist.
* See [Peter Michaux's article](http://michaux.ca/articles/lazy-function-definition-pattern) * See [Peter Michaux's article](http://michaux.ca/articles/lazy-function-definition-pattern)
* for more details. * for more details.
* *
@@ -5373,9 +5371,9 @@
} }
/** /**
* Creates a function that, when called, invokes `func` with any additional * Creates a function that invokes `func` with any additional `partial` arguments
* `partial` arguments prepended to those provided to the new function. This * prepended to those provided to the new function. This method is similar to
* method is similar to `_.bind` except it does **not** alter the `this` binding. * `_.bind` except it does **not** alter the `this` binding.
* *
* Note: This method does not set the `length` property of partially applied * Note: This method does not set the `length` property of partially applied
* functions. * functions.
@@ -5902,15 +5900,12 @@
* this.y = 0; * this.y = 0;
* } * }
* *
* Shape.prototype.move = function(x, y) { * Shape.prototype.z = 0;
* this.x += x;
* this.y += y;
* };
* *
* _.forIn(new Shape, function(value, key) { * _.forIn(new Shape, function(value, key) {
* console.log(key); * console.log(key);
* }); * });
* // => logs 'x', 'y', and 'move' (property order is not guaranteed across environments) * // => logs 'x', 'y', and 'z' (property order is not guaranteed across environments)
*/ */
function forIn(object, callback, thisArg) { function forIn(object, callback, thisArg) {
callback = callback && typeof thisArg == 'undefined' ? callback : baseCreateCallback(callback, thisArg, 3); callback = callback && typeof thisArg == 'undefined' ? callback : baseCreateCallback(callback, thisArg, 3);
@@ -6027,7 +6022,7 @@
* @alias methods * @alias methods
* @category Objects * @category Objects
* @param {Object} object The object to inspect. * @param {Object} object The object to inspect.
* @returns {Array} Returns an array of property names that have function values. * @returns {Array} Returns the new sorted array of property names.
* @example * @example
* *
* _.functions(_); * _.functions(_);
@@ -6035,6 +6030,7 @@
*/ */
function functions(object) { function functions(object) {
var result = []; var result = [];
baseForIn(object, function(value, key) { baseForIn(object, function(value, key) {
if (isFunction(value)) { if (isFunction(value)) {
result.push(key); result.push(key);
@@ -6073,7 +6069,7 @@
* @category Objects * @category Objects
* @param {Object} object The object to invert. * @param {Object} object The object to invert.
* @param {boolean} [multiValue=false] Allow multiple values per key. * @param {boolean} [multiValue=false] Allow multiple values per key.
* @returns {Object} Returns the created inverted object. * @returns {Object} Returns the new inverted object.
* @example * @example
* *
* _.invert({ 'first': 'fred', 'second': 'barney' }); * _.invert({ 'first': 'fred', 'second': 'barney' });
@@ -6542,17 +6538,24 @@
} }
/** /**
* Creates an array composed of the own enumerable property names of `object`. * Creates an array of the own enumerable property names of `object`.
* *
* @static * @static
* @memberOf _ * @memberOf _
* @category Objects * @category Objects
* @param {Object} object The object to inspect. * @param {Object} object The object to inspect.
* @returns {Array} Returns an array of property names. * @returns {Array} Returns the array of property names.
* @example * @example
* *
* _.keys({ 'one': 1, 'two': 2, 'three': 3 }); * function Shape() {
* // => ['one', 'two', 'three'] (property order is not guaranteed across environments) * this.x = 0;
* this.y = 0;
* }
*
* Shape.prototype.z = 0;
*
* _.keys(new Shape);
* // => ['x', 'y'] (property order is not guaranteed across environments)
*/ */
var keys = !nativeKeys ? shimKeys : function(object) { var keys = !nativeKeys ? shimKeys : function(object) {
if (!isObject(object)) { if (!isObject(object)) {
@@ -6586,7 +6589,7 @@
* per iteration. If a property name or object is provided it will be used * per iteration. If a property name or object is provided it will be used
* to create a "_.pluck" or "_.where" style callback, respectively. * to create a "_.pluck" or "_.where" style callback, respectively.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Object} Returns a new object with values of the results of each `callback` execution. * @returns {Object} Returns the new mapped object.
* @example * @example
* *
* _.mapValues({ 'a': 1, 'b': 2, 'c': 3} , function(num) { return num * 3; }); * _.mapValues({ 'a': 1, 'b': 2, 'c': 3} , function(num) { return num * 3; });
@@ -6707,7 +6710,7 @@
* iteration or property names to omit, specified as individual property * iteration or property names to omit, specified as individual property
* names or arrays of property names. * names or arrays of property names.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Object} Returns an object without the omitted properties. * @returns {Object} Returns the new object.
* @example * @example
* *
* _.omit({ 'name': 'fred', 'age': 40 }, 'age'); * _.omit({ 'name': 'fred', 'age': 40 }, 'age');
@@ -6795,7 +6798,7 @@
* iteration or property names to pick, specified as individual property * iteration or property names to pick, specified as individual property
* names or arrays of property names. * names or arrays of property names.
* @param {*} [thisArg] The `this` binding of `predicate`. * @param {*} [thisArg] The `this` binding of `predicate`.
* @returns {Object} Returns an object composed of the picked properties. * @returns {Object} Returns the new object.
* @example * @example
* *
* _.pick({ 'name': 'fred', '_userid': 'fred1' }, 'name'); * _.pick({ 'name': 'fred', '_userid': 'fred1' }, 'name');
@@ -6890,11 +6893,18 @@
* @memberOf _ * @memberOf _
* @category Objects * @category Objects
* @param {Object} object The object to inspect. * @param {Object} object The object to inspect.
* @returns {Array} Returns an array of property values. * @returns {Array} Returns the new array of property values.
* @example * @example
* *
* _.values({ 'one': 1, 'two': 2, 'three': 3 }); * function Shape(x, y) {
* // => [1, 2, 3] (property order is not guaranteed across environments) * this.x = x;
* this.y = y;
* }
*
* Shape.prototype.z = 0;
*
* _.values(new Shape(2, 1));
* // => [2, 1] (property order is not guaranteed across environments)
*/ */
function values(object) { function values(object) {
var index = -1, var index = -1,
@@ -7271,7 +7281,7 @@
* @param {string} [options.sourceURL] The sourceURL of the template's compiled source. * @param {string} [options.sourceURL] The sourceURL of the template's compiled source.
* @param {string} [options.variable] The data object variable name. * @param {string} [options.variable] The data object variable name.
* @returns {Function|string} Returns the interpolated string if a data object * @returns {Function|string} Returns the interpolated string if a data object
* is provided, else it returns a template function. * is provided, else the compiled template function.
* @example * @example
* *
* // using the "interpolate" delimiter to create a compiled template * // using the "interpolate" delimiter to create a compiled template
@@ -7635,7 +7645,7 @@
} }
/** /**
* Produces a callback bound to an optional `thisArg`. If `func` is a property * Creates a function bound to an optional `thisArg`. If `func` is a property
* name the created callback will return the property value for a given element. * name the created callback will return the property value for a given element.
* If `func` is an object the created callback will return `true` for elements * If `func` is an object the created callback will return `true` for elements
* that contain the equivalent object properties, otherwise it will return `false`. * that contain the equivalent object properties, otherwise it will return `false`.
@@ -7647,7 +7657,7 @@
* @param {*} [func=identity] The value to convert to a callback. * @param {*} [func=identity] The value to convert to a callback.
* @param {*} [thisArg] The `this` binding of the created callback. * @param {*} [thisArg] The `this` binding of the created callback.
* @param {number} [argCount] The number of arguments the callback accepts. * @param {number} [argCount] The number of arguments the callback accepts.
* @returns {Function} Returns a callback function. * @returns {Function} Returns the new function.
* @example * @example
* *
* var characters = [ * var characters = [
@@ -7896,7 +7906,7 @@
* @category Utilities * @category Utilities
* @param {string} value The value to parse. * @param {string} value The value to parse.
* @param {number} [radix] The radix used to interpret the value to parse. * @param {number} [radix] The radix used to interpret the value to parse.
* @returns {number} Returns the new integer value. * @returns {number} Returns the converted integer value.
* @example * @example
* *
* _.parseInt('08'); * _.parseInt('08');
@@ -7952,7 +7962,7 @@
* @param {number} [min=0] The minimum possible value. * @param {number} [min=0] The minimum possible value.
* @param {number} [max=1] The maximum possible value. * @param {number} [max=1] The maximum possible value.
* @param {boolean} [floating=false] Specify returning a floating-point number. * @param {boolean} [floating=false] Specify returning a floating-point number.
* @returns {number} Returns a random number. * @returns {number} Returns the random number.
* @example * @example
* *
* _.random(0, 5); * _.random(0, 5);
@@ -8051,7 +8061,7 @@
* @param {number} n The number of times to execute the callback. * @param {number} n The number of times to execute the callback.
* @param {Function} [callback=identity] The function called per iteration. * @param {Function} [callback=identity] The function called per iteration.
* @param {*} [thisArg] The `this` binding of `callback`. * @param {*} [thisArg] The `this` binding of `callback`.
* @returns {Array} Returns an array of the results of each `callback` execution. * @returns {Array} Returns the array of results.
* @example * @example
* *
* var diceRolls = _.times(3, _.partial(_.random, 1, 6)); * var diceRolls = _.times(3, _.partial(_.random, 1, 6));