Stack

Stacks are indexed collections which support very efficient O(1) addition and removal from the front using unshift(v) and shift().

type Stack<T> extends Collection.Indexed<T>

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

Create a new immutable Stack containing the values of the provided collection-like.

Stack<T>(collection?: Iterable<T> | ArrayLike<T>): Stack<T>

Note: Stack is a factory function and not a class, and does not use the new keyword during construction.

Static Methods

True if the provided value is a Stack.

Stack.isStack(maybeStack: unknown): maybeStack is Stack<unknown>

Creates a new Stack containing values.

Stack.of<T>(...values: Array<T>): Stack<T>

Members

The number of items in this Stack.

size: number

Reading values

Alias for Stack.first().

peek(): T | undefined

Returns the value associated with the provided key, or notSetValue if the Collection does not contain this key.

get<NSV>(key: number, notSetValue: NSV): T | NSV
get(key: number): T | undefined

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

has(key: number): boolean

True if a value exists within this Collection, using Immutable.is to determine equality.

includes(value: T): boolean

Returns the first value in this Collection.

first(): T | undefined

Returns the last value in this Collection.

last(): T | undefined

Persistent changes

Returns a new Stack with 0 size and no values.

clear(): Stack<T>

Note: clear can be used in withMutations.

Returns a new Stack with the provided values prepended, shifting other values ahead to higher indices.

unshift(...values: Array<T>): Stack<T>

This is very efficient for Stack.

Note: unshift can be used in withMutations.

Like Stack#unshift, but accepts a collection rather than varargs.

unshiftAll(iter: Iterable<T>): Stack<T>

Note: unshiftAll can be used in withMutations.

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>

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.

Note: shift can be used in withMutations.

Alias for Stack#unshift and is not equivalent to List#push.

push(...values: Array<T>): Stack<T>

Alias for Stack#unshiftAll.

pushAll(iter: Iterable<T>): Stack<T>

Alias for Stack#shift and is not equivalent to List#pop.

pop(): Stack<T>

Returns a new Stack with an updated value at index with the return value of calling updater with the existing value.

update(index: number, updater: (value: T | undefined) => T | undefined): this
update<R>(updater: (value: this) => R): R

Transient changes

Note: Not all methods can be used on a mutable collection or within withMutations! Check the documentation for each method to see if it mentions being safe to use in withMutations.

withMutations(mutator: (mutable: this) => unknown): this

Note: Not all methods can be used on a mutable collection or within withMutations! Check the documentation for each method to see if it mentions being safe to use in withMutations.

asMutable(): this

wasAltered(): boolean

asImmutable(): this

Sequence algorithms

Returns a new Stack with other collections concatenated to this one.

concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Stack<T | C>

Returns a new Stack with values passed through a mapper function.

map<M>(mapper: (value: T, key: number, iter: this) => M, context?: unknown): Stack<M>

Note: map() always returns a new instance, even if it produced the same value at every step.

Flat-maps the Stack, returning a new Stack.

Similar to stack.map(...).flatten(true).

flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>, context?: unknown): Stack<M>

Returns a new Set with only the values for which the predicate function returns true.

filter<F extends T>(predicate: (value: T, index: number, iter: this) => value is F, context?: unknown): Set<F>
filter(predicate: (value: T, index: number, iter: this) => unknown, context?: unknown): this

Note: filter() always returns a new instance, even if it results in not filtering out any values.

Returns a new Stack with the values for which the predicate function returns false and another for which it returns true.

partition<F extends T, C>(predicate: (this: C, value: T, index: number, iter: this) => value is F, context?: C): [Stack<T>, Stack<F>]
partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown, context?: C): [this, this]

Returns a Stack "zipped" with the provided collections.

Like zipWith, but using the default zipper: creating an Array.

zip<U>(other: Collection<unknown, U>): Stack<[T, U]>
zip<U, V>(other: Collection<unknown, U>, other2: Collection<unknown, V>): Stack<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>

Example:

const a = Stack([1, 2, 3]);
const b = Stack([4, 5, 6]);
const c = a.zip(b); // Stack [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]

Returns a Stack "zipped" with the provided collections.

Unlike zip, zipAll continues zipping until the longest collection is exhausted. Missing values from shorter collections are filled with undefined.

zipAll<U>(other: Collection<unknown, U>): Stack<[T, U]>
zipAll<U, V>(other: Collection<unknown, U>, other2: Collection<unknown, V>): Stack<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>

Example:

