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

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value of each key is the number of times the key was returned by iteratee. The iteratee is invoked with one argument: (value).

Since

0.5.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The iteratee to transform keys.

Returns

(Object): Returns the composed aggregate object.

Example

_.countBy([6.1, 4.2, 6.3], Math.floor);
// => { '4': 1, '6': 2 }
// The `_.property` iteratee shorthand.
_.countBy(['one', 'two', 'three'], 'length');
// => { '3': 2, '5': 1 }

_.every(collection, [predicate=_.identity])

Checks if predicate returns truthy for all elements of collection. Iteration is stopped once predicate returns falsey. The predicate is invoked with three arguments: (value, index|key, collection).

Note: This method returns true for empty collections because everything is true of elements of empty collections.

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [predicate=_.identity] (Function): The function invoked per iteration.

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', 'age': 36, 'active': false },
  { 'user': 'fred',   'age': 40, 'active': false }
];
// The `_.matches` iteratee shorthand.
_.every(users, { 'user': 'barney', 'active': false });
// => false
// The `_.matchesProperty` iteratee shorthand.
_.every(users, ['active', false]);
// => true
// The `_.property` iteratee shorthand.
_.every(users, 'active');
// => false

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

Iterates over elements of collection, returning an array of all elements predicate returns truthy for. The predicate is invoked with three arguments: (value, index|key, collection).

Note: Unlike _.remove, this method returns a new array.

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [predicate=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the new filtered array.

Example

var users = [
  { 'user': 'barney', 'age': 36, 'active': true },
  { 'user': 'fred',   'age': 40, 'active': false }
];
_.filter(users, function(o) { return !o.active; });
// => objects for ['fred']
// The `_.matches` iteratee shorthand.
_.filter(users, { 'age': 36, 'active': true });
// => objects for ['barney']
// The `_.matchesProperty` iteratee shorthand.
_.filter(users, ['active', false]);
// => objects for ['fred']
// The `_.property` iteratee shorthand.
_.filter(users, 'active');
// => objects for ['barney']

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

Iterates over elements of collection, returning the first element predicate returns truthy for. The predicate is invoked with three arguments: (value, index|key, collection).

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to inspect.
2. [predicate=_.identity] (Function): The function invoked per iteration.
3. [fromIndex=0] (number): The index to search from.

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 }
];
_.find(users, function(o) { return o.age < 40; });
// => object for 'barney'
// The `_.matches` iteratee shorthand.
_.find(users, { 'age': 1, 'active': true });
// => object for 'pebbles'
// The `_.matchesProperty` iteratee shorthand.
_.find(users, ['active', false]);
// => object for 'fred'
// The `_.property` iteratee shorthand.
_.find(users, 'active');
// => object for 'barney'

_.findLast(collection, [predicate=_.identity], [fromIndex=collection.length-1])

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

Since

2.0.0

Arguments

1. collection (Array|Object): The collection to inspect.
2. [predicate=_.identity] (Function): The function invoked per iteration.
3. [fromIndex=collection.length-1] (number): The index to search from.

Returns

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

Example

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

_.flatMap(collection, [iteratee=_.identity])

Creates a flattened array of values by running each element in collection thru iteratee and flattening the mapped results. The iteratee is invoked with three arguments: (value, index|key, collection).

Since

4.0.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the new flattened array.

Example

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

_.flatMapDeep(collection, [iteratee=_.identity])

This method is like _.flatMap except that it recursively flattens the mapped results.

Since

4.7.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the new flattened array.

Example

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

_.flatMapDepth(collection, [iteratee=_.identity], [depth=1])

This method is like _.flatMap except that it recursively flattens the mapped results up to depth times.

Since

4.7.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.
3. [depth=1] (number): The maximum recursion depth.

Returns

(Array): Returns the new flattened array.

Example

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

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

Iterates over elements of collection and invokes iteratee for each element. The iteratee is 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 use _.forIn or _.forOwn for object iteration.

Since

0.1.0

Aliases

_.each

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.

Returns

(*): Returns collection.

Example

_.forEach([1, 2], function(value) {
  console.log(value);
});
// => Logs `1` then `2`.
_.forEach({ 'a': 1, 'b': 2 }, function(value, key) {
  console.log(key);
});
// => Logs 'a' then 'b' (iteration order is not guaranteed).

