lodash v3.10.1-pre（API中文）

一切关于lodash的使用请移步lodash 查看，本文档暂时只做翻译API。

Array

• _.chunk
• _.compact
• _.difference
• _.drop
• _.dropRight
• _.dropRightWhile
• _.dropWhile
• _.fill
• _.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
• _.unzipWith
• _.without
• _.xor
• _.zip
• _.zipObject
• _.zipWith

Chain

• _
• _.chain
• _.tap
• _.thru
• _.prototype.chain
• _.prototype.commit
• _.prototype.concat
• _.prototype.plant
• _.prototype.reverse
• _.prototype.run -> value
• _.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
• _.partition
• _.pluck
• _.reduce
• _.reduceRight
• _.reject
• _.sample
• _.select -> filter
• _.shuffle
• _.size
• _.some
• _.sortBy
• _.sortByAll
• _.sortByOrder
• _.where

Date

• _.now

Function

• _.after
• _.ary
• _.backflow -> flowRight
• _.before
• _.bind
• _.bindAll
• _.bindKey
• _.compose -> flowRight
• _.curry
• _.curryRight
• _.debounce
• _.defer
• _.delay
• _.flow
• _.flowRight
• _.memoize
• _.modArgs
• _.negate
• _.once
• _.partial
• _.partialRight
• _.rearg
• _.restParam
• _.spread
• _.throttle
• _.wrap

Lang

• _.clone
• _.cloneDeep
• _.eq -> isEqual
• _.gt
• _.gte
• _.isArguments
• _.isArray
• _.isBoolean
• _.isDate
• _.isElement
• _.isEmpty
• _.isEqual
• _.isError
• _.isFinite
• _.isFunction
• _.isMatch
• _.isNaN
• _.isNative
• _.isNull
• _.isNumber
• _.isObject
• _.isPlainObject
• _.isRegExp
• _.isString
• _.isTypedArray
• _.isUndefined
• _.lt
• _.lte
• _.toArray
• _.toPlainObject

Math

• _.add
• _.ceil
• _.floor
• _.max
• _.min
• _.round
• _.sum

Number

• _.inRange
• _.random

Object

• _.assign
• _.create
• _.defaults
• _.defaultsDeep
• _.extend -> assign
• _.findKey
• _.findLastKey
• _.forIn
• _.forInRight
• _.forOwn
• _.forOwnRight
• _.functions
• _.get
• _.has
• _.invert
• _.keys
• _.keysIn
• _.mapKeys
• _.mapValues
• _.merge
• _.methods -> functions
• _.omit
• _.pairs
• _.pick
• _.result
• _.set
• _.transform
• _.values
• _.valuesIn

String

• _.camelCase
• _.capitalize
• _.deburr
• _.endsWith
• _.escape
• _.escapeRegExp
• _.kebabCase
• _.pad
• _.padLeft
• _.padRight
• _.parseInt
• _.repeat
• _.snakeCase
• _.startCase
• _.startsWith
• _.template
• _.trim
• _.trimLeft
• _.trimRight
• _.trunc
• _.unescape
• _.words

Utility

• _.attempt
• _.callback
• _.constant
• _.identity
• _.iteratee -> callback
• _.matches
• _.matchesProperty
• _.method
• _.methodOf
• _.mixin
• _.noConflict
• _.noop
• _.property
• _.propertyOf
• _.range
• _.runInContext
• _.times
• _.uniqueId

Methods

• _.templateSettings.imports._

Properties

• _.VERSION
• _.support
• _.support.enumErrorProps
• _.support.enumPrototypes
• _.support.nonEnumShadows
• _.support.ownLast
• _.support.spliceObjects
• _.support.unindexedChars
• _.templateSettings
• _.templateSettings.escape
• _.templateSettings.evaluate
• _.templateSettings.imports
• _.templateSettings.interpolate
• _.templateSettings.variable

“Array” Methods

_.chunk(array, [size=1])

# Ⓢ Ⓣ Ⓝ

以size为步长分割array，如果array不能够被平均分配，最后一部分剩下的元素为一组。

参数

1. array (Array): 待分割的数组。
2. [size=1] (number): 步长.

返回值

(Array): 返回已分割新数组.

示例

_.chunk(['a', 'b', 'c', 'd'], 2);
// => [['a', 'b'], ['c', 'd']]

_.chunk(['a', 'b', 'c', 'd'], 3);
// => [['a', 'b', 'c'], ['d']]

_.compact(array)

# Ⓢ Ⓣ Ⓝ

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

_.compact([0, 1, false, 2, '', 3]);
// => [1, 2, 3]

_.difference(array, [values])

# Ⓢ Ⓣ Ⓝ

Creates an array of unique array values not included in the other provided arrays using SameValueZero for equality comparisons.

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

_.difference([1, 2, 3], [4, 2]);
// => [1, 3]

_.drop(array, [n=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

_.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])

# Ⓢ Ⓣ Ⓝ

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

_.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])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

If an object is provided for predicate the created _.matches style callback returns true for elements that match 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 iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the slice of array.

Example

_.dropRightWhile([1, 2, 3], function(n) {
  return n > 1;
});
// => [1]

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