const a = Stack([1, 2]);
const b = Stack([3, 4, 5]);
const c = a.zipAll(b); // Stack [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]

Note: Since zipAll will return a collection as large as the largest input, some results may contain undefined values. TypeScript cannot account for these without cases (as of v2.5).

Returns a Stack "zipped" with the provided collections by using a custom zipper function.

zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z, otherCollection: Collection<unknown, U>): Stack<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z, otherCollection: Collection<unknown, U>, thirdCollection: Collection<unknown, V>): Stack<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z, ...collections: Array<Collection<unknown, unknown>>): Stack<Z>

Example:

const a = Stack([1, 2, 3]);
const b = Stack([4, 5, 6]);
const c = a.zipWith((a, b) => a + b, b);
// Stack [ 5, 7, 9 ]

Sequence algorithms

Returns an iterator of this Stack.

[Symbol.iterator](): IterableIterator<T>

Returns a new Stack with only the values for which the predicate function returns false.

filterNot(predicate: (value: T, index: number, iter: this) => boolean, context?: unknown): this

Note: filterNot() always returns a new instance, even if it results in not filtering out any values.

Returns a new Stack with the order of the values reversed.

reverse(): this

Returns Stack of the same type which includes the same entries, stably sorted by using a comparator.

sort(comparator?: Comparator<T>): this

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
• Alternatively, can return a value of the PairSorting enum type
• Is pure, i.e. it must always return the same value for the same pair of values.

Note: sort() always returns a new instance, even if the original was already sorted.

Note: This is always an eager operation.

Like sort, but also accepts a comparatorValueMapper which allows for sorting by more sophisticated means.

sortBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C, comparator?: Comparator<C>): this

Note: sortBy() always returns a new instance, even if the original was already sorted.

Note: This is always an eager operation.

Returns a Map of Stack, grouped by the return value of the grouper function.

groupBy<G>(grouper: (value: T, key: number, iter: this) => G, context?: unknown): Map<G, Stack<T>>

Note: This is not a lazy operation.

Conversion to JavaScript types

Deeply converts this Stack to equivalent native JavaScript Array.

toJS(): Array<DeepCopy<T>>

Shallowly converts this Stack to equivalent native JavaScript Array.

toJSON(): Array<T>

Shallowly converts this collection to an Array.

toArray(): Array<T>

Shallowly converts this Stack to a JavaScript Object.

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

Conversion to Seq

Returns a Seq.Indexed of the values of this Stack.

toSeq(): Seq.Indexed<T>

If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.

fromEntrySeq(): Seq.Keyed<unknown, unknown>

Returns a Seq.Keyed from this Stack where indices are treated as keys.

toKeyedSeq(): Seq.Keyed<number, T>

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

toIndexedSeq(): Seq.Indexed<T>

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

toSetSeq(): Seq.Set<T>

Combination

Returns a new Stack with the separator inserted between each value in this Stack.

interpose(separator: T): Stack<T>

Returns a new Stack with the values from each collection interleaved.

interleave(...collections: Array<Collection<unknown, T>>): Stack<T>

Returns a new Stack by replacing a region of this Stack with new values. If values are not provided, it only skips the region to be removed.

splice(index: number, removeNum: number, ...values: Array<T>): Stack<T>

Returns a new flattened Stack, optionally only flattening to a particular depth.

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

Search for value

Returns the first index at which a given value can be found in the Stack, or -1 if it is not present.

indexOf(searchValue: T): number

Returns the last index at which a given value can be found in the Stack, or -1 if it is not present.

lastIndexOf(searchValue: T): number

Returns the first index in the Stack where a value satisfies the provided predicate function. Otherwise -1 is returned.

findIndex(predicate: (value: T, index: number, iter: this) => boolean, context?: unknown): number

Returns the last index in the Stack where a value satisfies the provided predicate function. Otherwise -1 is returned.

findLastIndex(predicate: (value: T, index: number, iter: this) => boolean, context?: unknown): number

Returns the first value for which the predicate returns true.

find(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown, notSetValue?: T): T | undefined

Returns the last value for which the predicate returns true.

findLast(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown, notSetValue?: T): T | undefined

Note: predicate will be called for each entry in reverse.

Returns the first [key, value] entry for which the predicate returns true.

findEntry(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown, notSetValue?: T): [number, T] | undefined

Returns the last [key, value] entry for which the predicate returns true.

findLastEntry(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown, notSetValue?: T): [number, T] | undefined

Note: predicate will be called for each entry in reverse.

Returns the first key for which the predicate returns true.

