Skip to main content

interface BiMap<K,V>

A type-invariant immutable bi-directional Map where keys and values have a one-to-one mapping. See the BiMap documentation and the BiMap API documentation

Companion namespace: BiMap

Extends: FastIterable<T>

Implemented by: BiMapEmpty<K,V>, BiMap.NonEmpty<K,V>

Type parameters

NameDescription
Kthe key type
Vthe value type
example
const b1 = BiMap.empty<number, string>()
const b2 = BiMap.of([1, 'a'], [2, 'b'])

Properties

context

Returns the context associated to this collection instance.

Definition

readonly context: BiMap.Context<K, V>;

isEmpty

Returns true if the collection is empty.

Definition

readonly isEmpty: boolean;

example
BiMap.empty<number, number>().isEmpty   // => true
BiMap.of([1, 1], [2, 2]).isEmpty // => false

keyValueMap

Returns the Map representation of the key to value mapping.

Definition

readonly keyValueMap: RMap<K, V>;

example
BiMap.of([1, 10], [2, 20]).keyValueMap.toArray()
// => [[1, 10], [2, 20]]

size

Returns the number of entries

Definition

readonly size: number;

example
BiMap.of([1, 1], [2, 2]).size       // => 2

valueKeyMap

Returns the Map representation of the key to value mapping.

Definition

readonly valueKeyMap: RMap<V, K>;

example
BiMap.of([1, 10], [2, 20]).valueKeyMap.toArray()
// => [[10, 1], [20, 2]]

Methods

[Symbol.iterator]

Returns a FastIterator instance used to iterate over the values of this Iterable.

Definition

[Symbol.iterator](): FastIterator<T>;

Overrides

FastIterable.[Symbol.iterator]

addEntries

Returns the collection with the entries from the given StreamSource entries added.

Definitions

addEntries(entries: StreamSource.NonEmpty<readonly [K, V]>): BiMap.NonEmpty<K, V>;

addEntries(entries: StreamSource<readonly [K, V]>): BiMap<K, V>;

Parameters

NameTypeDescription
entriesStreamSource.NonEmpty<readonly [K, V]>a StreamSource containing tuples with a key and value
example
BiMap.of([1, 1]).addEntries([[2, 2], [1, 3]]).toArray()
// => [[1, 3], [2, 2]]

addEntry

Returns the collection with given entry added.

Definition

addEntry(entry: readonly [K, V]): BiMap.NonEmpty<K, V>;

Parameters

NameTypeDescription
entryreadonly [K, V]a tuple containing a key and value
example
BiMap.of([1, 1], [2, 2]).addEntry([1, 2]).toArray()
// => [[1, 2]]

assumeNonEmpty

Returns the collection as a .NonEmpty type

Definition

assumeNonEmpty(): BiMap.NonEmpty<K, V>;

throws

RimbuError.EmptyCollectionAssumedNonEmptyError if the collection is empty

example
BiMap.empty<number, number>().assumeNonEmpty()   // => throws
const m: BiMap<number, number> = BiMap.of([1, 1], [2, 2])
const m2: BiMap.NonEmpty<number, number> = m // => compiler error
const m3: BiMap.NonEmpty<number, number> = m.assumeNonEmpty()
note

returns reference to this collection

filter

Returns a collection containing only those entries that satisfy given pred predicate.

Definition

filter(pred: (entry: readonly [K, V], index: number, halt: () => void) => boolean): BiMap<K, V>;

Parameters

NameTypeDescription
pred(entry: readonly [K, V], index: number, halt: () => void) => booleana predicate function receiving:
- entry: the next entry
- index: the entry index
- halt: a function that, when called, ensures no next elements are passed
example
BiMap.of([1, 'a'], [2, 'b'], [3, 'c']).filter(entry => entry[0] === 2 || entry[1] === 'c').toArray()
// => [[2, 'b'], [3, 'c']]

forEach

Performs given function f for each entry of the collection, using given state as initial traversal state.

Definition

forEach(f: (entry: readonly [K, V], index: number, halt: () => void) => void, state?: TraverseState): void;

Parameters

NameTypeDescription
f(entry: readonly [K, V], index: number, halt: () => void) => voidthe function to perform for each entry, receiving:
- entry: the next tuple of a key and value
- index: the index of the element
- halt: a function that, if called, ensures that no new elements are passed
stateTraverseState(optional) the traverse state
example
BiMap.of([1, 'a'], [2, 'b'], [3, 'c']).forEach((entry, i, halt) => {
console.log([entry[1], entry[0]]);
if (i >= 1) halt();
})
// => logs ['a', 1] ['b', 2]
note