// using the `_.matches` callback shorthand
_.pluck(_.dropRightWhile(users, { 'user': 'pebbles', 'active': false }), 'user');
// => ['barney', 'fred']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.dropRightWhile(users, 'active', false), 'user');
// => ['barney']

// using the `_.property` callback shorthand
_.pluck(_.dropRightWhile(users, 'active'), 'user');
// => ['barney', 'fred', 'pebbles']

_.dropWhile(array, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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 iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the slice of array.

Example

_.dropWhile([1, 2, 3], function(n) {
  return n < 3;
});
// => [3]

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': true }
];

// using the `_.matches` callback shorthand
_.pluck(_.dropWhile(users, { 'user': 'barney', 'active': false }), 'user');
// => ['fred', 'pebbles']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.dropWhile(users, 'active', false), 'user');
// => ['pebbles']

// using the `_.property` callback shorthand
_.pluck(_.dropWhile(users, 'active'), 'user');
// => ['barney', 'fred', 'pebbles']

_.fill(array, value, [start=0], [end=array.length])

# Ⓢ Ⓣ Ⓝ

Fills elements of array with value from start up to, but not including, end.

Note: This method mutates array.

Arguments

1. array (Array): The array to fill.
2. value (*): The value to fill array with.
3. [start=0] (number): The start position.
4. [end=array.length] (number): The end position.

Returns

(Array): Returns array.

Example

var array = [1, 2, 3];

_.fill(array, 'a');
console.log(array);
// => ['a', 'a', 'a']

_.fill(Array(3), 2);
// => [2, 2, 2]

_.fill([4, 6, 8], '*', 1, 2);
// => [4, '*', 8]

_.findIndex(array, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.
3. [thisArg] (*): The this binding of predicate.

Returns

(number): Returns the index of the found element, else -1.

Example

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': true }
];

_.findIndex(users, function(chr) {
  return chr.user == 'barney';
});
// => 0

// using the `_.matches` callback shorthand
_.findIndex(users, { 'user': 'fred', 'active': false });
// => 1

// using the `_.matchesProperty` callback shorthand
_.findIndex(users, 'active', false);
// => 0

// using the `_.property` callback shorthand
_.findIndex(users, 'active');
// => 2

_.findLastIndex(array, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.
3. [thisArg] (*): The this binding of predicate.

Returns

(number): Returns the index of the found element, else -1.

Example

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

_.findLastIndex(users, function(chr) {
  return chr.user == 'pebbles';
});
// => 2

// using the `_.matches` callback shorthand
_.findLastIndex(users, { 'user': 'barney', 'active': true });
// => 0

// using the `_.matchesProperty` callback shorthand
_.findLastIndex(users, 'active', false);
// => 2

// using the `_.property` callback shorthand
_.findLastIndex(users, 'active');
// => 0

_.first(array)

# Ⓢ Ⓣ Ⓝ

Gets the first element of array.

Aliases

_.head

Arguments

1. array (Array): The array to query.

Returns

(*): Returns the first element of array.

Example

_.first([1, 2, 3]);
// => 1

_.first([]);
// => undefined

_.flatten(array, [isDeep])

# Ⓢ Ⓣ Ⓝ

Flattens a nested array. If isDeep is true the array is recursively flattened, otherwise it's 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

_.flatten([1, [2, 3, [4]]]);
// => [1, 2, 3, [4]]

// using `isDeep`
_.flatten([1, [2, 3, [4]]], true);
// => [1, 2, 3, 4]

_.flattenDeep(array)

# Ⓢ Ⓣ Ⓝ

Recursively flattens a nested array.

Arguments

1. array (Array): The array to recursively flatten.

Returns

(Array): Returns the new flattened array.

Example

_.flattenDeep([1, [2, 3, [4]]]);
// => [1, 2, 3, 4]

_.indexOf(array, value, [fromIndex=0])

# Ⓢ Ⓣ Ⓝ

Gets the index at which the first occurrence of value is found in array using SameValueZero for equality comparisons. If fromIndex is negative, it's used as the offset from the end of array. If array is sorted providing true for fromIndex performs a faster binary search.

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

_.indexOf([1, 2, 1, 2], 2);
// => 1

// using `fromIndex`
_.indexOf([1, 2, 1, 2], 2, 2);
// => 3

// performing a binary search
_.indexOf([1, 1, 2, 2], 2, true);
// => 2

_.initial(array)

# Ⓢ Ⓣ Ⓝ

Gets all but the last element of array.

Arguments

1. array (Array): The array to query.

Returns

(Array): Returns the slice of array.

Example

_.initial([1, 2, 3]);
// => [1, 2]

_.intersection([arrays])

# Ⓢ Ⓣ Ⓝ

Creates an array of unique values that are included in all of the provided arrays using SameValueZero for equality comparisons.

Arguments

1. [arrays] (...Array): The arrays to inspect.

Returns

(Array): Returns the new array of shared values.

Example

_.intersection([1, 2], [4, 2], [2, 1]);
// => [2]

_.last(array)

# Ⓢ Ⓣ Ⓝ

Gets the last element of array.

Arguments

1. array (Array): The array to query.

Returns

(*): Returns the last element of array.

Example

_.last([1, 2, 3]);
// => 3

_.lastIndexOf(array, value, [fromIndex=array.length-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

_.lastIndexOf([1, 2, 1, 2], 2);
// => 3

// using `fromIndex`
_.lastIndexOf([1, 2, 1, 2], 2, 2);
// => 1

// performing a binary search
_.lastIndexOf([1, 1, 2, 2], 2, true);
// => 3

_.pull(array, [values])

# Ⓢ Ⓣ Ⓝ

Removes all provided values from array using SameValueZero for equality comparisons.

Note: Unlike _.without, this method mutates array.

Arguments

1. array (Array): The array to modify.
2. [values] (...*): The values to remove.

Returns

(Array): Returns array.

Example

var array = [1, 2, 3, 1, 2, 3];

_.pull(array, 2, 3);
console.log(array);
// => [1, 1]

_.pullAt(array, [indexes])

# Ⓢ Ⓣ Ⓝ

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

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])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the new array of removed elements.

Example

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)