_.forEachRight(collection, [iteratee=_.identity])

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

Since

2.0.0

Aliases

_.eachRight

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.

Returns

(*): Returns collection.

Example

_.forEachRight([1, 2], function(value) {
  console.log(value);
});
// => Logs `2` then `1`.

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

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The order of grouped values is determined by the order they occur in collection. The corresponding value of each key is an array of elements responsible for generating the key. The iteratee is invoked with one argument: (value).

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The iteratee to transform keys.

Returns

(Object): Returns the composed aggregate object.

Example

_.groupBy([6.1, 4.2, 6.3], Math.floor);
// => { '4': [4.2], '6': [6.1, 6.3] }
// The `_.property` iteratee shorthand.
_.groupBy(['one', 'two', 'three'], 'length');
// => { '3': ['one', 'two'], '5': ['three'] }

_.includes(collection, value, [fromIndex=0])

Checks if value is in collection. If collection is a string, it’s checked for a substring of value, otherwise SameValueZero is used for equality comparisons. If fromIndex is negative, it’s used as the offset from the end of collection.

Since

0.1.0

Arguments

1. collection (Array|Object|string): The collection to inspect.
2. value (*): The value to search for.
3. [fromIndex=0] (number): The index to search from.

Returns

(boolean): Returns true if value is found, else false.

Example

_.includes([1, 2, 3], 1);
// => true
_.includes([1, 2, 3], 1, 2);
// => false
_.includes({ 'a': 1, 'b': 2 }, 1);
// => true
_.includes('abcd', 'bc');
// => true

_.invokeMap(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 path is a function, it’s invoked for, and this bound to, each element in collection.

Since

4.0.0

Arguments

1. collection (Array|Object): 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 each method with.

Returns

(Array): Returns the array of results.

Example

_.invokeMap([[5, 1, 7], [3, 2, 1]], 'sort');
// => [[1, 5, 7], [1, 2, 3]]
_.invokeMap([123, 456], String.prototype.split, '');
// => [['1', '2', '3'], ['4', '5', '6']]

_.keyBy(collection, [iteratee=_.identity])

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee is invoked with one argument: (value).

Since

4.0.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The iteratee to transform keys.

Returns

(Object): Returns the composed aggregate object.

Example

var array = [
  { 'dir': 'left', 'code': 97 },
  { 'dir': 'right', 'code': 100 }
];
_.keyBy(array, function(o) {
  return String.fromCharCode(o.code);
});
// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }
_.keyBy(array, 'dir');
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }

_.map(collection, [iteratee=_.identity])

Creates an array of values by running each element in collection thru iteratee. The iteratee is invoked with three arguments:
(value, index|key, collection).

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

The guarded methods are:
ary, chunk, curry, curryRight, drop, dropRight, every, fill, invert, parseInt, random, range, rangeRight, repeat, sampleSize, slice, some, sortBy, split, take, takeRight, template, trim, trimEnd, trimStart, and words

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the new mapped array.

Example

function square(n) {
  return n * n;
}
_.map([4, 8], square);
// => [16, 64]
_.map({ 'a': 4, 'b': 8 }, square);
// => [16, 64] (iteration order is not guaranteed)
var users = [
  { 'user': 'barney' },
  { 'user': 'fred' }
];
// The `_.property` iteratee shorthand.
_.map(users, 'user');
// => ['barney', 'fred']

_.orderBy(collection, [iteratees=[_.identity]], [orders])

This method is like _.sortBy 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, specify an order of “desc” for descending or “asc” for ascending sort order of corresponding values.

Since

4.0.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratees=[_.identity]] (Array[]|Function[]|Object[]|string[]): The iteratees to sort by.
3. [orders] (string[]): 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': 40 },
  { 'user': 'barney', 'age': 36 }
];
// Sort by `user` in ascending order and by `age` in descending order.
_.orderBy(users, ['user', 'age'], ['asc', 'desc']);
// => objects for [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 40]]

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

Creates an array of elements split into two groups, the first of which contains elements predicate returns truthy for, the second of which contains elements predicate returns falsey for. The predicate is invoked with one argument: (value).

Since