findKey(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): number | undefined

Returns the last key for which the predicate returns true.

findLastKey(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): number | undefined

Note: predicate will be called for each entry in reverse.

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

keyOf(searchValue: T): number | undefined

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

lastKeyOf(searchValue: T): number | undefined

Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

max(comparator?: Comparator<T>): T | undefined

Like max, but also accepts a comparatorValueMapper which allows for comparing by more sophisticated means.

maxBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C, comparator?: Comparator<C>): T | undefined

Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

min(comparator?: Comparator<T>): T | undefined

Like min, but also accepts a comparatorValueMapper which allows for comparing by more sophisticated means.

minBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C, comparator?: Comparator<C>): T | undefined

Value equality

True if this and the other Collection have value equality, as defined by Immutable.is().

equals(other: unknown): boolean

Note: This is equivalent to Immutable.is(this, other), but provided to allow for chained expressions.

Computes and returns the hashed identity for this Collection.

hashCode(): number

Reading deep values

Returns the value found by following a path of keys or indices through nested Collections.

getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

True if the result of following a path of keys or indices through nested Collections results in a set value.

hasIn(searchKeyPath: Iterable<unknown>): boolean

Conversion to Collections

Converts this Stack to a Map, Throws if keys are not hashable.

toMap(): Map<number, T>

Converts this Stack to a Map, maintaining the order of iteration.

toOrderedMap(): OrderedMap<number, T>

Converts this Stack to a Set, discarding keys.

toSet(): Set<T>

Converts this Stack to a Set, maintaining the order of iteration and discarding keys.

toOrderedSet(): OrderedSet<T>

Converts this Stack to a List, discarding keys.

toList(): List<T>

Returns itself.

toStack(): Stack<T>

Iterators

An iterator of this Stack's keys.

keys(): IterableIterator<number>

An iterator of this Stack's values.

values(): IterableIterator<T>

An iterator of this Stack's entries as [key, value] tuples.

entries(): IterableIterator<[number, T]>

Collections (Seq)

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

keySeq(): Seq.Indexed<number>

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

valueSeq(): Seq.Indexed<T>

Returns a new Seq.Indexed of [key, value] tuples.

entrySeq(): Seq.Indexed<[number, T]>

Side effects

The sideEffect is executed for every entry in the Stack.

forEach(sideEffect: (value: T, key: number, iter: this) => unknown, context?: unknown): number

Creating subsets

Returns a new Stack representing a portion of this Stack from start up to but not including end.

slice(begin?: number, end?: number): Stack<T>

Returns a new Stack containing all entries except the first.

rest(): Stack<T>

Returns a new Stack containing all entries except the last.

butLast(): Stack<T>

Returns a new Stack which excludes the first amount entries from this Stack.

skip(amount: number): Stack<T>

Returns a new Stack which excludes the last amount entries from this Stack.

skipLast(amount: number): Stack<T>

Returns a new Stack which includes entries starting from when predicate first returns false.

skipWhile(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): Stack<T>

Returns a new Stack which includes entries starting from when predicate first returns true.

skipUntil(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): Stack<T>

Returns a new Stack which includes the first amount entries from this Stack.

take(amount: number): Stack<T>

Returns a new Stack which includes the last amount entries from this Stack.

takeLast(amount: number): Stack<T>

Returns a new Stack which includes entries from this Stack as long as the predicate returns true.

takeWhile(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): Stack<T>

Returns a new Stack which includes entries from this Stack as long as the predicate returns false.

takeUntil(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): Stack<T>

Reducing a value

Reduces the Stack to a value by calling the reducer for every entry in the Stack and passing along the reduced value.

reduce<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R, initialReduction: R, context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

Reduces the Stack in reverse (from the right side).

reduceRight<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R, initialReduction: R, context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

True if predicate returns true for all entries in the Stack.

every(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): boolean

True if predicate returns true for any entry in the Stack.

some(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): boolean

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

join(separator?: string): string

Returns true if this Stack includes no values.

isEmpty(): boolean

Returns the size of this Stack.

count(): number
count(predicate: (value: T, key: number, iter: this) => boolean, context?: unknown): number

Returns a Map of counts, grouped by the return value of the grouper function.

countBy<G>(grouper: (value: T, key: number, iter: this) => G, context?: unknown): Map<G, number>

Comparison

True if iter includes every value in this Stack.

isSubset(iter: Iterable<T>): boolean

True if this Stack includes every value in iter.

isSuperset(iter: Iterable<T>): boolean