Iterable.Indexed

Indexed Iterables have incrementing numeric keys. They exhibit slightly different behavior than Iterable.Keyed for some methods in order to better mirror the behavior of JavaScript's Array, and add methods which do not make sense on non-indexed Iterables such as indexOf.

type Iterable.Indexed<T> extends Iterable<number, T>

Discussion

Unlike JavaScript arrays, Iterable.Indexeds are always dense. "Unset" indices and undefined indices are indistinguishable, and all indices from 0 to size are visited when iterated.

All Iterable.Indexed methods return re-indexed Iterables. In other words, indices always start at 0 and increment until size. If you wish to preserve indices, using them as keys, convert to a Iterable.Keyed by calling toKeyedSeq.

Construction

Iterable.Indexed()

Iterable.Indexed<T>(iter: Iterable.Indexed<T>): Iterable.Indexed<T> Iterable.Indexed<T>(iter: Iterable.Set<T>): Iterable.Indexed<T> Iterable.Indexed<K, V>(iter: Iterable.Keyed<K, V>): Iterable.Indexed<any> Iterable.Indexed<T>(array: Array<T>): Iterable.Indexed<T> Iterable.Indexed<T>(iterator: Iterator<T>): Iterable.Indexed<T> Iterable.Indexed<T>(iterable: Object): Iterable.Indexed<T>

Reading values

get()

Returns the value associated with the provided index, or notSetValue if the index is beyond the bounds of the Iterable.

get(index: number, notSetValue?: T): T

Overrides

Iterable#get()

Discussion

index may be a negative number, which indexes back from the end of the Iterable. s.get(-1) gets the last item in the Iterable.

has()

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

has(key: number): 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()

Conversion to Seq

toSeq()

Returns Seq.Indexed.

toSeq(): Seq.Indexed<T>

Overrides

Iterable#toSeq()

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>

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

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

Combination

interpose()

Returns an Iterable of the same type with separator between each item in this Iterable.

interpose(separator: T): Iterable.Indexed<T>

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>

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

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>

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

zip()

Returns an Iterable of the same type "zipped" with the provided iterables.

zip(...iterables: Array<Iterable<any, any>>): Iterable.Indexed<any>

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 ] ]

zipWith()

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>

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.

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

Search for value

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

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

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

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

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

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.

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

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.

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

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.

keyOf()

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

keyOf(searchValue: T): number

Inherited from

Iterable#keyOf()

lastKeyOf()

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

lastKeyOf(searchValue: T): number

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?: number,
iter?: Iterable<number, 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?: number,
iter?: Iterable<number, T>
) => C
,
comparator?: (valueA: C, valueB: C) => number
): T

Inherited from

Iterable#minBy()

Discussion

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

Value equality

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.

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 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<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.

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.

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<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.

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<number>

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?: number, iter?: Iterable<number, T>) => M,
context?: any
): Iterable<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, 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<number, 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<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) 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?: number,
iter?: Iterable<number, T>
) => C
,
comparator?: (valueA: C, valueB: C) => number
): Iterable<number, 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?: 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

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

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.

rest()

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

rest(): Iterable<number, T>

Inherited from

Iterable#rest()

butLast()

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

butLast(): Iterable<number, 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<number, 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<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, 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<number, 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<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, 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?: number, iter?: Iterable<number, T>) => boolean,
context?: any
): Iterable<number, T>

Inherited from

Iterable#takeUntil()

Discussion

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

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?: 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.

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.

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

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

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?: number, iter?: Iterable<number, 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?: number, iter?: Iterable<number, T>) => G,
context?: any
): Map<G, number>

Inherited from

Iterable#countBy()

Discussion

Note: This is not a lazy operation.

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.