Skip to content
Buy me a coffee

Collections

const Collections: object

Defined in: src/Collections.ts:1582

Static algorithms and factories that work on any collection: sorting, searching, reordering, empty and singleton collections, and unmodifiable, checked and synchronized wrappers.

List algorithms use get/set loops on lists with the RandomAccess brand and list iterators (or one array copy) on others, so they stay O(n) on a LinkedList. Every method throws NullPointerException for a null or undefined collection argument.

addAll: <E>(coll, …elements) => boolean

Adds each of elements to coll in order; returns true if coll changed.

Adds every element; true if the collection changed.

E

Collection<E>

…E[]

boolean

UnsupportedOperationException if coll does not support add

asLifoQueue: <E>(deque) => Queue<E>

Returns a last-in-first-out Queue view of deque: add/offer push at the front and remove/poll/ element/peek read the front, so the queue behaves as a stack. equals/hashCode are by identity.

Last-in-first-out Queue view of a deque: add/offer push at the front, remove/poll/element/peek read the front, addAll adds each element in turn at the front. equals/hashCode are by identity.

E

Deque<E>

Queue<E>

binarySearch: <E>(list, key, c?) => number

Searches list, which must be sorted ascending by c (natural ordering when c is null or omitted), for key. O(log n) comparisons; a list without the RandomAccess brand also costs O(n) iterator moves. The result is undefined if the list is not sorted.

Binary search in a list sorted by c (natural ordering when omitted).

E

List<E>

E

Comparator<E> | null

number

the index of a match, else -(insertionPoint) - 1

the index of a matching element (any one, if there are several), otherwise -(insertionPoint) - 1, where insertionPoint is the index at which key would be inserted; so the result is >= 0 only when the key is found

ClassCastException if natural ordering meets values that cannot be compared

checkedCollection: <E>(c, type) => Collection<E>

Returns a live view of c that throws ClassCastException when an element failing type is inserted (null passes the check; the backing collection decides). equals/hashCode are by identity. addAll checks every element before adding any.

View that throws ClassCastException when an element failing type is inserted. equals/hashCode are by identity.

E

Collection<E>

TypeCheck

Collection<E>

type

runtime check standing in for a class token, e.g. (x) => typeof x === 'string'

checkedList: <E>(l, type) => List<E>

Returns a live list view that type-checks every inserted element, including through set, replaceAll, list iterators and subList/reversed() views. List equality.

E

List<E>

TypeCheck

List<E>

ClassCastException when an element failing type is inserted

checkedMap: <K, V>(m, keyType, valueType) => Map<K, V>

Returns a live map view that type-checks keys and values on every way in: put, putIfAbsent, replace, putAll (checked before any is put), results of replaceAll/compute*/merge, and setValue on entries. Map equality.

K

V

Map<K, V>

TypeCheck

TypeCheck

Map<K, V>

ClassCastException when a key fails keyType or a value fails valueType

checkedNavigableMap: <K, V>(m, keyType, valueType) => NavigableMap<K, V>

Like checkedMap, for a navigable map; derived maps and key sets are checked too.

K

V

NavigableMap<K, V>

TypeCheck

TypeCheck

NavigableMap<K, V>

ClassCastException when a key fails keyType or a value fails valueType

checkedNavigableSet: <E>(s, type) => NavigableSet<E>

Returns a live navigable-set view that type-checks every inserted element, including through derived views.

E

NavigableSet<E>

TypeCheck

NavigableSet<E>

ClassCastException when an element failing type is inserted

checkedQueue: <E>(q, type) => Queue<E>

Returns a live queue view that type-checks every inserted element (add, offer, …).

E

Queue<E>

TypeCheck

Queue<E>

ClassCastException when an element failing type is inserted

checkedSet: <E>(s, type) => Set<E>

Returns a live set view that type-checks every inserted element. Set equality.

E

Set<E>

TypeCheck

Set<E>

ClassCastException when an element failing type is inserted

checkedSortedMap: <K, V>(m, keyType, valueType) => SortedMap<K, V>

Like checkedMap, for a sorted map; sub-map views are checked too.

K

V

SortedMap<K, V>

TypeCheck

TypeCheck

SortedMap<K, V>

ClassCastException when a key fails keyType or a value fails valueType

checkedSortedSet: <E>(s, type) => SortedSet<E>

Returns a live sorted-set view that type-checks every inserted element, including through sub-set views.

E

SortedSet<E>

TypeCheck

SortedSet<E>

ClassCastException when an element failing type is inserted

copy: <E>(dest, src) => void

Copies src over the first src.size() elements of dest; the rest of dest is unchanged. O(n).

Copies src over the first src.size() elements of dest.

E

List<E>

List<E>

void

IndexOutOfBoundsException if dest is shorter

