Type Parameters
Hierarchy
Properties
Methods
Returns
thisSee Also
Map#asImmutable
An alternative API for withMutations()
Note: Not all methods can be safely used on a mutable collection or within
withMutations! Check the documentation for each method to see if it allows being used inwithMutations.Returns
thisSee Also
Map#asMutable
Returns a new Collection of the same type containing all entries except the last.
Returns
this
Returns a new List with 0 size and no values in constant time.
Note:
clearcan be used inwithMutations.Returns
Returns the size of this Collection.
Regardless of if this Collection can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy
Seqif necessary.If
predicateis provided, then this returns the count of entries in the Collection for which thepredicatereturns true.Returns
numberParameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
number
Returns a new List which excludes this
indexand with a size 1 less than this List. Values at indices aboveindexare shifted down by 1 to fill the position.This is synonymous with
list.splice(index, 1).indexmay be a negative number, which indexes back from the end of the List.v.delete(-1)deletes the last item in the List.Note:
deletecannot be safely used in IE8Since
delete()re-indexes values, it produces a complete copy, which hasO(N)complexity.Note:
deletecannot be used inwithMutations.
Returns a new List having removed the value at this
keyPath. If any keys inkeyPathdo not exist, no change will occur.Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and removeIn() can update those values as well, treating them immutably by creating new copies of those values with the changes applied.
Note:
deleteIncannot be safely used inwithMutations.
An iterator of this
Collection's entries as[ key, value ]tuples.Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use
entrySeqinstead, if this is what you want.Returns
IterableIterator<[number, T]>
Returns a new Seq.Indexed of [key, value] tuples.
Returns
Indexed<[number, T]>
True if
predicatereturns true for all entries in the Collection.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
boolean
- filter<F>(
predicate: (value: T, index: number, iter: this) => value is F,
context?: unknown,
): NutrientViewer.Immutable.List<F>Returns a new List with only the values for which the
predicatefunction returns true.Note:
filter()always returns a new instance, even if it results in not filtering out any values. Returns a new Collection with only the values for which the
predicatefunction returns true.Note:
filter()always returns a new instance, even if it results in not filtering out any values.Parameters
predicate(value: T, index: number, iter: this) => unknowncontextunknownOptionalReturns
this
Returns a new Collection of the same type with only the entries for which the
predicatefunction returns false.Note:
filterNot()always returns a new instance, even if it results in not filtering out any values.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
this
Returns the first index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.
Parameters
predicate(value: T, index: number, iter: this) => booleancontextunknownOptionalReturns
number
- findLastIndex(
predicate: (value: T, index: number, iter: this) => boolean,
context?: unknown,
): numberReturns the last index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.
Parameters
predicate(value: T, index: number, iter: this) => booleancontextunknownOptionalReturns
number
- findLastKey(
predicate: (value: T, key: number, iter: this) => boolean,
context?: unknown,
): number | undefinedReturns the last key for which the
predicatereturns true.Note:
predicatewill be called for each entry in reverse.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
number | undefined
Returns
T | undefined
Flattens nested Collections.
Will deeply flatten the Collection by default, returning a Collection of the same type, but a
depthcan be provided in the form of a number or boolean (where true means to shallowly flatten one level). A depth of 0 (or shallow: false) will deeply flatten.Flattens only others Collection, not Arrays or Objects.
Note:
flatten(true)operates on Collection<unknown, Collection<K, V>> and returns Collection<K, V>Parameters
depthnumberOptionalReturns
Collection<unknown, unknown>Parameters
shallowbooleanOptionalReturns
Collection<unknown, unknown>
The
sideEffectis executed for every entry in the Collection.Unlike
Array#forEach, if any call ofsideEffectreturnsfalse, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).Parameters
sideEffect(value: T, key: number, iter: this) => unknowncontextunknownOptionalReturns
number
If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.
Returns
Keyed<unknown, unknown>
True if a value exists within this
Collection, usingImmutable.isto determine equality
Returns the first index at which a given value can be found in the Collection, or -1 if it is not present.
Parameters
searchValueTReturns
number
Returns a new List with
valueatindexwith a size 1 more than this List. Values at indices aboveindexare shifted over by 1.This is synonymous with
list.splice(index, 0, value).Since
insert()re-indexes values, it produces a complete copy, which hasO(N)complexity.Note:
insertcannot be used inwithMutations.Parameters
indexnumbervalueTReturns
Returns a Collection of the same type with the provided
collectionsinterleaved into this collection.The resulting Collection includes the first item from each, then the second from each, etc.
The shortest Collection stops interleave.
Since
interleave()re-indexes values, it produces a complete copy, which hasO(N)complexity.Note:
interleavecannot be used inwithMutations.Parameters
...collectionsCollection<unknown, T>[]Returns
this
Returns a Collection of the same type with
separatorbetween each item in this Collection.Parameters
separatorTReturns
this
Returns true if this Collection includes no values.
For some lazy
Seq,isEmptymight need to iterate to determine emptiness. At most one iteration will occur.Returns
boolean
Joins values together as a string, inserting a separator between each. The default separator is
",".Parameters
separatorstringOptionalReturns
string
Returns the key associated with the search value, or undefined.
Parameters
searchValueTReturns
number | undefined
An iterator of this
Collection's keys.Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use
keySeqinstead, if this is what you want.Returns
IterableIterator<number>
Returns a new Seq.Indexed of the keys of this Collection, discarding values.
Returns
Indexed<number>
Returns
T | undefined
Returns the last index at which a given value can be found in the Collection, or -1 if it is not present.
Parameters
searchValueTReturns
number
Returns the last key associated with the search value, or undefined.
Parameters
searchValueTReturns
number | undefined
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
The
comparatoris used in the same way asCollection#sort. If it is not provided, the default comparator is>.When two values are considered equivalent, the first encountered will be returned. Otherwise,
maxwill operate independent of the order of input as long as the comparator is commutative. The default comparator>is commutative only when types do not differ.If
comparatorreturns 0 and either value is NaN, undefined, or null, that value will be returned.
Note:
mergeDeepIncan be used inwithMutations.
Note:
mergeIncan be used inwithMutations.
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
The
comparatoris used in the same way asCollection#sort. If it is not provided, the default comparator is<.When two values are considered equivalent, the first encountered will be returned. Otherwise,
minwill operate independent of the order of input as long as the comparator is commutative. The default comparator<is commutative only when types do not differ.If
comparatorreturns 0 and either value is NaN, undefined, or null, that value will be returned.
- partition<F, C>(
predicate: (this: C, value: T, index: number, iter: this) => value is F,
context?: C,
): [NutrientViewer.Immutable.List<T>, NutrientViewer.Immutable.List<F>]Returns a new List with the values for which the
predicatefunction returns false and another for which is returns true. - partition<C>(
predicate: (this: C, value: T, index: number, iter: this) => unknown,
context?: C,
): [NutrientViewer.Immutable.List<T>, NutrientViewer.Immutable.List<T>]Returns a new indexed Collection with the values for which the
predicatefunction returns false and another for which is returns true.
Returns a new List with a size ones less than this List, excluding the last index in this List.
Note: this differs from
Array#popbecause it returns a new List rather than the removed value. Uselast()to get the last value in this List.List([ 1, 2, 3, 4 ]).pop()
// List[ 1, 2, 3 ]Note:
popcan be used inwithMutations.Returns
Returns a new List with the provided
valuesappended, starting at this List'ssize.Note:
pushcan be used inwithMutations.Parameters
...valuesT[]Returns
Reduces the Collection to a value by calling the
reducerfor every entry in the Collection and passing along the reduced value.If
initialReductionis not provided, the first item in the Collection will be used.
Parameters
indexnumberReturns
Returns a new Collection of the same type containing all entries except the first.
Returns
this
Returns a new Collection of the same type in reverse order.
Returns
this
Returns a new List which includes
valueatindex. Ifindexalready exists in this List, it will be replaced.indexmay be a negative number, which indexes back from the end of the List.v.set(-1, "value")sets the last item in the List.If
indexlarger thansize, the returned List'ssizewill be large enough to include theindex.Note:
setcan be used inwithMutations.Parameters
indexnumbervalueTReturns
Returns a new List having set
valueat thiskeyPath. If any keys inkeyPathdo not exist, a new immutable Map will be created at that key.Index numbers are used as keys to determine the path to follow in the List.
Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and setIn() can update those values as well, treating them immutably by creating new copies of those values with the changes applied.
Note:
setIncan be used inwithMutations.Parameters
keyPathIterable<unknown>valueunknownReturns
this
Returns a new List with size
size. Ifsizeis less than this List's size, the new List will exclude values at the higher indices. Ifsizeis greater than this List's size, the new List will have undefined values for the newly available indices.When building a new List and the final size is known up front,
setSizeused in conjunction withwithMutationsmay result in the more performant construction.Parameters
sizenumberReturns
Returns a new List with a size ones less than this List, excluding the first index in this List, shifting all other values to a lower index.
Note: this differs from
Array#shiftbecause it returns a new List rather than the removed value. Usefirst()to get the first value in this List.Note:
shiftcan be used inwithMutations.Returns
Returns a new List with its values shuffled thanks to the Fisher–Yates algorithm. It uses Math.random, but you can provide your own random number generator.
Parameters
random() => numberOptionalReturns
this
Returns a new Collection of the same type which excludes the first
amountentries from this Collection.Parameters
amountnumberReturns
this
Returns a new Collection of the same type which excludes the last
amountentries from this Collection.Parameters
amountnumberReturns
this
Returns a new Collection of the same type which includes entries starting from when
predicatefirst returns true.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
this
Returns a new Collection of the same type which includes entries starting from when
predicatefirst returns false.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
this
Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.
If begin is negative, it is offset from the end of the Collection. e.g.
slice(-2)returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.If end is negative, it is offset from the end of the Collection. e.g.
slice(0, -1)returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.If the requested slice is equivalent to the current Collection, then it will return itself.
Parameters
beginnumberOptionalendnumberOptionalReturns
this
True if
predicatereturns true for any entry in the Collection.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
boolean
Returns a new Collection of the same type which includes the same entries, stably sorted by using a
comparator.If a
comparatoris not provided, a default comparator uses<and>.comparator(valueA, valueB):- Returns
0if the elements should not be swapped. - Returns
-1(or any negative number) ifvalueAcomes beforevalueB - Returns
1(or any positive number) ifvalueAcomes aftervalueB - Alternatively, can return a value of the
PairSortingenum type - Is pure, i.e. it must always return the same value for the same pair of values.
When sorting collections which have no defined order, their ordered equivalents will be returned. e.g.
map.sort()returns OrderedMap.Note:
sort()Always returns a new instance, even if the original was already sorted.Note: This is always an eager operation.
Parameters
Returns
this- Returns
- sortBy<C>(
comparatorValueMapper: (value: T, key: number, iter: this) => C,
comparator?: Comparator<C>,
): thisLike
sort, but also accepts acomparatorValueMapperwhich allows for sorting by more sophisticated means:Note:
sortBy()Always returns a new instance, even if the original was already sorted.Note: This is always an eager operation.
Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.
indexmay be a negative number, which indexes back from the end of the Collection.s.splice(-2)splices after the second to last item.Since
splice()re-indexes values, it produces a complete copy, which hasO(N)complexity.Note:
splicecannot be used inwithMutations.Parameters
Returns
this
Returns a new Collection of the same type which includes the first
amountentries from this Collection.Parameters
amountnumberReturns
this
Returns a new Collection of the same type which includes the last
amountentries from this Collection.Parameters
amountnumberReturns
this
Returns a new Collection of the same type which includes entries from this Collection as long as the
predicatereturns false.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
this
Returns a new Collection of the same type which includes entries from this Collection as long as the
predicatereturns true.Parameters
predicate(value: T, key: number, iter: this) => booleancontextunknownOptionalReturns
this
Returns an Seq.Indexed of the values of this Collection, discarding keys.
Returns
Indexed<T>
Returns a Seq.Keyed from this Collection where indices are treated as keys.
This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Collection.
Returns
Keyed<number, T>
Converts this Collection to a List, discarding keys.
This is similar to
List(collection), but provided to allow for chained expressions. However, when called onMapor other keyed collections,collection.toList()discards the keys and creates a list of only the values, whereasList(collection)creates a list of entry tuples.Returns
Converts this Collection to a Map, maintaining the order of iteration.
Note: This is equivalent to
OrderedMap(this.toKeyedSeq()), but provided for convenience and to allow for chained expressions.Returns
OrderedMap<number, T>
Converts this Collection to a Set, maintaining the order of iteration and discarding keys.
Note: This is equivalent to
OrderedSet(this.valueSeq()), but provided for convenience and to allow for chained expressions.Returns
Converts this Collection to a Set, discarding keys. Throws if values are not hashable.
Note: This is equivalent to
Set(this), but provided to allow for chained expressions.Returns
Returns a new List with the provided
valuesprepended, shifting other values ahead to higher indices.Note:
unshiftcan be used inwithMutations.Parameters
...valuesT[]Returns
Returns a new List with an updated value at
indexwith the return value of callingupdaterwith the existing value, ornotSetValueifindexwas not set. If called with a single argument,updateris called with the List itself.indexmay be a negative number, which indexes back from the end of the List.v.update(-1)updates the last item in the List.This can be very useful as a way to "chain" a normal function into a sequence of methods. RxJS calls this "let" and lodash calls it "thru".
For example, to sum a List after mapping and filtering:
Note:
update(index)can be used inwithMutations.
An iterator of this
Collection's values.Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use
valueSeqinstead, if this is what you want.Returns
IterableIterator<T>
Returns an Seq.Indexed of the values of this Collection, discarding keys.
Returns
Indexed<T>
Returns
booleanSee Also
Map#wasAltered
Note: Not all methods can be safely used on a mutable collection or within
withMutations! Check the documentation for each method to see if it allows being used inwithMutations.Parameters
mutator(mutable: this) => unknownReturns
thisSee Also
Map#withMutations
Returns a List "zipped" with the provided collection.
Like
zipWith, but using the defaultzipper: creating anArray.- zip<U, V>(
other: Collection<unknown, U>,
other2: Collection<unknown, V>,
): NutrientViewer.Immutable.List<[T, U, V]>Returns a Collection of the same type "zipped" with the provided collections.
Like
zipWith, but using the defaultzipper: creating anArray.Type Parameters
UVParameters
otherCollection<unknown, U>other2Collection<unknown, V> Returns a Collection of the same type "zipped" with the provided collections.
Like
zipWith, but using the defaultzipper: creating anArray.Parameters
...collectionsCollection<unknown, unknown>[]Returns
NutrientViewer.Immutable.List<unknown>
Returns a List "zipped" with the provided collections.
Unlike
zip,zipAllcontinues zipping until the longest collection is exhausted. Missing values from shorter collections are filled withundefined.Note: Since zipAll will return a collection as large as the largest input, some results may contain undefined values. TypeScript cannot account for these without cases (as of v2.5).
- zipAll<U, V>(
other: Collection<unknown, U>,
other2: Collection<unknown, V>,
): NutrientViewer.Immutable.List<[T, U, V]>Returns a Collection "zipped" with the provided collections.
Unlike
zip,zipAllcontinues zipping until the longest collection is exhausted. Missing values from shorter collections are filled withundefined.const a = List([ 1, 2 ]);
const b = List([ 3, 4, 5 ]);
const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]Type Parameters
UVParameters
otherCollection<unknown, U>other2Collection<unknown, V> Returns a Collection "zipped" with the provided collections.
Unlike
zip,zipAllcontinues zipping until the longest collection is exhausted. Missing values from shorter collections are filled withundefined.const a = List([ 1, 2 ]);
const b = List([ 3, 4, 5 ]);
const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]Parameters
...collectionsCollection<unknown, unknown>[]Returns
NutrientViewer.Immutable.List<unknown>
- zipWith<U, Z>(
zipper: (value: T, otherValue: U) => Z,
otherCollection: Collection<unknown, U>,
): NutrientViewer.Immutable.List<Z>Returns a List "zipped" with the provided collections by using a custom
zipperfunction. - zipWith<U, V, Z>(
zipper: (value: T, otherValue: U, thirdValue: V) => Z,
otherCollection: Collection<unknown, U>,
thirdCollection: Collection<unknown, V>,
): NutrientViewer.Immutable.List<Z>Returns a Collection of the same type "zipped" with the provided collections by using a custom
zipperfunction.Type Parameters
UVZParameters
otherCollectionCollection<unknown, U>thirdCollectionCollection<unknown, V>Returns
- zipWith<Z>(
zipper: (...values: unknown[]) => Z,
...collections: Collection<unknown, unknown>[],
): NutrientViewer.Immutable.List<Z>Returns a Collection of the same type "zipped" with the provided collections by using a custom
zipperfunction.Type Parameters
ZParameters
zipper(...values: unknown[]) => Z...collectionsCollection<unknown, unknown>[]Returns
Immutable Record API
11
Returns
IterableIterator<T>
True if this and the other Collection have value equality, as defined by
Immutable.is().Note: This is equivalent to
Immutable.is(this, other), but provided to allow for chained expressions.Parameters
otherunknownReturns
boolean
Returns the value associated with the provided index, or notSetValue if the index is beyond the bounds of the Collection.
indexmay be a negative number, which indexes back from the end of the Collection.s.get(-1)gets the last item in the Collection.Returns the value associated with the provided key, or notSetValue if the Collection does not contain this key.
Note: it is possible a key may be associated with an
undefinedvalue, so ifnotSetValueis not provided and this method returnsundefined, that does not guarantee the key was not found.Parameters
indexnumberReturns
T | undefined
Returns the value found by following a path of keys or indices through nested Collections.
Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:
Parameters
searchKeyPathIterable<unknown>notSetValueunknownOptionalReturns
unknown
True if a key exists within this
Collection, usingImmutable.isto determine equalityParameters
keynumberReturns
boolean
Computes and returns the hashed identity for this Collection.
The
hashCodeof a Collection is used to determine potential equality, and is used when adding this to aSetor as a key in aMap, enabling lookup via a different instance.If two values have the same
hashCode, they are not guaranteed to be equal. If two values have differenthashCodes, they must not be equal.Returns
number
True if the result of following a path of keys or indices through nested Collections results in a set value.
Parameters
searchKeyPathIterable<unknown>Returns
boolean
Deeply converts this Indexed collection to equivalent native JavaScript Array.
Returns
DeepCopy<T>[]
Shallowly converts this Indexed collection to equivalent native JavaScript Array.
Returns
T[]
Shallowly converts this Collection to an Object.
Converts keys to Strings.
Returns
{ [key: string]: T }
The number of items in this List.