# Ⓢ Ⓣ Ⓝ

Gets all but the first element of array.

Aliases

_.tail

Arguments

1. array (Array): The array to query.

Returns

(Array): Returns the slice of array.

Example

_.rest([1, 2, 3]);
// => [2, 3]

_.slice(array, [start=0], [end=array.length])

# Ⓢ Ⓣ Ⓝ

Creates a slice of array from start up to, but not including, end.

Note: This method 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])

# Ⓢ Ⓣ Ⓝ

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's 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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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. array (Array): The sorted array to inspect.
2. value (*): The value to evaluate.
3. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
4. [thisArg] (*): The this binding of iteratee.

Returns

(number): Returns the index at which value should be inserted into array.

Example

_.sortedIndex([30, 50], 40);
// => 1

_.sortedIndex([4, 4, 5, 5], 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])

# Ⓢ Ⓣ Ⓝ

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.
4. [thisArg] (*): The this binding of iteratee.

Returns

(number): Returns the index at which value should be inserted into array.

Example

_.sortedLastIndex([4, 4, 5, 5], 5);
// => 4

_.take(array, [n=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

_.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])

# Ⓢ Ⓣ Ⓝ

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

_.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])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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 iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the slice of array.

Example

_.takeRightWhile([1, 2, 3], function(n) {
  return n > 1;
});
// => [2, 3]

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

// using the `_.matches` callback shorthand
_.pluck(_.takeRightWhile(users, { 'user': 'pebbles', 'active': false }), 'user');
// => ['pebbles']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.takeRightWhile(users, 'active', false), 'user');
// => ['fred', 'pebbles']

// using the `_.property` callback shorthand
_.pluck(_.takeRightWhile(users, 'active'), 'user');
// => []

_.takeWhile(array, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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 iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the slice of array.

Example

_.takeWhile([1, 2, 3], function(n) {
  return n < 3;
});
// => [1, 2]

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false},
  { 'user': 'pebbles', 'active': true }
];

// using the `_.matches` callback shorthand
_.pluck(_.takeWhile(users, { 'user': 'barney', 'active': false }), 'user');
// => ['barney']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.takeWhile(users, 'active', false), 'user');
// => ['barney', 'fred']

// using the `_.property` callback shorthand
_.pluck(_.takeWhile(users, 'active'), 'user');
// => []

_.union([arrays])

# Ⓢ Ⓣ Ⓝ

Creates an array of unique values, in order, from all of the provided arrays using SameValueZero for equality comparisons.

Arguments

1. [arrays] (...Array): The arrays to inspect.

Returns

(Array): Returns the new array of combined values.

Example

_.union([1, 2], [4, 2], [2, 1]);
// => [1, 2, 4]

_.uniq(array, [isSorted], [iteratee], [thisArg])

# Ⓢ Ⓣ Ⓝ

Creates a duplicate-free version of an array, using SameValueZero for equality comparisons, in which only the first occurence of each element is kept. Providing true for isSorted performs a faster search algorithm for sorted arrays. If an iteratee function is provided it's invoked for each element 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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Aliases

_.unique

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.
4. [thisArg] (*): The this binding of iteratee.

Returns

(Array): Returns the new duplicate-value-free array.

Example

_.uniq([2, 1, 2]);
// => [2, 1]

// 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)

# Ⓢ Ⓣ Ⓝ

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

var zipped = _.zip(['fred', 'barney'], [30, 40], [true, false]);
// => [['fred', 30, true], ['barney', 40, false]]

_.unzip(zipped);
// => [['fred', 'barney'], [30, 40], [true, false]]

_.unzipWith(array, [iteratee], [thisArg])

# Ⓢ Ⓣ Ⓝ

This method is like _.unzip except that it accepts an iteratee to specify how regrouped values should be combined. The iteratee is bound to thisArg and invoked with four arguments: (accumulator, value, index, group).

Arguments

1. array (Array): The array of grouped elements to process.
2. [iteratee] (Function): The function to combine regrouped values.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Array): Returns the new array of regrouped elements.

Example