IndexOutOfBoundsException if dest is shorter than src

UnsupportedOperationException if dest does not support set

disjoint: (c1, c2) => boolean

Returns true if c1 and c2 have no element in common. Iterates one collection and calls contains on the other, preferring a Set (or else the larger collection) for the contains side.

True when the two collections have no element in common.

Collection<unknown>

Collection<unknown>

boolean

EMPTY_LIST: List<never>

The shared immutable empty list, typed never; emptyList() returns the same instance with an element type.

EMPTY_MAP: Map<never, never>

The shared immutable empty map, typed never; emptyMap() returns the same instance with key and value types.

EMPTY_SET: Set<never>

The shared immutable empty set, typed never; emptySet() returns the same instance with an element type.

emptyEnumeration: <E>() => Enumeration<E>

Returns the shared enumeration over nothing: hasMoreElements() is false, nextElement() throws NoSuchElementException.

E

Enumeration<E>

emptyIterator: <E>() => Iterator<E>

Returns the shared iterator over nothing: hasNext() is false, next() throws NoSuchElementException, remove() throws IllegalStateException.

E

Iterator<E>

emptyList: <E>() => List<E>

Returns the shared immutable empty list (Collections.EMPTY_LIST); random access.

E

List<E>

emptyListIterator: <E>() => ListIterator<E>

Returns the shared list iterator over nothing: next()/previous() throw NoSuchElementException, remove()/set() throw IllegalStateException, add() throws UnsupportedOperationException.

E

ListIterator<E>

emptyMap: <K, V>() => Map<K, V>

Returns the shared immutable empty map (Collections.EMPTY_MAP).

K

V

Map<K, V>

emptyNavigableMap: <K, V>() => NavigableMap<K, V>

Returns the shared immutable empty navigable map (natural ordering); it rejects null keys like a TreeMap.

K

V

NavigableMap<K, V>

emptyNavigableSet: <E>() => NavigableSet<E>

Returns the shared immutable empty navigable set (natural ordering); lower/floor/ceiling/higher return null. Like a TreeSet, it rejects null queries with NullPointerException.

E

NavigableSet<E>

emptySet: <E>() => Set<E>

Returns the shared immutable empty set (Collections.EMPTY_SET).

E

Set<E>

emptySortedMap: <K, V>() => SortedMap<K, V>

Returns the shared immutable empty sorted map (natural ordering); it rejects null keys like a TreeMap.

K

V

SortedMap<K, V>

emptySortedSet: <E>() => SortedSet<E>

Returns the shared immutable empty sorted set (natural ordering). Like a TreeSet, it rejects null queries with NullPointerException; first()/last() throw NoSuchElementException.

E

SortedSet<E>

enumeration: <E>(c) => Enumeration<E>

Returns an Enumeration over c’s iterator, for legacy APIs. Its asIterator() does not support remove().

Enumeration over c’s iterator.

E

Collection<E>

Enumeration<E>

fill: <E>(list, v) => void

Replaces every element of list with v. O(n).

E

List<E>

E

void

UnsupportedOperationException if the list does not support set

frequency: (coll, o) => number

Returns the number of elements of coll equal to o (by Objects.equals). O(n).

Number of elements equal (Objects.equals) to o.

Collection<unknown>

unknown

number

indexOfSubList: (source, target) => number

Returns the first index at which target occurs as a contiguous run in source, or -1. An empty target matches at 0. O(n·m).

First index where target occurs as a contiguous run in source, or -1.

List<unknown>

List<unknown>

number

lastIndexOfSubList: (source, target) => number

Returns the last index at which target occurs as a contiguous run in source, or -1. An empty target matches at source.size(). O(n·m).

Last index where target occurs as a contiguous run in source, or -1.

List<unknown>

List<unknown>

number

list: <E>(e) => ArrayList<E>

Returns a new ArrayList holding the remaining elements of the enumeration e, in order.

The remaining elements of e, in order, in a new ArrayList.

E

Enumeration<E>

ArrayList<E>

max: <E>(coll, c?) => E

Returns the largest element of coll by c, or by natural ordering when c is null or omitted; the first one found on ties. O(n).

E

Collection<E>

Comparator<E> | null

E

NoSuchElementException when empty

NoSuchElementException if coll is empty

ClassCastException if natural ordering meets values that cannot be compared

NullPointerException if natural ordering meets a null element

min: <E>(coll, c?) => E

Returns the smallest element of coll by c, or by natural ordering when c is null or omitted; the first one found on ties. O(n).

E

Collection<E>

Comparator<E> | null

E

NoSuchElementException when empty

NoSuchElementException if coll is empty

ClassCastException if natural ordering meets values that cannot be compared

NullPointerException if natural ordering meets a null element

nCopies: <E>(n, o) => List<E>

