interface RMapBase<K,V,Tp>

undocumented

Companion namespace: RMapBase

Extends: VariantMapBase<K,V,Tp>

Implemented by: RMapBase.NonEmpty<K,V,Tp>

Type parameters

Name	Constraints	Default	Description
K			undocumented
V			undocumented
Tp	RMapBase.Types	RMapBase.Types	undocumented

Properties

context

Returns the context associated to this collection instance.

Definition

readonly context: WithKeyValue<Tp, K, V>['context'];

isEmpty

Returns true if the collection is empty.

Definition

readonly isEmpty: boolean;

example

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

Overrides

VariantMapBase.isEmpty

size

Returns the number of entries

Definition

readonly size: number;

example

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

Overrides

VariantMapBase.size

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<V2 extends V = V>(entries: StreamSource.NonEmpty<readonly [K, V2]>): WithKeyValue<Tp, K, V>['nonEmpty'];

addEntries<V2 extends V = V>(entries: StreamSource<readonly [K, V2]>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

Name	Constraints	Default	Description
V2	V	V

Parameters

Name	Type	Description
entries	StreamSource.NonEmpty<readonly [K, V2]>	a StreamSource containing tuples with a key and value

example

HashMap.of([1, 'a']).addEntries([[2, 'b']]).toArray()   // => [[1, 'a'], [2, 'b']]

addEntry

Returns the collection with given entry added.

Definition

addEntry(entry: readonly [K, V]): WithKeyValue<Tp, K, V>['nonEmpty'];

Parameters

Name	Type	Description
entry	readonly [K, V]	a tuple containing a key and value

example

HashMap.of([1, 'a']).addEntry([2, 'b']).toArray()   // => [[1, 'a'], [2, 'b']]
HashMap.of([1, 'a']).addEntry([1, 'b']).toArray()   // => [[1, 'b']]

assumeNonEmpty

Returns the collection as a .NonEmpty type

Definition

assumeNonEmpty(): WithKeyValue<Tp, K, V>['nonEmpty'];

throws

RimbuError.EmptyCollectionAssumedNonEmptyError if the collection is empty

example

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

note

returns reference to this collection

Overrides

VariantMapBase.assumeNonEmpty

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, options?: {
    negate?: boolean;
  }): WithKeyValue<Tp, K, V>['normal'];

Parameters

Name	Type	Description
pred	(entry: readonly [K, V], index: number, halt: () => void) => boolean	a predicate function receiving: - entry: the next entry - index: the entry index - halt: a function that, when called, ensures no next elements are passed
options	{     negate?: boolean;   }	(optional) an object containing the following properties: - negate: (default: false) when true will negate the predicate

example

HashMap.of([1, 'a'], [2, 'b'], [3, 'c']).filter(entry => entry[0] === 2 || entry[1] === 'c').toArray()
// => [[2, 'b'], [3, 'c']]

Overrides

VariantMapBase.filter

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, options?: {
    state?: TraverseState;
  }): void;

Parameters

Name	Type	Description
f	(entry: readonly [K, V], index: number, halt: () => void) => void	the 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
options	{     state?: TraverseState;   }	(optional) an object containing the following properties: - state:: (optional) the traversal state

example

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

Overrides

VariantMapBase.forEach

get

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

Definitions

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

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

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
key	RelatedTo<K, UK>	the key to look for

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.get(2)          // => 'b'
m.get(3)          // => undefined
m.get(2, 'none')  // => 'b'
m.get(3, 'none')  // => 'none'

Overrides

VariantMapBase.get

hasKey

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

Definition

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

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
key	RelatedTo<K, UK>	the key to look for

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.hasKey(2)    // => true
m.hasKey(3)    // => false

Overrides

VariantMapBase.hasKey

mapValues

Returns a collection with the same keys, but where the given mapFun function is applied to each entry value.

Definition

mapValues<V2>(mapFun: (value: V, key: K) => V2): (Tp & KeyValue<K, V2>)['normal'];

Type parameters

Name	Description
V2

Parameters

Name	Type	Description
mapFun	(value: V, key: K) => V2	a function taking a value and a key, and returning a new value

example

HashMap.of([1, 'a'], [2, 'abc']).mapValues(v => v.length).toArray()
// => [[1, 1], [2, 3]]

Overrides

VariantMapBase.mapValues

modifyAt

Returns the collection with the given atKey key modified according to given options.

Definition

modifyAt(atKey: K, options: {
    ifNew?: OptLazyOr<V, Token>;
    ifExists?: (<V2 extends V = V>(currentEntry: V & V2, remove: Token) => V |Token)| V;
  }): WithKeyValue<Tp, K, V>['normal'];

