Skip to main content

interface MultiMapBase<K,V,Tp>

undocumented

Companion namespace: MultiMapBase

Extends: VariantMultiMapBase<K,V,Tp>

Implemented by: HashMultiMapHashValue<K,V>, SortedMultiMapSortedValue<K,V>, MultiMapBase.NonEmpty<K,V,Tp>, MultiMap<K,V>, MultiMapEmpty<K,V,Tp>, HashMultiMapSortedValue<K,V>, SortedMultiMapHashValue<K,V>

Type parameters

NameConstraintsDefaultDescription
Kundocumented
Vundocumented
TpMultiMapBase.TypesMultiMapBase.Typesundocumented

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
HashMultiMapHashValue.empty<number>().isEmpty      // => true
HashMultiMapHashValue.of([1, 1], [2, 2]).isEmpty // => false

Overrides

VariantMultiMapBase.isEmpty

keyMap

Returns the Map representation of this collection.

Definition

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

example
const m = HashMultiMapHashValue.of([1, 1], [2, 2])
const map: HashMap<number, HashSet.NonEmpty<number>> = m.keyMap

Overrides

VariantMultiMapBase.keyMap

keySize

Returns the number of keys in the collection.

Definition

readonly keySize: number;

example
HashMultiMapHashValue.of([1, 1], [2, 2]).keySize      // => 2
HashMultiMapHashValue.of([1, 1], [1, 2]).keySize // => 1

Overrides

VariantMultiMapBase.keySize

size

Returns the number of unique key-value combinations in this collection.

Definition

readonly size: number;

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

Overrides

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

add

Returns the collection with the given value added to the given key values.

Definition

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

Parameters

NameTypeDescription
keyKthe key for which to add a value
valueVthe value to add to the key values
example
HashMultiMapHashValue.of([1, 'a']).add(2, 'b').toArray()   // => [[1, 'a'], [2, 'b']]
HashMultiMapHashValue.of([1, 'a']).add(1, 'b').toArray() // => [[1, 'a'], [1, 'b']]

addEntries

Returns the collection with the given entries added.

Definitions

addEntries(entries: StreamSource.NonEmpty<readonly [K, V]>): WithKeyValue<Tp, K, V>['nonEmpty'];

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

Parameters

NameTypeDescription
entriesStreamSource.NonEmpty<readonly [K, V]>a StreamSource containing entries to add
example
HashMultiMapHashValue.of([1, 'a']).addEntries([[2, 'b'], [1, 'c']).toArray()
// => [[1, 'a'], [1, 'c'], [2, '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
HashMultiMapHashValue.empty<number, number>().assumeNonEmpty()   // => throws
const m: HashMultiMapHashValue<number, number> = HashMultiMapHashValue.of([1, 1], [2, 2])
const m2: HashMultiMapHashValue.NonEmpty<number, number> = m // => compiler error
const m3: HashMultiMapHashValue.NonEmpty<number, number> = m.assumeNonEmpty()
note

returns reference to this collection

Overrides

VariantMultiMapBase.assumeNonEmpty

filter

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

Definition

filter(pred: (entry: [K, V], index: number, halt: () => void) => boolean, options?: {
    negate?: boolean;
  }): WithKeyValue<Tp, K, V>['normal'];

Parameters

NameTypeDescription
pred(entry: [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 entries are passed
options{
    negate?: boolean;
  }
(optional) an object containing the following properties:
- negate: (default: false) when true will negate the predicate
example
HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c'])
.filter(entry => entry[0] === 2 || entry[1] === 'c')
.toArray()
// => [[2, 'b'], [1, 'c']]

Overrides

VariantMultiMapBase.filter

forEach

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

Definition

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

Parameters

NameTypeDescription
f(entry: [K, V], index: number, halt: () => void) => voidthe function to perform for each element, 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;
  }
example
HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c']).forEach((entry, i, halt) => {
console.log([entry[1], entry[0]]);
if (i >= 1) halt();
})
// => logs ['a', 1] ['c', 1] (or other order)
note

O(N)

Overrides

VariantMultiMapBase.forEach

getValues

Returns the value collection associated to the given key.

Definition

getValues<UK = K>(key: RelatedTo<K, UK>): WithKeyValue<Tp, K, V>['keyMapValues'];

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key to look for
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'])
m.getValues(1).toArray() // => ['a']
m.getValues(10).toArray() // => []

Overrides

VariantMultiMapBase.getValues

hasEntry

Returns true if the given key has the given value as one of its values in the collection.

Definition

hasEntry<UK = K>(key: RelatedTo<K, UK>, value: V): boolean;

Type parameters

NameDefaultDescription
UKK

Parameters

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

Overrides

VariantMultiMapBase.hasEntry

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 = HashMultiMapHashValue.of([1, 'a'], [2, 'b'])
m.hasKey(2) // => true
m.hasKey(3) // => false

Overrides

VariantMultiMapBase.hasKey

modifyAt

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

Definition

modifyAt(atKey: K, options: {
    ifNew?: OptLazy<StreamSource<V>>;
    ifExists?: ((currentValues: WithKeyValue<Tp, K, V>['keyMapValuesNonEmpty']) => StreamSource<V>) | StreamSource<V>;
  }): WithKeyValue<Tp, K, V>['normal'];

Parameters