O(N)

getKey

Returns the key associated with the given value, or given otherwise value if the key is not in the collection.

Definitions

getKey<UV = V>(value: RelatedTo<V, UV>): K | undefined;

getKey<UV, O>(value: RelatedTo<V, UV>, otherwise: OptLazy<O>): K | O;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
valueRelatedTo<V, UV>thevalue to look for
example
const m = BiMap.of([1, 'a'], [2, 'b'])
m.getKey('b') // => 2
m.getKey('z') // => undefined
m.getKey('b', 'none') // => 2
m.getKey('z', 'none') // => 'none'

getValue

Returns the value associated with the given key, or given otherwise value if the key is not in the collection.

Definitions

getValue<UK = K>(key: RelatedTo<K, UK>): V | undefined;

getValue<UK, O>(key: RelatedTo<K, UK>, otherwise: OptLazy<O>): V | O;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key to look for
example
const m = BiMap.of([1, 'a'], [2, 'b'])
m.getValue(2) // => 'b'
m.getValue(3) // => undefined
m.getValue(2, 'none') // => 'b'
m.getValue(3, 'none') // => 'none'

hasKey

Returns true if the given key is present in the collection.

Definition

hasKey<UK = K>(key: RelatedTo<K, UK>): boolean;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key to look for
example
const m = BiMap.of([1, 'a'], [2, 'b'])
m.hasKey(2) // => true
m.hasKey(3) // => false

hasValue

Returns true if the given value is present in the collection.

Definition

hasValue<UV = V>(key: RelatedTo<V, UV>): boolean;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
keyRelatedTo<V, UV>
example
const m = BiMap.of([1, 'a'], [2, 'b'])
m.hasKey('a') // => true
m.hasKey('z') // => false

nonEmpty

Returns true if there is at least one entry in the collection, and instructs the compiler to treat the collection as a .NonEmpty type.

Definition

nonEmpty(): this is BiMap.NonEmpty<K, V>;

example
const m: BiMap<number, number> = BiMap.of([1, 1], [2, 2])
m.stream().first(0) // compiler allows fallback value since the Stream may be empty
if (m.nonEmpty()) {
m.stream().first(0) // compiler error: fallback value not allowed since Stream is not empty
}

removeKey

Returns the collection where the entry associated with given key is removed if it was part of the collection.

Definition