Parameters

Name	Type	Description
atKey	K	the key at which to modify the collection
options	{     ifNew?: OptLazyOr<V, Token>;     ifExists?: (<V2 extends V = V>(currentEntry: V & V2, remove: Token) => V |Token)| V;   }	an object containing the following information: - ifNew: (optional) if the given atKey is not present in the collection, this value or function will be used to generate a new entry. If a function returning the token argument is given, no new entry is created. - ifExists: (optional) if a value is associated with given atKey, this function is called with the given value to return a new value. As a second argument, a remove token is given. If the function returns this token, the current entry is removed.

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.modifyAt(3, { ifNew: 'c' }).toArray()
// => [[1, 'a'], [2, 'b'], [3, 'c']]
m.modifyAt(3, { ifNew: (none) => 1 < 2 ? none : 'c' }).toArray()
// => [[1, 'a'], [2, 'b']]
m.modifyAt(2, { ifExists: () => 'c' }).toArray()
// => [[1, 'a'], [2, 'c']]
m.modifyAt(2, { ifExists: (v) => v + 'z' }).toArray()
// => [[1, 'a'], [2, 'bz']]
m.modifyAt(2, { ifExists: (v, remove) => v === 'a' ? v : remove }).toArray()
// => [[1, 'a']]

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 WithKeyValue<Tp, K, V>['nonEmpty'];

example

const m: HashMap<number, number> = HashMap.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
}

Overrides

VariantMapBase.nonEmpty

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>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
key	RelatedTo<K, UK>	the key of the entry to remove

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.removeKey(2).toArray()   // => [[1, 'a']]
m.removeKey(3) === m       // true

note

guarantees same object reference if the key is not present

Overrides

VariantMapBase.removeKey

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>): [WithKeyValue<Tp, K, V>['normal'], V] | undefined;

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
key	RelatedTo<K, UK>	the key of the entry to remove

example

const m = HashMap.of([1, 'a'], [2, 'b'])
const result = m.removeKeyAndGet(2)
if (result !== undefined) console.log([result[0].toString(), result[1]])    // => logs [HashMap(1 => 'a'), 'b']
console.log(m.removeKeyAndGet(3))                                           // => logs undefined

Overrides

VariantMapBase.removeKeyAndGet

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>>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
keys	StreamSource<RelatedTo<K, UK>>	a StreamSource of keys to remove

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.removeKeys([1, 3]).toArray()     // => [[2, 'b']]
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

Overrides

VariantMapBase.removeKeys

set

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

Definition

set(key: K, value: V): WithKeyValue<Tp, K, V>['nonEmpty'];

Parameters

Name	Type	Description
key	K	the entry key to add
value	V	the entry value to add

example

HashMap.of([1, 'a']).set(2, 'b').toArray()   // => [[1, 'a'], [2, 'b']]
HashMap.of([1, 'a']).set(1, 'b').toArray()   // => [[1, 'b']]

note

if the key is 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

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

Overrides

VariantMapBase.stream

streamKeys

Returns a Stream containing all keys of this collection.

Definition

streamKeys(): Stream<K>;

example

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

Overrides

VariantMapBase.streamKeys

streamValues

Returns a Stream containing all values of this collection.

Definition

streamValues(): Stream<V>;

example

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

Overrides

VariantMapBase.streamValues

toArray

Returns an array containing all entries in this collection.

Definition

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

example

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

Overrides

VariantMapBase.toArray

toBuilder

Returns a builder object containing the entries of this collection.

Definition

toBuilder(): WithKeyValue<Tp, K, V>['builder'];

example

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

toJSON

Returns a JSON representation of this collection.

Definition

toJSON(): ToJSON<(readonly [K, V])[]>;

example

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

Overrides

VariantMapBase.toJSON

toString

Returns a string representation of this collection.

Definition

toString(): string;

example

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

Overrides

VariantMapBase.toString

updateAt

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

Definition

updateAt<UK = K>(key: RelatedTo<K, UK>, update: RMapBase.Update<V>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

Name	Default	Description
UK	K

Parameters

Name	Type	Description
key	RelatedTo<K, UK>	the key of the entry to update
update	RMapBase.Update<V>	a new value or function taking the current value and returning a new value

example

const m = HashMap.of([1, 'a'], [2, 'b'])
m.updateAt(3, 'a').toArray()
// => [[1, 'a'], [2, 'b']]
m.updateAt(2, 'c').toArray()
// => [[1, 'a'], [2, 'c']]
m.updateAt(2, v => v + 'z')
// => [[1, 'a'], [2, 'cz]]