3.0.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [predicate=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the array of grouped elements.

Example

var users = [
  { 'user': 'barney',  'age': 36, 'active': false },
  { 'user': 'fred',    'age': 40, 'active': true },
  { 'user': 'pebbles', 'age': 1,  'active': false }
];
_.partition(users, function(o) { return o.active; });
// => objects for [['fred'], ['barney', 'pebbles']]
// The `_.matches` iteratee shorthand.
_.partition(users, { 'age': 1, 'active': false });
// => objects for [['pebbles'], ['barney', 'fred']]
// The `_.matchesProperty` iteratee shorthand.
_.partition(users, ['active', false]);
// => objects for [['barney', 'pebbles'], ['fred']]
// The `_.property` iteratee shorthand.
_.partition(users, 'active');
// => objects for [['fred'], ['barney', 'pebbles']]

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

Reduces collection to a value which is the accumulated result of running each element in collection thru iteratee, where each successive invocation is supplied the return value of the previous. If accumulator is not given, the first element of collection is used as the initial value. The iteratee is 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, orderBy, and sortBy

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.
3. [accumulator] (*): The initial value.

Returns

(*): Returns the accumulated value.

Example

_.reduce([1, 2], function(sum, n) {
  return sum + n;
}, 0);
// => 3
_.reduce({ 'a': 1, 'b': 2, 'c': 1 }, function(result, value, key) {
  (result[value] || (result[value] = [])).push(key);
  return result;
}, {});
// => { '1': ['a', 'c'], '2': ['b'] } (iteration order is not guaranteed)

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

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

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratee=_.identity] (Function): The function invoked per iteration.
3. [accumulator] (*): The initial value.

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

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

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [predicate=_.identity] (Function): The function invoked per iteration.

Returns

(Array): Returns the new filtered array.

Example

var users = [
  { 'user': 'barney', 'age': 36, 'active': false },
  { 'user': 'fred',   'age': 40, 'active': true }
];
_.reject(users, function(o) { return !o.active; });
// => objects for ['fred']
// The `_.matches` iteratee shorthand.
_.reject(users, { 'age': 40, 'active': true });
// => objects for ['barney']
// The `_.matchesProperty` iteratee shorthand.
_.reject(users, ['active', false]);
// => objects for ['fred']
// The `_.property` iteratee shorthand.
_.reject(users, 'active');
// => objects for ['barney']

_.sample(collection)

Gets a random element from collection.

Since

2.0.0

Arguments

1. collection (Array|Object): The collection to sample.

Returns

(*): Returns the random element.

Example

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

_.sampleSize(collection, [n=1])

Gets n random elements at unique keys from collection up to the size of collection.

Since

4.0.0

Arguments

1. collection (Array|Object): The collection to sample.
2. [n=1] (number): The number of elements to sample.

Returns

(Array): Returns the random elements.

Example

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

_.shuffle(collection)

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

Since

0.1.0

Arguments

1. collection (Array|Object): 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 string keyed properties for objects.

Since

0.1.0

Arguments

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

Returns

(number): Returns the collection size.

Example

_.size([1, 2, 3]);
// => 3
_.size({ 'a': 1, 'b': 2 });
// => 2
_.size('pebbles');
// => 7

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

Checks if predicate returns truthy for any element of collection. Iteration is stopped once predicate returns truthy. The predicate is invoked with three arguments: (value, index|key, collection).

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [predicate=_.identity] (Function): The function invoked per iteration.

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 }
];
// The `_.matches` iteratee shorthand.
_.some(users, { 'user': 'barney', 'active': false });
// => false
// The `_.matchesProperty` iteratee shorthand.
_.some(users, ['active', false]);
// => true
// The `_.property` iteratee shorthand.
_.some(users, 'active');
// => true

_.sortBy(collection, [iteratees=[_.identity]])

Creates an array of elements, sorted in ascending order by the results of running each element in a collection thru each iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements. The iteratees are invoked with one argument: (value).

Since

0.1.0

Arguments

1. collection (Array|Object): The collection to iterate over.
2. [iteratees=[_.identity]] (…(Function|Function[])): The iteratees to sort by.

Returns

(Array): Returns the new sorted array.

Example

var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 36 },
  { 'user': 'fred',   'age': 40 },
  { 'user': 'barney', 'age': 34 }
];
_.sortBy(users, [function(o) { return o.user; }]);
// => objects for [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 40]]
_.sortBy(users, ['user', 'age']);
// => objects for [['barney', 34], ['barney', 36], ['fred', 40], ['fred', 48]]