Returns an immutable list of n copies of o (which may be null), in O(1) space. nCopies(0, o) is the shared empty list.

Immutable list of n copies of o (o may be null).

E

number

E

List<E>

IllegalArgumentException when n is negative or not an integer

IllegalArgumentException if n is negative or not an integer

newSequencedSetFromMap: <E>(map) => SequencedSet<E>

Like newSetFromMap, for a sequenced map: addFirst/addLast use putFirst/putLast, and reversed() is a set over the reversed map.

Sequenced set view of an empty sequenced map: addFirst/addLast use putFirst/putLast, the rest goes through map.sequencedKeySet().

E

SequencedMap<E, boolean>

SequencedSet<E>

IllegalArgumentException if map is not empty

IllegalArgumentException if map is not empty

newSetFromMap: <E>(map) => Set<E>

Returns a set backed by the empty map: add(e) is map.put(e, true), and every other operation goes through map.keySet(). The set takes on the map’s key semantics, e.g. an identity set over an IdentityHashMap. Use the map only through the returned set.

Set view of an empty map: add(e) is map.put(e, true) === null, everything else goes through map.keySet().

E

Map<E, boolean>

Set<E>

IllegalArgumentException if map is not empty

IllegalArgumentException if map is not empty

replaceAll: <E>(list, oldVal, newVal) => boolean

Replaces every element of list equal to oldVal (by Objects.equals) with newVal; returns true if any was replaced. O(n).

Replaces every element equal to oldVal with newVal; true if any was replaced.

E

List<E>

E

E

boolean

UnsupportedOperationException if the list does not support set

reverse: (list) => void

Reverses the order of the elements of list in place. O(n).

List<unknown>

void

UnsupportedOperationException if the list does not support set

reverseOrder: <T>(c?) => Comparator<T>

Returns a comparator that imposes the reverse of c, or of natural ordering when c is null or omitted. Reverse natural ordering is one shared instance, and reversing a reversed comparator returns the original.

Reverse of c, or of natural ordering when c is null/omitted (one shared instance). Reversing a reversed comparator gives back the original; reversing natural ordering gives the shared reverse.

T

Comparator<T> | null

Comparator<T>

rotate: (list, distance) => void

Rotates list in place by distance: the element at index i moves to (i + distance) mod size(). Any integer distance works, including negative ones and ones larger than the size. O(n).

Moves the element at i to (i + distance) mod size. Any integer distance (negative, larger than size) is fine.

List<unknown>

number

void

IllegalArgumentException if distance is not an integer (NaN, fractions, infinities)

IllegalArgumentException if distance is not an integer

UnsupportedOperationException if the list does not support set

shuffle: (list, rnd) => void

Randomly permutes list in place (Fisher-Yates). O(n). Pass a seeded RandomSource for a reproducible order; the default is Math.random. A non-random-access list of 5 or more elements is shuffled in an array copy and written back with its list iterator.

Fisher–Yates shuffle. rnd is a () => number in [0, 1) (default Math.random) or an object with nextInt(bound) returning an integer in [0, bound), like a RandomGenerator.

List<unknown>

RandomSource = Math.random

void

NullPointerException if list or an explicit rnd is null

NullPointerException if rnd is explicitly null

UnsupportedOperationException if the list does not support set

singleton: <E>(o) => Set<E>

Returns an immutable set holding only o (which may be null). Value equality with any Set. Mutators that would change it throw UnsupportedOperationException.

E

E

Set<E>

singletonList: <E>(o) => List<E>

Returns an immutable random-access list holding only o (which may be null). Value equality with any List. Mutators that would change it throw UnsupportedOperationException.

E

E

List<E>

singletonMap: <K, V>(key, value) => Map<K, V>

Returns an immutable map holding only the mapping key to value (either may be null). Value equality with any Map. Mutators that would change it throw UnsupportedOperationException.

K

V

K

V

Map<K, V>

sort: <E>(list, c?) => void

Sorts list stably by c, or by natural ordering when c is null or omitted; delegates to list.sort(c). O(n log n).

Stable sort; null/omitted comparator = natural ordering.

E

List<E>

Comparator<E> | null

void

ClassCastException if natural ordering meets values that cannot be compared

UnsupportedOperationException if the list does not support set

swap: (list, i, j) => void

Swaps the elements at positions i and j (a no-op when they are equal).

List<unknown>

number

number

void

IndexOutOfBoundsException

IndexOutOfBoundsException if i or j is out of range

synchronizedCollection: <E>(c) => Collection<E>

Returns a delegating view of c with its own identity: equals/hashCode are by identity. JS runs one thread per realm, so there is nothing to lock; the method exists so ported code keeps working.

Delegating view; equals/hashCode are by identity, as for the reference wrapper.

E

Collection<E>

Collection<E>

synchronizedList: <E>(l) => List<E>

