The object containing all immutable-lodash
functions.
- Source:
Example
// Important note for examples:
// Rather than specifying every example data structure like so:
let map = List([Map({ 'a': 1 }), Map({ 'b': 2 }), Map({ 'c': 3 }) ])
// Immutable Lists and Maps are implied:
let map = [ { 'a': 1 }, { 'b': 2 }, { 'c': 3 } ]
// This is to make the it easier for you to see what every function is actually doing.
// As a rule, `immutable-lodash` functions try to return the type of object that was passed in, or,
// where it makes more sense, a lazy `Seq`. The docs specify a "Returns:" type for every function,
// which you can see below.
Methods
_.at(iterable, […paths]) → {Iterable}
Creates an array of values corresponding to paths
of iterable
.
Example
let iterable = { 'a': [{ 'b': { 'c': 3 } }, 4] }
_.at(iterable, ['a[0].b.c', 'a[1]'])
// => [3, 4]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The iterable to iterate over. |
|
paths |
string | Array.<string> |
<optional> <repeatable> |
The property paths of elements to pick. |
- Source:
Returns:
Returns the picked values.
- Type
- Iterable
_.chunk(iterable, [size]) → {Iterable}
Creates an iterable of elements split into groups the length of size
.
If iterable
can't be split evenly, the final chunk will be the remaining
elements.
Example
let list = ['a', 'b', 'c', 'd']
_.chunk(list, 2)
// => [['a', 'b'], ['c', 'd']]
_.chunk(list, 3)
// => [['a', 'b', 'c'], ['d']]
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to process. |
||
size |
number |
<optional> |
1 | The length of each chunk |
- Source:
Returns:
Returns the new iterable of chunks.
- Type
- Iterable
_.compact(iterable, Returns)
Creates an iterable with all falsey values removed. The values false
, null
,
0
, ""
, undefined
, and NaN
are falsey.
Example
_.compact([0, 1, false, 2, '', 3])
// => [1, 2, 3]
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The iterable to compact. |
Returns |
Iterable | the new iterable of filtered values. |
- Source:
_.concat(iterable, […values], Returns)
Creates an Iterable of the same type concatenating iterable
with any additional iterables and/or values.
Example
_.concat(['a'], 2, [3], [[4]])
// => ['a', 2, 3, [4]]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The iterable to concatenate. |
|
values |
* |
<optional> <repeatable> |
The values to concatenate. |
Returns |
Iterable | the new concatenated sequence. |
- Source:
_.countBy([iteratee])
Creates a Map composed of keys generated from the results of running
each element of iterable
through 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).
Example
_.countBy([6.1, 4.2, 6.3], Math.floor)
// => { '4': 1, '6': 2 }
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iteratee |
function |
<optional> |
_.identity | The iteratee to transform keys. |
- Source:
_.defaults(iterable, […sources]) → {Iterable}
Creates new iterable with all properties of source iterables that resolve
to undefined
. Source iterables are applied from left to right.
Once a key is set, additional values of the same key are ignored.
Example
_.defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
// => { 'a': 1, 'b': 2 }
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The destination iterable. |
|
sources |
Iterable |
<optional> <repeatable> |
The source iterables. |
- Source:
- See:
Returns:
Returns iterable
.
- Type
- Iterable
_.defaultsDeep(iterable, […sources]) → {Iterable}
This method is like _.defaults
except that it recursively assigns
default properties.
Example
_.defaultsDeep({ 'a': { 'b': 2 } }, { 'a': { 'b': 1, 'c': 3 } })
// => { 'a': { 'b': 2, 'c': 3 } }
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The destination iterable. |
|
sources |
Iterable |
<optional> <repeatable> |
The source iterables. |
- Source:
- See:
Returns:
Returns iterable
.
- Type
- Iterable
_.difference(iterable, […values]) → {Iterable}
Creates an Iterable of iterable
values not included in the other given iterables
The order of result values is determined by the order they occur
in the first iterable.
Example
_.difference([2, 1], [2, 3])
// => [1]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The iterable to inspect. |
|
values |
Iterable |
<optional> <repeatable> |
The values to exclude. |
- Source:
- See:
-
- _.without, _.xor
Returns:
Returns the iterable of filtered values.
- Type
- Iterable
_.differenceBy(iterable, […values], [iteratee]) → {Iterable}
This method is like _.difference
except that it accepts iteratee
which
is invoked for each element of iterable
and values
to generate the criterion
by which they're compared. Result values are chosen from the first iterable.
The iteratee is invoked with one argument: (value).
Example
_.differenceBy([2.1, 1.2], [2.3, 3.4], Math.floor)
// => [1.2]
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to inspect. |
||
values |
Iterable |
<optional> <repeatable> |
The values to exclude. |
|
iteratee |
function |
<optional> |
_.identity | The iteratee invoked per element. |
- Source:
Returns:
Returns the new iterable of filtered values.
- Type
- Iterable
_.fill(iterable, value, [start], [end]) → {Iterable}
Fills elements of iterable
with value
from start
up to, but not
including, end
.
Example
let list = [1, 2, 3]
_.fill(list, 'a')
// => ['a', 'a', 'a']
_.fill([4, 6, 8, 10], '*', 1, 3)
// => [4, '*', '*', 10]
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to fill. |
||
value |
* | The value to fill |
||
start |
number |
<optional> |
0 | The start position. |
end |
number |
<optional> |
iterable.size | The end position. |
- Source:
Returns:
Returns iterable
.
- Type
- Iterable
_.groupBy(iterable, [iteratee]) → {Map}
Creates a map composed of keys generated from the results of running
each element of iterable
through iteratee
. The order of grouped values
is determined by the order they occur in iterable
. The corresponding
value of each key is a List of elements responsible for generating the
key. The iteratee is invoked with one argument: (value).
Example
_.groupBy([6.1, 4.2, 6.3], Math.floor)
// => { '4': [4.2], '6': [6.1, 6.3] }
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to iterate over. |
||
iteratee |
function |
<optional> |
_.identity | The iteratee to transform keys. |
- Source:
Returns:
Returns the composed aggregate map.
- Type
- Map
_.intersection([…iterables]) → {Iterable}
Returns a sequence of unique values that are included in all given iterables The order of result values is determined by the order they occur in the first iterable.
Example
_.intersection([2, 1], [2, 3])
// => Seq [2]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterables |
Iterable |
<optional> <repeatable> |
The iterables to inspect. |
- Source:
Returns:
Returns the new iterable of intersecting values.
- Type
- Iterable
_.invert(iterable) → {Iterable}
Creates an iterable composed of the inverted keys and values of iterable
.
If iterable
contains duplicate values, subsequent values overwrite
property assignments of previous values.
Example
let iterable = { 'a': 1, 'b': 2, 'c': 1 }
_.invert(iterable)
// => { '1': 'c', '2': 'b' }
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The iterable to invert. |
- Source:
Returns:
Returns the new inverted iterable.
- Type
- Iterable
_.keyBy(iterable, [iteratee]) → {Map}
Creates a Map composed of keys generated from the results of running
each element of iterable
through iteratee
. The corresponding value of
each key is the last element responsible for generating the key. The
iteratee is invoked with one argument: (value).
Example
let keys = [
{ 'dir': 'left', 'code': 97 },
{ 'dir': 'right', 'code': 100 }
]
_.keyBy(keys, (o) => String.fromCharCode(o.code))
// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }
_.keyBy(keys, 'dir')
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to iterate over. |
||
iteratee |
function |
<optional> |
_.identity | The iteratee to transform keys. |
- Source:
Returns:
Returns the composed aggregate map.
- Type
- Map
_.omit(iterable, […props]) → {Iterable}
The opposite of _.pick
this method creates a new iterable omitting the
supplied keys
Example
let map = { 'a': 1, 'b': '2', 'c': 3 }
_.omit(map, ['a', 'c'])
// => { 'b': '2' }
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The source iterable. |
|
props |
string | Array.<string> |
<optional> <repeatable> |
The property identifiers to omit. |
- Source:
Returns:
Returns the new iterable.
- Type
- Iterable
_.omitBy(iterable, [predicate]) → {Iterable}
The opposite of _.pick
this method creates a new iterable omitting the
supplied keys predicate
doesn't return truthy for. The predicate is invoked with two
arguments: (value, key).
Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }
_.omitBy(iterable, _.isNumber)
// => { 'b': '2' }
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The source iterable. |
||
predicate |
function |
<optional> |
_.identity | The function invoked per property. |
- Source:
Returns:
Returns the new iterable.
- Type
- Iterable
_.partition(iterable, [predicate]) → {List}
Creates a list 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).
Example
let users = [
{ 'user': 'barney', 'age': 36, 'active': false },
{ 'user': 'fred', 'age': 40, 'active': true },
{ 'user': 'pebbles', 'age': 1, 'active': false }
]
_.partition(users, (o) => o.active)
// => objects for [['fred'], ['barney', 'pebbles']]
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to iterate over. |
||
predicate |
function |
<optional> |
_.identity | The function invoked per iteration. |
- Source:
Returns:
Returns the list of grouped elements.
- Type
- List
_.pick(iterable, […props]) → {Iterable}
Creates an iterable composed of the picked iterable
properties.
Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }
_.pick(iterable, ['a', 'c'])
// => { 'a': 1, 'c': 3 }
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The source iterable. |
|
props |
string | Array.<string> |
<optional> <repeatable> |
The property identifiers to pick. |
- Source:
Returns:
Returns the new iterable.
- Type
- Iterable
_.pickBy(iterable, [predicate]) → {Iterable}
Creates an iterable composed of the iterable
properties predicate
returns
truthy for. The predicate is invoked with two arguments: (value, key).
Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }
_.pickBy(iterable, _.isNumber)
// => { 'a': 1, 'c': 3 }
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The source iterable. |
||
predicate |
function |
<optional> |
_.identity | The function invoked per property. |
- Source:
Returns:
Returns the new iterable.
- Type
- Iterable
_.pullAt(iterable, […indexes]) → {Iterable}
Removes elements from iterable
corresponding to indexes
and returns an
iterable of removed elements.
Example
let iterable = ['a', 'b', 'c', 'd']
_.pullAt(iterable, [1, 3])
// => ['b', 'd']
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterable |
Iterable | The iterable to modify. |
|
indexes |
number | Array.<number> |
<optional> <repeatable> |
The indexes of elements to remove. |
- Source:
Returns:
Returns the new iterable of removed elements.
- Type
- Iterable
_.sample(iterable) → {*}
Gets a random element from iterable
.
Example
_.sample([1, 2, 3, 4])
// => 2
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The iterable to sample. |
- Source:
Returns:
Returns the random element.
- Type
- *
_.sampleSize(iterable, [n]) → {List}
Gets n
random elements at unique keys from iterable
up to the
size of iterable
.
Example
_.sampleSize([1, 2, 3], 2)
// => List [3, 1]
_.sampleSize([1, 2, 3], 4)
// => List [2, 3, 1]
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The iterable to sample. |
||
n |
number |
<optional> |
1 | The number of elements to sample. |
- Source:
Returns:
Returns the random elements.
- Type
- List
_.shuffle(iterable) → {Iterable}
Creates an iterable of shuffled values, using a version of the Fisher-Yates shuffle.
Example
_.shuffle([1, 2, 3, 4])
// => [4, 1, 3, 2]
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The iterable to shuffle. |
- Source:
Returns:
Returns the new shuffled iterable.
- Type
- Iterable
_.sortedIndex(iterable, value) → {number}
Determines the lowest index at which value
should be inserted into iterable
in order to maintain its sort order.
Example
_.sortedIndex([30, 50], 40)
// => 1
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The sorted iterable to inspect. |
value |
* | The value to evaluate. |
- Source:
Returns:
Returns the index at which value
should be inserted
into iterable
.
- Type
- number
_.sortedIndexBy(iterable, value, [iteratee]) → {number}
This method is like _.sortedIndex
except that it accepts iteratee
which is invoked for value
and each element of iterable
to compute their
sort ranking. The iteratee is invoked with one argument: (value).
Example
let maps = [{ 'x': 4 }, { 'x': 5 }]
_.sortedIndexBy(maps, { 'x': 4 }, (o) => o.x)
// => 0
// The `_.property` iteratee shorthand.
_.sortedIndexBy(maps, { 'x': 4 }, 'x')
// => 0
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
iterable |
Iterable | The sorted iterable to inspect. |
||
value |
* | The value to evaluate. |
||
iteratee |
function |
<optional> |
_.identity | The iteratee invoked per element. |
- Source:
Returns:
Returns the index at which value
should be inserted
into iterable
.
- Type
- number
_.union([…iterables]) → {Seq}
Creates an iterable of unique values, in order, from all given iterables.
Example
_.union([2], [1, 2])
// => Seq [2, 1]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterables |
Iterable |
<optional> <repeatable> |
The iterables to inspect. |
- Source:
Returns:
Returns the new iterable of combined values.
- Type
- Seq
_.uniq(iterable) → {Seq}
Creates a duplicate-free sequence of the iterable, in which only the first occurrence of each element is kept.
Example
_.uniq([2, 1, 2])
// => Seq [2, 1]
Parameters:
Name | Type | Description |
---|---|---|
iterable |
Iterable | The iterable to inspect. |
- Source:
Returns:
Returns the new duplicate free sequence.
- Type
- Seq
_.xor([…iterables]) → {Seq}
Creates a sequence of unique values that is the symmetric difference of the given iterables. The order of result values is determined by the order they occur in the iterables.
Example
_.xor([2, 1], [2, 3])
// => [1, 3]
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
iterables |
Iterable |
<optional> <repeatable> |
The iterables to inspect. |
- Source:
- See:
Returns:
Returns the sequence of filtered values.
- Type
- Seq