removeKey<UK = K>(key: RelatedTo<K, UK>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key of the entry to remove
example
const m = BiMap.of([1, 1], [2, 2])
m.removeKey(2).toArray() // => [[1, 1]]
m.removeKey(3) === m // true
note

guarantees same object reference if the key is not present

removeKeyAndGet

Returns a tuple containing the collection of which the entry associated with given key is removed, and the value that is associated with that key. If the key is not present, it will return undefined instead.

Definition

removeKeyAndGet<UK = K>(key: RelatedTo<K, UK>): [BiMap<K, V>, V] | undefined;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key of the entry to remove
example
const m = BiMap.of([1, 1], [2, 2])
const result = m.removeKeyAndGet(2)
if (result !== undefined) console.log([result[0].toString(), result[1]]) // => logs [BiMap(1 <=> 1), 2]
console.log(m.removeKeyAndGet(3)) // => logs undefined

removeKeys

Returns the collection where the entries associated with each key in given keys are removed if they were present.

Definition

removeKeys<UK = K>(keys: StreamSource<RelatedTo<K, UK>>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keysStreamSource<RelatedTo<K, UK>>a StreamSource of keys to remove
example
const m = BiMap.of([1, 1], [2, 2])
m.removeKeys([1, 3]).toArray() // => [[2, 2]]
m.removeKeys([1, 3, 2]).toArray() // => []
m.removeKeys([3, 4, 5]) === m // => true
note

guarantees same object reference if none of the keys are present

removeValue

Returns the collection where the entry associated with given value is removed if it was part of the collection.

Definition

removeValue<UV = V>(value: RelatedTo<V, UV>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
valueRelatedTo<V, UV>the value of the entry to remove
example
const m = BiMap.of([1, 1], [2, 2])
m.removeValue(2).toArray() // => [[1, 1]]
m.removeValue(3) === m // true
note

guarantees same object reference if the key is not present

removeValueAndGet

Returns a tuple containing the collection of which the entry associated with given value is removed, and the key that is associated with that value. If the value is not present, it will return undefined instead.

Definition

removeValueAndGet<UV = V>(value: RelatedTo<V, UV>): [BiMap<K, V>, K] | undefined;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
valueRelatedTo<V, UV>the value of the entry to remove
example
const m = BiMap.of([1, 1], [2, 2])
const result = m.removeValueAndGet(2)
if (result !== undefined) console.log([result[0].toString(), result[1]]) // => logs [BiMap(1 <=> 1), 2]
console.log(m.removeValueAndGet(3)) // => logs undefined

removeValues

Returns the collection where the entries associated with each value in given values are removed if they were present.

Definition

removeValues<UV = V>(value: StreamSource<RelatedTo<V, UV>>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
valueStreamSource<RelatedTo<V, UV>>
example
const m = BiMap.of([1, 1], [2, 2])
m.removeValues([1, 3]).toArray() // => [[2, 2]]
m.removeValues([1, 3, 2]).toArray() // => []
m.removeValues([3, 4, 5]) === m // => true
note

guarantees same object reference if none of the keys are present

set

Returns the collection with the given key associated to the given value.

Definition

set(key: K, value: V): BiMap.NonEmpty<K, V>;

Parameters

NameTypeDescription
keyKthe entry key to add
valueVthe entry value to add
example
BiMap.of([1, 1], [2, 2]).set(1, 2).toArray()
// => [[1, 2]]
note

if the key and/or value are already associated, the previous value will be 'replaced'

stream

Returns a Stream containing all entries of this collection as tuples of key and value.

Definition

stream(): Stream<readonly [K, V]>;

example
BiMap.of([1, 1], [2, 2]).stream().toArray()  // => [[1, 1], [2, 2]]

streamKeys

Returns a Stream containing all keys of this collection.

Definition

streamKeys(): Stream<K>;

example
BiMap.of([[1, 'a'], [2, 'b']]).streamKeys().toArray()   // => [1, 2]

streamValues

Returns a Stream containing all values of this collection.

Definition

streamValues(): Stream<V>;

example
BiMap.of([[1, 'a'], [2, 'b']]).streamValues().toArray()   // => ['a', 'b']

toArray

Returns an array containing all entries in this collection.

Definition

toArray(): (readonly [K, V])[];

example
BiMap.of([1, 'a'], [2, 'b']).toArray()   // => [[1, 'a'], [2, 'b']]
note

O(log(N)) @note it is safe to mutate the returned array, however, the array elements are not copied, thus should be treated as read-only

toBuilder

Returns a builder object containing the entries of this collection.

Definition

toBuilder(): BiMap.Builder<K, V>;

example
const builder: BiMap.Builder<number, string> = BiMap.of([1, 'a'], [2, 'b']).toBuilder()

toJSON

Returns a JSON representation of this collection.

Definition

toJSON(): ToJSON<(readonly [K, V])[], this['context']['typeTag']>;

example
BiMap.of([1, 'a'], [2, 'b']).toJSON()   // => { dataType: 'BiMap', value: [[1, 'a'], [2, 'b']] }

toString

Returns a string representation of this collection.

Definition

toString(): string;

example
BiMap.of([1, 'a'], [2, 'b']).toString()   // => BiMap(1 <=> 'a', 2 <=> 'b')

updateKeyAt

Returns the collection where the key associated with given value is updated with the given update value or update function.

Definition

updateKeyAt<UV = V>(value: RelatedTo<V, UV>, update: Update<K>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UVV

Parameters

NameTypeDescription
valueRelatedTo<V, UV>the value of the entry to update
updateUpdate<K>a new value or function taking the current key and returning a new key
example
const m = BiMap.of([1, 1], [2, 2])
m.updateKeyAt(3, 3).toArray()
// => [[1, 1], [2, 2]]
m.updateKeyAt(2, 10).toArray()
// => [[1, 1], [10, 2]]
m.updateKeyAt(1, v => v + 1)
// => [[2, 1]]

updateValueAt

Returns the collection where the value associated with given key is updated with the given update value or update function.

Definition

updateValueAt<UK = K>(key: RelatedTo<K, UK>, update: Update<V>): BiMap<K, V>;

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key of the entry to update
updateUpdate<V>a new value or function taking the current value and returning a new value
example
const m = BiMap.of([1, 1], [2, 2])
m.updateValueAt(3, 3).toArray()
// => [[1, 1], [2, 2]]
m.updateValueAt(2, 10).toArray()
// => [[1, 1], [2, 10]]
m.updateValueAt(1, v => v + 1)
// => [[1, 2]]