OrderedSet

A type of Set that has the additional guarantee that the iteration order of values will be the order in which they were added.

type 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()

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

OrderedSet.isOrderedSet(maybeOrderedSet: any): boolean

OrderedSet.of()

OrderedSet.of<T>(...values: T[]): OrderedSet<T>

OrderedSet.fromKeys()

OrderedSet.fromKeys<T>(iter: Iterable<T, any>): OrderedSet<T> OrderedSet.fromKeys(obj: {[key: string]: any}): OrderedSet<string>

Persistent changes

add()

Returns a new Set which also includes this value.

add(value: T): Set<T>

Inherited from

Set#add()

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

clear()

Returns a new Set containing no values.

clear(): Set<T>

Inherited from

Set#clear()

union()

union(...iterables: Iterable<any, T>[]): Set<T> union(...iterables: Array<T>[]): Set<T>

Inherited from

Set#union()

intersect()

intersect(...iterables: Iterable<any, T>[]): Set<T> intersect(...iterables: Array<T>[]): Set<T>

Inherited from

Set#intersect()

subtract()

subtract(...iterables: Iterable<any, T>[]): Set<T> subtract(...iterables: Array<T>[]): Set<T>

Inherited from

Set#subtract()

Transient changes

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

asMutable()

asMutable(): Set<T>

Inherited from

Set#asMutable()

see

asImmutable()

asImmutable(): Set<T>

Inherited from

Set#asImmutable()

see

Conversion to Seq

toSeq()

Returns Seq.Set.

toSeq(): Seq.Set<T>

Inherited from

Collection.Set#toSeq()

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' }

toIndexedSeq()

Returns an Seq.Indexed of the values of this Iterable, discarding keys.

toIndexedSeq(): Seq.Indexed<T>

Inherited from

Iterable#toIndexedSeq()

toSetSeq()

Returns a Seq.Set of the values of this Iterable, discarding keys.

toSetSeq(): Seq.Set<T>

Inherited from

Iterable#toSetSeq()

Members

size

All collections maintain their current size as an integer.

size: number

Inherited from

Collection#size

Value equality

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.

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 hashCodes, they must not be equal.

Reading values

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.

has()

True if a key exists within this Iterable, using Immutable.is to determine equality

has(key: T): boolean

Inherited from

Iterable#has()

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

first()

The first value in the Iterable.

first(): T

Inherited from

Iterable#first()

last()

The last value in the Iterable.

last(): T

Inherited from

Iterable#last()

Reading deep values

getIn()

getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any

Inherited from

Iterable#getIn()

hasIn()

hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean

Inherited from

Iterable#hasIn()

Conversion to JavaScript types

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.

toArray()

Shallowly converts this iterable to an Array, discarding keys.

toArray(): Array<T>

Inherited from

Iterable#toArray()

toObject()

Shallowly converts this Iterable to an Object.

toObject(): {[key: string]: T}

Inherited from

Iterable#toObject()

Discussion

Throws if keys are not strings.

Conversion to Collections

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.

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.

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.

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.

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.

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

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.

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.

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)

keySeq()

Returns a new Seq.Indexed of the keys of this Iterable, discarding values.

keySeq(): Seq.Indexed<T>

Inherited from

Iterable#keySeq()

valueSeq()

Returns an Seq.Indexed of the values of this Iterable, discarding keys.

valueSeq(): Seq.Indexed<T>

Inherited from

Iterable#valueSeq()

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?: T, key?: T, iter?: Iterable<T, T>) => M,
context?: any
): Iterable<T, M>

Inherited from

Iterable#map()

Discussion

Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }

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

Discussion

Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }

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

Discussion

Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }

reverse()

Returns a new Iterable of the same type in reverse order.

reverse(): Iterable<T, T>

Inherited from

Iterable#reverse()

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) if valueA comes before valueB
  • Returns 1 (or any positive number) if valueA comes after valueB
  • 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.

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

Discussion

hitters.sortBy(hitter => hitter.avgHits);

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

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

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.

rest()

Returns a new Iterable of the same type containing all entries except the first.

rest(): Iterable<T, T>

Inherited from

Iterable#rest()

butLast()

Returns a new Iterable of the same type containing all entries except the last.

butLast(): Iterable<T, T>

Inherited from

Iterable#butLast()

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

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

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

Discussion

Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]

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

Discussion

Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]

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

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

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

Discussion

Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]

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

Discussion

Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']

Combination

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.

flatten()

flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>

Inherited from

Iterable#flatten()

flatMap()

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

Reducing a value

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.

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.

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

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

join()

Joins values together as a string, inserting a separator between each. The default separator is ",".

join(separator?: string): string

Inherited from

Iterable#join()

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.

count()

count(): number count(
predicate: (value?: T, key?: T, iter?: Iterable<T, T>) => boolean,
context?: any
): number

Inherited from

Iterable#count()

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

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

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.

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

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.

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

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.

keyOf()

Returns the key associated with the search value, or undefined.

keyOf(searchValue: T): T

Inherited from

Iterable#keyOf()

lastKeyOf()

Returns the last key associated with the search value, or undefined.

lastKeyOf(searchValue: T): T

Inherited from

Iterable#lastKeyOf()

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.

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

Discussion

hitters.maxBy(hitter => hitter.avgHits);

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.

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

Discussion

hitters.minBy(hitter => hitter.avgHits);

Comparison

isSubset()

isSubset(iter: Iterable<any, T>): boolean isSubset(iter: Array<T>): boolean

Inherited from

Iterable#isSubset()

isSuperset()

isSuperset(iter: Iterable<any, T>): boolean isSuperset(iter: Array<T>): boolean

Inherited from

Iterable#isSuperset()
This documentation is generated from immutable.d.ts. Pull requests and Issues welcome.