var zipped = _.zip([1, 2], [10, 20], [100, 200]);
// => [[1, 10, 100], [2, 20, 200]]

_.unzipWith(zipped, _.add);
// => [3, 30, 300]

_.without(array, [values])

# Ⓢ Ⓣ Ⓝ

Creates an array excluding all provided values using SameValueZero for equality comparisons.

Arguments

1. array (Array): The array to filter.
2. [values] (...*): The values to exclude.

Returns

(Array): Returns the new array of filtered values.

Example

_.without([1, 2, 1, 3], 1, 2);
// => [3]

_.xor([arrays])

# Ⓢ Ⓣ Ⓝ

Creates an array of unique values that is the symmetric difference of the provided arrays.

Arguments

1. [arrays] (...Array): The arrays to inspect.

Returns

(Array): Returns the new array of values.

Example

_.xor([1, 2], [4, 2]);
// => [1, 4]

_.zip([arrays])

# Ⓢ Ⓣ Ⓝ

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

_.zip(['fred', 'barney'], [30, 40], [true, false]);
// => [['fred', 30, true], ['barney', 40, false]]

_.zipObject(props, [values=[]])

# Ⓢ Ⓣ Ⓝ

The inverse of _.pairs; this method returns 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.

Aliases

_.object

Arguments

1. props (Array): The property names.
2. [values=[]] (Array): The property values.

Returns

(Object): Returns the new object.

Example

_.zipObject([['fred', 30], ['barney', 40]]);
// => { 'fred': 30, 'barney': 40 }

_.zipObject(['fred', 'barney'], [30, 40]);
// => { 'fred': 30, 'barney': 40 }

_.zipWith([arrays], [iteratee], [thisArg])

# Ⓢ Ⓣ Ⓝ

This method is like _.zip except that it accepts an iteratee to specify how grouped values should be combined. The iteratee is bound to thisArg and invoked with four arguments: (accumulator, value, index, group).

Arguments

1. [arrays] (...Array): The arrays to process.
2. [iteratee] (Function): The function to combine grouped values.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Array): Returns the new array of grouped elements.

Example

_.zipWith([1, 2], [10, 20], [100, 200], _.add);
// => [111, 222]

“Chain” Methods

_(value)

# Ⓢ Ⓣ

Creates a lodash object which wraps value to enable implicit chaining. Methods that operate on and return arrays, collections, and functions can be chained together. Methods that retrieve a single value or may return a primitive 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 strategy which merge iteratee calls; this can help to avoid the creation of intermediate data structures and greatly 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 have Array and String methods.

The wrapper Array methods are:
concat, join, pop, push, reverse, shift, slice, sort, splice, and unshift

The wrapper String methods are:
replace and split

The wrapper methods that support shortcut fusion are:
compact, drop, dropRight, dropRightWhile, dropWhile, filter, first, initial, last, map, pluck, reject, rest, reverse, slice, take, takeRight, takeRightWhile, takeWhile, toArray, and where

The chainable wrapper methods are:
after, ary, assign, at, before, bind, bindAll, bindKey, callback, chain, chunk, commit, compact, concat, constant, countBy, create, curry, debounce, defaults, defaultsDeep, defer, delay, difference, drop, dropRight, dropRightWhile, dropWhile, fill, filter, flatten, flattenDeep, flow, flowRight, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, functions, groupBy, indexBy, initial, intersection, invert, invoke, keys, keysIn, map, mapKeys, mapValues, matches, matchesProperty, memoize, merge, method, methodOf, mixin, modArgs, negate, omit, once, pairs, partial, partialRight, partition, pick, plant, pluck, property, propertyOf, pull, pullAt, push, range, rearg, reject, remove, rest, restParam, reverse, set, shuffle, slice, sort, sortBy, sortByAll, sortByOrder, splice, spread, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, times, toArray, toPlainObject, transform, union, uniq, unshift, unzip, unzipWith, values, valuesIn, where, without, wrap, xor, zip, zipObject, zipWith

The wrapper methods that are not chainable by default are:
add, attempt, camelCase, capitalize, ceil, clone, cloneDeep, deburr, endsWith, escape, escapeRegExp, every, find, findIndex, findKey, findLast, findLastIndex, findLastKey, findWhere, first, floor, get, gt, gte, has, identity, includes, indexOf, inRange, 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, lt, lte, max, min, noConflict, noop, now, pad, padLeft, padRight, parseInt, pop, random, reduce, reduceRight, repeat, result, round, runInContext, shift, size, snakeCase, some, sortedIndex, sortedLastIndex, startCase, startsWith, sum, template, trim, trimLeft, trimRight, trunc, unescape, uniqueId, value, and words

The wrapper method 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 the new lodash wrapper instance.

Example

var wrapped = _([1, 2, 3]);

// returns an unwrapped value
wrapped.reduce(function(total, n) {
  return total + n;
});
// => 6

// returns a wrapped value
var squares = wrapped.map(function(n) {
  return n * n;
});

_.isArray(squares);
// => false

_.isArray(squares.value());
// => true

_.chain(value)

# Ⓢ Ⓣ

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 wrapper instance.

Example

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])

