From 16ad7e53ff7cfb169b1eb97eed055b22bf594d0a Mon Sep 17 00:00:00 2001 From: John-David Dalton Date: Thu, 22 Jan 2015 00:37:55 -0800 Subject: [PATCH] Update docs. [ci skip] --- doc/README.md | 6641 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 6640 insertions(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index f993a71e7..65ed048c3 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1 +1,6640 @@ -# Lo-Dash v3.0.0-pre +# lodash v3.0.0 + + + + + +## `Array` +* `_.chunk` +* `_.compact` +* `_.difference` +* `_.drop` +* `_.dropRight` +* `_.dropRightWhile` +* `_.dropWhile` +* `_.findIndex` +* `_.findLastIndex` +* `_.first` +* `_.flatten` +* `_.flattenDeep` +* `_.head` -> `first` +* `_.indexOf` +* `_.initial` +* `_.intersection` +* `_.last` +* `_.lastIndexOf` +* `_.object` -> `zipObject` +* `_.pull` +* `_.pullAt` +* `_.remove` +* `_.rest` +* `_.slice` +* `_.sortedIndex` +* `_.sortedLastIndex` +* `_.tail` -> `rest` +* `_.take` +* `_.takeRight` +* `_.takeRightWhile` +* `_.takeWhile` +* `_.union` +* `_.uniq` +* `_.unique` -> `uniq` +* `_.unzip` +* `_.without` +* `_.xor` +* `_.zip` +* `_.zipObject` + + + + + +## `Chain` +* `_` +* `_.chain` +* `_.tap` +* `_.thru` +* `_.prototype.chain` +* `_.prototype.reverse` +* `_.prototype.toJSON` -> `value` +* `_.prototype.toString` +* `_.prototype.value` +* `_.prototype.valueOf` -> `value` + + + + + +## `Collection` +* `_.all` -> `every` +* `_.any` -> `some` +* `_.at` +* `_.collect` -> `map` +* `_.contains` -> `includes` +* `_.countBy` +* `_.detect` -> `find` +* `_.each` -> `forEach` +* `_.eachRight` -> `forEachRight` +* `_.every` +* `_.filter` +* `_.find` +* `_.findLast` +* `_.findWhere` +* `_.foldl` -> `reduce` +* `_.foldr` -> `reduceRight` +* `_.forEach` +* `_.forEachRight` +* `_.groupBy` +* `_.include` -> `includes` +* `_.includes` +* `_.indexBy` +* `_.inject` -> `reduce` +* `_.invoke` +* `_.map` +* `_.max` +* `_.min` +* `_.partition` +* `_.pluck` +* `_.reduce` +* `_.reduceRight` +* `_.reject` +* `_.sample` +* `_.select` -> `filter` +* `_.shuffle` +* `_.size` +* `_.some` +* `_.sortBy` +* `_.sortByAll` +* `_.where` + + + + + +## `Date` +* `_.now` + + + + + +## `Function` +* `_.after` +* `_.ary` +* `_.backflow` -> `flowRight` +* `_.before` +* `_.bind` +* `_.bindAll` +* `_.bindKey` +* `_.compose` -> `flowRight` +* `_.curry` +* `_.curryRight` +* `_.debounce` +* `_.defer` +* `_.delay` +* `_.flow` +* `_.flowRight` +* `_.memoize` +* `_.negate` +* `_.once` +* `_.partial` +* `_.partialRight` +* `_.rearg` +* `_.throttle` +* `_.wrap` + + + + + +## `Lang` +* `_.clone` +* `_.cloneDeep` +* `_.isArguments` +* `_.isArray` +* `_.isBoolean` +* `_.isDate` +* `_.isElement` +* `_.isEmpty` +* `_.isEqual` +* `_.isError` +* `_.isFinite` +* `_.isFunction` +* `_.isMatch` +* `_.isNaN` +* `_.isNative` +* `_.isNull` +* `_.isNumber` +* `_.isObject` +* `_.isPlainObject` +* `_.isRegExp` +* `_.isString` +* `_.isTypedArray` +* `_.isUndefined` +* `_.toArray` +* `_.toPlainObject` + + + + + +## `Number` +* `_.random` + + + + + +## `Object` +* `_.assign` +* `_.create` +* `_.defaults` +* `_.extend` -> `assign` +* `_.findKey` +* `_.findLastKey` +* `_.forIn` +* `_.forInRight` +* `_.forOwn` +* `_.forOwnRight` +* `_.functions` +* `_.has` +* `_.invert` +* `_.keys` +* `_.keysIn` +* `_.mapValues` +* `_.merge` +* `_.methods` -> `functions` +* `_.omit` +* `_.pairs` +* `_.pick` +* `_.result` +* `_.transform` +* `_.values` +* `_.valuesIn` + + + + + +## `String` +* `_.camelCase` +* `_.capitalize` +* `_.deburr` +* `_.endsWith` +* `_.escape` +* `_.escapeRegExp` +* `_.kebabCase` +* `_.pad` +* `_.padLeft` +* `_.padRight` +* `_.parseInt` +* `_.repeat` +* `_.snakeCase` +* `_.startsWith` +* `_.template` +* `_.trim` +* `_.trimLeft` +* `_.trimRight` +* `_.trunc` +* `_.unescape` +* `_.words` + + + + + +## `Utility` +* `_.attempt` +* `_.callback` +* `_.constant` +* `_.identity` +* `_.iteratee` -> `callback` +* `_.matches` +* `_.mixin` +* `_.noConflict` +* `_.noop` +* `_.property` +* `_.propertyOf` +* `_.range` +* `_.runInContext` +* `_.times` +* `_.uniqueId` + + + + + +## `Methods` +* `_.templateSettings.imports._` + + + + + +## `Properties` +* `_.VERSION` +* `_.support` +* `_.support.argsTag` +* `_.support.enumErrorProps` +* `_.support.enumPrototypes` +* `_.support.funcDecomp` +* `_.support.funcNames` +* `_.support.nodeTag` +* `_.support.nonEnumShadows` +* `_.support.nonEnumStrings` +* `_.support.ownLast` +* `_.support.spliceObjects` +* `_.support.unindexedChars` +* `_.templateSettings` +* `_.templateSettings.escape` +* `_.templateSettings.evaluate` +* `_.templateSettings.imports` +* `_.templateSettings.interpolate` +* `_.templateSettings.variable` + + + + + + + + + +## `“Array” Methods` + + + +### `_.chunk(array, [size=1])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4096 "View in source") [Ⓣ][1] + +Creates an array of elements split into groups the length of `size`. +If `collection` can't be split evenly, the final chunk will be the remaining +elements. + +#### Arguments +1. `array` *(Array)*: The array to process. +2. `[size=1]` *(numer)*: The length of each chunk. + +#### Returns +*(Array)*: Returns the new array containing chunks. + +#### Example +```js +_.chunk(['a', 'b', 'c', 'd'], 2); +// => [['a', 'b'], ['c', 'd']] + +_.chunk(['a', 'b', 'c', 'd'], 3); +// => [['a', 'b', 'c'], ['d']] +``` +* * * + + + + + +### `_.compact(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4127 "View in source") [Ⓣ][1] + +Creates an array with all falsey values removed. The values `false`, `null`, +`0`, `""`, `undefined`, and `NaN` are falsey. + +#### Arguments +1. `array` *(Array)*: The array to compact. + +#### Returns +*(Array)*: Returns the new array of filtered values. + +#### Example +```js +_.compact([0, 1, false, 2, '', 3]); +// => [1, 2, 3] +``` +* * * + + + + + +### `_.difference(array, [values])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4162 "View in source") [Ⓣ][1] + +Creates an array excluding all values of the provided arrays using +`SameValueZero` for equality comparisons. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `array` *(Array)*: The array to inspect. +2. `[values]` *(...Array)*: The arrays of values to exclude. + +#### Returns +*(Array)*: Returns the new array of filtered values. + +#### Example +```js +_.difference([1, 2, 3], [5, 2, 10]); +// => [1, 3] +``` +* * * + + + + + +### `_.drop(array, [n=1])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4200 "View in source") [Ⓣ][1] + +Creates a slice of `array` with `n` elements dropped from the beginning. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[n=1]` *(number)*: The number of elements to drop. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.drop([1, 2, 3]); +// => [2, 3] + +_.drop([1, 2, 3], 2); +// => [3] + +_.drop([1, 2, 3], 5); +// => [] + +_.drop([1, 2, 3], 0); +// => [1, 2, 3] +``` +* * * + + + + + +### `_.dropRight(array, [n=1])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4236 "View in source") [Ⓣ][1] + +Creates a slice of `array` with `n` elements dropped from the end. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[n=1]` *(number)*: The number of elements to drop. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.dropRight([1, 2, 3]); +// => [1, 2] + +_.dropRight([1, 2, 3], 2); +// => [1] + +_.dropRight([1, 2, 3], 5); +// => [] + +_.dropRight([1, 2, 3], 0); +// => [1, 2, 3] +``` +* * * + + + + + +### `_.dropRightWhile(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4288 "View in source") [Ⓣ][1] + +Creates a slice of `array` excluding elements dropped from the end. +Elements are dropped until `predicate` returns falsey. The predicate is +bound to `thisArg` and invoked with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per element. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.dropRightWhile([1, 2, 3], function(n) { return n > 1; }); +// => [1] + +var users = [ + { 'user': 'barney', 'status': 'busy', 'active': false }, + { 'user': 'fred', 'status': 'busy', 'active': true }, + { 'user': 'pebbles', 'status': 'away', 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.dropRightWhile(users, 'active'), 'user'); +// => ['barney'] + +// using the "_.matches" callback shorthand +_.pluck(_.dropRightWhile(users, { 'status': 'away' }), 'user'); +// => ['barney', 'fred'] +``` +* * * + + + + + +### `_.dropWhile(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4338 "View in source") [Ⓣ][1] + +Creates a slice of `array` excluding elements dropped from the beginning. +Elements are dropped until `predicate` returns falsey. The predicate is +bound to `thisArg` and invoked with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per element. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.dropWhile([1, 2, 3], function(n) { return n < 3; }); +// => [3] + +var users = [ + { 'user': 'barney', 'status': 'busy', 'active': true }, + { 'user': 'fred', 'status': 'busy', 'active': false }, + { 'user': 'pebbles', 'status': 'away', 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.dropWhile(users, 'active'), 'user'); +// => ['fred', 'pebbles'] + +// using the "_.matches" callback shorthand +_.pluck(_.dropWhile(users, { 'status': 'busy' }), 'user'); +// => ['pebbles'] +``` +* * * + + + + + +### `_.findIndex(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4388 "View in source") [Ⓣ][1] + +This method is like `_.find` except that it returns the index of the first +element `predicate` returns truthy for, instead of the element itself. + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(number)*: Returns the index of the found element, else `-1`. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true }, + { 'user': 'pebbles', 'age': 1, 'active': false } +]; + +_.findIndex(users, function(chr) { return chr.age < 40; }); +// => 0 + +// using the "_.matches" callback shorthand +_.findIndex(users, { 'age': 1 }); +// => 2 + +// using the "_.property" callback shorthand +_.findIndex(users, 'active'); +// => 1 +``` +* * * + + + + + +### `_.findLastIndex(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4440 "View in source") [Ⓣ][1] + +This method is like `_.findIndex` except that it iterates over elements +of `collection` from right to left. + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(number)*: Returns the index of the found element, else `-1`. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36, 'active': true }, + { 'user': 'fred', 'age': 40, 'active': false }, + { 'user': 'pebbles', 'age': 1, 'active': false } +]; + +_.findLastIndex(users, function(chr) { return chr.age < 40; }); +// => 2 + +// using the "_.matches" callback shorthand +_.findLastIndex(users, { 'age': 40 }); +// => 1 + +// using the "_.property" callback shorthand +_.findLastIndex(users, 'active'); +// => 0 +``` +* * * + + + + + +### `_.first(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4468 "View in source") [Ⓣ][1] + +Gets the first element of `array`. + +#### Arguments +1. `array` *(Array)*: The array to query. + +#### Returns +*(*)*: Returns the first element of `array`. + +#### Example +```js +_.first([1, 2, 3]); +// => 1 + +_.first([]); +// => undefined +``` +* * * + + + + + +### `_.flatten(array, [isDeep])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4492 "View in source") [Ⓣ][1] + +Flattens a nested array. If `isDeep` is `true` the array is recursively +flattened, otherwise it is only flattened a single level. + +#### Arguments +1. `array` *(Array)*: The array to flatten. +2. `[isDeep]` *(boolean)*: Specify a deep flatten. + +#### Returns +*(Array)*: Returns the new flattened array. + +#### Example +```js +_.flatten([1, [2], [3, [[4]]]]); +// => [1, 2, 3, [[4]]]; + +// using `isDeep` +_.flatten([1, [2], [3, [[4]]]], true); +// => [1, 2, 3, 4]; +``` +* * * + + + + + +### `_.flattenDeep(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4513 "View in source") [Ⓣ][1] + +Recursively flattens a nested array. + +#### Arguments +1. `array` *(Array)*: The array to recursively flatten. + +#### Returns +*(Array)*: Returns the new flattened array. + +#### Example +```js +_.flattenDeep([1, [2], [3, [[4]]]]); +// => [1, 2, 3, 4]; +``` +* * * + + + + + +### `_.indexOf(array, value, [fromIndex=0])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4550 "View in source") [Ⓣ][1] + +Gets the index at which the first occurrence of `value` is found in `array` +using `SameValueZero` for equality comparisons. If `fromIndex` is negative, +it is used as the offset from the end of `array`. If `array` is sorted +providing `true` for `fromIndex` performs a faster binary search. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `array` *(Array)*: The array to search. +2. `value` *(*)*: The value to search for. +3. `[fromIndex=0]` *(boolean|number)*: The index to search from or `true` to perform a binary search on a sorted array. + +#### Returns +*(number)*: Returns the index of the matched value, else `-1`. + +#### Example +```js +_.indexOf([1, 2, 3, 1, 2, 3], 2); +// => 1 + +// using `fromIndex` +_.indexOf([1, 2, 3, 1, 2, 3], 2, 3); +// => 4 + +// performing a binary search +_.indexOf([4, 4, 5, 5, 6, 6], 5, true); +// => 2 +``` +* * * + + + + + +### `_.initial(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4579 "View in source") [Ⓣ][1] + +Gets all but the last element of `array`. + +#### Arguments +1. `array` *(Array)*: The array to query. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.initial([1, 2, 3]); +// => [1, 2] +``` +* * * + + + + + +### `_.intersection([arrays])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4602 "View in source") [Ⓣ][1] + +Creates an array of unique values in all provided arrays using `SameValueZero` +for equality comparisons. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `[arrays]` *(...Array)*: The arrays to inspect. + +#### Returns +*(Array)*: Returns the new array of shared values. + +#### Example +```js +_.intersection([1, 2, 3], [5, 2, 1, 4], [2, 1]); +// => [1, 2] +``` +* * * + + + + + +### `_.last(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4657 "View in source") [Ⓣ][1] + +Gets the last element of `array`. + +#### Arguments +1. `array` *(Array)*: The array to query. + +#### Returns +*(*)*: Returns the last element of `array`. + +#### Example +```js +_.last([1, 2, 3]); +// => 3 +``` +* * * + + + + + +### `_.lastIndexOf(array, value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4687 "View in source") [Ⓣ][1] + +This method is like `_.indexOf` except that it iterates over elements of +`array` from right to left. + +#### Arguments +1. `array` *(Array)*: The array to search. +2. `value` *(*)*: The value to search for. +3. `[fromIndex=array.length-1]` *(boolean|number)*: The index to search from or `true` to perform a binary search on a sorted array. + +#### Returns +*(number)*: Returns the index of the matched value, else `-1`. + +#### Example +```js +_.lastIndexOf([1, 2, 3, 1, 2, 3], 2); +// => 4 + +// using `fromIndex` +_.lastIndexOf([1, 2, 3, 1, 2, 3], 2, 3); +// => 1 + +// performing a binary search +_.lastIndexOf([4, 4, 5, 5, 6, 6], 5, true); +// => 3 +``` +* * * + + + + + +### `_.pull(array, [values])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4734 "View in source") [Ⓣ][1] + +Removes all provided values from `array` using `SameValueZero` for equality +comparisons. + *Notes:** +- Unlike `_.without`, this method mutates `array`. +- `SameValueZero` comparisons are like strict equality comparisons, e.g. `===`, +except that `NaN` matches `NaN`. See the [ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `array` *(Array)*: The array to modify. +2. `[values]` *(...*)*: The values to remove. + +#### Returns +*(Array)*: Returns `array`. + +#### Example +```js +var array = [1, 2, 3, 1, 2, 3]; +_.pull(array, 2, 3); +console.log(array); +// => [1, 1] +``` +* * * + + + + + +### `_.pullAt(array, [indexes])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4779 "View in source") [Ⓣ][1] + +Removes elements from `array` corresponding to the given indexes and returns +an array of the removed elements. Indexes may be specified as an array of +indexes or as individual arguments. + *Note:** Unlike `_.at`, this method mutates `array`. + +#### Arguments +1. `array` *(Array)*: The array to modify. +2. `[indexes]` *(...(number|number[])*: The indexes of elements to remove, specified as individual indexes or arrays of indexes. + +#### Returns +*(Array)*: Returns the new array of removed elements. + +#### Example +```js +var array = [5, 10, 15, 20]; +var evens = _.pullAt(array, [1, 3]); + +console.log(array); +// => [5, 15] + +console.log(evens); +// => [10, 20] +``` +* * * + + + + + +### `_.remove(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4817 "View in source") [Ⓣ][1] + +Removes all elements from `array` that `predicate` returns truthy for +and returns an array of the removed elements. The predicate is bound to +`thisArg` and invoked with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + *Note:** Unlike `_.filter`, this method mutates `array`. + +#### Arguments +1. `array` *(Array)*: The array to modify. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the new array of removed elements. + +#### Example +```js +var array = [1, 2, 3, 4]; +var evens = _.remove(array, function(n) { return n % 2 == 0; }); + +console.log(array); +// => [1, 3] + +console.log(evens); +// => [2, 4] +``` +* * * + + + + + +### `_.rest(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4848 "View in source") [Ⓣ][1] + +Gets all but the first element of `array`. + +#### Arguments +1. `array` *(Array)*: The array to query. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.rest([1, 2, 3]); +// => [2, 3] +``` +* * * + + + + + +### `_.slice(array, [start=0])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4866 "View in source") [Ⓣ][1] + +Creates a slice of `array` from `start` up to, but not including, `end`. + *Note:** This function is used instead of `Array#slice` to support node +lists in IE < 9 and to ensure dense arrays are returned. + +#### Arguments +1. `array` *(Array)*: The array to slice. +2. `[start=0]` *(number)*: The start position. +3. `[end=array.length]` *(number)*: The end position. + +#### Returns +*(Array)*: Returns the slice of `array`. + +* * * + + + + + +### `_.sortedIndex(array, value, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4923 "View in source") [Ⓣ][1] + +Uses a binary search to determine the lowest index at which `value` should +be inserted into `array` in order to maintain its sort order. If an iteratee +function is provided it is invoked for `value` and each element of `array` +to compute their sort ranking. The iteratee is bound to `thisArg` and +invoked with one argument; (value). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The sorted array to inspect. +2. `value` *(*)*: The value to evaluate. +3. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(number)*: Returns the index at which `value` should be inserted +into `array`. + +#### Example +```js +_.sortedIndex([30, 50], 40); +// => 1 + +_.sortedIndex([4, 4, 5, 5, 6, 6], 5); +// => 2 + +var dict = { 'data': { 'thirty': 30, 'forty': 40, 'fifty': 50 } }; + +// using an iteratee function +_.sortedIndex(['thirty', 'fifty'], 'forty', function(word) { + return this.data[word]; +}, dict); +// => 1 + +// using the "_.property" callback shorthand +_.sortedIndex([{ 'x': 30 }, { 'x': 50 }], { 'x': 40 }, 'x'); +// => 1 +``` +* * * + + + + + +### `_.sortedLastIndex(array, value, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4951 "View in source") [Ⓣ][1] + +This method is like `_.sortedIndex` except that it returns the highest +index at which `value` should be inserted into `array` in order to +maintain its sort order. + +#### Arguments +1. `array` *(Array)*: The sorted array to inspect. +2. `value` *(*)*: The value to evaluate. +3. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(number)*: Returns the index at which `value` should be inserted +into `array`. + +#### Example +```js +_.sortedLastIndex([4, 4, 5, 5, 6, 6], 5); +// => 4 +``` +* * * + + + + + +### `_.take(array, [n=1])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L4983 "View in source") [Ⓣ][1] + +Creates a slice of `array` with `n` elements taken from the beginning. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[n=1]` *(number)*: The number of elements to take. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.take([1, 2, 3]); +// => [1] + +_.take([1, 2, 3], 2); +// => [1, 2] + +_.take([1, 2, 3], 5); +// => [1, 2, 3] + +_.take([1, 2, 3], 0); +// => [] +``` +* * * + + + + + +### `_.takeRight(array, [n=1])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5019 "View in source") [Ⓣ][1] + +Creates a slice of `array` with `n` elements taken from the end. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[n=1]` *(number)*: The number of elements to take. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.takeRight([1, 2, 3]); +// => [3] + +_.takeRight([1, 2, 3], 2); +// => [2, 3] + +_.takeRight([1, 2, 3], 5); +// => [1, 2, 3] + +_.takeRight([1, 2, 3], 0); +// => [] +``` +* * * + + + + + +### `_.takeRightWhile(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5071 "View in source") [Ⓣ][1] + +Creates a slice of `array` with elements taken from the end. Elements are +taken until `predicate` returns falsey. The predicate is bound to `thisArg` +and invoked with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per element. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.takeRightWhile([1, 2, 3], function(n) { return n > 1; }); +// => [2, 3] + +var users = [ + { 'user': 'barney', 'status': 'busy', 'active': false }, + { 'user': 'fred', 'status': 'busy', 'active': true }, + { 'user': 'pebbles', 'status': 'away', 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.takeRightWhile(users, 'active'), 'user'); +// => ['fred', 'pebbles'] + +// using the "_.matches" callback shorthand +_.pluck(_.takeRightWhile(users, { 'status': 'away' }), 'user'); +// => ['pebbles'] +``` +* * * + + + + + +### `_.takeWhile(array, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5121 "View in source") [Ⓣ][1] + +Creates a slice of `array` with elements taken from the beginning. Elements +are taken until `predicate` returns falsey. The predicate is bound to +`thisArg` and invoked with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `array` *(Array)*: The array to query. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per element. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the slice of `array`. + +#### Example +```js +_.takeWhile([1, 2, 3], function(n) { return n < 3; }); +// => [1, 2] + +var users = [ + { 'user': 'barney', 'status': 'busy', 'active': true }, + { 'user': 'fred', 'status': 'busy', 'active': false }, + { 'user': 'pebbles', 'status': 'away', 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.takeWhile(users, 'active'), 'user'); +// => ['barney'] + +// using the "_.matches" callback shorthand +_.pluck(_.takeWhile(users, { 'status': 'busy' }), 'user'); +// => ['barney', 'fred'] +``` +* * * + + + + + +### `_.union([arrays])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5151 "View in source") [Ⓣ][1] + +Creates an array of unique values, in order, of the provided arrays using +`SameValueZero` for equality comparisons. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `[arrays]` *(...Array)*: The arrays to inspect. + +#### Returns +*(Array)*: Returns the new array of combined values. + +#### Example +```js +_.union([1, 2, 3], [5, 2, 1, 4], [2, 1]); +// => [1, 2, 3, 5, 4] +``` +* * * + + + + + +### `_.uniq(array, [isSorted], [iteratee], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5203 "View in source") [Ⓣ][1] + +Creates a duplicate-value-free version of an array using `SameValueZero` +for equality comparisons. Providing `true` for `isSorted` performs a faster +search algorithm for sorted arrays. If an iteratee function is provided it +is invoked for each value in the array to generate the criterion by which +uniqueness is computed. The `iteratee` is bound to `thisArg` and invoked +with three arguments; (value, index, array). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `array` *(Array)*: The array to inspect. +2. `[isSorted]` *(boolean)*: Specify the array is sorted. +3. `[iteratee]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Array)*: Returns the new duplicate-value-free array. + +#### Example +```js +_.uniq([1, 2, 1]); +// => [1, 2] + +// using `isSorted` +_.uniq([1, 1, 2], true); +// => [1, 2] + +// using an iteratee function +_.uniq([1, 2.5, 1.5, 2], function(n) { return this.floor(n); }, Math); +// => [1, 2.5] + +// using the "_.property" callback shorthand +_.uniq([{ 'x': 1 }, { 'x': 2 }, { 'x': 1 }], 'x'); +// => [{ 'x': 1 }, { 'x': 2 }] +``` +* * * + + + + + +### `_.unzip(array)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5241 "View in source") [Ⓣ][1] + +This method is like `_.zip` except that it accepts an array of grouped +elements and creates an array regrouping the elements to their pre-`_.zip` +configuration. + +#### Arguments +1. `array` *(Array)*: The array of grouped elements to process. + +#### Returns +*(Array)*: Returns the new array of regrouped elements. + +#### Example +```js +var zipped = _.zip(['fred', 'barney'], [30, 40], [true, false]); +// => [['fred', 30, true], ['barney', 40, false]] + +_.unzip(zipped); +// => [['fred', 'barney'], [30, 40], [true, false]] +``` +* * * + + + + + +### `_.without(array, [values])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5272 "View in source") [Ⓣ][1] + +Creates an array excluding all provided values using `SameValueZero` for +equality comparisons. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `array` *(Array)*: The array to filter. +2. `[values]` *(...*)*: The values to exclude. + +#### Returns +*(Array)*: Returns the new array of filtered values. + +#### Example +```js +_.without([1, 2, 1, 0, 3, 1, 4], 0, 1); +// => [2, 3, 4] +``` +* * * + + + + + +### `_.xor([arrays])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5294 "View in source") [Ⓣ][1] + +Creates an array that is the symmetric difference of the provided arrays. +See [Wikipedia](https://en.wikipedia.org/wiki/Symmetric_difference) for +more details. + +#### Arguments +1. `[arrays]` *(...Array)*: The arrays to inspect. + +#### Returns +*(Array)*: Returns the new array of values. + +#### Example +```js +_.xor([1, 2, 3], [5, 2, 1, 4]); +// => [3, 5, 4] + +_.xor([1, 2, 5], [2, 3, 5], [3, 4, 5]); +// => [1, 4, 5] +``` +* * * + + + + + +### `_.zip([arrays])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5324 "View in source") [Ⓣ][1] + +Creates an array of grouped elements, the first of which contains the first +elements of the given arrays, the second of which contains the second elements +of the given arrays, and so on. + +#### Arguments +1. `[arrays]` *(...Array)*: The arrays to process. + +#### Returns +*(Array)*: Returns the new array of grouped elements. + +#### Example +```js +_.zip(['fred', 'barney'], [30, 40], [true, false]); +// => [['fred', 30, true], ['barney', 40, false]] +``` +* * * + + + + + +### `_.zipObject(props, [values=[]])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5351 "View in source") [Ⓣ][1] + +Creates an object composed from arrays of property names and values. Provide +either a single two dimensional array, e.g. `[[key1, value1], [key2, value2]]` +or two arrays, one of property names and one of corresponding values. + +#### Arguments +1. `props` *(Array)*: The property names. +2. `[values=[]]` *(Array)*: The property values. + +#### Returns +*(Object)*: Returns the new object. + +#### Example +```js +_.zipObject(['fred', 'barney'], [30, 40]); +// => { 'fred': 30, 'barney': 40 } +``` +* * * + + + + + + + +## `“Chain” Methods` + + + +### `._(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L919 "View in source") [Ⓣ][1] + +Creates a `lodash` object which wraps `value` to enable intuitive chaining. +Methods that operate on and return arrays, collections, and functions can +be chained together. Methods that return a boolean or single value will +automatically end the chain returning the unwrapped value. Explicit chaining +may be enabled using `_.chain`. The execution of chained methods is lazy, +that is, execution is deferred until `_#value` is implicitly or explicitly +called. + +Lazy evaluation allows several methods to support shortcut fusion. Shortcut +fusion is an optimization that merges iteratees to avoid creating intermediate +arrays and reduce the number of iteratee executions. + +Chaining is supported in custom builds as long as the `_#value` method is +directly or indirectly included in the build. + +In addition to lodash methods, wrappers also have the following `Array` methods: +`concat`, `join`, `pop`, `push`, `reverse`, `shift`, `slice`, `sort`, `splice`, +and `unshift` + +The wrapper functions that support shortcut fusion are: +`drop`, `dropRight`, `dropRightWhile`, `dropWhile`, `filter`, `first`, +`initial`, `last`, `map`, `pluck`, `reject`, `rest`, `reverse`, `slice`, +`take`, `takeRight`, `takeRightWhile`, `takeWhile`, and `where` + +The chainable wrapper functions are: +`after`, `ary`, `assign`, `at`, `before`, `bind`, `bindAll`, `bindKey`, +`callback`, `chain`, `chunk`, `compact`, `concat`, `constant`, `countBy`, +`create`, `curry`, `debounce`, `defaults`, `defer`, `delay`, `difference`, +`drop`, `dropRight`, `dropRightWhile`, `dropWhile`, `filter`, `flatten`, +`flattenDeep`, `flow`, `flowRight`, `forEach`, `forEachRight`, `forIn`, +`forInRight`, `forOwn`, `forOwnRight`, `functions`, `groupBy`, `indexBy`, +`initial`, `intersection`, `invert`, `invoke`, `keys`, `keysIn`, `map`, +`mapValues`, `matches`, `memoize`, `merge`, `mixin`, `negate`, `noop`, +`omit`, `once`, `pairs`, `partial`, `partialRight`, `partition`, `pick`, +`pluck`, `property`, `propertyOf`, `pull`, `pullAt`, `push`, `range`, +`rearg`, `reject`, `remove`, `rest`, `reverse`, `shuffle`, `slice`, `sort`, +`sortBy`, `sortByAll`, `splice`, `take`, `takeRight`, `takeRightWhile`, +`takeWhile`, `tap`, `throttle`, `thru`, `times`, `toArray`, `toPlainObject`, +`transform`, `union`, `uniq`, `unshift`, `unzip`, `values`, `valuesIn`, +`where`, `without`, `wrap`, `xor`, `zip`, and `zipObject` + +The wrapper functions that are **not** chainable by default are: +`attempt`, `camelCase`, `capitalize`, `clone`, `cloneDeep`, `deburr`, +`endsWith`, `escape`, `escapeRegExp`, `every`, `find`, `findIndex`, `findKey`, +`findLast`, `findLastIndex`, `findLastKey`, `findWhere`, `first`, `has`, +`identity`, `includes`, `indexOf`, `isArguments`, `isArray`, `isBoolean`, +`isDate`, `isElement`, `isEmpty`, `isEqual`, `isError`, `isFinite`, +`isFunction`, `isMatch` , `isNative`, `isNaN`, `isNull`, `isNumber`, +`isObject`, `isPlainObject`, `isRegExp`, `isString`, `isUndefined`, +`isTypedArray`, `join`, `kebabCase`, `last`, `lastIndexOf`, `max`, `min`, +`noConflict`, `now`, `pad`, `padLeft`, `padRight`, `parseInt`, `pop`, +`random`, `reduce`, `reduceRight`, `repeat`, `result`, `runInContext`, +`shift`, `size`, `snakeCase`, `some`, `sortedIndex`, `sortedLastIndex`, +`startsWith`, `template`, `trim`, `trimLeft`, `trimRight`, `trunc`, +`unescape`, `uniqueId`, `value`, and `words` + +The wrapper function `sample` will return a wrapped value when `n` is provided, +otherwise an unwrapped value is returned. + +#### Arguments +1. `value` *(*)*: The value to wrap in a `lodash` instance. + +#### Returns +*(Object)*: Returns a `lodash` instance. + +#### Example +```js +var wrapped = _([1, 2, 3]); + +// returns an unwrapped value +wrapped.reduce(function(sum, n) { return sum + n; }); +// => 6 + +// returns a wrapped value +var squares = wrapped.map(function(n) { return n * n; }); + +_.isArray(squares); +// => false + +_.isArray(squares.value()); +// => true +``` +* * * + + + + + +### `_.chain(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5396 "View in source") [Ⓣ][1] + +Creates a `lodash` object that wraps `value` with explicit method +chaining enabled. + +#### Arguments +1. `value` *(*)*: The value to wrap. + +#### Returns +*(Object)*: Returns the new `lodash` object. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 }, + { 'user': 'pebbles', 'age': 1 } +]; + +var youngest = _.chain(users) + .sortBy('age') + .map(function(chr) { return chr.user + ' is ' + chr.age; }) + .first() + .value(); +// => 'pebbles is 1' +``` +* * * + + + + + +### `_.tap(value, interceptor, [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5423 "View in source") [Ⓣ][1] + +This method invokes `interceptor` and returns `value`. The interceptor is +bound to `thisArg` and invoked with one argument; (value). The purpose of +this method is to "tap into" a method chain in order to perform operations +on intermediate results within the chain. + +#### Arguments +1. `value` *(*)*: The value to provide to `interceptor`. +2. `interceptor` *(Function)*: The function to invoke. +3. `[thisArg]` *(*)*: The `this` binding of `interceptor`. + +#### Returns +*(*)*: Returns `value`. + +#### Example +```js +_([1, 2, 3]) + .tap(function(array) { array.pop(); }) + .reverse() + .value(); +// => [2, 1] +``` +* * * + + + + + +### `_.thru(value, interceptor, [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5446 "View in source") [Ⓣ][1] + +This method is like `_.tap` except that it returns the result of `interceptor`. + +#### Arguments +1. `value` *(*)*: The value to provide to `interceptor`. +2. `interceptor` *(Function)*: The function to invoke. +3. `[thisArg]` *(*)*: The `this` binding of `interceptor`. + +#### Returns +*(*)*: Returns the result of `interceptor`. + +#### Example +```js +_([1, 2, 3]) + .last() + .thru(function(value) { return [value]; }) + .value(); +// => [3] +``` +* * * + + + + + +### `_.prototype.chain()` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5475 "View in source") [Ⓣ][1] + +Enables explicit method chaining on the wrapper object. + +#### Returns +*(*)*: Returns the `lodash` object. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 } +]; + +// without explicit chaining +_(users).first(); +// => { 'user': 'barney', 'age': 36 } + +// with explicit chaining +_(users).chain() + .first() + .pick('user') + .value(); +// => { 'user': 'barney' } +``` +* * * + + + + + +### `_.prototype.reverse()` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5499 "View in source") [Ⓣ][1] + +Reverses the wrapped array so the first element becomes the last, the +second element becomes the second to last, and so on. + *Note:** This method mutates the wrapped array. + +#### Returns +*(Object)*: Returns the new reversed `lodash` object. + +#### Example +```js +var array = [1, 2, 3]; + +_(array).reverse().value() +// => [3, 2, 1] + +console.log(array); +// => [3, 2, 1] +``` +* * * + + + + + +### `_.prototype.toString()` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5521 "View in source") [Ⓣ][1] + +Produces the result of coercing the unwrapped value to a string. + +#### Returns +*(string)*: Returns the coerced string value. + +#### Example +```js +_([1, 2, 3]).toString(); +// => '1,2,3' +``` +* * * + + + + + +### `_.prototype.value()` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5538 "View in source") [Ⓣ][1] + +Executes the chained sequence to extract the unwrapped value. + +#### Returns +*(*)*: Returns the resolved unwrapped value. + +#### Example +```js +_([1, 2, 3]).value(); +// => [1, 2, 3] +``` +* * * + + + + + + + +## `“Collection” Methods` + + + +### `_.at(collection, [props])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5564 "View in source") [Ⓣ][1] + +Creates an array of elements corresponding to the given keys, or indexes, +of `collection`. Keys may be specified as individual arguments or as arrays +of keys. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[props]` *(...(number|number[]|string|string[])*: The property names or indexes of elements to pick, specified individually or in arrays. + +#### Returns +*(Array)*: Returns the new array of picked elements. + +#### Example +```js +_.at(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]); +// => ['a', 'c', 'e'] + +_.at(['fred', 'barney', 'pebbles'], 0, 2); +// => ['fred', 'pebbles'] +``` +* * * + + + + + +### `_.countBy(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5657 "View in source") [Ⓣ][1] + +Creates an object composed of keys generated from the results of running +each element of `collection` through `iteratee`. The corresponding value +of each key is the number of times the key was returned by `iteratee`. +The `iteratee` is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns the composed aggregate object. + +#### Example +```js +_.countBy([4.3, 6.1, 6.4], function(n) { return Math.floor(n); }); +// => { '4': 1, '6': 2 } + +_.countBy([4.3, 6.1, 6.4], function(n) { return this.floor(n); }, Math); +// => { '4': 1, '6': 2 } + +_.countBy(['one', 'two', 'three'], 'length'); +// => { '3': 2, '5': 1 } +``` +* * * + + + + + +### `_.every(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5702 "View in source") [Ⓣ][1] + +Checks if `predicate` returns truthy for **all** elements of `collection`. +The predicate is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(boolean)*: Returns `true` if all elements pass the predicate check, +else `false`. + +#### Example +```js +_.every([true, 1, null, 'yes']); +// => false + +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 } +]; + +// using the "_.property" callback shorthand +_.every(users, 'age'); +// => true + +// using the "_.matches" callback shorthand +_.every(users, { 'age': 36 }); +// => false +``` +* * * + + + + + +### `_.filter(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5750 "View in source") [Ⓣ][1] + +Iterates over elements of `collection`, returning an array of all elements +`predicate` returns truthy for. The predicate is bound to `thisArg` and +invoked with three arguments; (value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the new filtered array. + +#### Example +```js +var evens = _.filter([1, 2, 3, 4], function(n) { return n % 2 == 0; }); +// => [2, 4] + +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.filter(users, 'active'), 'user'); +// => ['fred'] + +// using the "_.matches" callback shorthand +_.pluck(_.filter(users, { 'age': 36 }), 'user'); +// => ['barney'] +``` +* * * + + + + + +### `_.find(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5797 "View in source") [Ⓣ][1] + +Iterates over elements of `collection`, returning the first element +`predicate` returns truthy for. The predicate is bound to `thisArg` and +invoked with three arguments; (value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(*)*: Returns the matched element, else `undefined`. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true }, + { 'user': 'pebbles', 'age': 1, 'active': false } +]; + +_.result(_.find(users, function(chr) { return chr.age < 40; }), 'user'); +// => 'barney' + +// using the "_.matches" callback shorthand +_.result(_.find(users, { 'age': 1 }), 'user'); +// => 'pebbles' + +// using the "_.property" callback shorthand +_.result(_.find(users, 'active'), 'user'); +// => 'fred' +``` +* * * + + + + + +### `_.findLast(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5824 "View in source") [Ⓣ][1] + +This method is like `_.find` except that it iterates over elements of +`collection` from right to left. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(*)*: Returns the matched element, else `undefined`. + +#### Example +```js +_.findLast([1, 2, 3, 4], function(n) { return n % 2 == 1; }); +// => 3 +``` +* * * + + + + + +### `_.findWhere(collection, source)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5853 "View in source") [Ⓣ][1] + +Performs a deep comparison between each element in `collection` and the +source object, returning the first element that has equivalent property +values. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to search. +2. `source` *(Object)*: The object of property values to match. + +#### Returns +*(*)*: Returns the matched element, else `undefined`. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36, 'status': 'busy' }, + { 'user': 'fred', 'age': 40, 'status': 'busy' } +]; + +_.result(_.findWhere(users, { 'status': 'busy' }), 'user'); +// => 'barney' + +_.result(_.findWhere(users, { 'age': 40 }), 'user'); +// => 'fred' +``` +* * * + + + + + +### `_.forEach(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5883 "View in source") [Ⓣ][1] + +Iterates over elements of `collection` invoking `iteratee` for each element. +The `iteratee` is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). Iterator functions may exit iteration early +by explicitly returning `false`. + *Note:** As with other "Collections" methods, objects with a `length` property +are iterated like arrays. To avoid this behavior `_.forIn` or `_.forOwn` +may be used for object iteration. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Array|Object|string)*: Returns `collection`. + +#### Example +```js +_([1, 2, 3]).forEach(function(n) { console.log(n); }); +// => logs each value from left to right and returns the array + +_.forEach({ 'one': 1, 'two': 2, 'three': 3 }, function(n, key) { console.log(n, key); }); +// => logs each value-key pair and returns the object (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.forEachRight(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5906 "View in source") [Ⓣ][1] + +This method is like `_.forEach` except that it iterates over elements of +`collection` from right to left. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Array|Object|string)*: Returns `collection`. + +#### Example +```js +_([1, 2, 3]).forEachRight(function(n) { console.log(n); }).join(','); +// => logs each value from right to left and returns the array +``` +* * * + + + + + +### `_.groupBy(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5947 "View in source") [Ⓣ][1] + +Creates an object composed of keys generated from the results of running +each element of `collection` through `iteratee`. The corresponding value +of each key is an array of the elements responsible for generating the key. +The `iteratee` is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns the composed aggregate object. + +#### Example +```js +_.groupBy([4.2, 6.1, 6.4], function(n) { return Math.floor(n); }); +// => { '4': [4.2], '6': [6.1, 6.4] } + +_.groupBy([4.2, 6.1, 6.4], function(n) { return this.floor(n); }, Math); +// => { '4': [4.2], '6': [6.1, 6.4] } + +// using the "_.property" callback shorthand +_.groupBy(['one', 'two', 'three'], 'length'); +// => { '3': ['one', 'two'], '5': ['three'] } +``` +* * * + + + + + +### `_.includes(collection, target, [fromIndex=0])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5604 "View in source") [Ⓣ][1] + +Checks if `value` is in `collection` using `SameValueZero` for equality +comparisons. If `fromIndex` is negative, it is used as the offset from +the end of `collection`. + *Note:** `SameValueZero` comparisons are like strict equality comparisons, +e.g. `===`, except that `NaN` matches `NaN`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) +for more details. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to search. +2. `target` *(*)*: The value to search for. +3. `[fromIndex=0]` *(number)*: The index to search from. + +#### Returns +*(boolean)*: Returns `true` if a matching element is found, else `false`. + +#### Example +```js +_.includes([1, 2, 3], 1); +// => true + +_.includes([1, 2, 3], 1, 2); +// => false + +_.includes({ 'user': 'fred', 'age': 40 }, 'fred'); +// => true + +_.includes('pebbles', 'eb'); +// => true +``` +* * * + + + + + +### `_.indexBy(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L5994 "View in source") [Ⓣ][1] + +Creates an object composed of keys generated from the results of running +each element of `collection` through `iteratee`. The corresponding value +of each key is the last element responsible for generating the key. The +iteratee function is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns the composed aggregate object. + +#### Example +```js +var keyData = [ + { 'dir': 'left', 'code': 97 }, + { 'dir': 'right', 'code': 100 } +]; + +_.indexBy(keyData, 'dir'); +// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } } + +_.indexBy(keyData, function(object) { return String.fromCharCode(object.code); }); +// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } } + +_.indexBy(keyData, function(object) { return this.fromCharCode(object.code); }, String); +// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } } +``` +* * * + + + + + +### `_.invoke(collection, methodName, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6020 "View in source") [Ⓣ][1] + +Invokes the method named by `methodName` on each element in `collection`, +returning an array of the results of each invoked method. Any additional +arguments are provided to each invoked method. If `methodName` is a function +it is invoked for, and `this` bound to, each element in `collection`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `methodName` *(Function|string)*: The name of the method to invoke or the function invoked per iteration. +3. `[args]` *(...*)*: The arguments to invoke the method with. + +#### Returns +*(Array)*: Returns the array of results. + +#### Example +```js +_.invoke([[5, 1, 7], [3, 2, 1]], 'sort'); +// => [[1, 5, 7], [1, 2, 3]] + +_.invoke([123, 456], String.prototype.split, ''); +// => [['1', '2', '3'], ['4', '5', '6']] +``` +* * * + + + + + +### `_.map(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6063 "View in source") [Ⓣ][1] + +Creates an array of values by running each element in `collection` through +`iteratee`. The `iteratee` is bound to `thisArg` and invoked with three +arguments; (value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Array)*: Returns the new mapped array. + +#### Example +```js +_.map([1, 2, 3], function(n) { return n * 3; }); +// => [3, 6, 9] + +_.map({ 'one': 1, 'two': 2, 'three': 3 }, function(n) { return n * 3; }); +// => [3, 6, 9] (iteration order is not guaranteed) + +var users = [ + { 'user': 'barney' }, + { 'user': 'fred' } +]; + +// using the "_.property" callback shorthand +_.map(users, 'user'); +// => ['barney', 'fred'] +``` +* * * + + + + + +### `_.max(collection, [iteratee], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6112 "View in source") [Ⓣ][1] + +Gets the maximum value of `collection`. If `collection` is empty or falsey +`-Infinity` is returned. If an iteratee function is provided it is invoked +for each value in `collection` to generate the criterion by which the value +is ranked. The `iteratee` is bound to `thisArg` and invoked with three +arguments; (value, index, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(*)*: Returns the maximum value. + +#### Example +```js +_.max([4, 2, 8, 6]); +// => 8 + +_.max([]); +// => -Infinity + +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 } +]; + +_.max(users, function(chr) { return chr.age; }); +// => { 'user': 'fred', 'age': 40 }; + +// using the "_.property" callback shorthand +_.max(users, 'age'); +// => { 'user': 'fred', 'age': 40 }; +``` +* * * + + + + + +### `_.min(collection, [iteratee], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6157 "View in source") [Ⓣ][1] + +Gets the minimum value of `collection`. If `collection` is empty or falsey +`Infinity` is returned. If an iteratee function is provided it is invoked +for each value in `collection` to generate the criterion by which the value +is ranked. The `iteratee` is bound to `thisArg` and invoked with three +arguments; (value, index, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(*)*: Returns the minimum value. + +#### Example +```js +_.min([4, 2, 8, 6]); +// => 2 + +_.min([]); +// => Infinity + +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 } +]; + +_.min(users, function(chr) { return chr.age; }); +// => { 'user': 'barney', 'age': 36 }; + +// using the "_.property" callback shorthand +_.min(users, 'age'); +// => { 'user': 'barney', 'age': 36 }; +``` +* * * + + + + + +### `_.partition(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6203 "View in source") [Ⓣ][1] + +Creates an array of elements split into two groups, the first of which +contains elements `predicate` returns truthy for, while the second of which +contains elements `predicate` returns falsey for. The predicate is bound +to `thisArg` and invoked with three arguments; (value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the array of grouped elements. + +#### Example +```js +_.partition([1, 2, 3], function(n) { return n % 2; }); +// => [[1, 3], [2]] + +_.partition([1.2, 2.3, 3.4], function(n) { return this.floor(n) % 2; }, Math); +// => [[1, 3], [2]] + +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true }, + { 'user': 'pebbles', 'age': 1, 'active': false } +]; + +// using the "_.matches" callback shorthand +_.map(_.partition(users, { 'age': 1 }), function(array) { return _.pluck(array, 'user'); }); +// => [['pebbles'], ['barney', 'fred']] + +// using the "_.property" callback shorthand +_.map(_.partition(users, 'active'), function(array) { return _.pluck(array, 'user'); }); +// => [['fred'], ['barney', 'pebbles']] +``` +* * * + + + + + +### `_.pluck(collection, key)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6230 "View in source") [Ⓣ][1] + +Gets the value of `key` from all elements in `collection`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `key` *(string)*: The key of the property to pluck. + +#### Returns +*(Array)*: Returns the property values. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 } +]; + +_.pluck(users, 'user'); +// => ['barney', 'fred'] + +var userIndex = _.indexBy(users, 'user'); +_.pluck(userIndex, 'age'); +// => [36, 40] (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.reduce(collection, [iteratee=_.identity], [accumulator], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6262 "View in source") [Ⓣ][1] + +Reduces `collection` to a value which is the accumulated result of running +each element in `collection` through `iteratee`, where each successive +invocation is supplied the return value of the previous. If `accumulator` +is not provided the first element of `collection` is used as the initial +value. The `iteratee` is bound to `thisArg`and invoked with four arguments; +(accumulator, value, index|key, collection). + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[accumulator]` *(*)*: The initial value. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(*)*: Returns the accumulated value. + +#### Example +```js +var sum = _.reduce([1, 2, 3], function(sum, n) { return sum + n; }); +// => 6 + +var mapped = _.reduce({ 'a': 1, 'b': 2, 'c': 3 }, function(result, n, key) { + result[key] = n * 3; + return result; +}, {}); +// => { 'a': 3, 'b': 6, 'c': 9 } (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.reduceRight(collection, [iteratee=_.identity], [accumulator], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6286 "View in source") [Ⓣ][1] + +This method is like `_.reduce` except that it iterates over elements of +`collection` from right to left. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[accumulator]` *(*)*: The initial value. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(*)*: Returns the accumulated value. + +#### Example +```js +var array = [[0, 1], [2, 3], [4, 5]]; +_.reduceRight(array, function(flattened, other) { return flattened.concat(other); }, []); +// => [4, 5, 2, 3, 0, 1] +``` +* * * + + + + + +### `_.reject(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6329 "View in source") [Ⓣ][1] + +The opposite of `_.filter`; this method returns the elements of `collection` +that `predicate` does **not** return truthy for. + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Array)*: Returns the new filtered array. + +#### Example +```js +var odds = _.reject([1, 2, 3, 4], function(n) { return n % 2 == 0; }); +// => [1, 3] + +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true } +]; + +// using the "_.property" callback shorthand +_.pluck(_.reject(users, 'active'), 'user'); +// => ['barney'] + +// using the "_.matches" callback shorthand +_.pluck(_.reject(users, { 'age': 36 }), 'user'); +// => ['fred'] +``` +* * * + + + + + +### `_.sample(collection, [n])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6355 "View in source") [Ⓣ][1] + +Gets a random element or `n` random elements from a collection. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to sample. +2. `[n]` *(number)*: The number of elements to sample. + +#### Returns +*(*)*: Returns the random sample(s). + +#### Example +```js +_.sample([1, 2, 3, 4]); +// => 2 + +_.sample([1, 2, 3, 4], 2); +// => [3, 1] +``` +* * * + + + + + +### `_.shuffle(collection)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6381 "View in source") [Ⓣ][1] + +Creates an array of shuffled values, using a version of the Fisher-Yates +shuffle. See [Wikipedia](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle) +for more details. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to shuffle. + +#### Returns +*(Array)*: Returns the new shuffled array. + +#### Example +```js +_.shuffle([1, 2, 3, 4]); +// => [4, 1, 3, 2] +``` +* * * + + + + + +### `_.size(collection)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6418 "View in source") [Ⓣ][1] + +Gets the size of `collection` by returning `collection.length` for +array-like values or the number of own enumerable properties for objects. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to inspect. + +#### Returns +*(number)*: Returns the size of `collection`. + +#### Example +```js +_.size([1, 2]); +// => 2 + +_.size({ 'one': 1, 'two': 2, 'three': 3 }); +// => 3 + +_.size('pebbles'); +// => 7 +``` +* * * + + + + + +### `_.some(collection, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6465 "View in source") [Ⓣ][1] + +Checks if `predicate` returns truthy for **any** element of `collection`. +The function returns as soon as it finds a passing value and does not iterate +over the entire collection. The predicate is bound to `thisArg` and invoked +with three arguments; (value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(boolean)*: Returns `true` if any element passes the predicate check, +else `false`. + +#### Example +```js +_.some([null, 0, 'yes', false], Boolean); +// => true + +var users = [ + { 'user': 'barney', 'age': 36, 'active': false }, + { 'user': 'fred', 'age': 40, 'active': true } +]; + +// using the "_.property" callback shorthand +_.some(users, 'active'); +// => true + +// using the "_.matches" callback shorthand +_.some(users, { 'age': 1 }); +// => false +``` +* * * + + + + + +### `_.sortBy(collection, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6514 "View in source") [Ⓣ][1] + +Creates an array of elements, sorted in ascending order by the results of +running each element in a collection through `iteratee`. This method performs +a stable sort, that is, it preserves the original sort order of equal elements. +The `iteratee` is bound to `thisArg` and invoked with three arguments; +(value, index|key, collection). + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `[iteratee=_.identity]` *(Array|Function|Object|string)*: The function invoked per iteration. If a property name or an object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Array)*: Returns the new sorted array. + +#### Example +```js +_.sortBy([1, 2, 3], function(n) { return Math.sin(n); }); +// => [3, 1, 2] + +_.sortBy([1, 2, 3], function(n) { return this.sin(n); }, Math); +// => [3, 1, 2] + +var users = [ + { 'user': 'fred' }, + { 'user': 'pebbles' }, + { 'user': 'barney' } +]; + +// using the "_.property" callback shorthand +_.pluck(_.sortBy(users, 'user'), 'user'); +// => ['barney', 'fred', 'pebbles'] +``` +* * * + + + + + +### `_.sortByAll(collection, props)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6552 "View in source") [Ⓣ][1] + +This method is like `_.sortBy` except that it sorts by property names +instead of an iteratee function. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to iterate over. +2. `props` *(...(string|string[])*: The property names to sort by, specified as individual property names or arrays of property names. + +#### Returns +*(Array)*: Returns the new sorted array. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36 }, + { 'user': 'fred', 'age': 40 }, + { 'user': 'barney', 'age': 26 }, + { 'user': 'fred', 'age': 30 } +]; + +_.map(_.sortByAll(users, ['user', 'age']), _.values); +// => [['barney', 26], ['barney', 36], ['fred', 30], ['fred', 40]] +``` +* * * + + + + + +### `_.where(collection, source)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6601 "View in source") [Ⓣ][1] + +Performs a deep comparison between each element in `collection` and the +source object, returning an array of all elements that have equivalent +property values. + +#### Arguments +1. `collection` *(Array|Object|string)*: The collection to search. +2. `source` *(Object)*: The object of property values to match. + +#### Returns +*(Array)*: Returns the new filtered array. + +#### Example +```js +var users = [ + { 'user': 'barney', 'age': 36, 'status': 'busy', 'pets': ['hoppy'] }, + { 'user': 'fred', 'age': 40, 'status': 'busy', 'pets': ['baby puss', 'dino'] } +]; + +_.pluck(_.where(users, { 'age': 36 }), 'user'); +// => ['barney'] + +_.pluck(_.where(users, { 'pets': ['dino'] }), 'user'); +// => ['fred'] + +_.pluck(_.where(users, { 'status': 'busy' }), 'user'); +// => ['barney', 'fred'] +``` +* * * + + + + + + + +## `“Date” Methods` + + + +### `_.now` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6619 "View in source") [Ⓣ][1] + +Gets the number of milliseconds that have elapsed since the Unix epoch +(1 January 1970 00:00:00 UTC). + +#### Example +```js +_.defer(function(stamp) { console.log(_.now() - stamp); }, _.now()); +// => logs the number of milliseconds it took for the deferred function to be invoked +``` +* * * + + + + + + + +## `“Function” Methods` + + + +### `_.after(n, func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6648 "View in source") [Ⓣ][1] + +The opposite of `_.before`; this method creates a function that invokes +`func` once it is called `n` or more times. + +#### Arguments +1. `n` *(number)*: The number of calls before `func` is invoked. +2. `func` *(Function)*: The function to restrict. + +#### Returns +*(Function)*: Returns the new restricted function. + +#### Example +```js +var saves = ['profile', 'settings']; + +var done = _.after(saves.length, function() { + console.log('done saving!'); +}); + +_.forEach(saves, function(type) { + asyncSave({ 'type': type, 'complete': done }); +}); +// => logs 'done saving!' after the two async saves have completed +``` +* * * + + + + + +### `_.ary(func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6682 "View in source") [Ⓣ][1] + +Creates a function that accepts up to `n` arguments ignoring any +additional arguments. + +#### Arguments +1. `func` *(Function)*: The function to cap arguments for. +2. `[n=func.length]` *(number)*: The arity cap. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +_.map(['6', '8', '10'], _.ary(parseInt, 1)); +// => [6, 8, 10] +``` +* * * + + + + + +### `_.before(n, func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6706 "View in source") [Ⓣ][1] + +Creates a function that invokes `func`, with the `this` binding and arguments +of the created function, while it is called less than `n` times. Subsequent +calls to the created function return the result of the last `func` invocation. + +#### Arguments +1. `n` *(number)*: The number of calls at which `func` is no longer invoked. +2. `func` *(Function)*: The function to restrict. + +#### Returns +*(Function)*: Returns the new restricted function. + +#### Example +```js +jQuery('#add').on('click', _.before(5, addContactToList)); +// => allows adding up to 4 contacts to the list +``` +* * * + + + + + +### `_.bind(func, thisArg, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6762 "View in source") [Ⓣ][1] + +Creates a function that invokes `func` with the `this` binding of `thisArg` +and prepends any additional `_.bind` arguments to those provided to the +bound function. + +The `_.bind.placeholder` value, which defaults to `_` in monolithic builds, +may be used as a placeholder for partially applied arguments. + *Note:** Unlike native `Function#bind` this method does not set the `length` +property of bound functions. + +#### Arguments +1. `func` *(Function)*: The function to bind. +2. `thisArg` *(*)*: The `this` binding of `func`. +3. `[args]` *(...*)*: The arguments to be partially applied. + +#### Returns +*(Function)*: Returns the new bound function. + +#### Example +```js +var greet = function(greeting, punctuation) { + return greeting + ' ' + this.user + punctuation; +}; + +var object = { 'user': 'fred' }; + +var bound = _.bind(greet, object, 'hi'); +bound('!'); +// => 'hi fred!' + +// using placeholders +var bound = _.bind(greet, object, _, '!'); +bound('hi'); +// => 'hi fred!' +``` +* * * + + + + + +### `_.bindAll(object, [methodNames])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6799 "View in source") [Ⓣ][1] + +Binds methods of an object to the object itself, overwriting the existing +method. Method names may be specified as individual arguments or as arrays +of method names. If no method names are provided all enumerable function +properties, own and inherited, of `object` are bound. + *Note:** This method does not set the `length` property of bound functions. + +#### Arguments +1. `object` *(Object)*: The object to bind and assign the bound methods to. +2. `[methodNames]` *(...(string|string[])*: The object method names to bind, specified as individual method names or arrays of method names. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +var view = { + 'label': 'docs', + 'onClick': function() { console.log('clicked ' + this.label); } +}; + +_.bindAll(view); +jQuery('#docs').on('click', view.onClick); +// => logs 'clicked docs' when the element is clicked +``` +* * * + + + + + +### `_.bindKey(object, key, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6851 "View in source") [Ⓣ][1] + +Creates a function that invokes the method at `object[key]` and prepends +any additional `_.bindKey` arguments to those provided to the bound function. + +This method differs from `_.bind` by allowing bound functions to reference +methods that may be redefined or don't yet exist. +See [Peter Michaux's article](http://michaux.ca/articles/lazy-function-definition-pattern) +for more details. + +The `_.bindKey.placeholder` value, which defaults to `_` in monolithic +builds, may be used as a placeholder for partially applied arguments. + +#### Arguments +1. `object` *(Object)*: The object the method belongs to. +2. `key` *(string)*: The key of the method. +3. `[args]` *(...*)*: The arguments to be partially applied. + +#### Returns +*(Function)*: Returns the new bound function. + +#### Example +```js +var object = { + 'user': 'fred', + 'greet': function(greeting, punctuation) { + return greeting + ' ' + this.user + punctuation; + } +}; + +var bound = _.bindKey(object, 'greet', 'hi'); +bound('!'); +// => 'hi fred!' + +object.greet = function(greeting, punctuation) { + return greeting + 'ya ' + this.user + punctuation; +}; + +bound('!'); +// => 'hiya fred!' + +// using placeholders +var bound = _.bindKey(object, 'greet', _, '!'); +bound('hi'); +// => 'hiya fred!' +``` +* * * + + + + + +### `_.curry(func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6902 "View in source") [Ⓣ][1] + +Creates a function that accepts one or more arguments of `func` that when +called either invokes `func` returning its result, if all `func` arguments +have been provided, or returns a function that accepts one or more of the +remaining `func` arguments, and so on. The arity of `func` may be specified +if `func.length` is not sufficient. + +The `_.curry.placeholder` value, which defaults to `_` in monolithic builds, +may be used as a placeholder for provided arguments. + *Note:** This method does not set the `length` property of curried functions. + +#### Arguments +1. `func` *(Function)*: The function to curry. +2. `[arity=func.length]` *(number)*: The arity of `func`. + +#### Returns +*(Function)*: Returns the new curried function. + +#### Example +```js +var abc = function(a, b, c) { + return [a, b, c]; +}; + +var curried = _.curry(abc); + +curried(1)(2)(3); +// => [1, 2, 3] + +curried(1, 2)(3); +// => [1, 2, 3] + +curried(1, 2, 3); +// => [1, 2, 3] + +// using placeholders +curried(1)(_, 3)(2); +// => [1, 2, 3] +``` +* * * + + + + + +### `_.curryRight(func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L6948 "View in source") [Ⓣ][1] + +This method is like `_.curry` except that arguments are applied to `func` +in the manner of `_.partialRight` instead of `_.partial`. + +The `_.curryRight.placeholder` value, which defaults to `_` in monolithic +builds, may be used as a placeholder for provided arguments. + *Note:** This method does not set the `length` property of curried functions. + +#### Arguments +1. `func` *(Function)*: The function to curry. +2. `[arity=func.length]` *(number)*: The arity of `func`. + +#### Returns +*(Function)*: Returns the new curried function. + +#### Example +```js +var abc = function(a, b, c) { + return [a, b, c]; +}; + +var curried = _.curryRight(abc); + +curried(3)(2)(1); +// => [1, 2, 3] + +curried(2, 3)(1); +// => [1, 2, 3] + +curried(1, 2, 3); +// => [1, 2, 3] + +// using placeholders +curried(3)(1, _)(2); +// => [1, 2, 3] +``` +* * * + + + + + +### `_.debounce(func, wait, [options], [options.leading=false], [options.maxWait], [options.trailing=true])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7019 "View in source") [Ⓣ][1] + +Creates a function that delays invoking `func` until after `wait` milliseconds +have elapsed since the last time it was invoked. The created function comes +with a `cancel` method to cancel delayed invocations. Provide an options +object to indicate that `func` should be invoked on the leading and/or +trailing edge of the `wait` timeout. Subsequent calls to the debounced +function return the result of the last `func` invocation. + *Note:** If `leading` and `trailing` options are `true`, `func` is invoked +on the trailing edge of the timeout only if the the debounced function is +invoked more than once during the `wait` timeout. + +See [David Corbacho's article](http://drupalmotion.com/article/debounce-and-throttle-visual-explanation) +for details over the differences between `_.debounce` and `_.throttle`. + +#### Arguments +1. `func` *(Function)*: The function to debounce. +2. `wait` *(number)*: The number of milliseconds to delay. +3. `[options]` *(Object)*: The options object. +4. `[options.leading=false]` *(boolean)*: Specify invoking on the leading edge of the timeout. +5. `[options.maxWait]` *(number)*: The maximum time `func` is allowed to be delayed before it is invoked. +6. `[options.trailing=true]` *(boolean)*: Specify invoking on the trailing edge of the timeout. + +#### Returns +*(Function)*: Returns the new debounced function. + +#### Example +```js +// avoid costly calculations while the window size is in flux +jQuery(window).on('resize', _.debounce(calculateLayout, 150)); + +// invoke `sendMail` when the click event is fired, debouncing subsequent calls +jQuery('#postbox').on('click', _.debounce(sendMail, 300, { + 'leading': true, + 'trailing': false +})); + +// ensure `batchLog` is invoked once after 1 second of debounced calls +var source = new EventSource('/stream'); +jQuery(source).on('message', _.debounce(batchLog, 250, { + 'maxWait': 1000 +})); + +// cancel a debounced call +var todoChanges = _.debounce(batchLog, 1000); +Object.observe(models.todo, todoChanges); + +Object.observe(models, function(changes) { + if (_.find(changes, { 'user': 'todo', 'type': 'delete'})) { + todoChanges.cancel(); + } +}, ['delete']); + +// ...at some point `models.todo` is changed +models.todo.completed = true; + +// ...before 1 second has passed `models.todo` is deleted +// which cancels the debounced `todoChanges` call +delete models.todo; +``` +* * * + + + + + +### `_.defer(func, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7148 "View in source") [Ⓣ][1] + +Defers invoking the `func` until the current call stack has cleared. Any +additional arguments are provided to `func` when it is invoked. + +#### Arguments +1. `func` *(Function)*: The function to defer. +2. `[args]` *(...*)*: The arguments to invoke the function with. + +#### Returns +*(number)*: Returns the timer id. + +#### Example +```js +_.defer(function(text) { console.log(text); }, 'deferred'); +// logs 'deferred' after one or more milliseconds +``` +* * * + + + + + +### `_.delay(func, wait, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7168 "View in source") [Ⓣ][1] + +Invokes `func` after `wait` milliseconds. Any additional arguments are +provided to `func` when it is invoked. + +#### Arguments +1. `func` *(Function)*: The function to delay. +2. `wait` *(number)*: The number of milliseconds to delay invocation. +3. `[args]` *(...*)*: The arguments to invoke the function with. + +#### Returns +*(number)*: Returns the timer id. + +#### Example +```js +_.delay(function(text) { console.log(text); }, 1000, 'later'); +// => logs 'later' after one second +``` +* * * + + + + + +### `_.flow([funcs])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7196 "View in source") [Ⓣ][1] + +Creates a function that returns the result of invoking the provided +functions with the `this` binding of the created function, where each +successive invocation is supplied the return value of the previous. + +#### Arguments +1. `[funcs]` *(...Function)*: Functions to invoke. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +function add(x, y) { + return x + y; +} + +function square(n) { + return n * n; +} + +var addSquare = _.flow(add, square); +addSquare(1, 2); +// => 9 +``` +* * * + + + + + +### `_.flowRight([funcs])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7241 "View in source") [Ⓣ][1] + +This method is like `_.flow` except that it creates a function that +invokes the provided functions from right to left. + +#### Arguments +1. `[funcs]` *(...Function)*: Functions to invoke. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +function add(x, y) { + return x + y; +} + +function square(n) { + return n * n; +} + +var addSquare = _.flowRight(square, add); +addSquare(1, 2); +// => 9 +``` +* * * + + + + + +### `_.memoize(func, [resolver])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7315 "View in source") [Ⓣ][1] + +Creates a function that memoizes the result of `func`. If `resolver` is +provided it determines the cache key for storing the result based on the +arguments provided to the memoized function. By default, the first argument +provided to the memoized function is coerced to a string and used as the +cache key. The `func` is invoked with the `this` binding of the memoized +function. + *Note:** The cache is exposed as the `cache` property on the memoized +function. Its creation may be customized by replacing the `_.memoize.Cache` +constructor with one whose instances implement the ES `Map` method interface +of `get`, `has`, and `set`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-properties-of-the-map-prototype-object) +for more details. + +#### Arguments +1. `func` *(Function)*: The function to have its output memoized. +2. `[resolver]` *(Function)*: The function to resolve the cache key. + +#### Returns +*(Function)*: Returns the new memoizing function. + +#### Example +```js +var upperCase = _.memoize(function(string) { + return string.toUpperCase(); +}); + +upperCase('fred'); +// => 'FRED' + +// modifying the result cache +upperCase.cache.set('fred, 'BARNEY'); +upperCase('fred'); +// => 'BARNEY' + +// replacing `_.memoize.Cache` +var object = { 'user': 'fred' }; +var other = { 'user': 'barney' }; +var identity = _.memoize(_.identity); + +identity(object); +// => { 'user': 'fred' } +identity(other); +// => { 'user': 'fred' } + +_.memoize.Cache = WeakMap; +var identity = _.memoize(_.identity); + +identity(object); +// => { 'user': 'fred' } +identity(other); +// => { 'user': 'barney' } +``` +* * * + + + + + +### `_.negate(predicate)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7353 "View in source") [Ⓣ][1] + +Creates a function that negates the result of the predicate `func`. The +`func` predicate is invoked with the `this` binding and arguments of the +created function. + +#### Arguments +1. `predicate` *(Function)*: The predicate to negate. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +function isEven(n) { + return n % 2 == 0; +} + +_.filter([1, 2, 3, 4, 5, 6], _.negate(isEven)); +// => [1, 3, 5] +``` +* * * + + + + + +### `_.once(func)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7380 "View in source") [Ⓣ][1] + +Creates a function that is restricted to invoking `func` once. Repeat calls +to the function return the value of the first call. The `func` is invoked +with the `this` binding of the created function. + +#### Arguments +1. `func` *(Function)*: The function to restrict. + +#### Returns +*(Function)*: Returns the new restricted function. + +#### Example +```js +var initialize = _.once(createApplication); +initialize(); +initialize(); +// `initialize` invokes `createApplication` once +``` +* * * + + + + + +### `_.partial(func, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7416 "View in source") [Ⓣ][1] + +Creates a function that invokes `func` with `partial` arguments prepended +to those provided to the new function. This method is like `_.bind` except +it does **not** alter the `this` binding. + +The `_.partial.placeholder` value, which defaults to `_` in monolithic +builds, may be used as a placeholder for partially applied arguments. + *Note:** This method does not set the `length` property of partially +applied functions. + +#### Arguments +1. `func` *(Function)*: The function to partially apply arguments to. +2. `[args]` *(...*)*: The arguments to be partially applied. + +#### Returns +*(Function)*: Returns the new partially applied function. + +#### Example +```js +var greet = function(greeting, name) { + return greeting + ' ' + name; +}; + +var sayHelloTo = _.partial(greet, 'hello'); +sayHelloTo('fred'); +// => 'hello fred' + +// using placeholders +var greetFred = _.partial(greet, _, 'fred'); +greetFred('hi'); +// => 'hi fred' +``` +* * * + + + + + +### `_.partialRight(func, [args])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7454 "View in source") [Ⓣ][1] + +This method is like `_.partial` except that partially applied arguments +are appended to those provided to the new function. + +The `_.partialRight.placeholder` value, which defaults to `_` in monolithic +builds, may be used as a placeholder for partially applied arguments. + *Note:** This method does not set the `length` property of partially +applied functions. + +#### Arguments +1. `func` *(Function)*: The function to partially apply arguments to. +2. `[args]` *(...*)*: The arguments to be partially applied. + +#### Returns +*(Function)*: Returns the new partially applied function. + +#### Example +```js +var greet = function(greeting, name) { + return greeting + ' ' + name; +}; + +var greetFred = _.partialRight(greet, 'fred'); +greetFred('hi'); +// => 'hi fred' + +// using placeholders +var sayHelloTo = _.partialRight(greet, 'hello', _); +sayHelloTo('fred'); +// => 'hello fred' +``` +* * * + + + + + +### `_.rearg(func, indexes)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7487 "View in source") [Ⓣ][1] + +Creates a function that invokes `func` with arguments arranged according +to the specified indexes where the argument value at the first index is +provided as the first argument, the argument value at the second index is +provided as the second argument, and so on. + +#### Arguments +1. `func` *(Function)*: The function to rearrange arguments for. +2. `indexes` *(...(number|number[])*: The arranged argument indexes, specified as individual indexes or arrays of indexes. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +var rearged = _.rearg(function(a, b, c) { + return [a, b, c]; +}, 2, 0, 1); + +rearged('b', 'c', 'a') +// => ['a', 'b', 'c'] + +var map = _.rearg(_.map, [1, 0]); +map(function(n) { return n * 3; }, [1, 2, 3]); +// => [3, 6, 9] +``` +* * * + + + + + +### `_.throttle(func, wait, [options], [options.leading=true], [options.trailing=true])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7530 "View in source") [Ⓣ][1] + +Creates a function that only invokes `func` at most once per every `wait` +milliseconds. The created function comes with a `cancel` method to cancel +delayed invocations. Provide an options object to indicate that `func` +should be invoked on the leading and/or trailing edge of the `wait` timeout. +Subsequent calls to the throttled function return the result of the last +`func` call. + *Note:** If `leading` and `trailing` options are `true`, `func` is invoked +on the trailing edge of the timeout only if the the throttled function is +invoked more than once during the `wait` timeout. + +See [David Corbacho's article](http://drupalmotion.com/article/debounce-and-throttle-visual-explanation) +for details over the differences between `_.throttle` and `_.debounce`. + +#### Arguments +1. `func` *(Function)*: The function to throttle. +2. `wait` *(number)*: The number of milliseconds to throttle invocations to. +3. `[options]` *(Object)*: The options object. +4. `[options.leading=true]` *(boolean)*: Specify invoking on the leading edge of the timeout. +5. `[options.trailing=true]` *(boolean)*: Specify invoking on the trailing edge of the timeout. + +#### Returns +*(Function)*: Returns the new throttled function. + +#### Example +```js +// avoid excessively updating the position while scrolling +jQuery(window).on('scroll', _.throttle(updatePosition, 100)); + +// invoke `renewToken` when the click event is fired, but not more than once every 5 minutes +var throttled = _.throttle(renewToken, 300000, { 'trailing': false }) +jQuery('.interactive').on('click', throttled); + +// cancel a trailing throttled call +jQuery(window).on('popstate', throttled.cancel); +``` +* * * + + + + + +### `_.wrap(value, wrapper)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7570 "View in source") [Ⓣ][1] + +Creates a function that provides `value` to the wrapper function as its +first argument. Any additional arguments provided to the function are +appended to those provided to the wrapper function. The wrapper is invoked +with the `this` binding of the created function. + +#### Arguments +1. `value` *(*)*: The value to wrap. +2. `wrapper` *(Function)*: The wrapper function. + +#### Returns +*(Function)*: Returns the new function. + +#### Example +```js +var p = _.wrap(_.escape, function(func, text) { + return '

' + func(text) + '

'; +}); + +p('fred, barney, & pebbles'); +// => '

fred, barney, & pebbles

' +``` +* * * + + + + + + + +## `“Lang” Methods` + + + +### `_.clone(value, [isDeep], [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7626 "View in source") [Ⓣ][1] + +Creates a clone of `value`. If `isDeep` is `true` nested objects are cloned, +otherwise they are assigned by reference. If `customizer` is provided it is +invoked to produce the cloned values. If `customizer` returns `undefined` +cloning is handled by the method instead. The `customizer` is bound to +`thisArg` and invoked with two argument; (value [, index|key, object]). + *Note:** This method is loosely based on the structured clone algorithm. +The enumerable properties of `arguments` objects and objects created by +constructors other than `Object` are cloned to plain `Object` objects. An +empty object is returned for uncloneable values such as functions, DOM nodes, +Maps, Sets, and WeakMaps. See the [HTML5 specification](http://www.w3.org/TR/html5/infrastructure.html#internal-structured-cloning-algorithm) +for more details. + +#### Arguments +1. `value` *(*)*: The value to clone. +2. `[isDeep]` *(boolean)*: Specify a deep clone. +3. `[customizer]` *(Function)*: The function to customize cloning values. +4. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(*)*: Returns the cloned value. + +#### Example +```js +var users = [ + { 'user': 'barney' }, + { 'user': 'fred' } +]; + +var shallow = _.clone(users); +shallow[0] === users[0]; +// => true + +var deep = _.clone(users, true); +deep[0] === users[0]; +// => false + +// using a customizer callback +var body = _.clone(document.body, function(value) { + return _.isElement(value) ? value.cloneNode(false) : undefined; +}); + +body === document.body +// => false +body.nodeName +// => BODY +body.childNodes.length; +// => 0 +``` +* * * + + + + + +### `_.cloneDeep(value, [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7680 "View in source") [Ⓣ][1] + +Creates a deep clone of `value`. If `customizer` is provided it is invoked +to produce the cloned values. If `customizer` returns `undefined` cloning +is handled by the method instead. The `customizer` is bound to `thisArg` +and invoked with two argument; (value [, index|key, object]). + *Note:** This method is loosely based on the structured clone algorithm. +The enumerable properties of `arguments` objects and objects created by +constructors other than `Object` are cloned to plain `Object` objects. An +empty object is returned for uncloneable values such as functions, DOM nodes, +Maps, Sets, and WeakMaps. See the [HTML5 specification](http://www.w3.org/TR/html5/infrastructure.html#internal-structured-cloning-algorithm) +for more details. + +#### Arguments +1. `value` *(*)*: The value to deep clone. +2. `[customizer]` *(Function)*: The function to customize cloning values. +3. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(*)*: Returns the deep cloned value. + +#### Example +```js +var users = [ + { 'user': 'barney' }, + { 'user': 'fred' } +]; + +var deep = _.cloneDeep(users); +deep[0] === users[0]; +// => false + +// using a customizer callback +var el = _.cloneDeep(document.body, function(value) { + return _.isElement(value) ? value.cloneNode(true) : undefined; +}); + +body === document.body +// => false +body.nodeName +// => BODY +body.childNodes.length; +// => 20 +``` +* * * + + + + + +### `_.isArguments(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7701 "View in source") [Ⓣ][1] + +Checks if `value` is classified as an `arguments` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +(function() { return _.isArguments(arguments); })(); +// => true + +_.isArguments([1, 2, 3]); +// => false +``` +* * * + + + + + +### `_.isArray(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7730 "View in source") [Ⓣ][1] + +Checks if `value` is classified as an `Array` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isArray([1, 2, 3]); +// => true + +(function() { return _.isArray(arguments); })(); +// => false +``` +* * * + + + + + +### `_.isBoolean(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7750 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a boolean primitive or object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isBoolean(false); +// => true + +_.isBoolean(null); +// => false +``` +* * * + + + + + +### `_.isDate(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7770 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a `Date` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isDate(new Date); +// => true + +_.isDate('Mon April 23 2012'); +// => false +``` +* * * + + + + + +### `_.isElement(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7790 "View in source") [Ⓣ][1] + +Checks if `value` is a DOM element. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is a DOM element, else `false`. + +#### Example +```js +_.isElement(document.body); +// => true + +_.isElement(''); +// => false +``` +* * * + + + + + +### `_.isEmpty(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7828 "View in source") [Ⓣ][1] + +Checks if a value is empty. A value is considered empty unless it is an +`arguments` object, array, string, or jQuery-like collection with a length +greater than `0` or an object with own enumerable properties. + +#### Arguments +1. `value` *(Array|Object|string)*: The value to inspect. + +#### Returns +*(boolean)*: Returns `true` if `value` is empty, else `false`. + +#### Example +```js +_.isEmpty(null); +// => true + +_.isEmpty(true); +// => true + +_.isEmpty(1); +// => true + +_.isEmpty([1, 2, 3]); +// => false + +_.isEmpty({ 'a': 1 }); +// => false +``` +* * * + + + + + +### `_.isEqual(value, other, [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7880 "View in source") [Ⓣ][1] + +Performs a deep comparison between two values to determine if they are +equivalent. If `customizer` is provided it is invoked to compare values. +If `customizer` returns `undefined` comparisons are handled by the method +instead. The `customizer` is bound to `thisArg` and invoked with three +arguments; (value, other [, index|key]). + *Note:** This method supports comparing arrays, booleans, `Date` objects, +numbers, `Object` objects, regexes, and strings. Functions and DOM nodes +are **not** supported. Provide a customizer function to extend support +for comparing other values. + +#### Arguments +1. `value` *(*)*: The value to compare. +2. `other` *(*)*: The other value to compare. +3. `[customizer]` *(Function)*: The function to customize comparing values. +4. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(boolean)*: Returns `true` if the values are equivalent, else `false`. + +#### Example +```js +var object = { 'user': 'fred' }; +var other = { 'user': 'fred' }; + +object == other; +// => false + +_.isEqual(object, other); +// => true + +// using a customizer callback +var array = ['hello', 'goodbye']; +var other = ['hi', 'goodbye']; + +_.isEqual(array, other, function(value, other) { + return _.every([value, other], RegExp.prototype.test, /^h(?:i|ello)$/) || undefined; +}); +// => true +``` +* * * + + + + + +### `_.isError(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7906 "View in source") [Ⓣ][1] + +Checks if `value` is an `Error`, `EvalError`, `RangeError`, `ReferenceError`, +`SyntaxError`, `TypeError`, or `URIError` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is an error object, else `false`. + +#### Example +```js +_.isError(new Error); +// => true + +_.isError(Error); +// => false +``` +* * * + + + + + +### `_.isFinite(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7939 "View in source") [Ⓣ][1] + +Checks if `value` is a finite primitive number. + *Note:** This method is based on ES `Number.isFinite`. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.isfinite) +for more details. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is a finite number, else `false`. + +#### Example +```js +_.isFinite(10); +// => true + +_.isFinite('10'); +// => false + +_.isFinite(true); +// => false + +_.isFinite(Object(10)); +// => false + +_.isFinite(Infinity); +// => false +``` +* * * + + + + + +### `_.isFunction(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7959 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a `Function` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isFunction(_); +// => true + +_.isFunction(/abc/); +// => false +``` +* * * + + + + + +### `_.isMatch(source, source, [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8042 "View in source") [Ⓣ][1] + +Performs a deep comparison between `object` and `source` to determine if +`object` contains equivalent property values. If `customizer` is provided +it is invoked to compare values. If `customizer` returns `undefined` +comparisons are handled by the method instead. The `customizer` is bound +to `thisArg` and invoked with three arguments; (value, other, index|key). + *Note:** This method supports comparing properties of arrays, booleans, +`Date` objects, numbers, `Object` objects, regexes, and strings. Functions +and DOM nodes are **not** supported. Provide a customizer function to extend +support for comparing other values. + +#### Arguments +1. `source` *(Object)*: The object to inspect. +2. `source` *(Object)*: The object of property values to match. +3. `[customizer]` *(Function)*: The function to customize comparing values. +4. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(boolean)*: Returns `true` if `object` is a match, else `false`. + +#### Example +```js +var object = { 'user': 'fred', 'age': 40 }; + +_.isMatch(object, { 'age': 40 }); +// => true + +_.isMatch(object, { 'age': 36 }); +// => false + +// using a customizer callback +var object = { 'greeting': 'hello' }; +var source = { 'greeting': 'hi' }; + +_.isMatch(object, source, function(value, other) { + return _.every([value, other], RegExp.prototype.test, /^h(?:i|ello)$/) || undefined; +}); +// => true +``` +* * * + + + + + +### `_.isNaN(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8091 "View in source") [Ⓣ][1] + +Checks if `value` is `NaN`. + *Note:** This method is not the same as native `isNaN` which returns `true` +for `undefined` and other non-numeric values. See the [ES5 spec](https://es5.github.io/#x15.1.2.4) +for more details. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is `NaN`, else `false`. + +#### Example +```js +_.isNaN(NaN); +// => true + +_.isNaN(new Number(NaN)); +// => true + +isNaN(undefined); +// => true + +_.isNaN(undefined); +// => false +``` +* * * + + + + + +### `_.isNative(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8113 "View in source") [Ⓣ][1] + +Checks if `value` is a native function. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is a native function, else `false`. + +#### Example +```js +_.isNative(Array.prototype.push); +// => true + +_.isNative(_); +// => false +``` +* * * + + + + + +### `_.isNull(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8140 "View in source") [Ⓣ][1] + +Checks if `value` is `null`. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is `null`, else `false`. + +#### Example +```js +_.isNull(null); +// => true + +_.isNull(void 0); +// => false +``` +* * * + + + + + +### `_.isNumber(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8166 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a `Number` primitive or object. + *Note:** To exclude `Infinity`, `-Infinity`, and `NaN`, which are classified +as numbers, use the `_.isFinite` method. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isNumber(8.4); +// => true + +_.isNumber(NaN); +// => true + +_.isNumber('8.4'); +// => false +``` +* * * + + + + + +### `_.isObject(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L7996 "View in source") [Ⓣ][1] + +Checks if `value` is the language type of `Object`. +(e.g. arrays, functions, objects, regexes, `new Number(0)`, and `new String('')`) + *Note:** See the [ES5 spec](https://es5.github.io/#x8) for more details. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is an object, else `false`. + +#### Example +```js +_.isObject({}); +// => true + +_.isObject([1, 2, 3]); +// => true + +_.isObject(1); +// => false +``` +* * * + + + + + +### `_.isPlainObject(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8200 "View in source") [Ⓣ][1] + +Checks if `value` is a plain object, that is, an object created by the +`Object` constructor or one with a `[[Prototype]]` of `null`. + *Note:** This method assumes objects created by the `Object` constructor +have no inherited enumerable properties. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is a plain object, else `false`. + +#### Example +```js +function Foo() { + this.a = 1; +} + +_.isPlainObject(new Foo); +// => false + +_.isPlainObject([1, 2, 3]); +// => false + +_.isPlainObject({ 'x': 0, 'y': 0 }); +// => true + +_.isPlainObject(Object.create(null)); +// => true +``` +* * * + + + + + +### `_.isRegExp(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8228 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a `RegExp` object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isRegExp(/abc/); +// => true + +_.isRegExp('/abc/'); +// => false +``` +* * * + + + + + +### `_.isString(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8248 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a `String` primitive or object. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isString('abc'); +// => true + +_.isString(1); +// => false +``` +* * * + + + + + +### `_.isTypedArray(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8268 "View in source") [Ⓣ][1] + +Checks if `value` is classified as a typed array. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is correctly classified, else `false`. + +#### Example +```js +_.isTypedArray(new Uint8Array); +// => true + +_.isTypedArray([]); +// => false +``` +* * * + + + + + +### `_.isUndefined(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8288 "View in source") [Ⓣ][1] + +Checks if `value` is `undefined`. + +#### Arguments +1. `value` *(*)*: The value to check. + +#### Returns +*(boolean)*: Returns `true` if `value` is `undefined`, else `false`. + +#### Example +```js +_.isUndefined(void 0); +// => true + +_.isUndefined(null); +// => false +``` +* * * + + + + + +### `_.toArray(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8305 "View in source") [Ⓣ][1] + +Converts `value` to an array. + +#### Arguments +1. `value` *(*)*: The value to convert. + +#### Returns +*(Array)*: Returns the converted array. + +#### Example +```js +(function() { return _.toArray(arguments).slice(1); })(1, 2, 3); +// => [2, 3] +``` +* * * + + + + + +### `_.toPlainObject(value)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8341 "View in source") [Ⓣ][1] + +Converts `value` to a plain object flattening inherited enumerable +properties of `value` to own properties of the plain object. + +#### Arguments +1. `value` *(*)*: The value to convert. + +#### Returns +*(Object)*: Returns the converted plain object. + +#### Example +```js +function Foo() { + this.b = 2; +} + +Foo.prototype.c = 3; + +_.assign({ 'a': 1 }, new Foo); +// => { 'a': 1, 'b': 2 } + +_.assign({ 'a': 1 }, _.toPlainObject(new Foo)); +// => { 'a': 1, 'b': 2, 'c': 3 } +``` +* * * + + + + + + + +## `“Number” Methods` + + + +### `_.random([min=0], [max=1], [floating])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9228 "View in source") [Ⓣ][1] + +Produces a random number between `min` and `max` (inclusive). If only one +argument is provided a number between `0` and the given number is returned. +If `floating` is `true`, or either `min` or `max` are floats, a floating-point +number is returned instead of an integer. + +#### Arguments +1. `[min=0]` *(number)*: The minimum possible value. +2. `[max=1]` *(number)*: The maximum possible value. +3. `[floating]` *(boolean)*: Specify returning a floating-point number. + +#### Returns +*(number)*: Returns the random number. + +#### Example +```js +_.random(0, 5); +// => an integer between 0 and 5 + +_.random(5); +// => also an integer between 0 and 5 + +_.random(5, true); +// => a floating-point number between 0 and 5 + +_.random(1.2, 5.2); +// => a floating-point number between 1.2 and 5.2 +``` +* * * + + + + + + + +## `“Object” Methods` + + + +### `_.assign(object, [sources], [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8376 "View in source") [Ⓣ][1] + +Assigns own enumerable properties of source object(s) to the destination +object. Subsequent sources overwrite property assignments of previous sources. +If `customizer` is provided it is invoked to produce the assigned values. +The `customizer` is bound to `thisArg` and invoked with five arguments; +(objectValue, sourceValue, key, object, source). + +#### Arguments +1. `object` *(Object)*: The destination object. +2. `[sources]` *(...Object)*: The source objects. +3. `[customizer]` *(Function)*: The function to customize assigning values. +4. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +_.assign({ 'user': 'barney' }, { 'age': 40 }, { 'user': 'fred' }); +// => { 'user': 'fred', 'age': 40 } + +// using a customizer callback +var defaults = _.partialRight(_.assign, function(value, other) { + return typeof value == 'undefined' ? other : value; +}); + +defaults({ 'user': 'barney' }, { 'age': 36 }, { 'user': 'fred' }); +// => { 'user': 'barney', 'age': 36 } +``` +* * * + + + + + +### `_.create(prototype, [properties])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8410 "View in source") [Ⓣ][1] + +Creates an object that inherits from the given `prototype` object. If a +`properties` object is provided its own enumerable properties are assigned +to the created object. + +#### Arguments +1. `prototype` *(Object)*: The object to inherit from. +2. `[properties]` *(Object)*: The properties to assign to the object. + +#### Returns +*(Object)*: Returns the new object. + +#### Example +```js +function Shape() { + this.x = 0; + this.y = 0; +} + +function Circle() { + Shape.call(this); +} + +Circle.prototype = _.create(Shape.prototype, { 'constructor': Circle }); + +var circle = new Circle; +circle instanceof Circle; +// => true + +circle instanceof Shape; +// => true +``` +* * * + + + + + +### `_.defaults(object, [sources])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8434 "View in source") [Ⓣ][1] + +Assigns own enumerable properties of source object(s) to the destination +object for all destination properties that resolve to `undefined`. Once a +property is set, additional defaults of the same property are ignored. + +#### Arguments +1. `object` *(Object)*: The destination object. +2. `[sources]` *(...Object)*: The source objects. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +_.defaults({ 'user': 'barney' }, { 'age': 36 }, { 'user': 'fred' }); +// => { 'user': 'barney', 'age': 36 } +``` +* * * + + + + + +### `_.findKey(object, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8482 "View in source") [Ⓣ][1] + +This method is like `_.findIndex` except that it returns the key of the +first element `predicate` returns truthy for, instead of the element itself. + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `object` *(Object)*: The object to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(string|undefined)*: Returns the key of the matched element, else `undefined`. + +#### Example +```js +var users = { + 'barney': { 'age': 36, 'active': true }, + 'fred': { 'age': 40, 'active': false }, + 'pebbles': { 'age': 1, 'active': true } +}; + +_.findKey(users, function(chr) { return chr.age < 40; }); +// => 'barney' (iteration order is not guaranteed) + +// using the "_.matches" callback shorthand +_.findKey(users, { 'age': 1 }); +// => 'pebbles' + +// using the "_.property" callback shorthand +_.findKey(users, 'active'); +// => 'barney' +``` +* * * + + + + + +### `_.findLastKey(object, [predicate=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8526 "View in source") [Ⓣ][1] + +This method is like `_.findKey` except that it iterates over elements of +a collection in the opposite order. + +If a property name is provided for `predicate` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `predicate` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `object` *(Object)*: The object to search. +2. `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(string|undefined)*: Returns the key of the matched element, else `undefined`. + +#### Example +```js +var users = { + 'barney': { 'age': 36, 'active': true }, + 'fred': { 'age': 40, 'active': false }, + 'pebbles': { 'age': 1, 'active': true } +}; + +_.findLastKey(users, function(chr) { return chr.age < 40; }); +// => returns `pebbles` assuming `_.findKey` returns `barney` + +// using the "_.matches" callback shorthand +_.findLastKey(users, { 'age': 36 }); +// => 'barney' + +// using the "_.property" callback shorthand +_.findLastKey(users, 'active'); +// => 'pebbles' +``` +* * * + + + + + +### `_.forIn(object, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8558 "View in source") [Ⓣ][1] + +Iterates over own and inherited enumerable properties of an object invoking +`iteratee` for each property. The `iteratee` is bound to `thisArg` and invoked +with three arguments; (value, key, object). Iterator functions may exit +iteration early by explicitly returning `false`. + +#### Arguments +1. `object` *(Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.forIn(new Foo, function(value, key) { + console.log(key); +}); +// => logs 'a', 'b', and 'c' (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.forInRight(object, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8590 "View in source") [Ⓣ][1] + +This method is like `_.forIn` except that it iterates over properties of +`object` in the opposite order. + +#### Arguments +1. `object` *(Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.forInRight(new Foo, function(value, key) { + console.log(key); +}); +// => logs 'c', 'b', and 'a' assuming `_.forIn ` logs 'a', 'b', and 'c' +``` +* * * + + + + + +### `_.forOwn(object, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8615 "View in source") [Ⓣ][1] + +Iterates over own enumerable properties of an object invoking `iteratee` +for each property. The `iteratee` is bound to `thisArg` and invoked with +three arguments; (value, key, object). Iterator functions may exit iteration +early by explicitly returning `false`. + +#### Arguments +1. `object` *(Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +_.forOwn({ '0': 'zero', '1': 'one', 'length': 2 }, function(n, key) { + console.log(key); +}); +// => logs '0', '1', and 'length' (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.forOwnRight(object, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8640 "View in source") [Ⓣ][1] + +This method is like `_.forOwn` except that it iterates over properties of +`object` in the opposite order. + +#### Arguments +1. `object` *(Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +_.forOwnRight({ '0': 'zero', '1': 'one', 'length': 2 }, function(n, key) { + console.log(key); +}); +// => logs 'length', '1', and '0' assuming `_.forOwn` logs '0', '1', and 'length' +``` +* * * + + + + + +### `_.functions(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8660 "View in source") [Ⓣ][1] + +Creates an array of function property names from all enumerable properties, +own and inherited, of `object`. + +#### Arguments +1. `object` *(Object)*: The object to inspect. + +#### Returns +*(Array)*: Returns the new array of property names. + +#### Example +```js +_.functions(_); +// => ['all', 'any', 'bind', ...] +``` +* * * + + + + + +### `_.has(object, key)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8679 "View in source") [Ⓣ][1] + +Checks if `key` exists as a direct property of `object` instead of an +inherited property. + +#### Arguments +1. `object` *(Object)*: The object to inspect. +2. `key` *(string)*: The key to check. + +#### Returns +*(boolean)*: Returns `true` if `key` is a direct property, else `false`. + +#### Example +```js +_.has({ 'a': 1, 'b': 2, 'c': 3 }, 'b'); +// => true +``` +* * * + + + + + +### `_.invert(object, [multiValue])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8708 "View in source") [Ⓣ][1] + +Creates an object composed of the inverted keys and values of `object`. +If `object` contains duplicate values, subsequent values overwrite property +assignments of previous values unless `multiValue` is `true`. + +#### Arguments +1. `object` *(Object)*: The object to invert. +2. `[multiValue]` *(boolean)*: Allow multiple values per key. + +#### Returns +*(Object)*: Returns the new inverted object. + +#### Example +```js +_.invert({ 'first': 'fred', 'second': 'barney' }); +// => { 'fred': 'first', 'barney': 'second' } + +// without `multiValue` +_.invert({ 'first': 'fred', 'second': 'barney', 'third': 'fred' }); +// => { 'fred': 'third', 'barney': 'second' } + +// with `multiValue` +_.invert({ 'first': 'fred', 'second': 'barney', 'third': 'fred' }, true); +// => { 'fred': ['first', 'third'], 'barney': ['second'] } +``` +* * * + + + + + +### `_.keys(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8762 "View in source") [Ⓣ][1] + +Creates an array of the own enumerable property names of `object`. + *Note:** Non-object values are coerced to objects. See the +[ES spec](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-object.keys) +for more details. + +#### Arguments +1. `object` *(Object)*: The object to inspect. + +#### Returns +*(Array)*: Returns the array of property names. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.keys(new Foo); +// => ['a', 'b'] (iteration order is not guaranteed) + +_.keys('hi'); +// => ['0', '1'] +``` +* * * + + + + + +### `_.keysIn(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8796 "View in source") [Ⓣ][1] + +Creates an array of the own and inherited enumerable property names of `object`. + *Note:** Non-object values are coerced to objects. + +#### Arguments +1. `object` *(Object)*: The object to inspect. + +#### Returns +*(Array)*: Returns the array of property names. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.keysIn(new Foo); +// => ['a', 'b', 'c'] (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.mapValues(object, [iteratee=_.identity], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8890 "View in source") [Ⓣ][1] + +Creates an object with the same keys as `object` and values generated by +running each own enumerable property of `object` through `iteratee`. The +iteratee function is bound to `thisArg` and invoked with three arguments; +(value, key, object). + +If a property name is provided for `iteratee` the created "_.property" +style callback returns the property value of the given element. + +If an object is provided for `iteratee` the created "_.matches" style +callback returns `true` for elements that have the properties of the given +object, else `false`. + +#### Arguments +1. `object` *(Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function|Object|string)*: The function invoked per iteration. If a property name or object is provided it is used to create a "_.property" or "_.matches" style callback respectively. +3. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(Object)*: Returns the new mapped object. + +#### Example +```js +_.mapValues({ 'a': 1, 'b': 2, 'c': 3} , function(n) { return n * 3; }); +// => { 'a': 3, 'b': 6, 'c': 9 } + +var users = { + 'fred': { 'user': 'fred', 'age': 40 }, + 'pebbles': { 'user': 'pebbles', 'age': 1 } +}; + +// using the "_.property" callback shorthand +_.mapValues(users, 'age'); +// => { 'fred': 40, 'pebbles': 1 } (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.merge(object, [sources], [customizer], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8946 "View in source") [Ⓣ][1] + +Recursively merges own enumerable properties of the source object(s), that +don't resolve to `undefined` into the destination object. Subsequent sources +overwrite property assignments of previous sources. If `customizer` is +provided it is invoked to produce the merged values of the destination and +source properties. If `customizer` returns `undefined` merging is handled +by the method instead. The `customizer` is bound to `thisArg` and invoked +with five arguments; (objectValue, sourceValue, key, object, source). + +#### Arguments +1. `object` *(Object)*: The destination object. +2. `[sources]` *(...Object)*: The source objects. +3. `[customizer]` *(Function)*: The function to customize merging properties. +4. `[thisArg]` *(*)*: The `this` binding of `customizer`. + +#### Returns +*(Object)*: Returns `object`. + +#### Example +```js +var users = { + 'data': [{ 'user': 'barney' }, { 'user': 'fred' }] +}; + +var ages = { + 'data': [{ 'age': 36 }, { 'age': 40 }] +}; + +_.merge(users, ages); +// => { 'data': [{ 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }] } + +// using a customizer callback +var object = { + 'fruits': ['apple'], + 'vegetables': ['beet'] +}; + +var other = { + 'fruits': ['banana'], + 'vegetables': ['carrot'] +}; + +_.merge(object, other, function(a, b) { + return _.isArray(a) ? a.concat(b) : undefined; +}); +// => { 'fruits': ['apple', 'banana'], 'vegetables': ['beet', 'carrot'] } +``` +* * * + + + + + +### `_.omit(object, [predicate], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L8976 "View in source") [Ⓣ][1] + +The opposite of `_.pick`; this method creates an object composed of the +own and inherited enumerable properties of `object` that are not omitted. +Property names may be specified as individual arguments or as arrays of +property names. If `predicate` is provided it is invoked for each property +of `object` omitting the properties `predicate` returns truthy for. The +predicate is bound to `thisArg` and invoked with three arguments; +(value, key, object). + +#### Arguments +1. `object` *(Object)*: The source object. +2. `[predicate]` *(Function|...(string|string[])*: The function invoked per iteration or property names to omit, specified as individual property names or arrays of property names. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Object)*: Returns the new object. + +#### Example +```js +var object = { 'user': 'fred', 'age': 40 }; + +_.omit(object, 'age'); +// => { 'user': 'fred' } + +_.omit(object, _.isNumber); +// => { 'user': 'fred' } +``` +* * * + + + + + +### `_.pairs(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9004 "View in source") [Ⓣ][1] + +Creates a two dimensional array of the key-value pairs for `object`, +e.g. `[[key1, value1], [key2, value2]]`. + +#### Arguments +1. `object` *(Object)*: The object to inspect. + +#### Returns +*(Array)*: Returns the new array of key-value pairs. + +#### Example +```js +_.pairs({ 'barney': 36, 'fred': 40 }); +// => [['barney', 36], ['fred', 40]] (iteration order is not guaranteed) +``` +* * * + + + + + +### `_.pick(object, [predicate], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9043 "View in source") [Ⓣ][1] + +Creates an object composed of the picked `object` properties. Property +names may be specified as individual arguments or as arrays of property +names. If `predicate` is provided it is invoked for each property of `object` +picking the properties `predicate` returns truthy for. The predicate is +bound to `thisArg` and invoked with three arguments; (value, key, object). + +#### Arguments +1. `object` *(Object)*: The source object. +2. `[predicate]` *(Function|...(string|string[])*: The function invoked per iteration or property names to pick, specified as individual property names or arrays of property names. +3. `[thisArg]` *(*)*: The `this` binding of `predicate`. + +#### Returns +*(Object)*: Returns the new object. + +#### Example +```js +var object = { 'user': 'fred', 'age': 40 }; + +_.pick(object, 'user'); +// => { 'user': 'fred' } + +_.pick(object, _.isString); +// => { 'user': 'fred' } +``` +* * * + + + + + +### `_.result(object, key, [defaultValue])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9082 "View in source") [Ⓣ][1] + +Resolves the value of property `key` on `object`. If the value of `key` is +a function it is invoked with the `this` binding of `object` and its result +is returned, else the property value is returned. If the property value is +`undefined` the `defaultValue` is used in its place. + +#### Arguments +1. `object` *(Object)*: The object to query. +2. `key` *(string)*: The key of the property to resolve. +3. `[defaultValue]` *(*)*: The value returned if the property value resolves to `undefined`. + +#### Returns +*(*)*: Returns the resolved value. + +#### Example +```js +var object = { 'user': 'fred', 'age': _.constant(40) }; + +_.result(object, 'user'); +// => 'fred' + +_.result(object, 'age'); +// => 40 + +_.result(object, 'status', 'busy'); +// => 'busy' + +_.result(object, 'status', _.constant('busy')); +// => 'busy' +``` +* * * + + + + + +### `_.transform(object, [iteratee=_.identity], [accumulator], [thisArg])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9121 "View in source") [Ⓣ][1] + +An alternative to `_.reduce`; this method transforms `object` to a new +`accumulator` object which is the result of running each of its own enumerable +properties through `iteratee`, with each invocation potentially mutating +the `accumulator` object. The `iteratee` is bound to `thisArg` and invoked +with four arguments; (accumulator, value, key, object). Iterator functions +may exit iteration early by explicitly returning `false`. + +#### Arguments +1. `object` *(Array|Object)*: The object to iterate over. +2. `[iteratee=_.identity]` *(Function)*: The function invoked per iteration. +3. `[accumulator]` *(*)*: The custom accumulator value. +4. `[thisArg]` *(*)*: The `this` binding of `iteratee`. + +#### Returns +*(*)*: Returns the accumulated value. + +#### Example +```js +var squares = _.transform([1, 2, 3, 4, 5, 6], function(result, n) { + n *= n; + if (n % 2) { + return result.push(n) < 3; + } +}); +// => [1, 9, 25] + +var mapped = _.transform({ 'a': 1, 'b': 2, 'c': 3 }, function(result, n, key) { + result[key] = n * 3; +}); +// => { 'a': 3, 'b': 6, 'c': 9 } +``` +* * * + + + + + +### `_.values(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9168 "View in source") [Ⓣ][1] + +Creates an array of the own enumerable property values of `object`. + *Note:** Non-object values are coerced to objects. + +#### Arguments +1. `object` *(Object)*: The object to query. + +#### Returns +*(Array)*: Returns the array of property values. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.values(new Foo); +// => [1, 2] (iteration order is not guaranteed) + +_.values('hi'); +// => ['h', 'i'] +``` +* * * + + + + + +### `_.valuesIn(object)` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9195 "View in source") [Ⓣ][1] + +Creates an array of the own and inherited enumerable property values +of `object`. + *Note:** Non-object values are coerced to objects. + +#### Arguments +1. `object` *(Object)*: The object to query. + +#### Returns +*(Array)*: Returns the array of property values. + +#### Example +```js +function Foo() { + this.a = 1; + this.b = 2; +} + +Foo.prototype.c = 3; + +_.valuesIn(new Foo); +// => [1, 2, 3] (iteration order is not guaranteed) +``` +* * * + + + + + + + +## `“String” Methods` + + + +### `_.camelCase([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9285 "View in source") [Ⓣ][1] + +Converts `string` to camel case. +See [Wikipedia](https://en.wikipedia.org/wiki/CamelCase) for more details. + +#### Arguments +1. `[string='']` *(string)*: The string to convert. + +#### Returns +*(string)*: Returns the camel cased string. + +#### Example +```js +_.camelCase('Foo Bar'); +// => 'fooBar' + +_.camelCase('--foo-bar'); +// => 'fooBar' + +_.camelCase('__foo_bar__'); +// => 'fooBar' +``` +* * * + + + + + +### `_.capitalize([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9303 "View in source") [Ⓣ][1] + +Capitalizes the first character of `string`. + +#### Arguments +1. `[string='']` *(string)*: The string to capitalize. + +#### Returns +*(string)*: Returns the capitalized string. + +#### Example +```js +_.capitalize('fred'); +// => 'Fred' +``` +* * * + + + + + +### `_.deburr([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9323 "View in source") [Ⓣ][1] + +Deburrs `string` by converting latin-1 supplementary letters to basic latin letters. +See [Wikipedia](https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)#Character_table) +for more details. + +#### Arguments +1. `[string='']` *(string)*: The string to deburr. + +#### Returns +*(string)*: Returns the deburred string. + +#### Example +```js +_.deburr('déjà vu'); +// => 'deja vu' +``` +* * * + + + + + +### `_.endsWith([string=''], [target], [position=string.length])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9349 "View in source") [Ⓣ][1] + +Checks if `string` ends with the given target string. + +#### Arguments +1. `[string='']` *(string)*: The string to search. +2. `[target]` *(string)*: The string to search for. +3. `[position=string.length]` *(number)*: The position to search from. + +#### Returns +*(boolean)*: Returns `true` if `string` ends with `target`, else `false`. + +#### Example +```js +_.endsWith('abc', 'c'); +// => true + +_.endsWith('abc', 'b'); +// => false + +_.endsWith('abc', 'b', 2); +// => true +``` +* * * + + + + + +### `_.escape([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9390 "View in source") [Ⓣ][1] + +Converts the characters "&", "<", ">", '"', "'", and '`', in `string` to +their corresponding HTML entities. + *Note:** No other characters are escaped. To escape additional characters +use a third-party library like [_he_](https://mths.be/he). + +Though the ">" character is escaped for symmetry, characters like +">" and "/" don't require escaping in HTML and have no special meaning +unless they're part of a tag or unquoted attribute value. +See [Mathias Bynens's article](https://mathiasbynens.be/notes/ambiguous-ampersands) +(under "semi-related fun fact") for more details. + +Backticks are escaped because in Internet Explorer < 9, they can break out +of attribute values or HTML comments. See [#102](https://html5sec.org/#102), +[#108](https://html5sec.org/#108), and [#133](https://html5sec.org/#133) of +the [HTML5 Security Cheatsheet](https://html5sec.org/) for more details. + +When working with HTML you should always quote attribute values to reduce +XSS vectors. See [Ryan Grove's article](http://wonko.com/post/html-escaping) +for more details. + +#### Arguments +1. `[string='']` *(string)*: The string to escape. + +#### Returns +*(string)*: Returns the escaped string. + +#### Example +```js +_.escape('fred, barney, & pebbles'); +// => 'fred, barney, & pebbles' +``` +* * * + + + + + +### `_.escapeRegExp([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9412 "View in source") [Ⓣ][1] + +Escapes the `RegExp` special characters "\", "^", "$", ".", "|", "?", "*", +"+", "(", ")", "[", "]", "{" and "}" in `string`. + +#### Arguments +1. `[string='']` *(string)*: The string to escape. + +#### Returns +*(string)*: Returns the escaped string. + +#### Example +```js +_.escapeRegExp('[lodash](https://lodash.com/)'); +// => '\[lodash\]\(https://lodash\.com/\)' +``` +* * * + + + + + +### `_.kebabCase([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9440 "View in source") [Ⓣ][1] + +Converts `string` to kebab case (a.k.a. spinal case). +See [Wikipedia](https://en.wikipedia.org/wiki/Letter_case#Computers) for +more details. + +#### Arguments +1. `[string='']` *(string)*: The string to convert. + +#### Returns +*(string)*: Returns the kebab cased string. + +#### Example +```js +_.kebabCase('Foo Bar'); +// => 'foo-bar' + +_.kebabCase('fooBar'); +// => 'foo-bar' + +_.kebabCase('__foo_bar__'); +// => 'foo-bar' +``` +* * * + + + + + +### `_.pad([string=''], [length=0], [chars=' '])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9467 "View in source") [Ⓣ][1] + +Pads `string` on the left and right sides if it is shorter then the given +padding length. The `chars` string may be truncated if the number of padding +characters can't be evenly divided by the padding length. + +#### Arguments +1. `[string='']` *(string)*: The string to pad. +2. `[length=0]` *(number)*: The padding length. +3. `[chars=' ']` *(string)*: The string used as padding. + +#### Returns +*(string)*: Returns the padded string. + +#### Example +```js +_.pad('abc', 8); +// => ' abc ' + +_.pad('abc', 8, '_-'); +// => '_-abc_-_' + +_.pad('abc', 3); +// => 'abc' +``` +* * * + + + + + +### `_.padLeft([string=''], [length=0], [chars=' '])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9506 "View in source") [Ⓣ][1] + +Pads `string` on the left side if it is shorter then the given padding +length. The `chars` string may be truncated if the number of padding +characters exceeds the padding length. + +#### Arguments +1. `[string='']` *(string)*: The string to pad. +2. `[length=0]` *(number)*: The padding length. +3. `[chars=' ']` *(string)*: The string used as padding. + +#### Returns +*(string)*: Returns the padded string. + +#### Example +```js +_.padLeft('abc', 6); +// => ' abc' + +_.padLeft('abc', 6, '_-'); +// => '_-_abc' + +_.padLeft('abc', 3); +// => 'abc' +``` +* * * + + + + + +### `_.padRight([string=''], [length=0], [chars=' '])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9534 "View in source") [Ⓣ][1] + +Pads `string` on the right side if it is shorter then the given padding +length. The `chars` string may be truncated if the number of padding +characters exceeds the padding length. + +#### Arguments +1. `[string='']` *(string)*: The string to pad. +2. `[length=0]` *(number)*: The padding length. +3. `[chars=' ']` *(string)*: The string used as padding. + +#### Returns +*(string)*: Returns the padded string. + +#### Example +```js +_.padRight('abc', 6); +// => 'abc ' + +_.padRight('abc', 6, '_-'); +// => 'abc_-_' + +_.padRight('abc', 3); +// => 'abc' +``` +* * * + + + + + +### `_.parseInt(string, [radix])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9562 "View in source") [Ⓣ][1] + +Converts `string` to an integer of the specified radix. If `radix` is +`undefined` or `0`, a `radix` of `10` is used unless `value` is a hexadecimal, +in which case a `radix` of `16` is used. + *Note:** This method aligns with the ES5 implementation of `parseInt`. +See the [ES5 spec](https://es5.github.io/#E) for more details. + +#### Arguments +1. `string` *(string)*: The string to convert. +2. `[radix]` *(number)*: The radix to interpret `value` by. + +#### Returns +*(number)*: Returns the converted integer. + +#### Example +```js +_.parseInt('08'); +// => 8 + +_.map(['6', '08', '10'], _.parseInt); +// => [6, 8, 10] +``` +* * * + + + + + +### `_.repeat([string=''], [n=0])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9604 "View in source") [Ⓣ][1] + +Repeats the given string `n` times. + +#### Arguments +1. `[string='']` *(string)*: The string to repeat. +2. `[n=0]` *(number)*: The number of times to repeat the string. + +#### Returns +*(string)*: Returns the repeated string. + +#### Example +```js +_.repeat('*', 3); +// => '***' + +_.repeat('abc', 2); +// => 'abcabc' + +_.repeat('abc', 0); +// => '' +``` +* * * + + + + + +### `_.snakeCase([string=''])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9644 "View in source") [Ⓣ][1] + +Converts `string` to snake case. +See [Wikipedia](https://en.wikipedia.org/wiki/Snake_case) for more details. + +#### Arguments +1. `[string='']` *(string)*: The string to convert. + +#### Returns +*(string)*: Returns the snake cased string. + +#### Example +```js +_.snakeCase('Foo Bar'); +// => 'foo_bar' + +_.snakeCase('--foo-bar'); +// => 'foo_bar' + +_.snakeCase('fooBar'); +// => 'foo_bar' +``` +* * * + + + + + +### `_.startsWith([string=''], [target], [position=0])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9669 "View in source") [Ⓣ][1] + +Checks if `string` starts with the given target string. + +#### Arguments +1. `[string='']` *(string)*: The string to search. +2. `[target]` *(string)*: The string to search for. +3. `[position=0]` *(number)*: The position to search from. + +#### Returns +*(boolean)*: Returns `true` if `string` starts with `target`, else `false`. + +#### Example +```js +_.startsWith('abc', 'a'); +// => true + +_.startsWith('abc', 'b'); +// => false + +_.startsWith('abc', 'b', 1); +// => true +``` +* * * + + + + + +### `_.template([string=''], [options], [options.escape], [options.evaluate], [options.imports], [options.interpolate], [options.sourceURL], [options.variable])` +# [Ⓢ](https://github.com/lodash/lodash/blob/3.0.0/lodash.src.js#L9771 "View in source") [Ⓣ][1] + +Creates a compiled template function that can interpolate data properties +in "interpolate" delimiters, HTML-escape interpolated data properties in +"escape" delimiters, and execute JavaScript in "evaluate" delimiters. Data +properties may be accessed as free variables in the template. If a setting +object is provided it takes precedence over `_.templateSettings` values. + *Note:** In the development build `_.template` utilizes sourceURLs for easier debugging. +See the [HTML5 Rocks article on sourcemaps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/#toc-sourceurl) +for more details. + +For more information on precompiling templates see +[lodash's custom builds documentation](https://lodash.com/custom-builds). + +For more information on Chrome extension sandboxes see +[Chrome's extensions documentation](https://developer.chrome.com/extensions/sandboxingEval). + +#### Arguments +1. `[string='']` *(string)*: The template string. +2. `[options]` *(Object)*: The options object. +3. `[options.escape]` *(RegExp)*: The HTML "escape" delimiter. +4. `[options.evaluate]` *(RegExp)*: The "evaluate" delimiter. +5. `[options.imports]` *(Object)*: An object to import into the template as free variables. +6. `[options.interpolate]` *(RegExp)*: The "interpolate" delimiter. +7. `[options.sourceURL]` *(string)*: The sourceURL of the template's compiled source. +8. `[options.variable]` *(string)*: The data object variable name. + +#### Returns +*(Function)*: Returns the compiled template function. + +#### Example +```js +// using the "interpolate" delimiter to create a compiled template +var compiled = _.template('hello <%= user %>!'); +compiled({ 'user': 'fred' }); +// => 'hello fred!' + +// using the HTML "escape" delimiter to escape data property values +var compiled = _.template('<%- value %>'); +compiled({ 'value': '