NameTypeDescription
atKeyKthe key at which to modify the collection
options{
    ifNew?: OptLazy<StreamSource<V>>;
    ifExists?: ((currentValues: WithKeyValue<Tp, K, V>['keyMapValuesNonEmpty']) => StreamSource<V>) | StreamSource<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 new values. If a function returning the token argument is given, no new entry is created.
- ifExists: (optional) if given atKey exists in the collection, this function is called with the current values to return new values. As a second argument, a remove token is given. If the function returns this token, the current entry is removed.
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'])
m.modifyAt(3, { ifNew: ['c', 'd'] }).toArray()
// => [[1, 'a'], [2, 'b'], [3, 'c'], [3, 'd']]
m.modifyAt(3, { ifNew: () => 1 < 2 ? [] : ['c'] }).toArray()
// => [[1, 'a'], [2, 'b']]
m.modifyAt(2, { ifExists: () => ['c'] }).toArray()
// => [[1, 'a'], [2, 'c']]
m.modifyAt(2, { ifExists: (v) => v.add('d') }).toArray()
// => [[1, 'a'], [2, 'c'], [2, 'd']]
m.modifyAt(2, { ifExists: (v) => v.has('a') ? v : [] }).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: HashMultiMapHashValue<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

VariantMultiMapBase.nonEmpty

removeEntries

Returns the collection where given entries are removed.

Definition

removeEntries<UK = K, UV = V>(entries: StreamSource<[RelatedTo<K, UK>, RelatedTo<V, UV>]>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

NameDefaultDescription
UKK
UVV

Parameters

NameTypeDescription
entriesStreamSource<[RelatedTo<K, UK>, RelatedTo<V, UV>]>a StreamSource containing key-value entries to remove
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c'])
m.removeEntries([[2, 'b'], [1, 'd']]).toArray() // => [[1, 'a'], [1, 'c']]
m.removeEntries([2, 'q']).toArray() // => [[1, 'a'], [2, 'b'], [1, 'c']]
m.removeEntries(3) === m // true
note

guarantees same object reference if the key is not present

Overrides

VariantMultiMapBase.removeEntries

removeEntry

Returns the collection where given value if removed from the values associated with given key.

Definition

removeEntry<UK = K, UV = V>(key: RelatedTo<K, UK>, value: RelatedTo<V, UV>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

NameDefaultDescription
UKK
UVV

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key of the entry to remove
valueRelatedTo<V, UV>the value of the entry to remove
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c'])
m.removeEntry(2, 'b').toArray() // => [[1, 'a'], [1, 'c']]
m.removeEntry(2, 'q').toArray() // => [[1, 'a'], [2, 'b'], [1, 'c']]
m.removeEntry(3, 'a') === m // true
note

guarantees same object reference if the key is not present

Overrides

VariantMultiMapBase.removeEntry

removeKey

Returns the collection where the values associated with given key are removed.

Definition

removeKey<UK = K>(key: RelatedTo<K, UK>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keyRelatedTo<K, UK>the key of the entries to remove
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c'])
m.removeKey(2).toArray() // => [[1, 'a'], [1, 'c']]
m.removeKey(3) === m // true
note

guarantees same object reference if the key is not present

Overrides

VariantMultiMapBase.removeKey

removeKeyAndGet

Returns a tuple containing the collection of which the given key is removed, and the values that are 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'],
    WithKeyValue<Tp, K, V>['keyMapValuesNonEmpty']
  ] | undefined;

Type parameters

NameDefaultDescription
UKK

Parameters

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

Overrides

VariantMultiMapBase.removeKeyAndGet

removeKeys

Returns the collection where the values associated with given keys are removed.

Definition

removeKeys<UK = K>(keys: StreamSource<RelatedTo<K, UK>>): WithKeyValue<Tp, K, V>['normal'];

Type parameters

NameDefaultDescription
UKK

Parameters

NameTypeDescription
keysStreamSource<RelatedTo<K, UK>>a StreamSource of keys to remove
example
const m = HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c'])
m.removeKeys([2, 10]).toArray() // => [[1, 'a'], [1, 'c']]
m.removeKeys([10, 11]) === m // true
note

guarantees same object reference if the key is not present

Overrides

VariantMultiMapBase.removeKeys

setValues

Returns the collection where given key has the given values associated with it.

Definitions

setValues(key: K, values: StreamSource.NonEmpty<V>): WithKeyValue<Tp, K, V>['nonEmpty'];

setValues(key: K, values: StreamSource<V>): WithKeyValue<Tp, K, V>['normal'];

Parameters

NameTypeDescription
keyKthe key for which to set the values
valuesStreamSource.NonEmpty<V>the values to set for the key
example
HashMultiMapHashValue.of([1, 'a'], [2, 'b']).setValues(1, ['d', 'e']).toArray()
// => [[1, 'd'], [1, 'e'], [2, 'b']]

stream

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

Definition

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

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

Overrides

VariantMultiMapBase.stream

streamKeys

Returns a Stream containing all keys of this collection.

Definition

streamKeys(): Stream<K>;

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

Overrides

VariantMultiMapBase.streamKeys

streamValues

Returns a Stream containing all values of this collection.

Definition

streamValues(): Stream<V>;

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

Overrides

VariantMultiMapBase.streamValues

toArray

Returns an array containing all entries in this collection.

Definition

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

example
HashMultiMapHashValue.of([1, 'a'], [2, 'b'], [1, 'c']).toArray()   // => [[1, 'a'], [1, 'c'], [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

VariantMultiMapBase.toArray

toBuilder

Returns a builder object containing the entries of this collection.

Definition

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

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

toJSON

Returns a JSON representation of this collection.

Definition

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

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

Overrides

VariantMultiMapBase.toJSON

toString

Returns a string representation of this collection.

Definition

toString(): string;

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

Overrides

VariantMultiMapBase.toString