# Ⓢ Ⓣ

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

_([1, 2, 3])
 .tap(function(array) {
   array.pop();
 })
 .reverse()
 .value();
// => [2, 1]

_.thru(value, interceptor, [thisArg])

# Ⓢ Ⓣ

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

_('  abc  ')
 .chain()
 .trim()
 .thru(function(value) {
   return [value];
 })
 .value();
// => ['abc']

_.prototype.chain()

# Ⓢ Ⓣ

Enables explicit method chaining on the wrapper object.

Returns

(Object): Returns the new lodash wrapper instance.

Example

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.commit()

# Ⓢ Ⓣ

Executes the chained sequence and returns the wrapped result.

Returns

(Object): Returns the new lodash wrapper instance.

Example

var array = [1, 2];
var wrapped = _(array).push(3);

console.log(array);
// => [1, 2]

wrapped = wrapped.commit();
console.log(array);
// => [1, 2, 3]

wrapped.last();
// => 3

console.log(array);
// => [1, 2, 3]

_.prototype.concat([values])

# Ⓢ Ⓣ

Creates a new array joining a wrapped array with any additional arrays and/or values.

Arguments

1. [values] (...*): The values to concatenate.

Returns

(Array): Returns the new concatenated array.

Example

var array = [1];
var wrapped = _(array).concat(2, [3], [[4]]);

console.log(wrapped.value());
// => [1, 2, 3, [4]]

console.log(array);
// => [1]

_.prototype.plant()

# Ⓢ Ⓣ

Creates a clone of the chained sequence planting value as the wrapped value.

Returns

(Object): Returns the new lodash wrapper instance.

Example

var array = [1, 2];
var wrapped = _(array).map(function(value) {
  return Math.pow(value, 2);
});

var other = [3, 4];
var otherWrapped = wrapped.plant(other);

otherWrapped.value();
// => [9, 16]

wrapped.value();
// => [1, 4]

_.prototype.reverse()

# Ⓢ Ⓣ

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 wrapper instance.

Example

var array = [1, 2, 3];

_(array).reverse().value()
// => [3, 2, 1]

console.log(array);
// => [3, 2, 1]

_.prototype.toString()

# Ⓢ Ⓣ

Produces the result of coercing the unwrapped value to a string.

Returns

(string): Returns the coerced string value.

Example

_([1, 2, 3]).toString();
// => '1,2,3'

_.prototype.value()

# Ⓢ Ⓣ

Executes the chained sequence to extract the unwrapped value.

Aliases

_.prototype.run, _.prototype.toJSON, _.prototype.valueOf

Returns

(*): Returns the resolved unwrapped value.

Example

_([1, 2, 3]).value();
// => [1, 2, 3]

“Collection” Methods

_.at(collection, [props])

# Ⓢ Ⓣ Ⓝ

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

_.at(['a', 'b', 'c'], [0, 2]);
// => ['a', 'c']

_.at(['barney', 'fred', 'pebbles'], 0, 2);
// => ['barney', 'pebbles']

_.countBy(collection, [iteratee=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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. collection (Array|Object|string): The collection to iterate over.
2. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Object): Returns the composed aggregate object.

Example

_.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])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Aliases