Returns a delegating view of l (no locking is needed in JS); every method, equals included, passes through.

E

List<E>

List<E>

synchronizedMap: <K, V>(m) => Map<K, V>

Returns a delegating view of m (no locking is needed in JS); every method, equals included, passes through.

K

V

Map<K, V>

Map<K, V>

synchronizedNavigableMap: <K, V>(m) => NavigableMap<K, V>

Returns a delegating view of m (no locking is needed in JS); every method, equals included, passes through.

K

V

NavigableMap<K, V>

NavigableMap<K, V>

synchronizedNavigableSet: <E>(s) => NavigableSet<E>

Returns a delegating view of s (no locking is needed in JS); every method, equals included, passes through.

E

NavigableSet<E>

NavigableSet<E>

synchronizedSet: <E>(s) => Set<E>

Returns a delegating view of s (no locking is needed in JS); every method, equals included, passes through.

E

Set<E>

Set<E>

synchronizedSortedMap: <K, V>(m) => SortedMap<K, V>

Returns a delegating view of m (no locking is needed in JS); every method, equals included, passes through.

K

V

SortedMap<K, V>

SortedMap<K, V>

synchronizedSortedSet: <E>(s) => SortedSet<E>

Returns a delegating view of s (no locking is needed in JS); every method, equals included, passes through.

E

SortedSet<E>

SortedSet<E>

unmodifiableCollection: <E>(c) => Collection<E>

Returns a read-only live view of c: reads pass through, every mutator (also through iterators) throws UnsupportedOperationException. equals/hashCode are by identity, not the backing collection’s. Wrapping a view this method returned returns it unchanged.

E

Collection<E>

Collection<E>

unmodifiableList: <E>(list) => List<E>

Returns a read-only live view of list, with list equality. subList, reversed() and the iterators are read-only too; every mutator throws UnsupportedOperationException. Carries the RandomAccess brand when list does. Wrapping a view this method returned returns it unchanged.

E

List<E>

List<E>

unmodifiableMap: <K, V>(m) => Map<K, V>

Returns a read-only live view of m, with map equality. keySet(), values() and entrySet() are read-only (entries reject setValue); every mutator throws UnsupportedOperationException. Wrapping a view this method returned returns it unchanged.

K

V

Map<K, V>

Map<K, V>

unmodifiableNavigableMap: <K, V>(m) => NavigableMap<K, V>

Returns a read-only live view of a navigable map; every derived view and entry is read-only too. Every mutator, pollFirstEntry/pollLastEntry included, throws UnsupportedOperationException.

K

V

NavigableMap<K, V>

NavigableMap<K, V>

unmodifiableNavigableSet: <E>(s) => NavigableSet<E>

Returns a read-only live view of a navigable set; every derived view (descendingSet, subSet, …) is read-only too. Every mutator, pollFirst/pollLast included, throws UnsupportedOperationException.

E

NavigableSet<E>

NavigableSet<E>

unmodifiableSequencedCollection: <E>(c) => SequencedCollection<E>

Returns a read-only live view of a sequenced collection; reversed() is read-only too. Every mutator throws UnsupportedOperationException; equals/hashCode are by identity.

E

SequencedCollection<E>

SequencedCollection<E>

unmodifiableSequencedMap: <K, V>(m) => SequencedMap<K, V>

Returns a read-only live view of a sequenced map, with map equality; reversed() and the sequenced views are read-only too. Wrapping an unmodifiable sequenced (or sorted) map returns it.

Unmodifiable view with map equality; wrapping an unmodifiable sequenced (or sorted) map returns it.

K

V

SequencedMap<K, V>

SequencedMap<K, V>

unmodifiableSequencedSet: <E>(s) => SequencedSet<E>

Returns a read-only live view of a sequenced set, with set equality; reversed() is read-only too. Wrapping an unmodifiable sequenced (or sorted) set returns it.

Unmodifiable view with set equality; wrapping an unmodifiable sequenced (or sorted) set returns it.

E

SequencedSet<E>

SequencedSet<E>

unmodifiableSet: <E>(s) => Set<E>

Returns a read-only live view of s, with set equality. Every mutator throws UnsupportedOperationException. Wrapping a view this method returned returns it unchanged.

E

Set<E>

Set<E>

unmodifiableSortedMap: <K, V>(m) => SortedMap<K, V>

Returns a read-only live view of a sorted map; sub-map views are read-only too. Every mutator throws UnsupportedOperationException.

K

V

SortedMap<K, V>

SortedMap<K, V>

unmodifiableSortedSet: <E>(s) => SortedSet<E>

Returns a read-only live view of a sorted set; subSet/headSet/tailSet views are read-only too. Every mutator throws UnsupportedOperationException.

E

SortedSet<E>

SortedSet<E>