index
Immutable.js
Immutable data encourages pure functions (data-in, data-out) and lends itself to much simpler application development and enabling techniques from functional programming such as lazy evaluation.
While designed to bring these powerful functional concepts to JavaScript, it presents an Object-Oriented API familiar to Javascript engineers and closely mirroring that of Array, Map, and Set. It is easy and efficient to convert to and from plain Javascript types.
Note: all examples are presented in ES6. To run in all browsers, they need to be translated to ES3. For example:
// ES6 foo.map(x => x * x); // ES3 foo.map(function (x) { return x * x; });
fromJS()
Deeply converts plain JS objects and arrays to Immutable Maps and Lists.
fromJS(json: any, reviver?: (k: any, v: Iterable<any, any>) => any): any
Discussion
If a reviver
is optionally provided, it will be called with every collection as a Seq (beginning with the most nested collections and proceeding to the top-level collection itself), along with the key refering to each collection and the parent JS object provided as this
. For the top level, object, the key will be ""
. This reviver
is expected to return a new Immutable Iterable, allowing for custom conversions from deep JS objects.
This example converts JSON to List and OrderedMap:
Immutable.fromJS({a: {b: [10, 20, 30]}, c: 40}, function (key, value) { var isIndexed = Immutable.Iterable.isIndexed(value); return isIndexed ? value.toList() : value.toOrderedMap(); }); // true, "b", {b: [10, 20, 30]} // false, "a", {a: {b: [10, 20, 30]}, c: 40} // false, "", {"": {a: {b: [10, 20, 30]}, c: 40}}
If reviver
is not provided, the default behavior will convert Arrays into Lists and Objects into Maps.
reviver
acts similarly to the same parameter in JSON.parse
.
Immutable.fromJS
is conservative in its conversion. It will only convert arrays which pass Array.isArray
to Lists, and only raw objects (no custom prototype) to Map.
Keep in mind, when using JS objects to construct Immutable Maps, that JavaScript Object properties are always strings, even if written in a quote-less shorthand, while Immutable Maps accept keys of any type.
var obj = { 1: "one" }; Object.keys(obj); // [ "1" ] obj["1"]; // "one" obj[1]; // "one" var map = Map(obj); map.get("1"); // "one" map.get(1); // undefined
Property access for JavaScript Objects first converts the key to a string, but since Immutable Map keys can be of any type the argument to get()
is not altered.
"Using the reviver parameter"
is()
Value equality check with semantics similar to Object.is
, but treats Immutable Iterable
s as values, equal if the second Iterable
includes equivalent values.
is(first: any, second: any): boolean
Discussion
It's used throughout Immutable when checking for equality, including Map
key equality and Set
membership.
var map1 = Immutable.Map({a:1, b:1, c:1}); var map2 = Immutable.Map({a:1, b:1, c:1}); assert(map1 !== map2); assert(Object.is(map1, map2) === false); assert(Immutable.is(map1, map2) === true);
Note: Unlike Object.is
, Immutable.is
assumes 0
and -0
are the same value, matching the behavior of ES6 Map key equality.
List
Lists are ordered indexed dense collections, much like a JavaScript Array.
class List<T> extends Collection.Indexed<T>
Discussion
Lists are immutable and fully persistent with O(log32 N) gets and sets, and O(1) push and pop.
Lists implement Deque, with efficient addition and removal from both the end (push
, pop
) and beginning (unshift
, shift
).
Unlike a JavaScript Array, there is no distinction between an "unset" index and an index set to undefined
. List#forEach
visits all indices from 0 to size, regardless of whether they were explicitly defined.
Construction
List()
Create a new immutable List containing the values of the provided iterable-like.
List<T>(): List<T> List<T>(iter: Iterable.Indexed<T>): List<T> List<T>(iter: Iterable.Set<T>): List<T> List<K, V>(iter: Iterable.Keyed<K, V>): List<any> List<T>(array: Array<T>): List<T> List<T>(iterator: Iterator<T>): List<T> List<T>(iterable: Object): List<T>
Static methods
List.isList()
True if the provided value is a List
List.isList(maybeList: any): boolean
List.of()
Creates a new List containing values
.
List.of<T>(...values: T[]): List<T>
Members
List#size
size: number
Inherited from
Collection#size
Persistent changes
List#set()
Returns a new List which includes value
at index
. If index
already exists in this List, it will be replaced.
set(index: number, value: T): List<T>
Discussion
index
may 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 index
larger than size
, the returned List's size
will be large enough to include the index
.
List#delete()
Returns a new List which excludes this index
and with a size 1 less than this List. Values at indices above index
are shifted down by 1 to fill the position.
delete(index: number): List<T>
alias
remove()
Discussion
This is synonymous with list.splice(index, 1)
.
index
may be a negative number, which indexes back from the end of the List. v.delete(-1)
deletes the last item in the List.
Note: delete
cannot be safely used in IE8
List#insert()
Returns a new List with value
at index
with a size 1 more than this List. Values at indices above index
are shifted over by 1.
insert(index: number, value: T): List<T>
Discussion
This is synonymous with `list.splice(index, 0, value)
List#clear()
Returns a new List with 0 size and no values.
clear(): List<T>
List#push()
Returns a new List with the provided values
appended, starting at this List's size
.
push(...values: T[]): List<T>
List#pop()
Returns a new List with a size ones less than this List, excluding the last index in this List.
pop(): List<T>
Discussion
Note: this differs from Array#pop
because it returns a new List rather than the removed value. Use last()
to get the last value in this List.
List#unshift()
Returns a new List with the provided values
prepended, shifting other values ahead to higher indices.
unshift(...values: T[]): List<T>
List#shift()
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.
shift(): List<T>
Discussion
Note: this differs from Array#shift
because it returns a new List rather than the removed value. Use first()
to get the first value in this List.
List#update()
Returns a new List with an updated value at index
with the return value of calling updater
with the existing value, or notSetValue
if index
was not set. If called with a single argument, updater
is called with the List itself.
update(updater: (value: List<T>) => List<T>): List<T> update(index: number, updater: (value: T) => T): List<T> update(index: number, notSetValue: T, updater: (value: T) => T): List<T>
see
Discussion
index
may be a negative number, which indexes back from the end of the List. v.update(-1)
updates the last item in the List.
List#merge()
merge(...iterables: Iterable.Indexed<T>[]): List<T> merge(...iterables: Array<T>[]): List<T>
see
List#mergeWith()
mergeWith(merger: (previous?: T, next?: T, key?: number) => T,...iterables: Iterable.Indexed<T>[]): List<T> mergeWith(merger: (previous?: T, next?: T, key?: number) => T,...iterables: Array<T>[]): List<T>
see
List#mergeDeep()
mergeDeep(...iterables: Iterable.Indexed<T>[]): List<T> mergeDeep(...iterables: Array<T>[]): List<T>
see
List#mergeDeepWith()
mergeDeepWith(merger: (previous?: T, next?: T, key?: number) => T,...iterables: Iterable.Indexed<T>[]): List<T> mergeDeepWith(merger: (previous?: T, next?: T, key?: number) => T,...iterables: Array<T>[]): List<T>
see
List#setSize()
Returns a new List with size size
. If size
is less than this List's size, the new List will exclude values at the higher indices. If size
is greater than this List's size, the new List will have undefined values for the newly available indices.
setSize(size: number): List<T>
Discussion
When building a new List and the final size is known up front, setSize
used in conjunction with withMutations
may result in the more performant construction.
Deep persistent changes
List#setIn()
Returns a new List having set value
at this keyPath
. If any keys in keyPath
do not exist, a new immutable Map will be created at that key.
setIn(keyPath: Array<any>, value: any): List<T> setIn(keyPath: Iterable<any, any>, value: any): List<T>
Discussion
Index numbers are used as keys to determine the path to follow in the List.
List#deleteIn()
Returns a new List having removed the value at this keyPath
. If any keys in keyPath
do not exist, no change will occur.
deleteIn(keyPath: Array<any>): List<T> deleteIn(keyPath: Iterable<any, any>): List<T>
alias
removeIn()
List#updateIn()
updateIn(keyPath: Array<any>, updater: (value: any) => any): List<T> updateIn(keyPath: Array<any>,notSetValue: any,updater: (value: any) => any): List<T> updateIn(keyPath: Iterable<any, any>, updater: (value: any) => any): List<T> updateIn(keyPath: Iterable<any, any>,notSetValue: any,updater: (value: any) => any): List<T>
see
List#mergeIn()
mergeIn(keyPath: Iterable<any, any>,...iterables: Iterable.Indexed<T>[]): List<T> mergeIn(keyPath: Array<any>, ...iterables: Iterable.Indexed<T>[]): List<T> mergeIn(keyPath: Array<any>, ...iterables: Array<T>[]): List<T>
see
List#mergeDeepIn()
mergeDeepIn(keyPath: Iterable<any, any>,...iterables: Iterable.Indexed<T>[]): List<T> mergeDeepIn(keyPath: Array<any>, ...iterables: Iterable.Indexed<T>[]): List<T> mergeDeepIn(keyPath: Array<any>, ...iterables: Array<T>[]): List<T>
see
Transient changes
List#withMutations()
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
, push
, pop
, shift
, unshift
and merge
may be used mutatively.
withMutations(mutator: (mutable: List<T>) => any): List<T>
see
List#asMutable()
asMutable(): List<T>
see
List#asImmutable()
asImmutable(): List<T>
see
Conversion to Seq
List#toSeq()
Returns Seq.Indexed.
toSeq(): Seq.Indexed<T>
Inherited from
Collection.Indexed#toSeq
List#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<number, T>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
List#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<T>
Inherited from
Iterable#toIndexedSeq
List#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<T>
Inherited from
Iterable#toSetSeq
List#fromEntrySeq()
If this is an iterable of [key, value] entry tuples, it will return a Seq.Keyed of those entries.
fromEntrySeq(): Seq.Keyed<any, any>
Inherited from
Iterable.Indexed#fromEntrySeq
Value equality
List#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<number, T>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
List#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
List#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: number, notSetValue?: T): T
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
List#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: number): boolean
Inherited from
Iterable#has
List#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: T): boolean
Inherited from
Iterable#includes
alias
contains()
List#first()
The first value in the Iterable.
first(): T
Inherited from
Iterable#first
List#last()
The last value in the Iterable.
last(): T
Inherited from
Iterable#last
Reading deep values
List#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
List#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
List#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
List#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<T>
Inherited from
Iterable#toArray
List#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
List#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<number, T>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
List#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<number, T>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
List#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<T>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
List#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<T>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
List#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<T>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
List#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<T>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
List#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<number>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
List#values()
An iterator of this Iterable
's values.
values(): Iterator<T>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
List#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
List#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<number>
Inherited from
Iterable#keySeq
List#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<T>
Inherited from
Iterable#valueSeq
List#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
List#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: T, key?: number, iter?: Iterable<number, T>) => M,context?: any): Iterable<number, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
List#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
List#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
List#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<number, T>
Inherited from
Iterable#reverse
List#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: T, valueB: T) => number): Iterable<number, T>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
List#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<number, T>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
List#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: T, key?: number, iter?: Iterable<number, T>) => G,context?: any): Seq.Keyed<G, Iterable<number, T>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
List#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: T, key?: number, iter?: Iterable<number, T>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
List#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<number, T>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
List#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<number, T>
Inherited from
Iterable#rest
List#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<number, T>
Inherited from
Iterable#butLast
List#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<number, T>
Inherited from
Iterable#skip
List#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<number, T>
Inherited from
Iterable#skipLast
List#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
List#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
List#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<number, T>
Inherited from
Iterable#take
List#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<number, T>
Inherited from
Iterable#takeLast
List#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
List#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
List#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<number, T>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
List#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
List#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: T,key?: number,iter?: Iterable<number, T>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: T, key?: number, iter?: Iterable<number, T>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
List#interpose()
Returns an Iterable of the same type with separator
between each item in this Iterable.
interpose(separator: T): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#interpose
List#interleave()
Returns an Iterable of the same type with the provided iterables
interleaved into this iterable.
interleave(...iterables: Array<Iterable<any, T>>): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#interleave
Discussion
The resulting Iterable includes the first item from each, then the second from each, etc.
I.Seq.of(1,2,3).interleave(I.Seq.of('A','B','C')) // Seq [ 1, 'A', 2, 'B', 3, 'C' ]
The shortest Iterable stops interleave.
I.Seq.of(1,2,3).interleave( I.Seq.of('A','B'), I.Seq.of('X','Y','Z') ) // Seq [ 1, 'A', 'X', 2, 'B', 'Y' ]
List#splice()
Splice returns a new indexed Iterable by replacing a region of this Iterable with new values. If values are not provided, it only skips the region to be removed.
splice(index: number, removeNum: number, ...values: any[]): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#splice
Discussion
index
may be a negative number, which indexes back from the end of the Iterable. s.splice(-2)
splices after the second to last item.
Seq(['a','b','c','d']).splice(1, 2, 'q', 'r', 's') // Seq ['a', 'q', 'r', 's', 'd']
List#zip()
Returns an Iterable of the same type "zipped" with the provided iterables.
zip(...iterables: Array<Iterable<any, any>>): Iterable.Indexed<any>
Inherited from
Iterable.Indexed#zip
Discussion
Like zipWith
, but using the default zipper
: creating an Array
.
var a = Seq.of(1, 2, 3); var b = Seq.of(4, 5, 6); var c = a.zip(b); // Seq [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
List#zipWith()
Returns an Iterable of the same type "zipped" with the provided iterables by using a custom zipper
function.
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherIterable: Iterable<any, U>): Iterable.Indexed<Z> zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherIterable: Iterable<any, U>,thirdIterable: Iterable<any, V>): Iterable.Indexed<Z> zipWith<Z>(zipper: (...any: Array<any>) => Z,...iterables: Array<Iterable<any, any>>): Iterable.Indexed<Z>
Inherited from
Iterable.Indexed#zipWith
Example
var a = Seq.of(1, 2, 3); var b = Seq.of(4, 5, 6); var c = a.zipWith((a, b) => a + b, b); // Seq [ 5, 7, 9 ]
Reducing a value
List#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R,value?: T,key?: number,iter?: Iterable<number, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
List#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R,value?: T,key?: number,iter?: Iterable<number, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
List#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): boolean
Inherited from
Iterable#every
List#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): boolean
Inherited from
Iterable#some
List#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
List#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
List#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
List#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: T, key?: number, iter?: Iterable<number, T>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
List#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#find
List#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
List#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findEntry
List#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
List#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: T,key?: number,iter?: Iterable.Keyed<number, T>) => boolean,context?: any): number
Inherited from
Iterable#findKey
List#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: T,key?: number,iter?: Iterable.Keyed<number, T>) => boolean,context?: any): number
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
List#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: T): number
Inherited from
Iterable#keyOf
List#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: T): number
Inherited from
Iterable#lastKeyOf
List#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
List#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
List#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
List#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
List#indexOf()
Returns the first index at which a given value can be found in the Iterable, or -1 if it is not present.
indexOf(searchValue: T): number
Inherited from
Iterable.Indexed#indexOf
List#lastIndexOf()
Returns the last index at which a given value can be found in the Iterable, or -1 if it is not present.
lastIndexOf(searchValue: T): number
Inherited from
Iterable.Indexed#lastIndexOf
List#findIndex()
Returns the first index in the Iterable where a value satisfies the provided predicate function. Otherwise -1 is returned.
findIndex(predicate: (value?: T, index?: number, iter?: Iterable.Indexed<T>) => boolean,context?: any): number
Inherited from
Iterable.Indexed#findIndex
List#findLastIndex()
Returns the last index in the Iterable where a value satisfies the provided predicate function. Otherwise -1 is returned.
findLastIndex(predicate: (value?: T, index?: number, iter?: Iterable.Indexed<T>) => boolean,context?: any): number
Inherited from
Iterable.Indexed#findLastIndex
Comparison
List#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, T>): boolean isSubset(iter: Array<T>): boolean
Inherited from
Iterable#isSubset
List#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, T>): boolean isSuperset(iter: Array<T>): boolean
Inherited from
Iterable#isSuperset
Map
Immutable Map is an unordered Iterable.Keyed of (key, value) pairs with O(log32 N)
gets and O(log32 N)
persistent sets.
class Map<K, V> extends Collection.Keyed<K, V>
Discussion
Iteration order of a Map is undefined, however is stable. Multiple iterations of the same Map will iterate in the same order.
Map's keys can be of any type, and use Immutable.is
to determine key equality. This allows the use of any value (including NaN) as a key.
Because Immutable.is
returns equality based on value semantics, and Immutable collections are treated as values, any Immutable collection may be used as a key.
Map().set(List.of(1), 'listofone').get(List.of(1)); // 'listofone'
Any JavaScript object may be used as a key, however strict identity is used to evaluate key equality. Two similar looking objects will represent two different keys.
Implemented by a hash-array mapped trie.
Construction
Map()
Creates a new Immutable Map.
Map<K, V>(): Map<K, V> Map<K, V>(iter: Iterable.Keyed<K, V>): Map<K, V> Map<K, V>(iter: Iterable<any, Array<any>>): Map<K, V> Map<K, V>(array: Array<Array<any>>): Map<K, V> Map<V>(obj: {[key: string]: V}): Map<string, V> Map<K, V>(iterator: Iterator<Array<any>>): Map<K, V> Map<K, V>(iterable: Object): Map<K, V>
Discussion
Created with the same key value pairs as the provided Iterable.Keyed or JavaScript Object or expects an Iterable of [K, V] tuple entries.
var newMap = Map({key: "value"}); var newMap = Map([["key", "value"]]);
Keep in mind, when using JS objects to construct Immutable Maps, that JavaScript Object properties are always strings, even if written in a quote-less shorthand, while Immutable Maps accept keys of any type.
var obj = { 1: "one" }; Object.keys(obj); // [ "1" ] obj["1"]; // "one" obj[1]; // "one" var map = Map(obj); map.get("1"); // "one" map.get(1); // undefined
Property access for JavaScript Objects first converts the key to a string, but since Immutable Map keys can be of any type the argument to get()
is not altered.
Static methods
Map.isMap()
True if the provided value is a Map
Map.isMap(maybeMap: any): boolean
Map.of()
Creates a new Map from alternating keys and values
Map.of(...keyValues: any[]): Map<any, any>
Members
Map#size
size: number
Inherited from
Collection#size
Persistent changes
Map#set()
Returns a new Map also containing the new key, value pair. If an equivalent key already exists in this Map, it will be replaced.
set(key: K, value: V): Map<K, V>
Map#delete()
Returns a new Map which excludes this key
.
delete(key: K): Map<K, V>
alias
remove()
Discussion
Note: delete
cannot be safely used in IE8, but is provided to mirror the ES6 collection API.
Map#clear()
Returns a new Map containing no keys or values.
clear(): Map<K, V>
Map#update()
Returns a new Map having updated the value at this key
with the return value of calling updater
with the existing value, or notSetValue
if the key was not set. If called with only a single argument, updater
is called with the Map itself.
update(updater: (value: Map<K, V>) => Map<K, V>): Map<K, V> update(key: K, updater: (value: V) => V): Map<K, V> update(key: K, notSetValue: V, updater: (value: V) => V): Map<K, V>
Discussion
Equivalent to: map.set(key, updater(map.get(key, notSetValue)))
.
Map#merge()
Returns a new Map resulting from merging the provided Iterables (or JS objects) into this Map. In other words, this takes each entry of each iterable and sets it on this Map.
merge(...iterables: Iterable<K, V>[]): Map<K, V> merge(...iterables: {[key: string]: V}[]): Map<string, V>
Discussion
If any of the values provided to merge
are not Iterable (would return false for Immutable.Iterable.isIterable
) then they are deeply converted via Immutable.fromJS
before being merged. However, if the value is an Iterable but includes non-iterable JS objects or arrays, those nested values will be preserved.
var x = Immutable.Map({a: 10, b: 20, c: 30}); var y = Immutable.Map({b: 40, a: 50, d: 60}); x.merge(y) // { a: 50, b: 40, c: 30, d: 60 } y.merge(x) // { b: 20, a: 10, d: 60, c: 30 }
Map#mergeWith()
Like merge()
, mergeWith()
returns a new Map resulting from merging the provided Iterables (or JS objects) into this Map, but uses the merger
function for dealing with conflicts.
mergeWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: Iterable<K, V>[]): Map<K, V> mergeWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: {[key: string]: V}[]): Map<string, V>
Example
var x = Immutable.Map({a: 10, b: 20, c: 30}); var y = Immutable.Map({b: 40, a: 50, d: 60}); x.mergeWith((prev, next) => prev / next, y) // { a: 0.2, b: 0.5, c: 30, d: 60 } y.mergeWith((prev, next) => prev / next, x) // { b: 2, a: 5, d: 60, c: 30 }
Map#mergeDeep()
Like merge()
, but when two Iterables conflict, it merges them as well, recursing deeply through the nested data.
mergeDeep(...iterables: Iterable<K, V>[]): Map<K, V> mergeDeep(...iterables: {[key: string]: V}[]): Map<string, V>
Example
var x = Immutable.fromJS({a: { x: 10, y: 10 }, b: { x: 20, y: 50 } }); var y = Immutable.fromJS({a: { x: 2 }, b: { y: 5 }, c: { z: 3 } }); x.mergeDeep(y) // {a: { x: 2, y: 10 }, b: { x: 20, y: 5 }, c: { z: 3 } }
Map#mergeDeepWith()
Like mergeDeep()
, but when two non-Iterables conflict, it uses the merger
function to determine the resulting value.
mergeDeepWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: {[key: string]: V}[]): Map<string, V>
Example
var x = Immutable.fromJS({a: { x: 10, y: 10 }, b: { x: 20, y: 50 } }); var y = Immutable.fromJS({a: { x: 2 }, b: { y: 5 }, c: { z: 3 } }); x.mergeDeepWith((prev, next) => prev / next, y) // {a: { x: 5, y: 10 }, b: { x: 20, y: 10 }, c: { z: 3 } }
Deep persistent changes
Map#setIn()
Returns a new Map having set value
at this keyPath
. If any keys in keyPath
do not exist, a new immutable Map will be created at that key.
setIn(keyPath: Array<any>, value: any): Map<K, V> setIn(KeyPath: Iterable<any, any>, value: any): Map<K, V>
Map#deleteIn()
Returns a new Map having removed the value at this keyPath
. If any keys in keyPath
do not exist, no change will occur.
deleteIn(keyPath: Array<any>): Map<K, V> deleteIn(keyPath: Iterable<any, any>): Map<K, V>
alias
removeIn()
Map#updateIn()
Returns a new Map having applied the updater
to the entry found at the keyPath.
updateIn(keyPath: Array<any>, updater: (value: any) => any): Map<K, V> updateIn(keyPath: Array<any>,notSetValue: any,updater: (value: any) => any): Map<K, V> updateIn(keyPath: Iterable<any, any>, updater: (value: any) => any): Map<K, V> updateIn(keyPath: Iterable<any, any>,notSetValue: any,updater: (value: any) => any): Map<K, V>
Discussion
If any keys in keyPath
do not exist, new Immutable Map
s will be created at those keys. If the keyPath
does not already contain a value, the updater
function will be called with notSetValue
, if provided, otherwise undefined
.
var data = Immutable.fromJS({ a: { b: { c: 10 } } }); data = data.updateIn(['a', 'b', 'c'], val => val * 2); // { a: { b: { c: 20 } } }
If the updater
function returns the same value it was called with, then no change will occur. This is still true if notSetValue
is provided.
var data1 = Immutable.fromJS({ a: { b: { c: 10 } } }); data2 = data1.updateIn(['x', 'y', 'z'], 100, val => val); assert(data2 === data1);
Map#mergeIn()
A combination of updateIn
and merge
, returning a new Map, but performing the merge at a point arrived at by following the keyPath. In other words, these two lines are equivalent:
mergeIn(keyPath: Iterable<any, any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeIn(keyPath: Array<any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeIn(keyPath: Array<any>, ...iterables: {[key: string]: V}[]): Map<string, V>
Example
x.updateIn(['a', 'b', 'c'], abc => abc.merge(y)); x.mergeIn(['a', 'b', 'c'], y);
Map#mergeDeepIn()
A combination of updateIn
and mergeDeep
, returning a new Map, but performing the deep merge at a point arrived at by following the keyPath. In other words, these two lines are equivalent:
mergeDeepIn(keyPath: Iterable<any, any>,...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepIn(keyPath: Array<any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepIn(keyPath: Array<any>,...iterables: {[key: string]: V}[]): Map<string, V>
Example
x.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y)); x.mergeDeepIn(['a', 'b', 'c'], y);
Transient changes
Map#withMutations()
Every time you call one of the above functions, a new immutable Map is created. If a pure function calls a number of these to produce a final return value, then a penalty on performance and memory has been paid by creating all of the intermediate immutable Maps.
withMutations(mutator: (mutable: Map<K, V>) => any): Map<K, V>
Discussion
If you need to apply a series of mutations to produce a new immutable Map, withMutations()
creates a temporary mutable copy of the Map which can apply mutations in a highly performant manner. In fact, this is exactly how complex mutations like merge
are done.
As an example, this results in the creation of 2, not 4, new Maps:
var map1 = Immutable.Map(); var map2 = map1.withMutations(map => { map.set('a', 1).set('b', 2).set('c', 3); }); assert(map1.size === 0); assert(map2.size === 3);
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
and merge
may be used mutatively.
Map#asMutable()
Another way to avoid creation of intermediate Immutable maps is to create a mutable copy of this collection. Mutable copies always return this
, and thus shouldn't be used for equality. Your function should never return a mutable copy of a collection, only use it internally to create a new collection. If possible, use withMutations
as it provides an easier to use API.
asMutable(): Map<K, V>
Discussion
Note: if the collection is already mutable, asMutable
returns itself.
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
and merge
may be used mutatively.
Map#asImmutable()
The yin to asMutable
's yang. Because it applies to mutable collections, this operation is mutable and returns itself. Once performed, the mutable copy has become immutable and can be safely returned from a function.
asImmutable(): Map<K, V>
Conversion to Seq
Map#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Inherited from
Collection.Keyed#toSeq
Map#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Map#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Map#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Value equality
Map#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Map#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Map#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Map#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Map#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Map#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Map#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Map#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Map#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Map#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Map#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Map#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Map#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Map#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Map#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Map#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Map#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Map#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Map#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Map#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Map#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Map#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Map#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Map#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Map#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Map#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Map#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Map#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Map#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Map#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Map#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Map#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Map#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Map#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Map#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Map#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Map#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Map#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Map#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Map#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Map#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Map#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Map#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Map#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Map#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Map#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Map#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Map#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Map#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Map#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Map#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Map#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Map#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Map#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Map#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Map#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Map#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Map#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Map#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Map#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Map#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Map#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Map#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Map#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Map#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Map#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Map#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Map#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
OrderedMap
A type of Map that has the additional guarantee that the iteration order of entries will be the order in which they were set().
class OrderedMap<K, V> extends Map<K, V>
Discussion
The iteration behavior of OrderedMap is the same as native ES6 Map and JavaScript Object.
Note that OrderedMap
are more expensive than non-ordered Map
and may consume more memory. OrderedMap#set
is amortized O(log32 N), but not stable.
Construction
OrderedMap()
Creates a new Immutable OrderedMap.
OrderedMap<K, V>(): OrderedMap<K, V> OrderedMap<K, V>(iter: Iterable.Keyed<K, V>): OrderedMap<K, V> OrderedMap<K, V>(iter: Iterable<any, Array<any>>): OrderedMap<K, V> OrderedMap<K, V>(array: Array<Array<any>>): OrderedMap<K, V> OrderedMap<V>(obj: {[key: string]: V}): OrderedMap<string, V> OrderedMap<K, V>(iterator: Iterator<Array<any>>): OrderedMap<K, V> OrderedMap<K, V>(iterable: Object): OrderedMap<K, V>
Discussion
Created with the same key value pairs as the provided Iterable.Keyed or JavaScript Object or expects an Iterable of [K, V] tuple entries.
The iteration order of key-value pairs provided to this constructor will be preserved in the OrderedMap.
var newOrderedMap = OrderedMap({key: "value"}); var newOrderedMap = OrderedMap([["key", "value"]]);
Static methods
OrderedMap.isOrderedMap()
True if the provided value is an OrderedMap.
OrderedMap.isOrderedMap(maybeOrderedMap: any): boolean
Members
OrderedMap#size
size: number
Inherited from
Collection#size
Persistent changes
OrderedMap#set()
Returns a new Map also containing the new key, value pair. If an equivalent key already exists in this Map, it will be replaced.
set(key: K, value: V): Map<K, V>
Inherited from
Map#set
OrderedMap#delete()
Returns a new Map which excludes this key
.
delete(key: K): Map<K, V>
Inherited from
Map#delete
alias
remove()
Discussion
Note: delete
cannot be safely used in IE8, but is provided to mirror the ES6 collection API.
OrderedMap#clear()
Returns a new Map containing no keys or values.
clear(): Map<K, V>
Inherited from
Map#clear
OrderedMap#update()
Returns a new Map having updated the value at this key
with the return value of calling updater
with the existing value, or notSetValue
if the key was not set. If called with only a single argument, updater
is called with the Map itself.
update(updater: (value: Map<K, V>) => Map<K, V>): Map<K, V> update(key: K, updater: (value: V) => V): Map<K, V> update(key: K, notSetValue: V, updater: (value: V) => V): Map<K, V>
Inherited from
Map#update
Discussion
Equivalent to: map.set(key, updater(map.get(key, notSetValue)))
.
OrderedMap#merge()
Returns a new Map resulting from merging the provided Iterables (or JS objects) into this Map. In other words, this takes each entry of each iterable and sets it on this Map.
merge(...iterables: Iterable<K, V>[]): Map<K, V> merge(...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#merge
Discussion
If any of the values provided to merge
are not Iterable (would return false for Immutable.Iterable.isIterable
) then they are deeply converted via Immutable.fromJS
before being merged. However, if the value is an Iterable but includes non-iterable JS objects or arrays, those nested values will be preserved.
var x = Immutable.Map({a: 10, b: 20, c: 30}); var y = Immutable.Map({b: 40, a: 50, d: 60}); x.merge(y) // { a: 50, b: 40, c: 30, d: 60 } y.merge(x) // { b: 20, a: 10, d: 60, c: 30 }
OrderedMap#mergeWith()
Like merge()
, mergeWith()
returns a new Map resulting from merging the provided Iterables (or JS objects) into this Map, but uses the merger
function for dealing with conflicts.
mergeWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: Iterable<K, V>[]): Map<K, V> mergeWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#mergeWith
Example
var x = Immutable.Map({a: 10, b: 20, c: 30}); var y = Immutable.Map({b: 40, a: 50, d: 60}); x.mergeWith((prev, next) => prev / next, y) // { a: 0.2, b: 0.5, c: 30, d: 60 } y.mergeWith((prev, next) => prev / next, x) // { b: 2, a: 5, d: 60, c: 30 }
OrderedMap#mergeDeep()
Like merge()
, but when two Iterables conflict, it merges them as well, recursing deeply through the nested data.
mergeDeep(...iterables: Iterable<K, V>[]): Map<K, V> mergeDeep(...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#mergeDeep
Example
var x = Immutable.fromJS({a: { x: 10, y: 10 }, b: { x: 20, y: 50 } }); var y = Immutable.fromJS({a: { x: 2 }, b: { y: 5 }, c: { z: 3 } }); x.mergeDeep(y) // {a: { x: 2, y: 10 }, b: { x: 20, y: 5 }, c: { z: 3 } }
OrderedMap#mergeDeepWith()
Like mergeDeep()
, but when two non-Iterables conflict, it uses the merger
function to determine the resulting value.
mergeDeepWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepWith(merger: (previous?: V, next?: V, key?: K) => V,...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#mergeDeepWith
Example
var x = Immutable.fromJS({a: { x: 10, y: 10 }, b: { x: 20, y: 50 } }); var y = Immutable.fromJS({a: { x: 2 }, b: { y: 5 }, c: { z: 3 } }); x.mergeDeepWith((prev, next) => prev / next, y) // {a: { x: 5, y: 10 }, b: { x: 20, y: 10 }, c: { z: 3 } }
Deep persistent changes
OrderedMap#setIn()
Returns a new Map having set value
at this keyPath
. If any keys in keyPath
do not exist, a new immutable Map will be created at that key.
setIn(keyPath: Array<any>, value: any): Map<K, V> setIn(KeyPath: Iterable<any, any>, value: any): Map<K, V>
Inherited from
Map#setIn
OrderedMap#deleteIn()
Returns a new Map having removed the value at this keyPath
. If any keys in keyPath
do not exist, no change will occur.
deleteIn(keyPath: Array<any>): Map<K, V> deleteIn(keyPath: Iterable<any, any>): Map<K, V>
Inherited from
Map#deleteIn
alias
removeIn()
OrderedMap#updateIn()
Returns a new Map having applied the updater
to the entry found at the keyPath.
updateIn(keyPath: Array<any>, updater: (value: any) => any): Map<K, V> updateIn(keyPath: Array<any>,notSetValue: any,updater: (value: any) => any): Map<K, V> updateIn(keyPath: Iterable<any, any>, updater: (value: any) => any): Map<K, V> updateIn(keyPath: Iterable<any, any>,notSetValue: any,updater: (value: any) => any): Map<K, V>
Inherited from
Map#updateIn
Discussion
If any keys in keyPath
do not exist, new Immutable Map
s will be created at those keys. If the keyPath
does not already contain a value, the updater
function will be called with notSetValue
, if provided, otherwise undefined
.
var data = Immutable.fromJS({ a: { b: { c: 10 } } }); data = data.updateIn(['a', 'b', 'c'], val => val * 2); // { a: { b: { c: 20 } } }
If the updater
function returns the same value it was called with, then no change will occur. This is still true if notSetValue
is provided.
var data1 = Immutable.fromJS({ a: { b: { c: 10 } } }); data2 = data1.updateIn(['x', 'y', 'z'], 100, val => val); assert(data2 === data1);
OrderedMap#mergeIn()
A combination of updateIn
and merge
, returning a new Map, but performing the merge at a point arrived at by following the keyPath. In other words, these two lines are equivalent:
mergeIn(keyPath: Iterable<any, any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeIn(keyPath: Array<any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeIn(keyPath: Array<any>, ...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#mergeIn
Example
x.updateIn(['a', 'b', 'c'], abc => abc.merge(y)); x.mergeIn(['a', 'b', 'c'], y);
OrderedMap#mergeDeepIn()
A combination of updateIn
and mergeDeep
, returning a new Map, but performing the deep merge at a point arrived at by following the keyPath. In other words, these two lines are equivalent:
mergeDeepIn(keyPath: Iterable<any, any>,...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepIn(keyPath: Array<any>, ...iterables: Iterable<K, V>[]): Map<K, V> mergeDeepIn(keyPath: Array<any>,...iterables: {[key: string]: V}[]): Map<string, V>
Inherited from
Map#mergeDeepIn
Example
x.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y)); x.mergeDeepIn(['a', 'b', 'c'], y);
Transient changes
OrderedMap#withMutations()
Every time you call one of the above functions, a new immutable Map is created. If a pure function calls a number of these to produce a final return value, then a penalty on performance and memory has been paid by creating all of the intermediate immutable Maps.
withMutations(mutator: (mutable: Map<K, V>) => any): Map<K, V>
Inherited from
Map#withMutations
Discussion
If you need to apply a series of mutations to produce a new immutable Map, withMutations()
creates a temporary mutable copy of the Map which can apply mutations in a highly performant manner. In fact, this is exactly how complex mutations like merge
are done.
As an example, this results in the creation of 2, not 4, new Maps:
var map1 = Immutable.Map(); var map2 = map1.withMutations(map => { map.set('a', 1).set('b', 2).set('c', 3); }); assert(map1.size === 0); assert(map2.size === 3);
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
and merge
may be used mutatively.
OrderedMap#asMutable()
Another way to avoid creation of intermediate Immutable maps is to create a mutable copy of this collection. Mutable copies always return this
, and thus shouldn't be used for equality. Your function should never return a mutable copy of a collection, only use it internally to create a new collection. If possible, use withMutations
as it provides an easier to use API.
asMutable(): Map<K, V>
Inherited from
Map#asMutable
Discussion
Note: if the collection is already mutable, asMutable
returns itself.
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
and merge
may be used mutatively.
OrderedMap#asImmutable()
The yin to asMutable
's yang. Because it applies to mutable collections, this operation is mutable and returns itself. Once performed, the mutable copy has become immutable and can be safely returned from a function.
asImmutable(): Map<K, V>
Inherited from
Map#asImmutable
Conversion to Seq
OrderedMap#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Inherited from
Collection.Keyed#toSeq
OrderedMap#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
OrderedMap#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
OrderedMap#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Value equality
OrderedMap#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
OrderedMap#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
OrderedMap#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
OrderedMap#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
OrderedMap#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
OrderedMap#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
OrderedMap#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
OrderedMap#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
OrderedMap#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
OrderedMap#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
OrderedMap#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
OrderedMap#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
OrderedMap#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
OrderedMap#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
OrderedMap#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
OrderedMap#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
OrderedMap#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
OrderedMap#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
OrderedMap#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
OrderedMap#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
OrderedMap#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
OrderedMap#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
OrderedMap#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
OrderedMap#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
OrderedMap#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
OrderedMap#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
OrderedMap#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
OrderedMap#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
OrderedMap#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
OrderedMap#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
OrderedMap#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
OrderedMap#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
OrderedMap#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
OrderedMap#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
OrderedMap#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
OrderedMap#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
OrderedMap#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
OrderedMap#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
OrderedMap#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
OrderedMap#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
OrderedMap#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
OrderedMap#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
OrderedMap#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
OrderedMap#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
OrderedMap#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
OrderedMap#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
OrderedMap#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
OrderedMap#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
OrderedMap#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
OrderedMap#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
OrderedMap#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
OrderedMap#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
OrderedMap#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
OrderedMap#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
OrderedMap#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
OrderedMap#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedMap#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
OrderedMap#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedMap#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
OrderedMap#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedMap#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
OrderedMap#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
OrderedMap#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
OrderedMap#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
OrderedMap#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
OrderedMap#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
OrderedMap#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
OrderedMap#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
OrderedMap#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
OrderedMap#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
OrderedMap#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Set
A Collection of unique values with O(log32 N)
adds and has.
class Set<T> extends Collection.Set<T>
Discussion
When iterating a Set, the entries will be (value, value) pairs. Iteration order of a Set is undefined, however is stable. Multiple iterations of the same Set will iterate in the same order.
Set values, like Map keys, may be of any type. Equality is determined using Immutable.is
, enabling Sets to uniquely include other Immutable collections, custom value types, and NaN.
Construction
Set()
Create a new immutable Set containing the values of the provided iterable-like.
Set<T>(): Set<T> Set<T>(iter: Iterable.Set<T>): Set<T> Set<T>(iter: Iterable.Indexed<T>): Set<T> Set<K, V>(iter: Iterable.Keyed<K, V>): Set<any> Set<T>(array: Array<T>): Set<T> Set<T>(iterator: Iterator<T>): Set<T> Set<T>(iterable: Object): Set<T>
Static methods
Set.isSet()
True if the provided value is a Set
Set.isSet(maybeSet: any): boolean
Set.of()
Creates a new Set containing values
.
Set.of<T>(...values: T[]): Set<T>
Set.fromKeys()
Set.fromKeys()
creates a new immutable Set containing the keys from this Iterable or JavaScript Object.
Set.fromKeys<T>(iter: Iterable<T, any>): Set<T> Set.fromKeys(obj: {[key: string]: any}): Set<string>
Members
Set#size
size: number
Inherited from
Collection#size
Persistent changes
Set#add()
Returns a new Set which also includes this value.
add(value: T): Set<T>
Set#delete()
Returns a new Set which excludes this value.
delete(value: T): Set<T>
alias
remove()
Discussion
Note: delete
cannot be safely used in IE8
Set#clear()
Returns a new Set containing no values.
clear(): Set<T>
Set#union()
Returns a Set including any value from iterables
that does not already exist in this Set.
union(...iterables: Iterable<any, T>[]): Set<T> union(...iterables: Array<T>[]): Set<T>
alias
merge()
Set#intersect()
Returns a Set which has removed any values not also contained within iterables
.
intersect(...iterables: Iterable<any, T>[]): Set<T> intersect(...iterables: Array<T>[]): Set<T>
Set#subtract()
Returns a Set excluding any values contained within iterables
.
subtract(...iterables: Iterable<any, T>[]): Set<T> subtract(...iterables: Array<T>[]): Set<T>
Transient changes
Set#withMutations()
Note: Not all methods can be used on a mutable collection or within withMutations
! Only add
may be used mutatively.
withMutations(mutator: (mutable: Set<T>) => any): Set<T>
see
Set#asMutable()
asMutable(): Set<T>
see
Set#asImmutable()
asImmutable(): Set<T>
see
Conversion to Seq
Set#toSeq()
Returns Seq.Set.
toSeq(): Seq.Set<T>
Inherited from
Collection.Set#toSeq
Set#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<T, T>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Set#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<T>
Inherited from
Iterable#toIndexedSeq
Set#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<T>
Inherited from
Iterable#toSetSeq
Value equality
Set#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<T, T>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Set#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Set#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: T, notSetValue?: T): T
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Set#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: T): boolean
Inherited from
Iterable#has
Set#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: T): boolean
Inherited from
Iterable#includes
alias
contains()
Set#first()
The first value in the Iterable.
first(): T
Inherited from
Iterable#first
Set#last()
The last value in the Iterable.
last(): T
Inherited from
Iterable#last
Reading deep values
Set#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Set#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Set#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Set#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<T>
Inherited from
Iterable#toArray
Set#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Set#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<T, T>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Set#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<T, T>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Set#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<T>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Set#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<T>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Set#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<T>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Set#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<T>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Set#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<T>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Set#values()
An iterator of this Iterable
's values.
values(): Iterator<T>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Set#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Set#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<T>
Inherited from
Iterable#keySeq
Set#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<T>
Inherited from
Iterable#valueSeq
Set#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Set#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => M,context?: any): Iterable<T, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Set#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Set#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Set#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<T, T>
Inherited from
Iterable#reverse
Set#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: T, valueB: T) => number): Iterable<T, T>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Set#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<T, T>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Set#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: T, key?: T, iter?: Iterable<T, T>) => G,context?: any): Seq.Keyed<G, Iterable<T, T>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Set#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: T, key?: T, iter?: Iterable<T, T>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Set#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<T, T>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Set#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<T, T>
Inherited from
Iterable#rest
Set#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<T, T>
Inherited from
Iterable#butLast
Set#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<T, T>
Inherited from
Iterable#skip
Set#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<T, T>
Inherited from
Iterable#skipLast
Set#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Set#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Set#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<T, T>
Inherited from
Iterable#take
Set#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<T, T>
Inherited from
Iterable#takeLast
Set#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Set#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Set#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<T, T>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Set#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Set#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Set#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: T, key?: T, iter?: Iterable<T, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Set#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: T, key?: T, iter?: Iterable<T, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Set#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Set#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Set#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Set#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Set#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Set#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: T, key?: T, iter?: Iterable<T, T>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Set#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#find
Set#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Set#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findEntry
Set#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Set#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: T, key?: T, iter?: Iterable.Keyed<T, T>) => boolean,context?: any): T
Inherited from
Iterable#findKey
Set#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: T, key?: T, iter?: Iterable.Keyed<T, T>) => boolean,context?: any): T
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Set#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: T): T
Inherited from
Iterable#keyOf
Set#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: T): T
Inherited from
Iterable#lastKeyOf
Set#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Set#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Set#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Set#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Set#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, T>): boolean isSubset(iter: Array<T>): boolean
Inherited from
Iterable#isSubset
Set#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, T>): boolean isSuperset(iter: Array<T>): boolean
Inherited from
Iterable#isSuperset
OrderedSet
A type of Set that has the additional guarantee that the iteration order of values will be the order in which they were add
ed.
class OrderedSet<T> extends Set<T>
Discussion
The iteration behavior of OrderedSet is the same as native ES6 Set.
Note that OrderedSet
are more expensive than non-ordered Set
and may consume more memory. OrderedSet#add
is amortized O(log32 N), but not stable.
Construction
OrderedSet()
Create a new immutable OrderedSet containing the values of the provided iterable-like.
OrderedSet<T>(): OrderedSet<T> OrderedSet<T>(iter: Iterable.Set<T>): OrderedSet<T> OrderedSet<T>(iter: Iterable.Indexed<T>): OrderedSet<T> OrderedSet<K, V>(iter: Iterable.Keyed<K, V>): OrderedSet<any> OrderedSet<T>(array: Array<T>): OrderedSet<T> OrderedSet<T>(iterator: Iterator<T>): OrderedSet<T> OrderedSet<T>(iterable: Object): OrderedSet<T>
Static methods
OrderedSet.isOrderedSet()
True if the provided value is an OrderedSet.
OrderedSet.isOrderedSet(maybeOrderedSet: any): boolean
OrderedSet.of()
Creates a new OrderedSet containing values
.
OrderedSet.of<T>(...values: T[]): OrderedSet<T>
OrderedSet.fromKeys()
OrderedSet.fromKeys()
creates a new immutable OrderedSet containing the keys from this Iterable or JavaScript Object.
OrderedSet.fromKeys<T>(iter: Iterable<T, any>): OrderedSet<T> OrderedSet.fromKeys(obj: {[key: string]: any}): OrderedSet<string>
Members
OrderedSet#size
size: number
Inherited from
Collection#size
Persistent changes
OrderedSet#add()
Returns a new Set which also includes this value.
add(value: T): Set<T>
Inherited from
Set#add
OrderedSet#delete()
Returns a new Set which excludes this value.
delete(value: T): Set<T>
Inherited from
Set#delete
alias
remove()
Discussion
Note: delete
cannot be safely used in IE8
OrderedSet#clear()
Returns a new Set containing no values.
clear(): Set<T>
Inherited from
Set#clear
OrderedSet#union()
Returns a Set including any value from iterables
that does not already exist in this Set.
union(...iterables: Iterable<any, T>[]): Set<T> union(...iterables: Array<T>[]): Set<T>
Inherited from
Set#union
alias
merge()
OrderedSet#intersect()
Returns a Set which has removed any values not also contained within iterables
.
intersect(...iterables: Iterable<any, T>[]): Set<T> intersect(...iterables: Array<T>[]): Set<T>
Inherited from
Set#intersect
OrderedSet#subtract()
Returns a Set excluding any values contained within iterables
.
subtract(...iterables: Iterable<any, T>[]): Set<T> subtract(...iterables: Array<T>[]): Set<T>
Inherited from
Set#subtract
Transient changes
OrderedSet#withMutations()
Note: Not all methods can be used on a mutable collection or within withMutations
! Only add
may be used mutatively.
withMutations(mutator: (mutable: Set<T>) => any): Set<T>
Inherited from
Set#withMutations
see
OrderedSet#asMutable()
asMutable(): Set<T>
Inherited from
Set#asMutable
see
OrderedSet#asImmutable()
asImmutable(): Set<T>
Inherited from
Set#asImmutable
see
Conversion to Seq
OrderedSet#toSeq()
Returns Seq.Set.
toSeq(): Seq.Set<T>
Inherited from
Collection.Set#toSeq
OrderedSet#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<T, T>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
OrderedSet#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<T>
Inherited from
Iterable#toIndexedSeq
OrderedSet#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<T>
Inherited from
Iterable#toSetSeq
Value equality
OrderedSet#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<T, T>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
OrderedSet#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
OrderedSet#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: T, notSetValue?: T): T
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
OrderedSet#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: T): boolean
Inherited from
Iterable#has
OrderedSet#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: T): boolean
Inherited from
Iterable#includes
alias
contains()
OrderedSet#first()
The first value in the Iterable.
first(): T
Inherited from
Iterable#first
OrderedSet#last()
The last value in the Iterable.
last(): T
Inherited from
Iterable#last
Reading deep values
OrderedSet#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
OrderedSet#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
OrderedSet#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
OrderedSet#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<T>
Inherited from
Iterable#toArray
OrderedSet#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
OrderedSet#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<T, T>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
OrderedSet#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<T, T>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
OrderedSet#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<T>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
OrderedSet#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<T>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
OrderedSet#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<T>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
OrderedSet#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<T>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
OrderedSet#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<T>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
OrderedSet#values()
An iterator of this Iterable
's values.
values(): Iterator<T>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
OrderedSet#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
OrderedSet#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<T>
Inherited from
Iterable#keySeq
OrderedSet#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<T>
Inherited from
Iterable#valueSeq
OrderedSet#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
OrderedSet#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => M,context?: any): Iterable<T, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
OrderedSet#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
OrderedSet#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
OrderedSet#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<T, T>
Inherited from
Iterable#reverse
OrderedSet#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: T, valueB: T) => number): Iterable<T, T>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
OrderedSet#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<T, T>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
OrderedSet#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: T, key?: T, iter?: Iterable<T, T>) => G,context?: any): Seq.Keyed<G, Iterable<T, T>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
OrderedSet#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: T, key?: T, iter?: Iterable<T, T>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
OrderedSet#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<T, T>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
OrderedSet#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<T, T>
Inherited from
Iterable#rest
OrderedSet#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<T, T>
Inherited from
Iterable#butLast
OrderedSet#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<T, T>
Inherited from
Iterable#skip
OrderedSet#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<T, T>
Inherited from
Iterable#skipLast
OrderedSet#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
OrderedSet#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
OrderedSet#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<T, T>
Inherited from
Iterable#take
OrderedSet#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<T, T>
Inherited from
Iterable#takeLast
OrderedSet#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
OrderedSet#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): Iterable<T, T>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
OrderedSet#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<T, T>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
OrderedSet#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
OrderedSet#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: T, key?: T, iter?: Iterable<T, T>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
OrderedSet#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: T, key?: T, iter?: Iterable<T, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
OrderedSet#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: T, key?: T, iter?: Iterable<T, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
OrderedSet#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): boolean
Inherited from
Iterable#every
OrderedSet#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): boolean
Inherited from
Iterable#some
OrderedSet#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
OrderedSet#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
OrderedSet#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
OrderedSet#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: T, key?: T, iter?: Iterable<T, T>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
OrderedSet#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#find
OrderedSet#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedSet#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findEntry
OrderedSet#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedSet#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: T, key?: T, iter?: Iterable.Keyed<T, T>) => boolean,context?: any): T
Inherited from
Iterable#findKey
OrderedSet#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: T, key?: T, iter?: Iterable.Keyed<T, T>) => boolean,context?: any): T
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
OrderedSet#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: T): T
Inherited from
Iterable#keyOf
OrderedSet#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: T): T
Inherited from
Iterable#lastKeyOf
OrderedSet#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
OrderedSet#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
OrderedSet#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
OrderedSet#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: T, key?: T, iter?: Iterable<T, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
OrderedSet#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, T>): boolean isSubset(iter: Array<T>): boolean
Inherited from
Iterable#isSubset
OrderedSet#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, T>): boolean isSuperset(iter: Array<T>): boolean
Inherited from
Iterable#isSuperset
Stack
Stacks are indexed collections which support very efficient O(1) addition and removal from the front using unshift(v)
and shift()
.
class Stack<T> extends Collection.Indexed<T>
Discussion
For familiarity, Stack also provides push(v)
, pop()
, and peek()
, but be aware that they also operate on the front of the list, unlike List or a JavaScript Array.
Note: reverse()
or any inherent reverse traversal (reduceRight
, lastIndexOf
, etc.) is not efficient with a Stack.
Stack is implemented with a Single-Linked List.
Construction
Stack()
Create a new immutable Stack containing the values of the provided iterable-like.
Stack<T>(): Stack<T> Stack<T>(iter: Iterable.Indexed<T>): Stack<T> Stack<T>(iter: Iterable.Set<T>): Stack<T> Stack<K, V>(iter: Iterable.Keyed<K, V>): Stack<any> Stack<T>(array: Array<T>): Stack<T> Stack<T>(iterator: Iterator<T>): Stack<T> Stack<T>(iterable: Object): Stack<T>
Discussion
The iteration order of the provided iterable is preserved in the resulting Stack
.
Static methods
Stack.isStack()
True if the provided value is a Stack
Stack.isStack(maybeStack: any): boolean
Stack.of()
Creates a new Stack containing values
.
Stack.of<T>(...values: T[]): Stack<T>
Members
Stack#size
size: number
Inherited from
Collection#size
Reading values
Stack#peek()
Alias for Stack.first()
.
peek(): T
Stack#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: number, notSetValue?: T): T
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Stack#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: number): boolean
Inherited from
Iterable#has
Stack#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: T): boolean
Inherited from
Iterable#includes
alias
contains()
Stack#first()
The first value in the Iterable.
first(): T
Inherited from
Iterable#first
Stack#last()
The last value in the Iterable.
last(): T
Inherited from
Iterable#last
Persistent changes
Stack#clear()
Returns a new Stack with 0 size and no values.
clear(): Stack<T>
Stack#unshift()
Returns a new Stack with the provided values
prepended, shifting other values ahead to higher indices.
unshift(...values: T[]): Stack<T>
Discussion
This is very efficient for Stack.
Stack#unshiftAll()
Like Stack#unshift
, but accepts a iterable rather than varargs.
unshiftAll(iter: Iterable<any, T>): Stack<T> unshiftAll(iter: Array<T>): Stack<T>
Stack#shift()
Returns a new Stack with a size ones less than this Stack, excluding the first item in this Stack, shifting all other values to a lower index.
shift(): Stack<T>
Discussion
Note: this differs from Array#shift
because it returns a new Stack rather than the removed value. Use first()
or peek()
to get the first value in this Stack.
Stack#push()
Alias for Stack#unshift
and is not equivalent to List#push
.
push(...values: T[]): Stack<T>
Stack#pushAll()
Alias for Stack#unshiftAll
.
pushAll(iter: Iterable<any, T>): Stack<T> pushAll(iter: Array<T>): Stack<T>
Stack#pop()
Alias for Stack#shift
and is not equivalent to List#pop
.
pop(): Stack<T>
Transient changes
Stack#withMutations()
Note: Not all methods can be used on a mutable collection or within withMutations
! Only set
, push
, and pop
may be used mutatively.
withMutations(mutator: (mutable: Stack<T>) => any): Stack<T>
see
Stack#asMutable()
asMutable(): Stack<T>
see
Stack#asImmutable()
asImmutable(): Stack<T>
see
Conversion to Seq
Stack#toSeq()
Returns Seq.Indexed.
toSeq(): Seq.Indexed<T>
Inherited from
Collection.Indexed#toSeq
Stack#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<number, T>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Stack#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<T>
Inherited from
Iterable#toIndexedSeq
Stack#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<T>
Inherited from
Iterable#toSetSeq
Stack#fromEntrySeq()
If this is an iterable of [key, value] entry tuples, it will return a Seq.Keyed of those entries.
fromEntrySeq(): Seq.Keyed<any, any>
Inherited from
Iterable.Indexed#fromEntrySeq
Value equality
Stack#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<number, T>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Stack#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading deep values
Stack#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Stack#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Stack#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Stack#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<T>
Inherited from
Iterable#toArray
Stack#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Stack#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<number, T>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Stack#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<number, T>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Stack#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<T>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Stack#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<T>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Stack#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<T>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Stack#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<T>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Stack#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<number>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Stack#values()
An iterator of this Iterable
's values.
values(): Iterator<T>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Stack#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Stack#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<number>
Inherited from
Iterable#keySeq
Stack#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<T>
Inherited from
Iterable#valueSeq
Stack#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Stack#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: T, key?: number, iter?: Iterable<number, T>) => M,context?: any): Iterable<number, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Stack#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Stack#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Stack#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<number, T>
Inherited from
Iterable#reverse
Stack#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: T, valueB: T) => number): Iterable<number, T>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Stack#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<number, T>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Stack#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: T, key?: number, iter?: Iterable<number, T>) => G,context?: any): Seq.Keyed<G, Iterable<number, T>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Stack#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: T, key?: number, iter?: Iterable<number, T>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Stack#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<number, T>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Stack#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<number, T>
Inherited from
Iterable#rest
Stack#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<number, T>
Inherited from
Iterable#butLast
Stack#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<number, T>
Inherited from
Iterable#skip
Stack#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<number, T>
Inherited from
Iterable#skipLast
Stack#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Stack#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Stack#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<number, T>
Inherited from
Iterable#take
Stack#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<number, T>
Inherited from
Iterable#takeLast
Stack#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Stack#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): Iterable<number, T>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Stack#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<number, T>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Stack#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Stack#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: T,key?: number,iter?: Iterable<number, T>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: T, key?: number, iter?: Iterable<number, T>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Stack#interpose()
Returns an Iterable of the same type with separator
between each item in this Iterable.
interpose(separator: T): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#interpose
Stack#interleave()
Returns an Iterable of the same type with the provided iterables
interleaved into this iterable.
interleave(...iterables: Array<Iterable<any, T>>): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#interleave
Discussion
The resulting Iterable includes the first item from each, then the second from each, etc.
I.Seq.of(1,2,3).interleave(I.Seq.of('A','B','C')) // Seq [ 1, 'A', 2, 'B', 3, 'C' ]
The shortest Iterable stops interleave.
I.Seq.of(1,2,3).interleave( I.Seq.of('A','B'), I.Seq.of('X','Y','Z') ) // Seq [ 1, 'A', 'X', 2, 'B', 'Y' ]
Stack#splice()
Splice returns a new indexed Iterable by replacing a region of this Iterable with new values. If values are not provided, it only skips the region to be removed.
splice(index: number, removeNum: number, ...values: any[]): Iterable.Indexed<T>
Inherited from
Iterable.Indexed#splice
Discussion
index
may be a negative number, which indexes back from the end of the Iterable. s.splice(-2)
splices after the second to last item.
Seq(['a','b','c','d']).splice(1, 2, 'q', 'r', 's') // Seq ['a', 'q', 'r', 's', 'd']
Stack#zip()
Returns an Iterable of the same type "zipped" with the provided iterables.
zip(...iterables: Array<Iterable<any, any>>): Iterable.Indexed<any>
Inherited from
Iterable.Indexed#zip
Discussion
Like zipWith
, but using the default zipper
: creating an Array
.
var a = Seq.of(1, 2, 3); var b = Seq.of(4, 5, 6); var c = a.zip(b); // Seq [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
Stack#zipWith()
Returns an Iterable of the same type "zipped" with the provided iterables by using a custom zipper
function.
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherIterable: Iterable<any, U>): Iterable.Indexed<Z> zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherIterable: Iterable<any, U>,thirdIterable: Iterable<any, V>): Iterable.Indexed<Z> zipWith<Z>(zipper: (...any: Array<any>) => Z,...iterables: Array<Iterable<any, any>>): Iterable.Indexed<Z>
Inherited from
Iterable.Indexed#zipWith
Example
var a = Seq.of(1, 2, 3); var b = Seq.of(4, 5, 6); var c = a.zipWith((a, b) => a + b, b); // Seq [ 5, 7, 9 ]
Reducing a value
Stack#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R,value?: T,key?: number,iter?: Iterable<number, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Stack#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R,value?: T,key?: number,iter?: Iterable<number, T>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Stack#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Stack#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Stack#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Stack#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Stack#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Stack#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: T, key?: number, iter?: Iterable<number, T>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Stack#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#find
Stack#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): T
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Stack#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findEntry
Stack#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: T, key?: number, iter?: Iterable<number, T>) => boolean,context?: any,notSetValue?: T): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Stack#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: T,key?: number,iter?: Iterable.Keyed<number, T>) => boolean,context?: any): number
Inherited from
Iterable#findKey
Stack#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: T,key?: number,iter?: Iterable.Keyed<number, T>) => boolean,context?: any): number
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Stack#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: T): number
Inherited from
Iterable#keyOf
Stack#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: T): number
Inherited from
Iterable#lastKeyOf
Stack#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Stack#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Stack#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: T, valueB: T) => number): T
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Stack#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: T,key?: number,iter?: Iterable<number, T>) => C,comparator?: (valueA: C, valueB: C) => number): T
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Stack#indexOf()
Returns the first index at which a given value can be found in the Iterable, or -1 if it is not present.
indexOf(searchValue: T): number
Inherited from
Iterable.Indexed#indexOf
Stack#lastIndexOf()
Returns the last index at which a given value can be found in the Iterable, or -1 if it is not present.
lastIndexOf(searchValue: T): number
Inherited from
Iterable.Indexed#lastIndexOf
Stack#findIndex()
Returns the first index in the Iterable where a value satisfies the provided predicate function. Otherwise -1 is returned.
findIndex(predicate: (value?: T, index?: number, iter?: Iterable.Indexed<T>) => boolean,context?: any): number
Inherited from
Iterable.Indexed#findIndex
Stack#findLastIndex()
Returns the last index in the Iterable where a value satisfies the provided predicate function. Otherwise -1 is returned.
findLastIndex(predicate: (value?: T, index?: number, iter?: Iterable.Indexed<T>) => boolean,context?: any): number
Inherited from
Iterable.Indexed#findLastIndex
Comparison
Stack#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, T>): boolean isSubset(iter: Array<T>): boolean
Inherited from
Iterable#isSubset
Stack#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, T>): boolean isSuperset(iter: Array<T>): boolean
Inherited from
Iterable#isSuperset
Range()
Returns a Seq.Indexed of numbers from start
(inclusive) to end
(exclusive), by step
, where start
defaults to 0, step
to 1, and end
to infinity. When start
is equal to end
, returns empty range.
Range(start?: number, end?: number, step?: number): Seq.Indexed<number>
Example
Range() // [0,1,2,3,...] Range(10) // [10,11,12,13,...] Range(10,15) // [10,11,12,13,14] Range(10,30,5) // [10,15,20,25] Range(30,10,5) // [30,25,20,15] Range(30,30,5) // []
Repeat()
Returns a Seq.Indexed of value
repeated times
times. When times
is not defined, returns an infinite Seq
of value
.
Repeat<T>(value: T, times?: number): Seq.Indexed<T>
Example
Repeat('foo') // ['foo','foo','foo',...] Repeat('bar',4) // ['bar','bar','bar','bar']
Record
Creates a new Class which produces Record instances. A record is similar to a JS object, but enforce a specific set of allowed string keys, and have default values.
Example
var ABRecord = Record({a:1, b:2}) var myRecord = new ABRecord({b:3})
Records always have a value for the keys they define. remove
ing a key from a record simply resets it to the default value for that key.
myRecord.size // 2 myRecord.get('a') // 1 myRecord.get('b') // 3 myRecordWithoutB = myRecord.remove('b') myRecordWithoutB.get('b') // 2 myRecordWithoutB.size // 2
Values provided to the constructor not found in the Record type will be ignored. For example, in this case, ABRecord is provided a key "x" even though only "a" and "b" have been defined. The value for "x" will be ignored for this record.
var myRecord = new ABRecord({b:3, x:10}) myRecord.get('x') // undefined
Because Records have a known set of string keys, property get access works as expected, however property sets will throw an Error.
Note: IE8 does not support property access. Only use get()
when supporting IE8.
myRecord.b // 3 myRecord.b = 5 // throws Error
Record Classes can be extended as well, allowing for custom methods on your Record. This is not a common pattern in functional environments, but is in many JS programs.
Note: TypeScript does not support this type of subclassing.
class ABRecord extends Record({a:1,b:2}) { getAB() { return this.a + this.b; } } var myRecord = new ABRecord({b: 3}) myRecord.getAB() // 4
Construction
Record()
Record(defaultValues: {[key: string]: any}, name?: string): Record.Class
Types
Record.ClassRecord.Class
class Record.Class
Seq
Represents a sequence of values, but may not be backed by a concrete data structure.
class Seq<K, V> extends Iterable<K, V>
Discussion
Seq is immutable — Once a Seq is created, it cannot be changed, appended to, rearranged or otherwise modified. Instead, any mutative method called on a Seq
will return a new Seq
.
Seq is lazy — Seq does as little work as necessary to respond to any method call. Values are often created during iteration, including implicit iteration when reducing or converting to a concrete data structure such as a List
or JavaScript Array
.
For example, the following performs no work, because the resulting Seq's values are never iterated:
var oddSquares = Immutable.Seq.of(1,2,3,4,5,6,7,8) .filter(x => x % 2).map(x => x * x);
Once the Seq is used, it performs only the work necessary. In this example, no intermediate data structures are ever created, filter is only called three times, and map is only called once:
console.log(oddSquares.get(1)); // 9
Seq allows for the efficient chaining of operations, allowing for the expression of logic that can otherwise be very tedious:
Immutable.Seq({a:1, b:1, c:1}) .flip().map(key => key.toUpperCase()).flip().toObject(); // Map { A: 1, B: 1, C: 1 }
As well as expressing logic that would otherwise be memory or time limited:
Immutable.Range(1, Infinity) .skip(1000) .map(n => -n) .filter(n => n % 2 === 0) .take(2) .reduce((r, n) => r * n, 1); // 1006008
Seq is often used to provide a rich collection API to JavaScript Object.
Immutable.Seq({ x: 0, y: 1, z: 2 }).map(v => v * 2).toObject(); // { x: 0, y: 2, z: 4 }
Construction
Seq()
Creates a Seq.
Seq<K, V>(): Seq<K, V> Seq<K, V>(seq: Seq<K, V>): Seq<K, V> Seq<K, V>(iterable: Iterable<K, V>): Seq<K, V> Seq<T>(array: Array<T>): Seq.Indexed<T> Seq<V>(obj: {[key: string]: V}): Seq.Keyed<string, V> Seq<T>(iterator: Iterator<T>): Seq.Indexed<T> Seq<T>(iterable: Object): Seq.Indexed<T>
Discussion
Returns a particular kind of Seq
based on the input.
- If a
Seq
, that sameSeq
. - If an
Iterable
, aSeq
of the same kind (Keyed, Indexed, or Set). - If an Array-like, an
Seq.Indexed
. - If an Object with an Iterator, an
Seq.Indexed
. - If an Iterator, an
Seq.Indexed
. - If an Object, a
Seq.Keyed
.
Static methods
Seq.isSeq()
True if maybeSeq
is a Seq, it is not backed by a concrete structure such as Map, List, or Set.
Seq.isSeq(maybeSeq: any): boolean
Seq.of()
Returns a Seq of the values provided. Alias for Seq.Indexed.of()
.
Seq.of<T>(...values: T[]): Seq.Indexed<T>
Types
Seq.KeyedMembers
Seq#size
size: number
Force evaluation
Seq#cacheResult()
Because Sequences are lazy and designed to be chained together, they do not cache their results. For example, this map function is called a total of 6 times, as each join
iterates the Seq of three values.
cacheResult(): Seq<K, V>
Example
var squares = Seq.of(1,2,3).map(x => x * x); squares.join() + squares.join();
If you know a Seq
will be used multiple times, it may be more efficient to first cache it in memory. Here, the map function is called only 3 times.
var squares = Seq.of(1,2,3).map(x => x * x).cacheResult(); squares.join() + squares.join();
Use this method judiciously, as it must fully evaluate a Seq which can be a burden on memory and possibly performance.
Note: after calling cacheResult
, a Seq will always have a size
.
Value equality
Seq#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Seq#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Seq#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Seq#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Seq#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Seq#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Seq#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Seq#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Seq#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Seq#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Seq#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Seq#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Seq#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Seq#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Seq#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Seq#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Conversion to Seq
Seq#toSeq()
Converts this Iterable to a Seq of the same kind (indexed, keyed, or set).
toSeq(): Seq<K, V>
Inherited from
Iterable#toSeq
Seq#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Seq#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Seq#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Iterators
Seq#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Seq#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Seq#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Seq#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Seq#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Seq#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Seq#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Seq#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Seq#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Seq#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Seq#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Seq#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Seq#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Seq#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Seq#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Seq#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Seq#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Seq#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Seq#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Seq#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Seq#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Seq#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Seq#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Seq#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Seq#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Seq#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Seq#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Seq#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Seq#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Seq#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Seq#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Seq#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Seq#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Seq#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Seq#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Seq#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Seq#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Seq#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Seq#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Seq#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Seq#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Seq#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Seq#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Seq#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Seq#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Seq#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Seq#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Seq#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Seq.Keyed
Seq
which represents key-value pairs.
class Seq.Keyed<K, V> extends Seq<K, V>, Iterable.Keyed<K, V>
Construction
Seq.Keyed()
Always returns a Seq.Keyed, if input is not keyed, expects an iterable of [K, V] tuples.
Seq.Keyed<K, V>(): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable.Keyed<K, V>): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable<any, any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(array: Array<any>): Seq.Keyed<K, V> Seq.Keyed<V>(obj: {[key: string]: V}): Seq.Keyed<string, V> Seq.Keyed<K, V>(iterator: Iterator<any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(iterable: Object): Seq.Keyed<K, V>
Members
Seq.Keyed#size
size: number
Inherited from
Seq#size
Conversion to Seq
Seq.Keyed#toSeq()
Returns itself
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Seq.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Seq.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Seq.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Force evaluation
Seq.Keyed#cacheResult()
Because Sequences are lazy and designed to be chained together, they do not cache their results. For example, this map function is called a total of 6 times, as each join
iterates the Seq of three values.
cacheResult(): Seq<K, V>
Inherited from
Seq#cacheResult
Example
var squares = Seq.of(1,2,3).map(x => x * x); squares.join() + squares.join();
If you know a Seq
will be used multiple times, it may be more efficient to first cache it in memory. Here, the map function is called only 3 times.
var squares = Seq.of(1,2,3).map(x => x * x).cacheResult(); squares.join() + squares.join();
Use this method judiciously, as it must fully evaluate a Seq which can be a burden on memory and possibly performance.
Note: after calling cacheResult
, a Seq will always have a size
.
Value equality
Seq.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Seq.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Seq.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Seq.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Seq.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Seq.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Seq.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Seq.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Seq.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Seq.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Seq.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Seq.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Seq.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Seq.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Seq.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Seq.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Seq.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Seq.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Seq.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Seq.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Seq.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Seq.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Seq.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Seq.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Seq.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Seq.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Seq.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Seq.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Seq.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Seq.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Seq.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Seq.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Seq.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Seq.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Seq.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Seq.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Seq.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Seq.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Seq.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Seq.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Seq.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Seq.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Seq.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Seq.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Seq.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Seq.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Seq.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Seq.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Seq.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Seq.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Seq.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Seq.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Seq.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Seq.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Seq.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Seq.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Seq.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Seq.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Seq.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Seq.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Seq.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Seq.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Seq.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Seq.Keyed
Seq
which represents key-value pairs.
class Seq.Keyed<K, V> extends Seq<K, V>, Iterable.Keyed<K, V>
Construction
Seq.Keyed()
Always returns a Seq.Keyed, if input is not keyed, expects an iterable of [K, V] tuples.
Seq.Keyed<K, V>(): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable.Keyed<K, V>): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable<any, any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(array: Array<any>): Seq.Keyed<K, V> Seq.Keyed<V>(obj: {[key: string]: V}): Seq.Keyed<string, V> Seq.Keyed<K, V>(iterator: Iterator<any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(iterable: Object): Seq.Keyed<K, V>
Members
Seq.Keyed#size
size: number
Inherited from
Seq#size
Conversion to Seq
Seq.Keyed#toSeq()
Returns itself
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Seq.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Seq.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Seq.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Force evaluation
Seq.Keyed#cacheResult()
Because Sequences are lazy and designed to be chained together, they do not cache their results. For example, this map function is called a total of 6 times, as each join
iterates the Seq of three values.
cacheResult(): Seq<K, V>
Inherited from
Seq#cacheResult
Example
var squares = Seq.of(1,2,3).map(x => x * x); squares.join() + squares.join();
If you know a Seq
will be used multiple times, it may be more efficient to first cache it in memory. Here, the map function is called only 3 times.
var squares = Seq.of(1,2,3).map(x => x * x).cacheResult(); squares.join() + squares.join();
Use this method judiciously, as it must fully evaluate a Seq which can be a burden on memory and possibly performance.
Note: after calling cacheResult
, a Seq will always have a size
.
Value equality
Seq.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Seq.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Seq.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Seq.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Seq.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Seq.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Seq.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Seq.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Seq.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Seq.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Seq.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Seq.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Seq.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Seq.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Seq.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Seq.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Seq.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Seq.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Seq.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Seq.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Seq.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Seq.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Seq.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Seq.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Seq.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Seq.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Seq.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Seq.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Seq.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Seq.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Seq.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Seq.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Seq.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Seq.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Seq.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Seq.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Seq.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Seq.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Seq.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Seq.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Seq.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Seq.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Seq.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Seq.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Seq.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Seq.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Seq.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Seq.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Seq.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Seq.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Seq.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Seq.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Seq.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Seq.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Seq.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Seq.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Seq.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Seq.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Seq.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Seq.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Seq.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Seq.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Seq.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Seq.Keyed
Seq
which represents key-value pairs.
class Seq.Keyed<K, V> extends Seq<K, V>, Iterable.Keyed<K, V>
Construction
Seq.Keyed()
Always returns a Seq.Keyed, if input is not keyed, expects an iterable of [K, V] tuples.
Seq.Keyed<K, V>(): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable.Keyed<K, V>): Seq.Keyed<K, V> Seq.Keyed<K, V>(seq: Iterable<any, any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(array: Array<any>): Seq.Keyed<K, V> Seq.Keyed<V>(obj: {[key: string]: V}): Seq.Keyed<string, V> Seq.Keyed<K, V>(iterator: Iterator<any>): Seq.Keyed<K, V> Seq.Keyed<K, V>(iterable: Object): Seq.Keyed<K, V>
Members
Seq.Keyed#size
size: number
Inherited from
Seq#size
Conversion to Seq
Seq.Keyed#toSeq()
Returns itself
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Seq.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Seq.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Seq.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Force evaluation
Seq.Keyed#cacheResult()
Because Sequences are lazy and designed to be chained together, they do not cache their results. For example, this map function is called a total of 6 times, as each join
iterates the Seq of three values.
cacheResult(): Seq<K, V>
Inherited from
Seq#cacheResult
Example
var squares = Seq.of(1,2,3).map(x => x * x); squares.join() + squares.join();
If you know a Seq
will be used multiple times, it may be more efficient to first cache it in memory. Here, the map function is called only 3 times.
var squares = Seq.of(1,2,3).map(x => x * x).cacheResult(); squares.join() + squares.join();
Use this method judiciously, as it must fully evaluate a Seq which can be a burden on memory and possibly performance.
Note: after calling cacheResult
, a Seq will always have a size
.
Value equality
Seq.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Seq.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Seq.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Seq.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Seq.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Seq.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Seq.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Seq.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Seq.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Seq.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Seq.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Seq.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Seq.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Seq.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Seq.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Seq.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Seq.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Seq.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Seq.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Seq.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Seq.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Seq.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Seq.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Seq.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Seq.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Seq.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Seq.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Seq.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Seq.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Seq.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Seq.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Seq.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Seq.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Seq.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Seq.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Seq.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Seq.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Seq.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Seq.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Seq.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Seq.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Seq.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Seq.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Seq.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Seq.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Seq.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Seq.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Seq.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Seq.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Seq.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Seq.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Seq.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Seq.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Seq.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Seq.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Seq.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Seq.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Seq.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Seq.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Seq.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Seq.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Seq.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Seq.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Seq.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Seq.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Seq.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Iterable
The Iterable
is a set of (key, value) entries which can be iterated, and is the base class for all collections in immutable
, allowing them to make use of all the Iterable methods (such as map
and filter
).
class Iterable<K, V>
Discussion
Note: An iterable is always iterated in the same order, however that order may not always be well defined, as is the case for the Map
and Set
.
Construction
Iterable()
Creates an Iterable.
Iterable<K, V>(iterable: Iterable<K, V>): Iterable<K, V> Iterable<T>(array: Array<T>): Iterable.Indexed<T> Iterable<V>(obj: {[key: string]: V}): Iterable.Keyed<string, V> Iterable<T>(iterator: Iterator<T>): Iterable.Indexed<T> Iterable<T>(iterable: Object): Iterable.Indexed<T> Iterable<V>(value: V): Iterable.Indexed<V>
Discussion
The type of Iterable created is based on the input.
- If an
Iterable
, that sameIterable
. - If an Array-like, an
Iterable.Indexed
. - If an Object with an Iterator, an
Iterable.Indexed
. - If an Iterator, an
Iterable.Indexed
. - If an Object, an
Iterable.Keyed
.
This methods forces the conversion of Objects and Strings to Iterables. If you want to ensure that a Iterable of one item is returned, use Seq.of
.
Static methods
Iterable.isIterable()
True if maybeIterable
is an Iterable, or any of its subclasses.
Iterable.isIterable(maybeIterable: any): boolean
Iterable.isKeyed()
True if maybeKeyed
is an Iterable.Keyed, or any of its subclasses.
Iterable.isKeyed(maybeKeyed: any): boolean
Iterable.isIndexed()
True if maybeIndexed
is a Iterable.Indexed, or any of its subclasses.
Iterable.isIndexed(maybeIndexed: any): boolean
Iterable.isAssociative()
True if maybeAssociative
is either a keyed or indexed Iterable.
Iterable.isAssociative(maybeAssociative: any): boolean
Iterable.isOrdered()
True if maybeOrdered
is an Iterable where iteration order is well defined. True for Iterable.Indexed as well as OrderedMap and OrderedSet.
Iterable.isOrdered(maybeOrdered: any): boolean
Types
Iterable.KeyedValue equality
Iterable#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Iterable#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Iterable#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Iterable#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Iterable#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
alias
contains()
Iterable#first()
The first value in the Iterable.
first(): V
Iterable#last()
The last value in the Iterable.
last(): V
Reading deep values
Iterable#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Iterable#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Conversion to JavaScript types
Iterable#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Iterable#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Iterable#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Discussion
Throws if keys are not strings.
Conversion to Collections
Iterable#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Iterable#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Iterable#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Iterable#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Conversion to Seq
Iterable#toSeq()
Converts this Iterable to a Seq of the same kind (indexed, keyed, or set).
toSeq(): Seq<K, V>
Iterable#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Iterable#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Iterable#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Iterators
Iterable#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Iterable#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Iterable#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Iterable#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Iterable#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Iterable#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Sequence algorithms
Iterable#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Iterable#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Iterable#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Iterable#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Iterable#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Iterable#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Example
hitters.sortBy(hitter => hitter.avgHits);
Iterable#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Discussion
Note: This is always an eager operation.
Side effects
Iterable#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Iterable#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Iterable#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Iterable#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Iterable#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Iterable#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Iterable#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Iterable#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Iterable#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Iterable#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Iterable#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Iterable#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Iterable#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Iterable#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Iterable#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Iterable#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Iterable#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Iterable#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Iterable#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Iterable#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Iterable#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Iterable#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Iterable#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Discussion
Note: This is not a lazy operation.
Search for value
Iterable#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Iterable#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Iterable#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Iterable#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Iterable#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Iterable#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Example
hitters.maxBy(hitter => hitter.avgHits);
Iterable#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Iterable#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Iterable#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Iterable.Keyed
Keyed Iterables have discrete keys tied to each value.
class Iterable.Keyed<K, V> extends Iterable<K, V>
Discussion
When iterating Iterable.Keyed
, each iteration will yield a [K, V]
tuple, in other words, Iterable#entries
is the default iterator for Keyed Iterables.
Construction
Iterable.Keyed()
Creates an Iterable.Keyed
Iterable.Keyed<K, V>(iter: Iterable.Keyed<K, V>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iter: Iterable<any, any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(array: Array<any>): Iterable.Keyed<K, V> Iterable.Keyed<V>(obj: {[key: string]: V}): Iterable.Keyed<string, V> Iterable.Keyed<K, V>(iterator: Iterator<any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iterable: Object): Iterable.Keyed<K, V>
Discussion
Similar to Iterable()
, however it expects iterable-likes of [K, V] tuples if not constructed from a Iterable.Keyed or JS Object.
Conversion to Seq
Iterable.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Iterable.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Iterable.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Iterable.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Sequence functions
Iterable.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Iterable.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Iterable.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Value equality
Iterable.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Iterable.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Iterable.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Iterable.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Iterable.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Iterable.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Iterable.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Iterable.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Iterable.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Iterable.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Iterable.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Iterable.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Iterable.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Iterable.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Iterable.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Iterable.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Iterable.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Iterable.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Iterable.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Iterable.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Iterable.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Iterable.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Iterable.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Iterable.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Iterable.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Iterable.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Iterable.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Iterable.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Iterable.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Iterable.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Iterable.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Iterable.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Iterable.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Iterable.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Iterable.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Iterable.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Iterable.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Iterable.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Iterable.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Iterable.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Iterable.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Iterable.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Iterable.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Iterable.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Iterable.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Iterable.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Iterable.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Iterable.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Iterable.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Iterable.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Iterable.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Iterable.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Iterable.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Iterable.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Iterable.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Iterable.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Iterable.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Iterable.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Iterable.Keyed
Keyed Iterables have discrete keys tied to each value.
class Iterable.Keyed<K, V> extends Iterable<K, V>
Discussion
When iterating Iterable.Keyed
, each iteration will yield a [K, V]
tuple, in other words, Iterable#entries
is the default iterator for Keyed Iterables.
Construction
Iterable.Keyed()
Creates an Iterable.Keyed
Iterable.Keyed<K, V>(iter: Iterable.Keyed<K, V>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iter: Iterable<any, any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(array: Array<any>): Iterable.Keyed<K, V> Iterable.Keyed<V>(obj: {[key: string]: V}): Iterable.Keyed<string, V> Iterable.Keyed<K, V>(iterator: Iterator<any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iterable: Object): Iterable.Keyed<K, V>
Discussion
Similar to Iterable()
, however it expects iterable-likes of [K, V] tuples if not constructed from a Iterable.Keyed or JS Object.
Conversion to Seq
Iterable.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Iterable.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Iterable.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Iterable.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Sequence functions
Iterable.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Iterable.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Iterable.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Value equality
Iterable.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Iterable.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Iterable.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Iterable.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Iterable.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Iterable.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Iterable.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Iterable.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Iterable.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Iterable.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Iterable.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Iterable.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Iterable.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Iterable.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Iterable.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Iterable.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Iterable.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Iterable.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Iterable.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Iterable.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Iterable.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Iterable.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Iterable.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Iterable.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Iterable.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Iterable.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Iterable.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Iterable.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Iterable.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Iterable.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Iterable.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Iterable.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Iterable.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Iterable.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Iterable.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Iterable.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Iterable.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Iterable.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Iterable.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Iterable.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Iterable.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Iterable.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Iterable.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Iterable.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Iterable.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Iterable.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Iterable.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Iterable.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Iterable.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Iterable.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Iterable.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Iterable.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Iterable.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Iterable.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Iterable.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Iterable.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Iterable.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Iterable.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Iterable.Keyed
Keyed Iterables have discrete keys tied to each value.
class Iterable.Keyed<K, V> extends Iterable<K, V>
Discussion
When iterating Iterable.Keyed
, each iteration will yield a [K, V]
tuple, in other words, Iterable#entries
is the default iterator for Keyed Iterables.
Construction
Iterable.Keyed()
Creates an Iterable.Keyed
Iterable.Keyed<K, V>(iter: Iterable.Keyed<K, V>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iter: Iterable<any, any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(array: Array<any>): Iterable.Keyed<K, V> Iterable.Keyed<V>(obj: {[key: string]: V}): Iterable.Keyed<string, V> Iterable.Keyed<K, V>(iterator: Iterator<any>): Iterable.Keyed<K, V> Iterable.Keyed<K, V>(iterable: Object): Iterable.Keyed<K, V>
Discussion
Similar to Iterable()
, however it expects iterable-likes of [K, V] tuples if not constructed from a Iterable.Keyed or JS Object.
Conversion to Seq
Iterable.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Iterable.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Iterable.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Iterable.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Sequence functions
Iterable.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Iterable.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Iterable.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Value equality
Iterable.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Iterable.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Iterable.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Iterable.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Iterable.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Iterable.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Iterable.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Iterable.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Iterable.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Iterable.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Iterable.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Iterable.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Iterable.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Iterable.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Iterable.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Iterable.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Iterable.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Iterable.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Iterable.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Iterable.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Iterable.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Iterable.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Iterable.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Iterable.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Iterable.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Iterable.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Iterable.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Iterable.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Iterable.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Iterable.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Iterable.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Iterable.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Iterable.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Iterable.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Iterable.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Iterable.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Iterable.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Iterable.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Iterable.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Iterable.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Iterable.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Iterable.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Iterable.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Iterable.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Iterable.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Iterable.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Iterable.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Iterable.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Iterable.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Iterable.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Iterable.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Iterable.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Iterable.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Iterable.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Iterable.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Iterable.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Iterable.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Iterable.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Iterable.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Iterable.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Iterable.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Iterable.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Collection
Collection is the abstract base class for concrete data structures. It cannot be constructed directly.
class Collection<K, V> extends Iterable<K, V>
Discussion
Implementations should extend one of the subclasses, Collection.Keyed
, Collection.Indexed
, or Collection.Set
.
Types
Collection.KeyedMembers
Collection#size
size: number
Value equality
Collection#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Collection#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Collection#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Collection#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Collection#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Collection#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Collection#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Collection#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Collection#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Collection#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Collection#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Collection#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Collection#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Collection#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Collection#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Collection#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Conversion to Seq
Collection#toSeq()
Converts this Iterable to a Seq of the same kind (indexed, keyed, or set).
toSeq(): Seq<K, V>
Inherited from
Iterable#toSeq
Collection#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Collection#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Collection#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Iterators
Collection#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Collection#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Collection#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Collection#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Collection#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Collection#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Collection#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Collection#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Collection#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Collection#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Collection#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Collection#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Collection#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Collection#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Collection#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Collection#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Collection#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Collection#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Collection#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Collection#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Collection#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Collection#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Collection#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Collection#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Collection#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Collection#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Collection#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Collection#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Collection#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Collection#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Collection#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Collection#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Collection#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Collection#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Collection#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Collection#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Collection#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Collection#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Collection#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Collection#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Collection#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Collection#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Collection#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Collection#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Collection#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Collection#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Collection#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Collection#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Collection.Keyed
Collection
which represents key-value pairs.
class Collection.Keyed<K, V> extends Collection<K, V>, Iterable.Keyed<K, V>
Members
Collection.Keyed#size
size: number
Inherited from
Collection#size
Conversion to Seq
Collection.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Collection.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Collection.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Collection.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Value equality
Collection.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Collection.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Collection.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Collection.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Collection.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Collection.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Collection.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Collection.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Collection.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Collection.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Collection.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Collection.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Collection.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Collection.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Collection.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Collection.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Collection.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Collection.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Collection.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Collection.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Collection.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Collection.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Collection.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Collection.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Collection.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Collection.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Collection.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Collection.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Collection.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Collection.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Collection.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Collection.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Collection.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Collection.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Collection.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Collection.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Collection.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Collection.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Collection.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Collection.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Collection.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Collection.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Collection.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Collection.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Collection.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Collection.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Collection.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Collection.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Collection.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Collection.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Collection.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Collection.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Collection.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Collection.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Collection.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Collection.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Collection.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Collection.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Collection.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Collection.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Collection.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Collection.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Collection.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Collection.Keyed
Collection
which represents key-value pairs.
class Collection.Keyed<K, V> extends Collection<K, V>, Iterable.Keyed<K, V>
Members
Collection.Keyed#size
size: number
Inherited from
Collection#size
Conversion to Seq
Collection.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Collection.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Collection.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Collection.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Value equality
Collection.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Collection.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Collection.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Collection.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Collection.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Collection.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Collection.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Collection.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Collection.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Collection.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Collection.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Collection.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Collection.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Collection.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Collection.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Collection.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Collection.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Collection.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Collection.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Collection.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Collection.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Collection.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Collection.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Collection.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Collection.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Collection.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Collection.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Collection.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Collection.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Collection.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Collection.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Collection.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Collection.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Collection.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Collection.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Collection.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Collection.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Collection.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Collection.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Collection.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Collection.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Collection.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Collection.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Collection.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Collection.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Collection.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Collection.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Collection.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Collection.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Collection.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Collection.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Collection.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Collection.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Collection.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Collection.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Collection.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Collection.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Collection.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Collection.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Collection.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Collection.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Collection.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Collection.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
Collection.Keyed
Collection
which represents key-value pairs.
class Collection.Keyed<K, V> extends Collection<K, V>, Iterable.Keyed<K, V>
Members
Collection.Keyed#size
size: number
Inherited from
Collection#size
Conversion to Seq
Collection.Keyed#toSeq()
Returns Seq.Keyed.
toSeq(): Seq.Keyed<K, V>
Overrides
Iterable#toSeq
Collection.Keyed#toKeyedSeq()
Returns a Seq.Keyed from this Iterable where indices are treated as keys.
toKeyedSeq(): Seq.Keyed<K, V>
Inherited from
Iterable#toKeyedSeq
Discussion
This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.
The returned Seq will have identical iteration order as this Iterable.
Example:
var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }
Collection.Keyed#toIndexedSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
toIndexedSeq(): Seq.Indexed<V>
Inherited from
Iterable#toIndexedSeq
Collection.Keyed#toSetSeq()
Returns a Seq.Set of the values of this Iterable, discarding keys.
toSetSeq(): Seq.Set<V>
Inherited from
Iterable#toSetSeq
Value equality
Collection.Keyed#equals()
True if this and the other Iterable have value equality, as defined by Immutable.is()
.
equals(other: Iterable<K, V>): boolean
Inherited from
Iterable#equals
Discussion
Note: This is equivalent to Immutable.is(this, other)
, but provided to allow for chained expressions.
Collection.Keyed#hashCode()
Computes and returns the hashed identity for this Iterable.
hashCode(): number
Inherited from
Iterable#hashCode
Discussion
The hashCode
of an Iterable is used to determine potential equality, and is used when adding this to a Set
or as a key in a Map
, enabling lookup via a different instance.
var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);
If two values have the same hashCode
, they are not guaranteed to be equal. If two values have different hashCode
s, they must not be equal.
Reading values
Collection.Keyed#get()
Returns the value associated with the provided key, or notSetValue if the Iterable does not contain this key.
get(key: K, notSetValue?: V): V
Inherited from
Iterable#get
Discussion
Note: it is possible a key may be associated with an undefined
value, so if notSetValue
is not provided and this method returns undefined
, that does not guarantee the key was not found.
Collection.Keyed#has()
True if a key exists within this Iterable
, using Immutable.is
to determine equality
has(key: K): boolean
Inherited from
Iterable#has
Collection.Keyed#includes()
True if a value exists within this Iterable
, using Immutable.is
to determine equality
includes(value: V): boolean
Inherited from
Iterable#includes
alias
contains()
Collection.Keyed#first()
The first value in the Iterable.
first(): V
Inherited from
Iterable#first
Collection.Keyed#last()
The last value in the Iterable.
last(): V
Inherited from
Iterable#last
Reading deep values
Collection.Keyed#getIn()
Returns the value found by following a path of keys or indices through nested Iterables.
getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any
Inherited from
Iterable#getIn
Collection.Keyed#hasIn()
True if the result of following a path of keys or indices through nested Iterables results in a set value.
hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean
Inherited from
Iterable#hasIn
Conversion to JavaScript types
Collection.Keyed#toJS()
Deeply converts this Iterable to equivalent JS.
toJS(): any
Inherited from
Iterable#toJS
alias
toJSON()
Discussion
Iterable.Indexeds
, and Iterable.Sets
become Arrays, while Iterable.Keyeds
become Objects.
Collection.Keyed#toArray()
Shallowly converts this iterable to an Array, discarding keys.
toArray(): Array<V>
Inherited from
Iterable#toArray
Collection.Keyed#toObject()
Shallowly converts this Iterable to an Object.
toObject(): {[key: string]: V}
Inherited from
Iterable#toObject
Discussion
Throws if keys are not strings.
Conversion to Collections
Collection.Keyed#toMap()
Converts this Iterable to a Map, Throws if keys are not hashable.
toMap(): Map<K, V>
Inherited from
Iterable#toMap
Discussion
Note: This is equivalent to Map(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toOrderedMap()
Converts this Iterable to a Map, maintaining the order of iteration.
toOrderedMap(): OrderedMap<K, V>
Inherited from
Iterable#toOrderedMap
Discussion
Note: This is equivalent to OrderedMap(this.toKeyedSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toSet()
Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.
toSet(): Set<V>
Inherited from
Iterable#toSet
Discussion
Note: This is equivalent to Set(this)
, but provided to allow for chained expressions.
Collection.Keyed#toOrderedSet()
Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.
toOrderedSet(): OrderedSet<V>
Inherited from
Iterable#toOrderedSet
Discussion
Note: This is equivalent to OrderedSet(this.valueSeq())
, but provided for convenience and to allow for chained expressions.
Collection.Keyed#toList()
Converts this Iterable to a List, discarding keys.
toList(): List<V>
Inherited from
Iterable#toList
Discussion
Note: This is equivalent to List(this)
, but provided to allow for chained expressions.
Collection.Keyed#toStack()
Converts this Iterable to a Stack, discarding keys. Throws if values are not hashable.
toStack(): Stack<V>
Inherited from
Iterable#toStack
Discussion
Note: This is equivalent to Stack(this)
, but provided to allow for chained expressions.
Iterators
Collection.Keyed#keys()
An iterator of this Iterable
's keys.
keys(): Iterator<K>
Inherited from
Iterable#keys
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use keySeq
instead, if this is what you want.
Collection.Keyed#values()
An iterator of this Iterable
's values.
values(): Iterator<V>
Inherited from
Iterable#values
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use valueSeq
instead, if this is what you want.
Collection.Keyed#entries()
An iterator of this Iterable
's entries as [key, value]
tuples.
entries(): Iterator<Array<any>>
Inherited from
Iterable#entries
Discussion
Note: this will return an ES6 iterator which does not support Immutable JS sequence algorithms. Use entrySeq
instead, if this is what you want.
Iterables (Seq)
Collection.Keyed#keySeq()
Returns a new Seq.Indexed of the keys of this Iterable, discarding values.
keySeq(): Seq.Indexed<K>
Inherited from
Iterable#keySeq
Collection.Keyed#valueSeq()
Returns an Seq.Indexed of the values of this Iterable, discarding keys.
valueSeq(): Seq.Indexed<V>
Inherited from
Iterable#valueSeq
Collection.Keyed#entrySeq()
Returns a new Seq.Indexed of [key, value] tuples.
entrySeq(): Seq.Indexed<Array<any>>
Inherited from
Iterable#entrySeq
Sequence algorithms
Collection.Keyed#map()
Returns a new Iterable of the same type with values passed through a mapper
function.
map<M>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,context?: any): Iterable<K, M>
Inherited from
Iterable#map
Example
Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }
Collection.Keyed#filter()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns true.
filter(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filter
Example
Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }
Collection.Keyed#filterNot()
Returns a new Iterable of the same type with only the entries for which the predicate
function returns false.
filterNot(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#filterNot
Example
Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }
Collection.Keyed#reverse()
Returns a new Iterable of the same type in reverse order.
reverse(): Iterable<K, V>
Inherited from
Iterable#reverse
Collection.Keyed#sort()
Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator
.
sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>
Inherited from
Iterable#sort
Discussion
If a comparator
is not provided, a default comparator uses <
and >
.
comparator(valueA, valueB)
:
- Returns
0
if the elements should not be swapped. - Returns
-1
(or any negative number) ifvalueA
comes beforevalueB
- Returns
1
(or any positive number) ifvalueA
comes aftervalueB
- 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.
Collection.Keyed#sortBy()
Like sort
, but also accepts a comparatorValueMapper
which allows for sorting by more sophisticated means:
sortBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): Iterable<K, V>
Inherited from
Iterable#sortBy
Example
hitters.sortBy(hitter => hitter.avgHits);
Collection.Keyed#groupBy()
Returns a Iterable.Keyed
of Iterable.Keyeds
, grouped by the return value of the grouper
function.
groupBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Seq.Keyed<G, Iterable<K, V>>
Inherited from
Iterable#groupBy
Discussion
Note: This is always an eager operation.
Side effects
Collection.Keyed#forEach()
The sideEffect
is executed for every entry in the Iterable.
forEach(sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): number
Inherited from
Iterable#forEach
Discussion
Unlike Array#forEach
, if any call of sideEffect
returns false
, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).
Creating subsets
Collection.Keyed#slice()
Returns a new Iterable of the same type representing a portion of this Iterable from start up to but not including end.
slice(begin?: number, end?: number): Iterable<K, V>
Inherited from
Iterable#slice
Discussion
If begin is negative, it is offset from the end of the Iterable. e.g. slice(-2)
returns a Iterable of the last two entries. If it is not provided the new Iterable will begin at the beginning of this Iterable.
If end is negative, it is offset from the end of the Iterable. e.g. slice(0, -1)
returns an Iterable of everything but the last entry. If it is not provided, the new Iterable will continue through the end of this Iterable.
If the requested slice is equivalent to the current Iterable, then it will return itself.
Collection.Keyed#rest()
Returns a new Iterable of the same type containing all entries except the first.
rest(): Iterable<K, V>
Inherited from
Iterable#rest
Collection.Keyed#butLast()
Returns a new Iterable of the same type containing all entries except the last.
butLast(): Iterable<K, V>
Inherited from
Iterable#butLast
Collection.Keyed#skip()
Returns a new Iterable of the same type which excludes the first amount
entries from this Iterable.
skip(amount: number): Iterable<K, V>
Inherited from
Iterable#skip
Collection.Keyed#skipLast()
Returns a new Iterable of the same type which excludes the last amount
entries from this Iterable.
skipLast(amount: number): Iterable<K, V>
Inherited from
Iterable#skipLast
Collection.Keyed#skipWhile()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns false.
skipWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipWhile
Example
Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]
Collection.Keyed#skipUntil()
Returns a new Iterable of the same type which includes entries starting from when predicate
first returns true.
skipUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#skipUntil
Example
Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]
Collection.Keyed#take()
Returns a new Iterable of the same type which includes the first amount
entries from this Iterable.
take(amount: number): Iterable<K, V>
Inherited from
Iterable#take
Collection.Keyed#takeLast()
Returns a new Iterable of the same type which includes the last amount
entries from this Iterable.
takeLast(amount: number): Iterable<K, V>
Inherited from
Iterable#takeLast
Collection.Keyed#takeWhile()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns true.
takeWhile(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeWhile
Example
Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]
Collection.Keyed#takeUntil()
Returns a new Iterable of the same type which includes entries from this Iterable as long as the predicate
returns false.
takeUntil(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): Iterable<K, V>
Inherited from
Iterable#takeUntil
Example
Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']
Combination
Collection.Keyed#concat()
Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.
concat(...valuesOrIterables: any[]): Iterable<K, V>
Inherited from
Iterable#concat
Discussion
For Seqs, all entries will be present in the resulting iterable, even if they have the same key.
Collection.Keyed#flatten()
Flattens nested Iterables.
flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>
Inherited from
Iterable#flatten
Discussion
Will deeply flatten the Iterable by default, returning an Iterable of the same type, but a depth
can 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 Iterable, not Arrays or Objects.
Note: flatten(true)
operates on Iterable
Collection.Keyed#flatMap()
Flat-maps the Iterable, returning an Iterable of the same type.
flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,context?: any): Iterable<MK, MV> flatMap<MK, MV>(mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,context?: any): Iterable<MK, MV>
Inherited from
Iterable#flatMap
Discussion
Similar to iter.map(...).flatten(true)
.
Reducing a value
Collection.Keyed#reduce()
Reduces the Iterable to a value by calling the reducer
for every entry in the Iterable and passing along the reduced value.
reduce<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduce
see
Discussion
If initialReduction
is not provided, or is null, the first item in the Iterable will be used.
Collection.Keyed#reduceRight()
Reduces the Iterable in reverse (from the right side).
reduceRight<R>(reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,initialReduction?: R,context?: any): R
Inherited from
Iterable#reduceRight
Discussion
Note: Similar to this.reverse().reduce(), and provided for parity with Array#reduceRight
.
Collection.Keyed#every()
True if predicate
returns true for all entries in the Iterable.
every(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#every
Collection.Keyed#some()
True if predicate
returns true for any entry in the Iterable.
some(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): boolean
Inherited from
Iterable#some
Collection.Keyed#join()
Joins values together as a string, inserting a separator between each. The default separator is ","
.
join(separator?: string): string
Inherited from
Iterable#join
Collection.Keyed#isEmpty()
Returns true if this Iterable includes no values.
isEmpty(): boolean
Inherited from
Iterable#isEmpty
Discussion
For some lazy Seq
, isEmpty
might need to iterate to determine emptiness. At most one iteration will occur.
Collection.Keyed#count()
Returns the size of this Iterable.
count(): number count(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any): number
Inherited from
Iterable#count
Discussion
Regardless of if this Iterable can describe its size lazily (some Seqs cannot), this method will always return the correct size. E.g. it evaluates a lazy Seq
if necessary.
If predicate
is provided, then this returns the count of entries in the Iterable for which the predicate
returns true.
Collection.Keyed#countBy()
Returns a Seq.Keyed
of counts, grouped by the return value of the grouper
function.
countBy<G>(grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,context?: any): Map<G, number>
Inherited from
Iterable#countBy
Discussion
Note: This is not a lazy operation.
Search for value
Collection.Keyed#find()
Returns the first value for which the predicate
returns true.
find(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#find
Collection.Keyed#findLast()
Returns the last value for which the predicate
returns true.
findLast(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): V
Inherited from
Iterable#findLast
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findEntry()
Returns the first [key, value] entry for which the predicate
returns true.
findEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findEntry
Collection.Keyed#findLastEntry()
Returns the last [key, value] entry for which the predicate
returns true.
findLastEntry(predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,context?: any,notSetValue?: V): Array<any>
Inherited from
Iterable#findLastEntry
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#findKey()
Returns the key for which the predicate
returns true.
findKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findKey
Collection.Keyed#findLastKey()
Returns the last key for which the predicate
returns true.
findLastKey(predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,context?: any): K
Inherited from
Iterable#findLastKey
Discussion
Note: predicate
will be called for each entry in reverse.
Collection.Keyed#keyOf()
Returns the key associated with the search value, or undefined.
keyOf(searchValue: V): K
Inherited from
Iterable#keyOf
Collection.Keyed#lastKeyOf()
Returns the last key associated with the search value, or undefined.
lastKeyOf(searchValue: V): K
Inherited from
Iterable#lastKeyOf
Collection.Keyed#max()
Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
max(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#max
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is >
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, max
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#maxBy()
Like max
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
maxBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#maxBy
Example
hitters.maxBy(hitter => hitter.avgHits);
Collection.Keyed#min()
Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.
min(comparator?: (valueA: V, valueB: V) => number): V
Inherited from
Iterable#min
Discussion
The comparator
is used in the same way as Iterable#sort
. If it is not provided, the default comparator is <
.
When two values are considered equivalent, the first encountered will be returned. Otherwise, min
will 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 comparator
returns 0 and either value is NaN, undefined, or null, that value will be returned.
Collection.Keyed#minBy()
Like min
, but also accepts a comparatorValueMapper
which allows for comparing by more sophisticated means:
minBy<C>(comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,comparator?: (valueA: C, valueB: C) => number): V
Inherited from
Iterable#minBy
Example
hitters.minBy(hitter => hitter.avgHits);
Comparison
Collection.Keyed#isSubset()
True if iter
includes every value in this Iterable.
isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean
Inherited from
Iterable#isSubset
Collection.Keyed#isSuperset()
True if this Iterable includes every value in iter
.
isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
Inherited from
Iterable#isSuperset
Sequence functions
Collection.Keyed#flip()
Returns a new Iterable.Keyed of the same type where the keys and values have been flipped.
flip(): Iterable.Keyed<V, K>
Inherited from
Iterable.Keyed#flip
Example
Seq({ a: 'z', b: 'y' }).flip() // { z: 'a', y: 'b' }
Collection.Keyed#mapKeys()
Returns a new Iterable.Keyed of the same type with keys passed through a mapper
function.
mapKeys<M>(mapper: (key?: K, value?: V, iter?: Iterable.Keyed<K, V>) => M,context?: any): Iterable.Keyed<M, V>
Inherited from
Iterable.Keyed#mapKeys
Example
Seq({ a: 1, b: 2 }) .mapKeys(x => x.toUpperCase()) // Seq { A: 1, B: 2 }
Collection.Keyed#mapEntries()
Returns a new Iterable.Keyed of the same type with entries ([key, value] tuples) passed through a mapper
function.
mapEntries<KM, VM>(mapper: (entry?: Array<any>,index?: number,iter?: Iterable.Keyed<K, V>) => Array<any>,context?: any): Iterable.Keyed<KM, VM>
Inherited from
Iterable.Keyed#mapEntries
Example
Seq({ a: 1, b: 2 }) .mapEntries(([k, v]) => [k.toUpperCase(), v * 2]) // Seq { A: 2, B: 4 }
© 2014–2015 Facebook, Inc.
Licensed under the 3-clause BSD License.
https://facebook.github.io/immutable-js/docs/