_.all

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. [predicate=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(boolean): Returns true if all elements pass the predicate check, else false.

Example

_.every([true, 1, null, 'yes'], Boolean);
// => false

var users = [
  { 'user': 'barney', 'active': false },
  { 'user': 'fred',   'active': false }
];

// using the `_.matches` callback shorthand
_.every(users, { 'user': 'barney', 'active': false });
// => false

// using the `_.matchesProperty` callback shorthand
_.every(users, 'active', false);
// => true

// using the `_.property` callback shorthand
_.every(users, 'active');
// => false

_.filter(collection, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Aliases

_.select

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. [predicate=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the new filtered array.

Example

_.filter([4, 5, 6], function(n) {
  return n % 2 == 0;
});
// => [4, 6]

var users = [
  { 'user': 'barney', 'age': 36, 'active': true },
  { 'user': 'fred',   'age': 40, 'active': false }
];

// using the `_.matches` callback shorthand
_.pluck(_.filter(users, { 'age': 36, 'active': true }), 'user');
// => ['barney']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.filter(users, 'active', false), 'user');
// => ['fred']

// using the `_.property` callback shorthand
_.pluck(_.filter(users, 'active'), 'user');
// => ['barney']

_.find(collection, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Aliases

_.detect

Arguments

1. collection (Array|Object|string): The collection to search.
2. [predicate=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(*): Returns the matched element, else undefined.

Example

var users = [
  { 'user': 'barney',  'age': 36, 'active': true },
  { 'user': 'fred',    'age': 40, 'active': false },
  { 'user': 'pebbles', 'age': 1,  'active': true }
];

_.result(_.find(users, function(chr) {
  return chr.age < 40;
}), 'user');
// => 'barney'

// using the `_.matches` callback shorthand
_.result(_.find(users, { 'age': 1, 'active': true }), 'user');
// => 'pebbles'

// using the `_.matchesProperty` callback shorthand
_.result(_.find(users, 'active', false), 'user');
// => 'fred'

// using the `_.property` callback shorthand
_.result(_.find(users, 'active'), 'user');
// => 'barney'

_.findLast(collection, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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.
3. [thisArg] (*): The this binding of predicate.

Returns

(*): Returns the matched element, else undefined.

Example

_.findLast([1, 2, 3, 4], function(n) {
  return n % 2 == 1;
});
// => 3

_.findWhere(collection, source)

# Ⓢ Ⓣ Ⓝ

Performs a deep comparison between each element in collection and the source object, returning the first element that has equivalent property values.

Note: This method supports comparing arrays, booleans, Date objects, numbers, Object objects, regexes, and strings. Objects are compared by their own, not inherited, enumerable properties. For comparing a single own or inherited property value see _.matchesProperty.

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

var users = [
  { 'user': 'barney', 'age': 36, 'active': true },
  { 'user': 'fred',   'age': 40, 'active': false }
];

_.result(_.findWhere(users, { 'age': 36, 'active': true }), 'user');
// => 'barney'

_.result(_.findWhere(users, { 'age': 40, 'active': false }), 'user');
// => 'fred'

_.forEach(collection, [iteratee=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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). Iteratee 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.

Aliases

_.each

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

_([1, 2]).forEach(function(n) {
  console.log(n);
}).value();
// => logs each value from left to right and returns the array

_.forEach({ 'a': 1, 'b': 2 }, 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])

# Ⓢ Ⓣ Ⓝ

This method is like _.forEach except that it iterates over elements of collection from right to left.

Aliases

_.eachRight

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

_([1, 2]).forEachRight(function(n) {
  console.log(n);
}).value();
// => logs each value from right to left and returns the array

_.groupBy(collection, [iteratee=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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. collection (Array|Object|string): The collection to iterate over.
2. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Object): Returns the composed aggregate object.

Example

_.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])

# Ⓢ Ⓣ Ⓝ

Checks if target is in collection using SameValueZero for equality comparisons. If fromIndex is negative, it's used as the offset from the end of collection.

Aliases

_.contains, _.include

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

_.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])

# Ⓢ Ⓣ Ⓝ

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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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. collection (Array|Object|string): The collection to iterate over.
2. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Object): Returns the composed aggregate object.

Example

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, path, [args])

# Ⓢ Ⓣ Ⓝ

Invokes the method at path of 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's invoked for, and this bound to, each element in collection.

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. path (Array|Function|string): The path 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

_.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])

# Ⓢ Ⓣ Ⓝ

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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Many lodash methods are guarded to work as iteratees for methods like _.every, _.filter, _.map, _.mapValues, _.reject, and _.some.

The guarded methods are:
ary, callback, chunk, clone, create, curry, curryRight, drop, dropRight, every, fill, flatten, invert, max, min, parseInt, slice, sortBy, take, takeRight, template, trim, trimLeft, trimRight, trunc, random, range, sample, some, sum, uniq, and words

Aliases

_.collect

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Array): Returns the new mapped array.

Example

function timesThree(n) {
  return n * 3;
}

_.map([1, 2], timesThree);
// => [3, 6]

_.map({ 'a': 1, 'b': 2 }, timesThree);
// => [3, 6] (iteration order is not guaranteed)

var users = [
  { 'user': 'barney' },
  { 'user': 'fred' }
];

// using the `_.property` callback shorthand
_.map(users, 'user');
// => ['barney', 'fred']

_.partition(collection, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the array of grouped elements.

Example

_.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.2, 3.4], [2.3]]

var users = [
  { 'user': 'barney',  'age': 36, 'active': false },
  { 'user': 'fred',    'age': 40, 'active': true },
  { 'user': 'pebbles', 'age': 1,  'active': false }
];

var mapper = function(array) {
  return _.pluck(array, 'user');
};

// using the `_.matches` callback shorthand
_.map(_.partition(users, { 'age': 1, 'active': false }), mapper);
// => [['pebbles'], ['barney', 'fred']]

// using the `_.matchesProperty` callback shorthand
_.map(_.partition(users, 'active', false), mapper);
// => [['barney', 'pebbles'], ['fred']]

// using the `_.property` callback shorthand
_.map(_.partition(users, 'active'), mapper);
// => [['fred'], ['barney', 'pebbles']]

_.pluck(collection, path)

# Ⓢ Ⓣ Ⓝ

Gets the property value of path from all elements in collection.

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. path (Array|string): The path of the property to pluck.

Returns

(Array): Returns the property values.

Example

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])

# Ⓢ Ⓣ Ⓝ

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).

Many lodash methods are guarded to work as iteratees for methods like _.reduce, _.reduceRight, and _.transform.

The guarded methods are:
assign, defaults, defaultsDeep, includes, merge, sortByAll, and sortByOrder

Aliases

_.foldl, _.inject

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

_.reduce([1, 2], function(total, n) {
  return total + n;
});
// => 3

_.reduce({ 'a': 1, 'b': 2 }, function(result, n, key) {
  result[key] = n * 3;
  return result;
}, {});
// => { 'a': 3, 'b': 6 } (iteration order is not guaranteed)

