lodash v4.17.20
Array
_.chunk
_.compact
_.concat
_.difference
_.differenceBy
_.differenceWith
_.drop
_.dropRight
_.dropRightWhile
_.dropWhile
_.fill
_.findIndex
_.findLastIndex
_.first
->head
_.flatten
_.flattenDeep
_.flattenDepth
_.fromPairs
_.head
_.indexOf
_.initial
_.intersection
_.intersectionBy
_.intersectionWith
_.join
_.last
_.lastIndexOf
_.nth
_.pull
_.pullAll
_.pullAllBy
_.pullAllWith
_.pullAt
_.remove
_.reverse
_.slice
_.sortedIndex
_.sortedIndexBy
_.sortedIndexOf
_.sortedLastIndex
_.sortedLastIndexBy
_.sortedLastIndexOf
_.sortedUniq
_.sortedUniqBy
_.tail
_.take
_.takeRight
_.takeRightWhile
_.takeWhile
_.union
_.unionBy
_.unionWith
_.uniq
_.uniqBy
_.uniqWith
_.unzip
_.unzipWith
_.without
_.xor
_.xorBy
_.xorWith
_.zip
_.zipObject
_.zipObjectDeep
_.zipWith
Collection
_.countBy
_.each
->forEach
_.eachRight
->forEachRight
_.every
_.filter
_.find
_.findLast
_.flatMap
_.flatMapDeep
_.flatMapDepth
_.forEach
_.forEachRight
_.groupBy
_.includes
_.invokeMap
_.keyBy
_.map
_.orderBy
_.partition
_.reduce
_.reduceRight
_.reject
_.sample
_.sampleSize
_.shuffle
_.size
_.some
_.sortBy
Date
Function
_.after
_.ary
_.before
_.bind
_.bindKey
_.curry
_.curryRight
_.debounce
_.defer
_.delay
_.flip
_.memoize
_.negate
_.once
_.overArgs
_.partial
_.partialRight
_.rearg
_.rest
_.spread
_.throttle
_.unary
_.wrap
Lang
_.castArray
_.clone
_.cloneDeep
_.cloneDeepWith
_.cloneWith
_.conformsTo
_.eq
_.gt
_.gte
_.isArguments
_.isArray
_.isArrayBuffer
_.isArrayLike
_.isArrayLikeObject
_.isBoolean
_.isBuffer
_.isDate
_.isElement
_.isEmpty
_.isEqual
_.isEqualWith
_.isError
_.isFinite
_.isFunction
_.isInteger
_.isLength
_.isMap
_.isMatch
_.isMatchWith
_.isNaN
_.isNative
_.isNil
_.isNull
_.isNumber
_.isObject
_.isObjectLike
_.isPlainObject
_.isRegExp
_.isSafeInteger
_.isSet
_.isString
_.isSymbol
_.isTypedArray
_.isUndefined
_.isWeakMap
_.isWeakSet
_.lt
_.lte
_.toArray
_.toFinite
_.toInteger
_.toLength
_.toNumber
_.toPlainObject
_.toSafeInteger
_.toString
Math
_.add
_.ceil
_.divide
_.floor
_.max
_.maxBy
_.mean
_.meanBy
_.min
_.minBy
_.multiply
_.round
_.subtract
_.sum
_.sumBy
Number
Object
_.assign
_.assignIn
_.assignInWith
_.assignWith
_.at
_.create
_.defaults
_.defaultsDeep
_.entries
->toPairs
_.entriesIn
->toPairsIn
_.extend
->assignIn
_.extendWith
->assignInWith
_.findKey
_.findLastKey
_.forIn
_.forInRight
_.forOwn
_.forOwnRight
_.functions
_.functionsIn
_.get
_.has
_.hasIn
_.invert
_.invertBy
_.invoke
_.keys
_.keysIn
_.mapKeys
_.mapValues
_.merge
_.mergeWith
_.omit
_.omitBy
_.pick
_.pickBy
_.result
_.set
_.setWith
_.toPairs
_.toPairsIn
_.transform
_.unset
_.update
_.updateWith
_.values
_.valuesIn
Seq
_
_.chain
_.tap
_.thru
_.prototype[Symbol.iterator]
_.prototype.at
_.prototype.chain
_.prototype.commit
_.prototype.next
_.prototype.plant
_.prototype.reverse
_.prototype.toJSON
->value
_.prototype.value
_.prototype.valueOf
->value
String
_.camelCase
_.capitalize
_.deburr
_.endsWith
_.escape
_.escapeRegExp
_.kebabCase
_.lowerCase
_.lowerFirst
_.pad
_.padEnd
_.padStart
_.parseInt
_.repeat
_.replace
_.snakeCase
_.split
_.startCase
_.startsWith
_.template
_.toLower
_.toUpper
_.trim
_.trimEnd
_.trimStart
_.truncate
_.unescape
_.upperCase
_.upperFirst
_.words
Util
_.attempt
_.bindAll
_.cond
_.conforms
_.constant
_.defaultTo
_.flow
_.flowRight
_.identity
_.iteratee
_.matches
_.matchesProperty
_.method
_.methodOf
_.mixin
_.noConflict
_.noop
_.nthArg
_.over
_.overEvery
_.overSome
_.property
_.propertyOf
_.range
_.rangeRight
_.runInContext
_.stubArray
_.stubFalse
_.stubObject
_.stubString
_.stubTrue
_.times
_.toPath
_.uniqueId
Properties
_.VERSION
_.templateSettings
_.templateSettings.escape
_.templateSettings.evaluate
_.templateSettings.imports
_.templateSettings.interpolate
_.templateSettings.variable
Methods
“Array” Methods
_.chunk(size, array)
Creates an array of elements split into groups the length of size
.
If array
can't be split evenly, the final chunk will be the remaining
elements.
Since
3.0.0
Arguments
size
(number): The length of each chunkarray
(Array): The array to process.
Returns
(Array): Returns the new array of chunks.
Example
_.chunk(2, ['a', 'b', 'c', 'd']);
// => [['a', 'b'], ['c', 'd']]
_.chunk(3, ['a', 'b', 'c', 'd']);
// => [['a', 'b', 'c'], ['d']]
_.compact(array)
Creates an array with all falsey values removed. The values false
, null
,
0
, ""
, undefined
, and NaN
are falsey.
Since
0.1.0
Arguments
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]
_.concat(array, values)
Creates a new array concatenating array
with any additional arrays
and/or values.
Since
4.0.0
Arguments
array
(Array): The array to concatenate.values
(*|*[]): The values to concatenate.
Returns
(Array): Returns the new concatenated array.
Example
var array = [1];
var other = _.concat(array, [2, [3], [[4]]]);
// => [1, 2, 3, [4]]
// => [1]
_.difference(array, values)
Creates an array of array
values not included in the other given arrays
using SameValueZero
for equality comparisons. The order and references of result values are
determined by the first array.
Note: Unlike _.pullAll
, this method returns a new array.
Since
0.1.0
Arguments
array
(Array): The array to inspect.values
(Array|Array[]): The values to exclude.
Returns
(Array): Returns the new array of filtered values.
Example
_.difference([2, 1], [2, 3]);
// => [1]
_.differenceBy(iteratee, array, values)
This method is like _.difference
except that it accepts iteratee
which
is invoked for each element of array
and values
to generate the criterion
by which they're compared. The order and references of result values are
determined by the first array. The iteratee is invoked with one argument:
(value).
Note: Unlike _.pullAllBy
, this method returns a new array.
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.array
(Array): The array to inspect.values
(Array|Array[]): The values to exclude.
Returns
(Array): Returns the new array of filtered values.
Example
_.differenceBy(Math.floor, [2.1, 1.2], [2.3, 3.4]);
// => [1.2]
// The `_.property` iteratee shorthand.
_.differenceBy('x', [{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }]);
// => [{ 'x': 2 }]
_.differenceWith(comparator, array, values)
This method is like _.difference
except that it accepts comparator
which is invoked to compare elements of array
to values
. The order and
references of result values are determined by the first array. The comparator
is invoked with two arguments: (arrVal, othVal).
Note: Unlike _.pullAllWith
, this method returns a new array.
Since
4.0.0
Arguments
comparator
(Function): The comparator invoked per element.array
(Array): The array to inspect.values
(Array|Array[]): The values to exclude.
Returns
(Array): Returns the new array of filtered values.
Example
var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
_.differenceWith(_.isEqual, objects, [{ 'x': 1, 'y': 2 }]);
// => [{ 'x': 2, 'y': 1 }]
_.drop(n, array)
Creates a slice of array
with n
elements dropped from the beginning.
Since
0.5.0
Arguments
n
(number): The number of elements to drop.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.drop(1, [1, 2, 3]);
// => [2, 3]
_.drop(2, [1, 2, 3]);
// => [3]
_.drop(5, [1, 2, 3]);
// => []
_.drop(0, [1, 2, 3]);
// => [1, 2, 3]
_.dropRight(n, array)
Creates a slice of array
with n
elements dropped from the end.
Since
3.0.0
Arguments
n
(number): The number of elements to drop.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.dropRight(1, [1, 2, 3]);
// => [1, 2]
_.dropRight(2, [1, 2, 3]);
// => [1]
_.dropRight(5, [1, 2, 3]);
// => []
_.dropRight(0, [1, 2, 3]);
// => [1, 2, 3]
_.dropRightWhile(predicate, array)
Creates a slice of array
excluding elements dropped from the end.
Elements are dropped until predicate
returns falsey. The predicate is
invoked with three arguments: (value, index, array).
Since
3.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
var users = [
{ 'user': 'barney', 'active': true },
{ 'user': 'fred', 'active': false },
{ 'user': 'pebbles', 'active': false }
];
_.dropRightWhile(function(o) { return !o.active; }, users);
// => objects for ['barney']
// The `_.matches` iteratee shorthand.
_.dropRightWhile({ 'user': 'pebbles', 'active': false }, users);
// => objects for ['barney', 'fred']
// The `_.matchesProperty` iteratee shorthand.
_.dropRightWhile(['active', false], users);
// => objects for ['barney']
// The `_.property` iteratee shorthand.
_.dropRightWhile('active', users);
// => objects for ['barney', 'fred', 'pebbles']
_.dropWhile(predicate, array)
Creates a slice of array
excluding elements dropped from the beginning.
Elements are dropped until predicate
returns falsey. The predicate is
invoked with three arguments: (value, index, array).
Since
3.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
var users = [
{ 'user': 'barney', 'active': false },
{ 'user': 'fred', 'active': false },
{ 'user': 'pebbles', 'active': true }
];
_.dropWhile(function(o) { return !o.active; }, users);
// => objects for ['pebbles']
// The `_.matches` iteratee shorthand.
_.dropWhile({ 'user': 'barney', 'active': false }, users);
// => objects for ['fred', 'pebbles']
// The `_.matchesProperty` iteratee shorthand.
_.dropWhile(['active', false], users);
// => objects for ['pebbles']
// The `_.property` iteratee shorthand.
_.dropWhile('active', users);
// => objects for ['barney', 'fred', 'pebbles']
_.fill(start, end, value, array)
Fills elements of array
with value
from start
up to, but not
including, end
.
Since
3.2.0
Arguments
start
(number): The start position.end
(number): The end position.value
(*): The value to fillarray
with.array
(Array): The array to fill.
Returns
(Array): Returns array
.
Example
var array = [1, 2, 3];
_.fill(0, array.length, 'a', array);
// => ['a', 'a', 'a']
_.fill(0, Array(3).length, 2, Array(3));
// => [2, 2, 2]
_.fill(1, 3, '*', [4, 6, 8, 10]);
// => [4, '*', '*', 10]
_.findIndex(predicate, array)
This method is like _.find
except that it returns the index of the first
element predicate
returns truthy for instead of the element itself.
Since
1.1.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to inspect.
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(function(o) { return o.user == 'barney'; }, users);
// => 0
// The `_.matches` iteratee shorthand.
_.findIndex({ 'user': 'fred', 'active': false }, users);
// => 1
// The `_.matchesProperty` iteratee shorthand.
_.findIndex(['active', false], users);
// => 0
// The `_.property` iteratee shorthand.
_.findIndex('active', users);
// => 2
_.findLastIndex(predicate, array)
This method is like _.findIndex
except that it iterates over elements
of collection
from right to left.
Since
2.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to inspect.
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(function(o) { return o.user == 'pebbles'; }, users);
// => 2
// The `_.matches` iteratee shorthand.
_.findLastIndex({ 'user': 'barney', 'active': true }, users);
// => 0
// The `_.matchesProperty` iteratee shorthand.
_.findLastIndex(['active', false], users);
// => 2
// The `_.property` iteratee shorthand.
_.findLastIndex('active', users);
// => 0
_.flatten(array)
Flattens array
a single level deep.
Since
0.1.0
Arguments
array
(Array): The array to flatten.
Returns
(Array): Returns the new flattened array.
Example
_.flatten([1, [2, [3, [4]], 5]]);
// => [1, 2, [3, [4]], 5]
_.flattenDeep(array)
Recursively flattens array
.
Since
3.0.0
Arguments
array
(Array): The array to flatten.
Returns
(Array): Returns the new flattened array.
Example
_.flattenDeep([1, [2, [3, [4]], 5]]);
// => [1, 2, 3, 4, 5]
_.flattenDepth(depth, array)
Recursively flatten array
up to depth
times.
Since
4.4.0
Arguments
depth
(number): The maximum recursion depth.array
(Array): The array to flatten.
Returns
(Array): Returns the new flattened array.
Example
var array = [1, [2, [3, [4]], 5]];
_.flattenDepth(1, array);
// => [1, 2, [3, [4]], 5]
_.flattenDepth(2, array);
// => [1, 2, 3, [4], 5]
_.fromPairs(pairs)
The inverse of _.toPairs
; this method returns an object composed
from key-value pairs
.
Since
4.0.0
Arguments
pairs
(Array): The key-value pairs.
Returns
(Object): Returns the new object.
Example
_.fromPairs([['a', 1], ['b', 2]]);
// => { 'a': 1, 'b': 2 }
_.head(array)
Gets the first element of array
.
Since
0.1.0
Aliases
_.first
Arguments
array
(Array): The array to query.
Returns
(*): Returns the first element of array
.
Example
_.head([1, 2, 3]);
// => 1
_.head([]);
// => undefined
_.indexOf(value, array)
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
.
Since
0.1.0
Arguments
value
(*): The value to search for.array
(Array): The array to inspect.
Returns
(number): Returns the index of the matched value, else -1
.
Example
_.indexOf(2, [1, 2, 1, 2]);
// => 1
// Search from the `fromIndex`.
_.indexOf([2, 2], [1, 2, 1, 2]);
// => 3
_.initial(array)
Gets all but the last element of array
.
Since
0.1.0
Arguments
array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.initial([1, 2, 3]);
// => [1, 2]
_.intersection(arrays, arrays)
Creates an array of unique values that are included in all given arrays
using SameValueZero
for equality comparisons. The order and references of result values are
determined by the first array.
Since
0.1.0
Arguments
arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of intersecting values.
Example
_.intersection([2, 3], [2, 1]);
// => [2]
_.intersectionBy(iteratee, arrays, arrays)
This method is like _.intersection
except that it accepts iteratee
which is invoked for each element of each arrays
to generate the criterion
by which they're compared. The order and references of result values are
determined by the first array. The iteratee is invoked with one argument:
(value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of intersecting values.
Example
_.intersectionBy(Math.floor, [2.1, 1.2], [2.3, 3.4]);
// => [2.1]
// The `_.property` iteratee shorthand.
_.intersectionBy('x', [{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }]);
// => [{ 'x': 1 }]
_.intersectionWith(comparator, arrays, arrays)
This method is like _.intersection
except that it accepts comparator
which is invoked to compare elements of arrays
. The order and references
of result values are determined by the first array. The comparator is
invoked with two arguments: (arrVal, othVal).
Since
4.0.0
Arguments
comparator
(Function): The comparator invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of intersecting values.
Example
var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];
_.intersectionWith(_.isEqual, objects, others);
// => [{ 'x': 1, 'y': 2 }]
_.join(separator, array)
Converts all elements in array
into a string separated by separator
.
Since
4.0.0
Arguments
separator
(string): The element separator.array
(Array): The array to convert.
Returns
(string): Returns the joined string.
Example
_.join('~', ['a', 'b', 'c']);
// => 'a~b~c'
_.last(array)
Gets the last element of array
.
Since
0.1.0
Arguments
array
(Array): The array to query.
Returns
(*): Returns the last element of array
.
Example
_.last([1, 2, 3]);
// => 3
_.lastIndexOf(value, array)
This method is like _.indexOf
except that it iterates over elements of
array
from right to left.
Since
0.1.0
Arguments
value
(*): The value to search for.array
(Array): The array to inspect.
Returns
(number): Returns the index of the matched value, else -1
.
Example
_.lastIndexOf(2, [1, 2, 1, 2]);
// => 3
// Search from the `fromIndex`.
_.lastIndexOf([2, 2], [1, 2, 1, 2]);
// => 1
_.nth(n, array)
Gets the element at index n
of array
. If n
is negative, the nth
element from the end is returned.
Since
4.11.0
Arguments
n
(number): The index of the element to return.array
(Array): The array to query.
Returns
(*): Returns the nth element of array
.
Example
var array = ['a', 'b', 'c', 'd'];
_.nth(1, array);
// => 'b'
_.nth(-2, array);
// => 'c';
_.pull(values, array)
Removes all given values from array
using
SameValueZero
for equality comparisons.
Since
2.0.0
Arguments
values
(*|*[]): The values to remove.array
(Array): The array to modify.
Returns
(Array): Returns array
.
Example
var array = ['a', 'b', 'c', 'a', 'b', 'c'];
_.pull(['a', 'c'], array);
// => ['b', 'b']
_.pullAll(values, array)
This method is like _.pull
except that it accepts an array of values to remove.
Since
4.0.0
Arguments
values
(Array): The values to remove.array
(Array): The array to modify.
Returns
(Array): Returns array
.
Example
var array = ['a', 'b', 'c', 'a', 'b', 'c'];
_.pullAll(['a', 'c'], array);
// => ['b', 'b']
_.pullAllBy(iteratee, values, array)
This method is like _.pullAll
except that it accepts iteratee
which is
invoked for each element of array
and values
to generate the criterion
by which they're compared. The iteratee is invoked with one argument: (value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.values
(Array): The values to remove.array
(Array): The array to modify.
Returns
(Array): Returns array
.
Example
var array = [{ 'x': 1 }, { 'x': 2 }, { 'x': 3 }, { 'x': 1 }];
_.pullAllBy('x', [{ 'x': 1 }, { 'x': 3 }], array);
// => [{ 'x': 2 }]
_.pullAllWith(comparator, values, array)
This method is like _.pullAll
except that it accepts comparator
which
is invoked to compare elements of array
to values
. The comparator is
invoked with two arguments: (arrVal, othVal).
Since
4.6.0
Arguments
comparator
(Function): The comparator invoked per element.values
(Array): The values to remove.array
(Array): The array to modify.
Returns
(Array): Returns array
.
Example
var array = [{ 'x': 1, 'y': 2 }, { 'x': 3, 'y': 4 }, { 'x': 5, 'y': 6 }];
_.pullAllWith(_.isEqual, [{ 'x': 3, 'y': 4 }], array);
// => [{ 'x': 1, 'y': 2 }, { 'x': 5, 'y': 6 }]
_.pullAt(indexes, array)
Removes elements from array
corresponding to indexes
and returns an
array of removed elements.
Since
3.0.0
Arguments
indexes
(number|number[]): The indexes of elements to remove.array
(Array): The array to modify.
Returns
(Array): Returns the new array of removed elements.
Example
var array = ['a', 'b', 'c', 'd'];
var pulled = _.pullAt([1, 3], array);
// => ['a', 'c']
// => ['b', 'd']
_.remove(predicate, array)
Removes all elements from array
that predicate
returns truthy for
and returns an array of the removed elements. The predicate is invoked
with three arguments: (value, index, array).
Since
2.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to modify.
Returns
(Array): Returns the new array of removed elements.
Example
var array = [1, 2, 3, 4];
var evens = _.remove(function(n) {
return n % 2 == 0;
}, array);
// => [1, 3]
// => [2, 4]
_.reverse(array)
Reverses array
so that the first element becomes the last, the second
element becomes the second to last, and so on.
Since
4.0.0
Arguments
array
(Array): The array to modify.
Returns
(Array): Returns array
.
Example
var array = [1, 2, 3];
_.reverse(array);
// => [3, 2, 1]
// => [3, 2, 1]
_.slice(start, end, array)
Creates a slice of array
from start
up to, but not including, end
.
Note: This method is used instead of
Array#slice
to ensure dense arrays are
returned.
Since
3.0.0
Arguments
start
(number): The start position.end
(number): The end position.array
(Array): The array to slice.
Returns
(Array): Returns the slice of array
.
_.sortedIndex(value, array)
Uses a binary search to determine the lowest index at which value
should be inserted into array
in order to maintain its sort order.
Since
0.1.0
Arguments
value
(*): The value to evaluate.array
(Array): The sorted array to inspect.
Returns
(number): Returns the index at which value
should be inserted into array
.
Example
_.sortedIndex(40, [30, 50]);
// => 1
_.sortedIndexBy(iteratee, value, array)
This method is like _.sortedIndex
except that it accepts iteratee
which is invoked for value
and each element of array
to compute their
sort ranking. The iteratee is invoked with one argument: (value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.value
(*): The value to evaluate.array
(Array): The sorted array to inspect.
Returns
(number): Returns the index at which value
should be inserted into array
.
Example
var objects = [{ 'x': 4 }, { 'x': 5 }];
_.sortedIndexBy(function(o) { return o.x; }, { 'x': 4 }, objects);
// => 0
// The `_.property` iteratee shorthand.
_.sortedIndexBy('x', { 'x': 4 }, objects);
// => 0
_.sortedIndexOf(value, array)
This method is like _.indexOf
except that it performs a binary
search on a sorted array
.
Since
4.0.0
Arguments
value
(*): The value to search for.array
(Array): The array to inspect.
Returns
(number): Returns the index of the matched value, else -1
.
Example
_.sortedIndexOf(5, [4, 5, 5, 5, 6]);
// => 1
_.sortedLastIndex(value, array)
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.
Since
3.0.0
Arguments
value
(*): The value to evaluate.array
(Array): The sorted array to inspect.
Returns
(number): Returns the index at which value
should be inserted into array
.
Example
_.sortedLastIndex(5, [4, 5, 5, 5, 6]);
// => 4
_.sortedLastIndexBy(iteratee, value, array)
This method is like _.sortedLastIndex
except that it accepts iteratee
which is invoked for value
and each element of array
to compute their
sort ranking. The iteratee is invoked with one argument: (value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.value
(*): The value to evaluate.array
(Array): The sorted array to inspect.
Returns
(number): Returns the index at which value
should be inserted into array
.
Example
var objects = [{ 'x': 4 }, { 'x': 5 }];
_.sortedLastIndexBy(function(o) { return o.x; }, { 'x': 4 }, objects);
// => 1
// The `_.property` iteratee shorthand.
_.sortedLastIndexBy('x', { 'x': 4 }, objects);
// => 1
_.sortedLastIndexOf(value, array)
This method is like _.lastIndexOf
except that it performs a binary
search on a sorted array
.
Since
4.0.0
Arguments
value
(*): The value to search for.array
(Array): The array to inspect.
Returns
(number): Returns the index of the matched value, else -1
.
Example
_.sortedLastIndexOf(5, [4, 5, 5, 5, 6]);
// => 3
_.sortedUniq(array)
This method is like _.uniq
except that it's designed and optimized
for sorted arrays.
Since
4.0.0
Arguments
array
(Array): The array to inspect.
Returns
(Array): Returns the new duplicate free array.
Example
_.sortedUniq([1, 1, 2]);
// => [1, 2]
_.sortedUniqBy(iteratee, array)
This method is like _.uniqBy
except that it's designed and optimized
for sorted arrays.
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.array
(Array): The array to inspect.
Returns
(Array): Returns the new duplicate free array.
Example
_.sortedUniqBy(Math.floor, [1.1, 1.2, 2.3, 2.4]);
// => [1.1, 2.3]
_.tail(array)
Gets all but the first element of array
.
Since
4.0.0
Arguments
array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.tail([1, 2, 3]);
// => [2, 3]
_.take(n, array)
Creates a slice of array
with n
elements taken from the beginning.
Since
0.1.0
Arguments
n
(number): The number of elements to take.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.take(1, [1, 2, 3]);
// => [1]
_.take(2, [1, 2, 3]);
// => [1, 2]
_.take(5, [1, 2, 3]);
// => [1, 2, 3]
_.take(0, [1, 2, 3]);
// => []
_.takeRight(n, array)
Creates a slice of array
with n
elements taken from the end.
Since
3.0.0
Arguments
n
(number): The number of elements to take.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
_.takeRight(1, [1, 2, 3]);
// => [3]
_.takeRight(2, [1, 2, 3]);
// => [2, 3]
_.takeRight(5, [1, 2, 3]);
// => [1, 2, 3]
_.takeRight(0, [1, 2, 3]);
// => []
_.takeRightWhile(predicate, array)
Creates a slice of array
with elements taken from the end. Elements are
taken until predicate
returns falsey. The predicate is invoked with
three arguments: (value, index, array).
Since
3.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
var users = [
{ 'user': 'barney', 'active': true },
{ 'user': 'fred', 'active': false },
{ 'user': 'pebbles', 'active': false }
];
_.takeRightWhile(function(o) { return !o.active; }, users);
// => objects for ['fred', 'pebbles']
// The `_.matches` iteratee shorthand.
_.takeRightWhile({ 'user': 'pebbles', 'active': false }, users);
// => objects for ['pebbles']
// The `_.matchesProperty` iteratee shorthand.
_.takeRightWhile(['active', false], users);
// => objects for ['fred', 'pebbles']
// The `_.property` iteratee shorthand.
_.takeRightWhile('active', users);
// => []
_.takeWhile(predicate, array)
Creates a slice of array
with elements taken from the beginning. Elements
are taken until predicate
returns falsey. The predicate is invoked with
three arguments: (value, index, array).
Since
3.0.0
Arguments
predicate
(Function): The function invoked per iteration.array
(Array): The array to query.
Returns
(Array): Returns the slice of array
.
Example
var users = [
{ 'user': 'barney', 'active': false },
{ 'user': 'fred', 'active': false },
{ 'user': 'pebbles', 'active': true }
];
_.takeWhile(function(o) { return !o.active; }, users);
// => objects for ['barney', 'fred']
// The `_.matches` iteratee shorthand.
_.takeWhile({ 'user': 'barney', 'active': false }, users);
// => objects for ['barney']
// The `_.matchesProperty` iteratee shorthand.
_.takeWhile(['active', false], users);
// => objects for ['barney', 'fred']
// The `_.property` iteratee shorthand.
_.takeWhile('active', users);
// => []
_.union(arrays, arrays)
Creates an array of unique values, in order, from all given arrays using
SameValueZero
for equality comparisons.
Since
0.1.0
Arguments
arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of combined values.
Example
_.union([1, 2], [2]);
// => [2, 1]
_.unionBy(iteratee, arrays, arrays)
This method is like _.union
except that it accepts iteratee
which is
invoked for each element of each arrays
to generate the criterion by
which uniqueness is computed. Result values are chosen from the first
array in which the value occurs. The iteratee is invoked with one argument:
(value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of combined values.
Example
_.unionBy(Math.floor, [2.1], [1.2, 2.3]);
// => [2.1, 1.2]
// The `_.property` iteratee shorthand.
_.unionBy('x', [{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }]);
// => [{ 'x': 1 }, { 'x': 2 }]
_.unionWith(comparator, arrays, arrays)
This method is like _.union
except that it accepts comparator
which
is invoked to compare elements of arrays
. Result values are chosen from
the first array in which the value occurs. The comparator is invoked
with two arguments: (arrVal, othVal).
Since
4.0.0
Arguments
comparator
(Function): The comparator invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of combined values.
Example
var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];
_.unionWith(_.isEqual, objects, others);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
_.uniq(array)
Creates a duplicate-free version of an array, using
SameValueZero
for equality comparisons, in which only the first occurrence of each element
is kept. The order of result values is determined by the order they occur
in the array.
Since
0.1.0
Arguments
array
(Array): The array to inspect.
Returns
(Array): Returns the new duplicate free array.
Example
_.uniq([2, 1, 2]);
// => [2, 1]
_.uniqBy(iteratee, array)
This method is like _.uniq
except that it accepts iteratee
which is
invoked for each element in array
to generate the criterion by which
uniqueness is computed. The order of result values is determined by the
order they occur in the array. The iteratee is invoked with one argument:
(value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.array
(Array): The array to inspect.
Returns
(Array): Returns the new duplicate free array.
Example
_.uniqBy(Math.floor, [2.1, 1.2, 2.3]);
// => [2.1, 1.2]
// The `_.property` iteratee shorthand.
_.uniqBy('x', [{ 'x': 1 }, { 'x': 2 }, { 'x': 1 }]);
// => [{ 'x': 1 }, { 'x': 2 }]
_.uniqWith(comparator, array)
This method is like _.uniq
except that it accepts comparator
which
is invoked to compare elements of array
. The order of result values is
determined by the order they occur in the array.The comparator is invoked
with two arguments: (arrVal, othVal).
Since
4.0.0
Arguments
comparator
(Function): The comparator invoked per element.array
(Array): The array to inspect.
Returns
(Array): Returns the new duplicate free array.
Example
var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 2 }];
_.uniqWith(_.isEqual, objects);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
_.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.
Since
1.2.0
Arguments
array
(Array): The array of grouped elements to process.
Returns
(Array): Returns the new array of regrouped elements.
Example
var zipped = _.zip(['a', 'b'], [[1, 2], [true, false]]);
// => [['a', 1, true], ['b', 2, false]]
_.unzip(zipped);
// => [['a', 'b'], [1, 2], [true, false]]
_.unzipWith(iteratee, array)
This method is like _.unzip
except that it accepts iteratee
to specify
how regrouped values should be combined. The iteratee is invoked with the
elements of each group: (...group).
Since
3.8.0
Arguments
iteratee
(Function): The function to combine regrouped values.array
(Array): The array of grouped elements to process.
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(_.add, zipped);
// => [3, 30, 300]
_.without(values, array)
Creates an array excluding all given values using
SameValueZero
for equality comparisons.
Note: Unlike _.pull
, this method returns a new array.
Since
0.1.0
Arguments
values
(*|*[]): The values to exclude.array
(Array): The array to inspect.
Returns
(Array): Returns the new array of filtered values.
Example
_.without([1, 2], [2, 1, 2, 3]);
// => [3]
_.xor(arrays, arrays)
Creates an array of unique values that is the symmetric difference of the given arrays. The order of result values is determined by the order they occur in the arrays.
Since
2.4.0
Arguments
arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of filtered values.
Example
_.xor([2, 3], [2, 1]);
// => [1, 3]
_.xorBy(iteratee, arrays, arrays)
This method is like _.xor
except that it accepts iteratee
which is
invoked for each element of each arrays
to generate the criterion by
which by which they're compared. The order of result values is determined
by the order they occur in the arrays. The iteratee is invoked with one
argument: (value).
Since
4.0.0
Arguments
iteratee
(Function): The iteratee invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of filtered values.
Example
_.xorBy(Math.floor, [2.1, 1.2], [2.3, 3.4]);
// => [1.2, 3.4]
// The `_.property` iteratee shorthand.
_.xorBy('x', [{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }]);
// => [{ 'x': 2 }]
_.xorWith(comparator, arrays, arrays)
This method is like _.xor
except that it accepts comparator
which is
invoked to compare elements of arrays
. The order of result values is
determined by the order they occur in the arrays. The comparator is invoked
with two arguments: (arrVal, othVal).
Since
4.0.0
Arguments
comparator
(Function): The comparator invoked per element.arrays
(Array): The arrays to inspect.arrays
(Array): The arrays to inspect.
Returns
(Array): Returns the new array of filtered values.
Example
var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];
_.xorWith(_.isEqual, objects, others);
// => [{ 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
_.zip(arrays, 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.
Since
0.1.0
Arguments
arrays
(Array): The arrays to process.arrays
(Array): The arrays to process.
Returns
(Array): Returns the new array of grouped elements.
Example
_.zip(['a', 'b'], [[1, 2], [true, false]]);
// => [['a', 1, true], ['b', 2, false]]
_.zipObject(props, values)
This method is like _.fromPairs
except that it accepts two arrays,
one of property identifiers and one of corresponding values.
Since
0.4.0
Arguments
props
(Array): The property identifiers.values
(Array): The property values.
Returns
(Object): Returns the new object.
Example
_.zipObject(['a', 'b'], [1, 2]);
// => { 'a': 1, 'b': 2 }
_.zipObjectDeep(props, values)
This method is like _.zipObject
except that it supports property paths.
Since
4.1.0
Arguments
props
(Array): The property identifiers.values
(Array): The property values.
Returns
(Object): Returns the new object.
Example
_.zipObjectDeep(['a.b[0].c', 'a.b[1].d'], [1, 2]);
// => { 'a': { 'b': [{ 'c': 1 }, { 'd': 2 }] } }
_.zipWith(iteratee, arrays, arrays)
This method is like _.zip
except that it accepts iteratee
to specify
how grouped values should be combined. The iteratee is invoked with the
elements of each group: (...group).
Since
3.8.0
Arguments
iteratee
(Function): The function to combine grouped values.arrays
(Array): The arrays to process.arrays
(Array): The arrays to process.
Returns
(Array): Returns the new array of grouped elements.
Example
_.zipWith([[100, 200], function(a, b, c) {
return a + b + c;
}], [1, 2], [10, 20]);
// => [111, 222]
“Collection” Methods
_.countBy(iteratee, collection)
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
iteratee
(Function): The iteratee to transform keys.collection
(Array|Object): The collection to iterate over.
Returns
(Object): Returns the composed aggregate object.
Example
_.countBy(Math.floor, [6.1, 4.2, 6.3]);
// => { '4': 1, '6': 2 }
// The `_.property` iteratee shorthand.
_.countBy('length', ['one', 'two', 'three']);
// => { '3': 2, '5': 1 }
_.every(predicate, collection)
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
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(boolean): Returns true
if all elements pass the predicate check, else false
.
Example
_.every(Boolean, [true, 1, null, 'yes']);
// => false
var users = [
{ 'user': 'barney', 'age': 36, 'active': false },
{ 'user': 'fred', 'age': 40, 'active': false }
];
// The `_.matches` iteratee shorthand.
_.every({ 'user': 'barney', 'active': false }, users);
// => false
// The `_.matchesProperty` iteratee shorthand.
_.every(['active', false], users);
// => true
// The `_.property` iteratee shorthand.
_.every('active', users);
// => false
_.filter(predicate, collection)
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
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new filtered array.
Example
var users = [
{ 'user': 'barney', 'age': 36, 'active': true },
{ 'user': 'fred', 'age': 40, 'active': false }
];
_.filter(function(o) { return !o.active; }, users);
// => objects for ['fred']
// The `_.matches` iteratee shorthand.
_.filter({ 'age': 36, 'active': true }, users);
// => objects for ['barney']
// The `_.matchesProperty` iteratee shorthand.
_.filter(['active', false], users);
// => objects for ['fred']
// The `_.property` iteratee shorthand.
_.filter('active', users);
// => objects for ['barney']
// Combining several predicates using `_.overEvery` or `_.overSome`.
_.filter(_.overSome([{ 'age': 36 }, ['age', 40]]), users);
// => objects for ['fred', 'barney']
_.find(predicate, collection)
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
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to inspect.
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(function(o) { return o.age < 40; }, users);
// => object for 'barney'
// The `_.matches` iteratee shorthand.
_.find({ 'age': 1, 'active': true }, users);
// => object for 'pebbles'
// The `_.matchesProperty` iteratee shorthand.
_.find(['active', false], users);
// => object for 'fred'
// The `_.property` iteratee shorthand.
_.find('active', users);
// => object for 'barney'
_.findLast(predicate, collection)
This method is like _.find
except that it iterates over elements of
collection
from right to left.
Since
2.0.0
Arguments
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to inspect.
Returns
(*): Returns the matched element, else undefined
.
Example
_.findLast(function(n) {
return n % 2 == 1;
}, [1, 2, 3, 4]);
// => 3
_.flatMap(iteratee, collection)
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
iteratee
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new flattened array.
Example
function duplicate(n) {
return [n, n];
}
_.flatMap(duplicate, [1, 2]);
// => [1, 1, 2, 2]
_.flatMapDeep(iteratee, collection)
This method is like _.flatMap
except that it recursively flattens the
mapped results.
Since
4.7.0
Arguments
iteratee
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new flattened array.
Example
function duplicate(n) {
return [[[n, n]]];
}
_.flatMapDeep(duplicate, [1, 2]);
// => [1, 1, 2, 2]
_.flatMapDepth(iteratee, depth, collection)
This method is like _.flatMap
except that it recursively flattens the
mapped results up to depth
times.
Since
4.7.0
Arguments
iteratee
(Function): The function invoked per iteration.depth
(number): The maximum recursion depth.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new flattened array.
Example
function duplicate(n) {
return [[[n, n]]];
}
_.flatMapDepth(duplicate, 2, [1, 2]);
// => [[1, 1], [2, 2]]
_.forEach(iteratee, collection)
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
iteratee
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(*): Returns collection
.
Example
_.forEach(function(value) {
console.log(value);
}, [1, 2]);
// => Logs `1` then `2`.
_.forEach(function(value, key) {
console.log(key);
}, { 'a': 1, 'b': 2 });
// => Logs 'a' then 'b' (iteration order is not guaranteed).
_.forEachRight(iteratee, collection)
This method is like _.forEach
except that it iterates over elements of
collection
from right to left.
Since
2.0.0
Aliases
_.eachRight
Arguments
iteratee
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(*): Returns collection
.
Example
_.forEachRight(function(value) {
console.log(value);
}, [1, 2]);
// => Logs `2` then `1`.
_.groupBy(iteratee, collection)
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
iteratee
(Function): The iteratee to transform keys.collection
(Array|Object): The collection to iterate over.
Returns
(Object): Returns the composed aggregate object.
Example
_.groupBy(Math.floor, [6.1, 4.2, 6.3]);
// => { '4': [4.2], '6': [6.1, 6.3] }
// The `_.property` iteratee shorthand.
_.groupBy('length', ['one', 'two', 'three']);
// => { '3': ['one', 'two'], '5': ['three'] }
_.includes(value, collection)
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
value
(*): The value to search for.collection
(Array|Object|string): The collection to inspect.
Returns
(boolean): Returns true
if value
is found, else false
.
Example
_.includes(1, [1, 2, 3]);
// => true
_.includes([1, 2], [1, 2, 3]);
// => false
_.includes(1, { 'a': 1, 'b': 2 });
// => true
_.includes('bc', 'abcd');
// => true
_.invokeMap(path, collection)
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
path
(Array|Function|string): The path of the method to invoke or the function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the array of results.
Example
_.invokeMap('sort', [[5, 1, 7], [3, 2, 1]]);
// => [[1, 5, 7], [1, 2, 3]]
_.invokeMap([String.prototype.split, ''], [123, 456]);
// => [['1', '2', '3'], ['4', '5', '6']]
_.keyBy(iteratee, collection)
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
iteratee
(Function): The iteratee to transform keys.collection
(Array|Object): The collection to iterate over.
Returns
(Object): Returns the composed aggregate object.
Example
var array = [
{ 'dir': 'left', 'code': 97 },
{ 'dir': 'right', 'code': 100 }
];
_.keyBy(function(o) {
return String.fromCharCode(o.code);
}, array);
// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }
_.keyBy('dir', array);
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }
_.map(iteratee, collection)
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
iteratee
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new mapped array.
Example
function square(n) {
return n * n;
}
_.map(square, [4, 8]);
// => [16, 64]
_.map(square, { 'a': 4, 'b': 8 });
// => [16, 64] (iteration order is not guaranteed)
var users = [
{ 'user': 'barney' },
{ 'user': 'fred' }
];
// The `_.property` iteratee shorthand.
_.map('user', users);
// => ['barney', 'fred']
_.orderBy(iteratees, orders, collection)
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
iteratees
(Array[]|Function[]|Object[]|string[]): The iteratees to sort by.orders
(string[]): The sort orders ofiteratees
.collection
(Array|Object): The collection to iterate over.
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(['user', 'age'], ['asc', 'desc'], users);
// => objects for [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 40]]
_.partition(predicate, collection)
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
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
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(function(o) { return o.active; }, users);
// => objects for [['fred'], ['barney', 'pebbles']]
// The `_.matches` iteratee shorthand.
_.partition({ 'age': 1, 'active': false }, users);
// => objects for [['pebbles'], ['barney', 'fred']]
// The `_.matchesProperty` iteratee shorthand.
_.partition(['active', false], users);
// => objects for [['barney', 'pebbles'], ['fred']]
// The `_.property` iteratee shorthand.
_.partition('active', users);
// => objects for [['fred'], ['barney', 'pebbles']]
_.reduce(iteratee, accumulator, collection)
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
iteratee
(Function): The function invoked per iteration.accumulator
(*): The initial value.collection
(Array|Object): The collection to iterate over.
Returns
(*): Returns the accumulated value.
Example
_.reduce(function(sum, n) {
return sum + n;
}, 0, [1, 2]);
// => 3
_.reduce(function(result, value, key) {
(result[value] || (result[value] = [])).push(key);
return result;
}, {}, { 'a': 1, 'b': 2, 'c': 1 });
// => { '1': ['a', 'c'], '2': ['b'] } (iteration order is not guaranteed)
_.reduceRight(iteratee, accumulator, collection)
This method is like _.reduce
except that it iterates over elements of
collection
from right to left.
Since
0.1.0
Arguments
iteratee
(Function): The function invoked per iteration.accumulator
(*): The initial value.collection
(Array|Object): The collection to iterate over.
Returns
(*): Returns the accumulated value.
Example
var array = [[0, 1], [2, 3], [4, 5]];
_.reduceRight(function(flattened, other) {
return flattened.concat(other);
}, [], array);
// => [4, 5, 2, 3, 0, 1]
_.reject(predicate, collection)
The opposite of _.filter
; this method returns the elements of collection
that predicate
does not return truthy for.
Since
0.1.0
Arguments
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new filtered array.
Example
var users = [
{ 'user': 'barney', 'age': 36, 'active': false },
{ 'user': 'fred', 'age': 40, 'active': true }
];
_.reject(function(o) { return !o.active; }, users);
// => objects for ['fred']
// The `_.matches` iteratee shorthand.
_.reject({ 'age': 40, 'active': true }, users);
// => objects for ['barney']
// The `_.matchesProperty` iteratee shorthand.
_.reject(['active', false], users);
// => objects for ['fred']
// The `_.property` iteratee shorthand.
_.reject('active', users);
// => objects for ['barney']
_.sample(collection)
Gets a random element from collection
.
Since
2.0.0
Arguments
collection
(Array|Object): The collection to sample.
Returns
(*): Returns the random element.
Example
_.sample([1, 2, 3, 4]);
// => 2
_.sampleSize(n, collection)
Gets n
random elements at unique keys from collection
up to the
size of collection
.
Since
4.0.0
Arguments
n
(number): The number of elements to sample.collection
(Array|Object): The collection to sample.
Returns
(Array): Returns the random elements.
Example
_.sampleSize(2, [1, 2, 3]);
// => [3, 1]
_.sampleSize(4, [1, 2, 3]);
// => [2, 3, 1]
_.shuffle(collection)
Creates an array of shuffled values, using a version of the Fisher-Yates shuffle.
Since
0.1.0
Arguments
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
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(predicate, collection)
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
predicate
(Function): The function invoked per iteration.collection
(Array|Object): The collection to iterate over.
Returns
(boolean): Returns true
if any element passes the predicate check, else false
.
Example
_.some(Boolean, [null, 0, 'yes', false]);
// => true
var users = [
{ 'user': 'barney', 'active': true },
{ 'user': 'fred', 'active': false }
];
// The `_.matches` iteratee shorthand.
_.some({ 'user': 'barney', 'active': false }, users);
// => false
// The `_.matchesProperty` iteratee shorthand.
_.some(['active', false], users);
// => true
// The `_.property` iteratee shorthand.
_.some('active', users);
// => true
_.sortBy(iteratees, collection)
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
iteratees
(Function|Function[]): The iteratees to sort by.collection
(Array|Object): The collection to iterate over.
Returns
(Array): Returns the new sorted array.
Example
var users = [
{ 'user': 'fred', 'age': 48 },
{ 'user': 'barney', 'age': 36 },
{ 'user': 'fred', 'age': 30 },
{ 'user': 'barney', 'age': 34 }
];
_.sortBy([function(o) { return o.user; }], users);
// => objects for [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 30]]
_.sortBy(['user', 'age'], users);
// => objects for [['barney', 34], ['barney', 36], ['fred', 30], ['fred', 48]]
“Date” Methods
_.now()
Gets the timestamp of the number of milliseconds that have elapsed since
the Unix epoch (1 January 1970 00
:00:00 UTC).
Since
2.4.0
Returns
(number): Returns the timestamp.
Example
_.defer([function(stamp) {
console.log(_.now(null) - stamp);
}, _.now()]);
// => Logs the number of milliseconds it took for the deferred invocation.
“Function” Methods
_.after(func, n)
The opposite of _.before
; this method creates a function that invokes
func
once it's called n
or more times.
Since
0.1.0
Arguments
func
(Function): The function to restrict.n
(number): The number of calls beforefunc
is invoked.
Returns
(Function): Returns the new restricted function.
Example
var saves = ['profile', 'settings'];
var done = _.after(function() {
console.log('done saving!');
}, saves.length);
_.forEach(function(type) {
asyncSave({ 'type': type, 'complete': done });
}, saves);
// => Logs 'done saving!' after the two async saves have completed.
_.ary(n, func)
Creates a function that invokes func
, with up to n
arguments,
ignoring any additional arguments.
Since
3.0.0
Arguments
n
(number): The arity cap.func
(Function): The function to cap arguments for.
Returns
(Function): Returns the new capped function.
Example
_.map(_.ary(parseInt, 1), ['6', '8', '10']);
// => [6, 8, 10]
_.before(func, n)
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.
Since
3.0.0
Arguments
func
(Function): The function to restrict.n
(number): The number of calls at whichfunc
is no longer invoked.
Returns
(Function): Returns the new restricted function.
Example
jQuery(element).on('click', _.before(addContactToList, 5));
// => Allows adding up to 4 contacts to the list.
_.bind(func, thisArg)
Creates a function that invokes func
with the this
binding of thisArg
and partials
prepended to the arguments it receives.
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 doesn't set the "length"
property of bound functions.
Since
0.1.0
Arguments
func
(Function): The function to bind.thisArg
(*): Thethis
binding offunc
.
Returns
(Function): Returns the new bound function.
Example
function greet(greeting, punctuation) {
return greeting + ' ' + this.user + punctuation;
}
var object = { 'user': 'fred' };
var bound = _.bind(greet, [object, 'hi']);
bound('!');
// => 'hi fred!'
// Bound with placeholders.
var bound = _.bind(greet, [object, _, '!']);
bound('hi');
// => 'hi fred!'
_.bindKey(object, key)
Creates a function that invokes the method at object[key]
with partials
prepended to the arguments it receives.
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.
Since
0.10.0
Arguments
object
(Object): The object to invoke the method on.key
(string): The key of the method.
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!'
// Bound with placeholders.
var bound = _.bindKey(object, ['greet', _, '!']);
bound('hi');
// => 'hiya fred!'
_.curry(func)
Creates a function that accepts arguments of func
and either invokes
func
returning its result, if at least arity
number of arguments have
been provided, or returns a function that accepts 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 doesn't set the "length" property of curried functions.
Since
2.0.0
Arguments
func
(Function): The function to curry.
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]
// Curried with placeholders.
curried(1)(_, 3)(2);
// => [1, 2, 3]
_.curryRight(func)
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 doesn't set the "length" property of curried functions.
Since
3.0.0
Arguments
func
(Function): The function to curry.
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]
// Curried with placeholders.
curried(3)(1, _)(2);
// => [1, 2, 3]
_.debounce(wait, func)
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 func
invocations and a flush
method to immediately invoke them.
Provide options
to indicate whether func
should be invoked on the
leading and/or trailing edge of the wait
timeout. The func
is invoked
with the last arguments provided to the debounced function. 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 debounced function
is invoked more than once during the wait
timeout.
If wait
is 0
and leading
is false
, func
invocation is deferred
until to the next tick, similar to setTimeout
with a timeout of 0
.
See David Corbacho's article
for details over the differences between _.debounce
and _.throttle
.
Since
0.1.0
Arguments
wait
(number): The number of milliseconds to delay.func
(Function): The function to debounce.
Returns
(Function): Returns the new debounced function.
Example
// Avoid costly calculations while the window size is in flux.
jQuery(window).on('resize', _.debounce(150, calculateLayout));
// Invoke `sendMail` when clicked, debouncing subsequent calls.
jQuery(element).on('click', _.debounce([300, {
'leading': true,
'trailing': false
}], sendMail));
// Ensure `batchLog` is invoked once after 1 second of debounced calls.
var debounced = _.debounce([250, { 'maxWait': 1000 }], batchLog);
var source = new EventSource('/stream');
jQuery(source).on('message', debounced);
// Cancel the trailing debounced invocation.
jQuery(window).on('popstate', debounced.cancel);
_.defer(func)
Defers invoking the func
until the current call stack has cleared. Any
additional arguments are provided to func
when it's invoked.
Since
0.1.0
Arguments
func
(Function): The function to defer.
Returns
(number): Returns the timer id.
Example
_.defer([function(text) {
console.log(text);
}, 'deferred']);
// => Logs 'deferred' after one millisecond.
_.delay(wait, func)
Invokes func
after wait
milliseconds. Any additional arguments are
provided to func
when it's invoked.
Since
0.1.0
Arguments
wait
(number): The number of milliseconds to delay invocation.func
(Function): The function to delay.
Returns
(number): Returns the timer id.
Example
_.delay([1000, 'later'], function(text) {
console.log(text);
});
// => Logs 'later' after one second.
_.flip(func)
Creates a function that invokes func
with arguments reversed.
Since
4.0.0
Arguments
func
(Function): The function to flip arguments for.
Returns
(Function): Returns the new flipped function.
Example
var flipped = _.flip(function() {
return _.toArray(arguments);
});
flipped('a', 'b', 'c', 'd');
// => ['d', 'c', 'b', 'a']
_.memoize(func)
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 used as the map 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 clear
, delete
, get
, has
, and set
.
Since
0.1.0
Arguments
func
(Function): The function to have its output memoized.
Returns
(Function): Returns the new memoized function.
Example
var object = { 'a': 1, 'b': 2 };
var other = { 'c': 3, 'd': 4 };
var values = _.memoize(_.values);
values(object);
// => [1, 2]
values(other);
// => [3, 4]
object.a = 2;
values(object);
// => [1, 2]
// Modify the result cache.
values.cache.set(object, ['a', 'b']);
values(object);
// => ['a', 'b']
// Replace `_.memoize.Cache`.
_.memoize.Cache = WeakMap;
_.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.
Since
3.0.0
Arguments
predicate
(Function): The predicate to negate.
Returns
(Function): Returns the new negated function.
Example
function isEven(n) {
return n % 2 == 0;
}
_.filter(_.negate(isEven), [1, 2, 3, 4, 5, 6]);
// => [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 invocation. The func
is
invoked with the this
binding and arguments of the created function.
Since
0.1.0
Arguments
func
(Function): The function to restrict.
Returns
(Function): Returns the new restricted function.
Example
var initialize = _.once(createApplication);
initialize();
initialize();
// => `createApplication` is invoked once
_.overArgs(func, transforms)
Creates a function that invokes func
with its arguments transformed.
Since
4.0.0
Arguments
func
(Function): The function to wrap.transforms
(Function|Function[]): The argument transforms.
Returns
(Function): Returns the new function.
Example
function doubled(n) {
return n * 2;
}
function square(n) {
return n * n;
}
var func = _.overArgs(function(x, y) {
return [x, y];
}, [square, doubled]);
func(9, 3);
// => [81, 6]
func(10, 5);
// => [100, 10]
_.partial(func, partials)
Creates a function that invokes func
with partials
prepended to the
arguments it receives. 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 doesn't set the "length" property of partially
applied functions.
Since
0.2.0
Arguments
func
(Function): The function to partially apply arguments to.partials
(*|*[]): The arguments to be partially applied.
Returns
(Function): Returns the new partially applied function.
Example
function greet(greeting, name) {
return greeting + ' ' + name;
}
var sayHelloTo = _.partial(greet, 'hello');
sayHelloTo('fred');
// => 'hello fred'
// Partially applied with 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 the arguments it receives.
The _.partialRight.placeholder
value, which defaults to _
in monolithic
builds, may be used as a placeholder for partially applied arguments.
Note: This method doesn't set the "length" property of partially
applied functions.
Since
1.0.0
Arguments
func
(Function): The function to partially apply arguments to.partials
(*|*[]): The arguments to be partially applied.
Returns
(Function): Returns the new partially applied function.
Example
function greet(greeting, name) {
return greeting + ' ' + name;
}
var greetFred = _.partialRight(greet, 'fred');
greetFred('hi');
// => 'hi fred'
// Partially applied with placeholders.
var sayHelloTo = _.partialRight(greet, ['hello', _]);
sayHelloTo('fred');
// => 'hello fred'
_.rearg(indexes, func)
Creates a function that invokes func
with arguments arranged according
to the specified indexes
where the argument value at the first index is
provided as the first argument, the argument value at the second index is
provided as the second argument, and so on.
Since
3.0.0
Arguments
indexes
(number|number[]): The arranged argument indexes.func
(Function): The function to rearrange arguments for.
Returns
(Function): Returns the new function.
Example
var rearged = _.rearg([2, 0, 1], function(a, b, c) {
return [a, b, c];
});
rearged('b', 'c', 'a')
// => ['a', 'b', 'c']
_.rest(func)
Creates a function that invokes func
with the this
binding of the
created function and arguments from start
and beyond provided as
an array.
Note: This method is based on the
rest parameter.
Since
4.0.0
Arguments
func
(Function): The function to apply a rest parameter to.
Returns
(Function): Returns the new function.
Example
var say = _.rest(function(what, names) {
return what + ' ' + _.initial(names).join(', ') +
(_.size(names) > 1 ? ', & ' : '') + _.last(names);
});
say('hello', 'fred', 'barney', 'pebbles');
// => 'hello fred, barney, & pebbles'
_.spread(func)
Creates a function that invokes func
with the this
binding of the
create function and an array of arguments much like
Function#apply
.
Note: This method is based on the
spread operator.
Since
3.2.0
Arguments
func
(Function): The function to spread arguments over.
Returns
(Function): Returns the new function.
Example
var say = _.spread(function(who, what) {
return who + ' says ' + what;
});
say(['fred', 'hello']);
// => 'fred says hello'
var numbers = Promise.all([
Promise.resolve(40),
Promise.resolve(36)
]);
numbers.then(_.spread(function(x, y) {
return x + y;
}));
// => a Promise of 76
_.throttle(wait, func)
Creates a throttled function that only invokes func
at most once per
every wait
milliseconds. The throttled function comes with a cancel
method to cancel delayed func
invocations and a flush
method to
immediately invoke them. Provide options
to indicate whether func
should be invoked on the leading and/or trailing edge of the wait
timeout. The func
is invoked with the last arguments provided to the
throttled function. Subsequent calls to the throttled 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 throttled function
is invoked more than once during the wait
timeout.
If wait
is 0
and leading
is false
, func
invocation is deferred
until to the next tick, similar to setTimeout
with a timeout of 0
.
See David Corbacho's article
for details over the differences between _.throttle
and _.debounce
.
Since
0.1.0
Arguments
wait
(number): The number of milliseconds to throttle invocations to.func
(Function): The function to throttle.
Returns
(Function): Returns the new throttled function.
Example
// Avoid excessively updating the position while scrolling.
jQuery(window).on('scroll', _.throttle(100, updatePosition));
// Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
var throttled = _.throttle([300000, { 'trailing': false }], renewToken);
jQuery(element).on('click', throttled);
// Cancel the trailing throttled invocation.
jQuery(window).on('popstate', throttled.cancel);
_.unary(func)
Creates a function that accepts up to one argument, ignoring any additional arguments.
Since
4.0.0
Arguments
func
(Function): The function to cap arguments for.
Returns
(Function): Returns the new capped function.
Example
_.map(_.unary(parseInt), ['6', '8', '10']);
// => [6, 8, 10]
_.wrap(wrapper, value)
Creates a function that provides value
to wrapper
as its first
argument. Any additional arguments provided to the function are appended
to those provided to the wrapper
. The wrapper is invoked with the this
binding of the created function.
Since
0.1.0
Arguments
wrapper
(Function): The wrapper function.value
(*): The value to wrap.
Returns
(Function): Returns the new function.
Example
var p = _.wrap(function(func, text) {
return '<p>' + func(text) + '</p>';
}, _.escape);
p('fred, barney, & pebbles');
// => '<p>fred, barney, & pebbles</p>'
“Lang” Methods
_.castArray(value)
Casts value
as an array if it's not one.
Since
4.4.0
Arguments
value
(*): The value to inspect.
Returns
(Array): Returns the cast array.
Example
_.castArray(1);
// => [1]
_.castArray({ 'a': 1 });
// => [{ 'a': 1 }]
_.castArray('abc');
// => ['abc']
_.castArray(null);
// => [null]
_.castArray(undefined);
// => [undefined]
_.castArray(null);
// => []
var array = [1, 2, 3];
// => true
_.clone(value)
Creates a shallow clone of value
.
Note: This method is loosely based on the
structured clone algorithm
and supports cloning arrays, array buffers, booleans, date objects, maps,
numbers, Object
objects, regexes, sets, strings, symbols, and typed
arrays. The own enumerable properties of arguments
objects are cloned
as plain objects. An empty object is returned for uncloneable values such
as error objects, functions, DOM nodes, and WeakMaps.
Since
0.1.0
Arguments
value
(*): The value to clone.
Returns
(*): Returns the cloned value.
Example
var objects = [{ 'a': 1 }, { 'b': 2 }];
var shallow = _.clone(objects);
// => true
_.cloneDeep(value)
This method is like _.clone
except that it recursively clones value
.
Since
1.0.0
Arguments
value
(*): The value to recursively clone.
Returns
(*): Returns the deep cloned value.
Example
var objects = [{ 'a': 1 }, { 'b': 2 }];
var deep = _.cloneDeep(objects);
// => false
_.cloneDeepWith(customizer, value)
This method is like _.cloneWith
except that it recursively clones value
.
Since
4.0.0
Arguments
customizer
(Function): The function to customize cloning.value
(*): The value to recursively clone.
Returns
(*): Returns the deep cloned value.
Example
function customizer(value) {
if (_.isElement(value)) {
return value.cloneNode(true);
}
}
var el = _.cloneDeepWith(customizer, document.body);
// => false
// => 'BODY'
// => 20
_.cloneWith(customizer, value)
This method is like _.clone
except that it accepts customizer
which
is invoked to produce the cloned value. If customizer
returns undefined
,
cloning is handled by the method instead. The customizer
is invoked with
up to four arguments; (value [, index|key, object, stack]).
Since
4.0.0
Arguments
customizer
(Function): The function to customize cloning.value
(*): The value to clone.
Returns
(*): Returns the cloned value.
Example
function customizer(value) {
if (_.isElement(value)) {
return value.cloneNode(false);
}
}
var el = _.cloneWith(customizer, document.body);
// => false
// => 'BODY'
// => 0
_.conformsTo(source, object)
Checks if object
conforms to source
by invoking the predicate
properties of source
with the corresponding property values of object
.
Note: This method is equivalent to _.conforms
when source
is
partially applied.
Since
4.14.0
Arguments
source
(Object): The object of property predicates to conform to.object
(Object): The object to inspect.
Returns
(boolean): Returns true
if object
conforms, else false
.
Example
var object = { 'a': 1, 'b': 2 };
_.conformsTo({ 'b': function(n) { return n > 1; } }, object);
// => true
_.conformsTo({ 'b': function(n) { return n > 2; } }, object);
// => false
_.eq(value, other)
Performs a
SameValueZero
comparison between two values to determine if they are equivalent.
Since
4.0.0
Arguments
value
(*): The value to compare.other
(*): The other value to compare.
Returns
(boolean): Returns true
if the values are equivalent, else false
.
Example
var object = { 'a': 1 };
var other = { 'a': 1 };
_.eq(object, object);
// => true
_.eq(object, other);
// => false
_.eq('a', 'a');
// => true
_.eq('a', Object('a'));
// => false
_.eq(NaN, NaN);
// => true
_.gt(value, other)
Checks if value
is greater than other
.
Since
3.9.0
Arguments
value
(*): The value to compare.other
(*): The other value to compare.
Returns
(boolean): Returns true
if value
is greater than other
, else false
.
Example
_.gt(3, 1);
// => true
_.gt(3, 3);
// => false
_.gt(1, 3);
// => false
_.gte(value, other)
Checks if value
is greater than or equal to other
.
Since
3.9.0
Arguments
value
(*): The value to compare.other
(*): The other value to compare.
Returns
(boolean): Returns true
if value
is greater than or equal to other
, else false
.
Example
_.gte(3, 1);
// => true
_.gte(3, 3);
// => true
_.gte(1, 3);
// => false
_.isArguments(value)
Checks if value
is likely an arguments
object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an arguments
object, else false
.
Example
_.isArguments(function() { return arguments; }());
// => true
_.isArguments([1, 2, 3]);
// => false
_.isArray(value)
Checks if value
is classified as an Array
object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an array, else false
.
Example
_.isArray([1, 2, 3]);
// => true
_.isArray(document.body.children);
// => false
_.isArray('abc');
// => false
_.isArray(_.noop);
// => false
_.isArrayBuffer(value)
Checks if value
is classified as an ArrayBuffer
object.
Since
4.3.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an array buffer, else false
.
Example
_.isArrayBuffer(new ArrayBuffer(2));
// => true
_.isArrayBuffer(new Array(2));
// => false
_.isArrayLike(value)
Checks if value
is array-like. A value is considered array-like if it's
not a function and has a value.length
that's an integer greater than or
equal to 0
and less than or equal to Number.MAX_SAFE_INTEGER
.
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is array-like, else false
.
Example
_.isArrayLike([1, 2, 3]);
// => true
_.isArrayLike(document.body.children);
// => true
_.isArrayLike('abc');
// => true
_.isArrayLike(_.noop);
// => false
_.isArrayLikeObject(value)
This method is like _.isArrayLike
except that it also checks if value
is an object.
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an array-like object, else false
.
Example
_.isArrayLikeObject([1, 2, 3]);
// => true
_.isArrayLikeObject(document.body.children);
// => true
_.isArrayLikeObject('abc');
// => false
_.isArrayLikeObject(_.noop);
// => false
_.isBoolean(value)
Checks if value
is classified as a boolean primitive or object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a boolean, else false
.
Example
_.isBoolean(false);
// => true
_.isBoolean(null);
// => false
_.isBuffer(value)
Checks if value
is a buffer.
Since
4.3.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a buffer, else false
.
Example
_.isBuffer(new Buffer(2));
// => true
_.isBuffer(new Uint8Array(2));
// => false
_.isDate(value)
Checks if value
is classified as a Date
object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a date object, else false
.
Example
_.isDate(new Date);
// => true
_.isDate('Mon April 23 2012');
// => false
_.isElement(value)
Checks if value
is likely a DOM element.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a DOM element, else false
.
Example
_.isElement(document.body);
// => true
_.isElement('<body>');
// => false
_.isEmpty(value)
Checks if value
is an empty object, collection, map, or set.
Objects are considered empty if they have no own enumerable string keyed
properties.
Array-like values such as arguments
objects, arrays, buffers, strings, or
jQuery-like collections are considered empty if they have a length
of 0
.
Similarly, maps and sets are considered empty if they have a size
of 0
.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is empty, else false
.
Example
_.isEmpty(null);
// => true
_.isEmpty(true);
// => true
_.isEmpty(1);
// => true
_.isEmpty([1, 2, 3]);
// => false
_.isEmpty({ 'a': 1 });
// => false
_.isEqual(value, other)
Performs a deep comparison between two values to determine if they are
equivalent.
Note: This method supports comparing arrays, array buffers, booleans,
date objects, error objects, maps, numbers, Object
objects, regexes,
sets, strings, symbols, and typed arrays. Object
objects are compared
by their own, not inherited, enumerable properties. Functions and DOM
nodes are compared by strict equality, i.e. ===
.
Since
0.1.0
Arguments
value
(*): The value to compare.other
(*): The other value to compare.
Returns
(boolean): Returns true
if the values are equivalent, else false
.
Example
var object = { 'a': 1 };
var other = { 'a': 1 };
_.isEqual(object, other);
// => true
object === other;
// => false
_.isEqualWith(customizer, value, other)
This method is like _.isEqual
except that it accepts customizer
which
is invoked to compare values. If customizer
returns undefined
, comparisons
are handled by the method instead. The customizer
is invoked with up to
six arguments: (objValue, othValue [, index|key, object, other, stack]).
Since
4.0.0
Arguments
customizer
(Function): The function to customize comparisons.value
(*): The value to compare.other
(*): The other value to compare.
Returns
(boolean): Returns true
if the values are equivalent, else false
.
Example
function isGreeting(value) {
return /^h(?:i|ello)$/.test(value);
}
function customizer(objValue, othValue) {
if (isGreeting(objValue) && isGreeting(othValue)) {
return true;
}
}
var array = ['hello', 'goodbye'];
var other = ['hi', 'goodbye'];
_.isEqualWith(customizer, array, other);
// => true
_.isError(value)
Checks if value
is an Error
, EvalError
, RangeError
, ReferenceError
,
SyntaxError
, TypeError
, or URIError
object.
Since
3.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an error object, else false
.
Example
_.isError(new Error);
// => true
_.isError(Error);
// => false
_.isFinite(value)
Checks if value
is a finite primitive number.
Note: This method is based on
Number.isFinite
.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a finite number, else false
.
Example
_.isFinite(3);
// => true
_.isFinite(Number.MIN_VALUE);
// => true
_.isFinite(Infinity);
// => false
_.isFinite('3');
// => false
_.isFunction(value)
Checks if value
is classified as a Function
object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a function, else false
.
Example
_.isFunction(_);
// => true
_.isFunction(/abc/);
// => false
_.isInteger(value)
Checks if value
is an integer.
Note: This method is based on
Number.isInteger
.
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an integer, else false
.
Example
_.isInteger(3);
// => true
_.isInteger(Number.MIN_VALUE);
// => false
_.isInteger(Infinity);
// => false
_.isInteger('3');
// => false
_.isLength(value)
Checks if value
is a valid array-like length.
Note: This method is loosely based on
ToLength
.
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a valid length, else false
.
Example
_.isLength(3);
// => true
_.isLength(Number.MIN_VALUE);
// => false
_.isLength(Infinity);
// => false
_.isLength('3');
// => false
_.isMap(value)
Checks if value
is classified as a Map
object.
Since
4.3.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a map, else false
.
Example
_.isMap(new Map);
// => true
_.isMap(new WeakMap);
// => false
_.isMatch(source, object)
Performs a partial deep comparison between object
and source
to
determine if object
contains equivalent property values.
Note: This method is equivalent to _.matches
when source
is
partially applied.
Partial comparisons will match empty array and empty object source
values against any array or object value, respectively. See _.isEqual
for a list of supported value comparisons.
Since
3.0.0
Arguments
source
(Object): The object of property values to match.object
(Object): The object to inspect.
Returns
(boolean): Returns true
if object
is a match, else false
.
Example
var object = { 'a': 1, 'b': 2 };
_.isMatch({ 'b': 2 }, object);
// => true
_.isMatch({ 'b': 1 }, object);
// => false
_.isMatchWith(customizer, source, object)
This method is like _.isMatch
except that it accepts customizer
which
is invoked to compare values. If customizer
returns undefined
, comparisons
are handled by the method instead. The customizer
is invoked with five
arguments: (objValue, srcValue, index|key, object, source).
Since
4.0.0
Arguments
customizer
(Function): The function to customize comparisons.source
(Object): The object of property values to match.object
(Object): The object to inspect.
Returns
(boolean): Returns true
if object
is a match, else false
.
Example
function isGreeting(value) {
return /^h(?:i|ello)$/.test(value);
}
function customizer(objValue, srcValue) {
if (isGreeting(objValue) && isGreeting(srcValue)) {
return true;
}
}
var object = { 'greeting': 'hello' };
var source = { 'greeting': 'hi' };
_.isMatchWith(customizer, source, object);
// => true
_.isNaN(value)
Checks if value
is NaN
.
Note: This method is based on
Number.isNaN
and is not the same as
global isNaN
which returns true
for
undefined
and other non-number values.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is NaN
, else false
.
Example
_.isNaN(NaN);
// => true
_.isNaN(new Number(NaN));
// => true
isNaN(undefined);
// => true
_.isNaN(undefined);
// => false
_.isNative(value)
Checks if value
is a pristine native function.
Note: This method can't reliably detect native functions in the presence
of the core-js package because core-js circumvents this kind of detection.
Despite multiple requests, the core-js maintainer has made it clear: any
attempt to fix the detection will be obstructed. As a result, we're left
with little choice but to throw an error. Unfortunately, this also affects
packages, like babel-polyfill,
which rely on core-js.
Since
3.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a native function, else false
.
Example
_.isNative(Array.prototype.push);
// => true
_.isNative(_);
// => false
_.isNil(value)
Checks if value
is null
or undefined
.
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is nullish, else false
.
Example
_.isNil(null);
// => true
_.isNil(void 0);
// => true
_.isNil(NaN);
// => false
_.isNull(value)
Checks if value
is null
.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is null
, else false
.
Example
_.isNull(null);
// => true
_.isNull(void 0);
// => false
_.isNumber(value)
Checks if value
is classified as a Number
primitive or object.
Note: To exclude Infinity
, -Infinity
, and NaN
, which are
classified as numbers, use the _.isFinite
method.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a number, else false
.
Example
_.isNumber(3);
// => true
_.isNumber(Number.MIN_VALUE);
// => true
_.isNumber(Infinity);
// => true
_.isNumber('3');
// => false
_.isObject(value)
Checks if value
is the
language type
of Object
. (e.g. arrays, functions, objects, regexes, new Number(0)
, and new String('')
)
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is an object, else false
.
Example
_.isObject({});
// => true
_.isObject([1, 2, 3]);
// => true
_.isObject(_.noop);
// => true
_.isObject(null);
// => false
_.isObjectLike(value)
Checks if value
is object-like. A value is object-like if it's not null
and has a typeof
result of "object".
Since
4.0.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is object-like, else false
.
Example
_.isObjectLike({});
// => true
_.isObjectLike([1, 2, 3]);
// => true
_.isObjectLike(_.noop);
// => false
_.isObjectLike(null);
// => false
_.isPlainObject(value)
Checks if value
is a plain object, that is, an object created by the
Object
constructor or one with a [[Prototype]]
of null
.
Since
0.8.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a plain object, else false
.
Example
function Foo() {
this.a = 1;
}
_.isPlainObject(new Foo);
// => false
_.isPlainObject([1, 2, 3]);
// => false
_.isPlainObject({ 'x': 0, 'y': 0 });
// => true
_.isPlainObject(Object.create(null));
// => true
_.isRegExp(value)
Checks if value
is classified as a RegExp
object.
Since
0.1.0
Arguments
value
(*): The value to check.
Returns
(boolean): Returns true
if value
is a regexp, else false
.
Example
_.isRegExp(/abc/);
// => true
_.isRegExp('/abc/');
// => false
_.isSafeInteger(value)
Checks if value
is a safe integer. An integer is safe if it's an IEEE-754
double precision number which isn't the result o