_.reduceRight(collection, [iteratee=_.identity], [accumulator], [thisArg])

# Ⓢ Ⓣ Ⓝ

This method is like _.reduce except that it iterates over elements of collection from right to left.

Aliases

_.foldr

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

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])

# Ⓢ Ⓣ Ⓝ

The opposite of _.filter; this method returns the elements of collection that predicate does not return truthy for.

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. [predicate=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(Array): Returns the new filtered array.

Example

_.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 `_.matches` callback shorthand
_.pluck(_.reject(users, { 'age': 40, 'active': true }), 'user');
// => ['barney']

// using the `_.matchesProperty` callback shorthand
_.pluck(_.reject(users, 'active', false), 'user');
// => ['fred']

// using the `_.property` callback shorthand
_.pluck(_.reject(users, 'active'), 'user');
// => ['barney']

_.sample(collection, [n])

# Ⓢ Ⓣ Ⓝ

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

_.sample([1, 2, 3, 4]);
// => 2

_.sample([1, 2, 3, 4], 2);
// => [3, 1]

_.shuffle(collection)

# Ⓢ Ⓣ Ⓝ

Creates an array of shuffled values, using a version of the Fisher-Yates shuffle.

Arguments

1. collection (Array|Object|string): The collection to shuffle.

Returns

(Array): Returns the new shuffled array.

Example

_.shuffle([1, 2, 3, 4]);
// => [4, 1, 3, 2]

_.size(collection)

# Ⓢ Ⓣ Ⓝ

Gets the size of collection by returning its 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

_.size([1, 2, 3]);
// => 3

_.size({ 'a': 1, 'b': 2 });
// => 2

_.size('pebbles');
// => 7

_.some(collection, [predicate=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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.

Aliases

_.any

Arguments

1. collection (Array|Object|string): The collection to iterate over.
2. [predicate=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of predicate.

Returns

(boolean): Returns true if any element passes the predicate check, else false.

Example

_.some([null, 0, 'yes', false], Boolean);
// => true

var users = [
  { 'user': 'barney', 'active': true },
  { 'user': 'fred',   'active': false }
];

// using the `_.matches` callback shorthand
_.some(users, { 'user': 'barney', 'active': false });
// => false

// using the `_.matchesProperty` callback shorthand
_.some(users, 'active', false);
// => true

// using the `_.property` callback shorthand
_.some(users, 'active');
// => true

_.sortBy(collection, [iteratee=_.identity], [thisArg])

# Ⓢ Ⓣ Ⓝ

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 iteratee the created _.property style callback returns the property value of the given element.

If a value is also provided for thisArg the created _.matchesProperty style callback returns true for elements that have a matching property value, else false.

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. collection (Array|Object|string): The collection to iterate over.
2. [iteratee=_.identity] (Function|Object|string): The function invoked per iteration.
3. [thisArg] (*): The this binding of iteratee.

Returns

(Array): Returns the new sorted array.

Example

_.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, iteratees)

# Ⓢ Ⓣ Ⓝ

This method is like _.sortBy except that it can sort by multiple iteratees or property names.

If a property name is provided for an iteratee the created _.property style callback returns the property value of the given element.

If an object is provided for an iteratee 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. iteratees (...(Function|Function[]|Object|Object[]|string|string[]): The iteratees to sort by, specified as individual values or arrays of values.

Returns

(Array): Returns the new sorted array.

Example

var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 36 },
  { 'user': 'fred',   'age': 42 },
  { 'user': 'barney', 'age': 34 }
];

_.map(_.sortByAll(users, ['user', 'age']), _.values);
// => [['barney', 34], ['barney', 36], ['fred', 42], ['fred', 48]]

_.map(_.sortByAll(users, 'user', function(chr) {
  return Math.floor(chr.age / 10);
}), _.values);
// => [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 42]]

_.sortByOrder(collection, iteratees, [orders])

# Ⓢ Ⓣ Ⓝ

This method is like _.sortByAll except that it allows specifying the sort orders of the iteratees to sort by. If orders is unspecified, all values are sorted in ascending order. Otherwise, a value is sorted in ascending order if its corresponding order is "asc", and descending if "desc".

If a property name is provided for an iteratee the created _.property style callback returns the property value of the given element.

If an object is provided for an iteratee 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. iteratees (Function[]|Object[]|string[]): The iteratees to sort by.
3. [orders] (boolean[]): The sort orders of iteratees.

Returns

(Array): Returns the new sorted array.

Example

var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 34 },
  { 'user': 'fred',   'age': 42 },
  { 'user': 'barney', 'age': 36 }
];

// sort by `user` in ascending order and by `age` in descending order
_.map(_.sortByOrder(users, ['user', 'age'], ['asc', 'desc']), _.values);
// => [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 42]]

_.where(collection, source)

# Ⓢ Ⓣ Ⓝ

Performs a deep comparison between each element in collection and the source object, returning an array of all elements that have equivalent property values.

Note: This method supports comparing arrays, booleans, Date objects, numbers, Object objects, regexes, and strings. Objects are compared by their own, not inherited, enumerable properties. For comparing a single own or inherited property value see _.matchesProperty.

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

var users = [
  { 'user': 'barney', 'age': 36, 'active': false, 'pets': ['hoppy'] },
  { 'user': 'fred',   'age': 40, 'active': true, 'pets': ['baby puss', 'dino'] }
];

_.pluck(_.where(users, { 'age': 36, 'active': false }), 'user');
// => ['barney']

_.pluck(_.where(users, { 'pets': ['dino'] }), 'user');
// => ['fred']

“Date” Methods

_.now

# Ⓢ Ⓣ Ⓝ

Gets the number of milliseconds that have elapsed since the Unix epoch (1 January 1970 00:00:00 UTC).

Example

_.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)

# Ⓢ Ⓣ Ⓝ

The opposite of _.before; this method creates a function that invokes func once it's 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

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, [n=func.length])

# Ⓢ Ⓣ Ⓝ

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

_.map(['6', '8', '10'], _.ary(parseInt, 1));
// => [6, 8, 10]

_.before(n, func)

# Ⓢ Ⓣ Ⓝ

Creates a function that invokes func, with the this binding and arguments of the created function, while it's 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

jQuery('#add').on('click', _.before(5, addContactToList));
// => allows adding up to 4 contacts to the list

_.bind(func, thisArg, [partials])

# Ⓢ Ⓣ Ⓝ

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. [partials] (...*): The arguments to be partially applied.

Returns

(Function): Returns the new bound function.

Example

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])

# Ⓢ Ⓣ Ⓝ

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

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, [partials])

# Ⓢ Ⓣ Ⓝ

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 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. [partials] (...*): The arguments to be partially applied.

Returns

(Function): Returns the new bound function.

Example

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, [arity=func.length])

# Ⓢ Ⓣ Ⓝ

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

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, [arity=func.length])

# Ⓢ Ⓣ Ⓝ

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

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=0], [options])

# Ⓢ Ⓣ Ⓝ

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked. The debounced 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 for details over the differences between _.debounce and _.throttle.

Arguments

1. func (Function): The function to debounce.
2. [wait=0] (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's invoked.
6. [options.trailing=true] (boolean): Specify invoking on the trailing edge of the timeout.

Returns

(Function): Returns the new debounced function.

Example

// 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])

# Ⓢ Ⓣ Ⓝ

Defers invoking the func until the current call stack has cleared. Any additional arguments are provided to func when it's 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

_.defer(function(text) {
  console.log(text);
}, 'deferred');
// logs 'deferred' after one or more milliseconds

_.delay(func, wait, [args])

# Ⓢ Ⓣ Ⓝ

Invokes func after wait milliseconds. Any additional arguments are provided to func when it's 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

_.delay(function(text) {
  console.log(text);
}, 1000, 'later');
// => logs 'later' after one second

_.flow([funcs])

# Ⓢ Ⓣ Ⓝ

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

function square(n) {
  return n * n;
}

var addSquare = _.flow(_.add, square);
addSquare(1, 2);
// => 9

_.flowRight([funcs])

# Ⓢ Ⓣ Ⓝ

This method is like _.flow except that it creates a function that invokes the provided functions from right to left.

Aliases

_.backflow, _.compose

Arguments

1. [funcs] (...Function): Functions to invoke.

Returns

(Function): Returns the new function.

Example

function square(n) {
  return n * n;
}

var addSquare = _.flowRight(square, _.add);
addSquare(1, 2);
// => 9

_.memoize(func, [resolver])

# Ⓢ Ⓣ Ⓝ

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 Map method interface of get, has, and set.

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

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' }

_.modArgs(func, [transforms])

# Ⓢ Ⓣ Ⓝ

Creates a function that runs each argument through a corresponding transform function.

Arguments

1. func (Function): The function to wrap.
2. [transforms] (...(Function|Function[]): The functions to transform arguments, specified as individual functions or arrays of functions.

Returns

(Function): Returns the new function.

Example

function doubled(n) {
  return n * 2;
}

function square(n) {
  return n * n;
}

var modded = _.modArgs(function(x, y) {
  return [x, y];
}, square, doubled);

modded(1, 2);
// => [1, 4]

modded(5, 10);
// => [25, 20]

_.negate(predicate)

# Ⓢ Ⓣ Ⓝ

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

function isEven(n) {
  return n % 2 == 0;
}

_.filter([1, 2, 3, 4, 5, 6], _.negate(isEven));
// => [1, 3, 5]

_.once(func)

# Ⓢ Ⓣ Ⓝ

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 and arguments of the created function.

Arguments

1. func (Function): The function to restrict.

Returns

(Function): Returns the new restricted function.

Example

var initialize = _.once(createApplication);
initialize();
initialize();
// `initialize` invokes `createApplication` once

_.partial(func, [partials])

# Ⓢ Ⓣ Ⓝ

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. [partials] (...*): The arguments to be partially applied.

Returns

(Function): Returns the new partially applied function.

Example

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, [partials])

# Ⓢ Ⓣ Ⓝ

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. [partials] (...*): The arguments to be partially applied.

Returns

(Function): Returns the new partially applied function.

Example

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)

# Ⓢ Ⓣ Ⓝ