Skip to main content

interface MultiSet<T>

A type-invariant immutable MultiSet of value type T. In the MultiSet, each value can occur multiple times. See the MultiSet documentation and the MultiSet API documentation

Companion namespace: MultiSet

Extends: MultiSetBase<T,Tp>

Implemented by: MultiSet.NonEmpty<T>

Type parameters

NameDescription
Tthe value type

Properties

context

Returns the context associated to this collection instance.

Definition

readonly context: WithElem<Tp, T>['context'];

Overrides

MultiSetBase.context

countMap

Returns the Map representation of this collection.

Definition

readonly countMap: WithElem<Tp, T>['countMap'];

example
const m = HashMultiSet.of(1, 2, 2)
const map: HashMap.NonEmpty<number, number> = m.countMap

Overrides

VariantMultiSetBase.countMap

isEmpty

Returns true if the collection is empty.

Definition

readonly isEmpty: boolean;

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

Overrides

VariantMultiSetBase.isEmpty

size

Returns the number of values in the collection.

Definition

readonly size: number;

example
HashMultiSet.of(1, 2).size         // => 2
HashMultiSet.of(1, 2, 2).size // => 3

Overrides

VariantMultiSetBase.size

sizeDistinct

Returns the number of distinct values in the collection.

Definition

readonly sizeDistinct: number;

example
HashMultiSet.of(1, 2).sizeDistinct       // => 2
HashMultiSet.of(1, 2, 2).sizeDistinct // => 2

Overrides

VariantMultiSetBase.sizeDistinct

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 amount times.

Definitions

add(value: T): WithElem<Tp, T>['nonEmpty'];

add(value: T, amount: number): WithElem<Tp, T>['normal'];

Parameters

NameTypeDescription
valueTthe value to add
example
HashMultiSet.of(1, 2).add(2).toArray()      // => [1, 2, 2]
HashMultiSet.of(1, 2).add(3, 2).toArray() // => [1, 2, 3, 3]
note

amount < 0 will be normalized to 0

Overrides

MultiSetBase.add

addAll

Returns the collection with the values in values added.

Definitions

addAll(values: StreamSource.NonEmpty<T>): WithElem<Tp, T>['nonEmpty'];

addAll(values: StreamSource<T>): WithElem<Tp, T>['normal'];

Parameters

NameTypeDescription
valuesStreamSource.NonEmpty<T>a StreamSource containing values to add
example
HashMultiSet.of(1, 2).addAll([2, 3]).toArray()   // => [1, 2, 2, 3]

Overrides

MultiSetBase.addAll

addEntries

Returns the collection where for every entry in entries consisting of a tuple of a value and an amount, that value is added amount times.

Definition

addEntries(entries: StreamSource<readonly [T, number]>): WithElem<Tp, T>['normal'];

Parameters

NameTypeDescription
entriesStreamSource<readonly [T, number]>a StreamSource containing tuples that contain a value and an amount
example
HashMultiSet.of(1, 2).addEntries([[2, 2], [3, 2]]).toArray()
// => [1, 2, 2, 2, 3, 3]

Overrides

MultiSetBase.addEntries

assumeNonEmpty

Returns the collection as a .NonEmpty type

Definition

assumeNonEmpty(): WithElem<Tp, T>['nonEmpty'];

throws

RimbuError.EmptyCollectionAssumedNonEmptyError if the collection is empty

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

returns reference to this collection

Overrides

VariantMultiSetBase.assumeNonEmpty

count

Returns the amount of occurrances of the given value in the collection.

Definition

count<U = T>(value: RelatedTo<T, U>): number;

Type parameters

NameDefaultDescription
UT

Parameters

NameTypeDescription
valueRelatedTo<T, U>the value to look for
example
const m = HashMultiSet.of(1, 2, 2)
m.count(5) // => 0
m.count(2) // => 2

Overrides

VariantMultiSetBase.count

filterEntries

Returns the collection containing only those values for which the given pred function returns true.

Definitions

filterEntries<TF extends T>(pred: (entry: readonly [T, number], index: number) => entry is [TF, number], options?: {
    negate?: false | undefined;
  }): WithElem<Tp, TF>['normal'];

filterEntries<TF extends T>(pred: (entry: readonly [T, number], index: number) => entry is [TF, number], options: {
    negate: true;
  }): WithElem<Tp, Exclude<T, TF>>['normal'];

filterEntries(pred: (entry: readonly [T, number], index: number) => boolean, options?: {
    negate?: boolean;
  }): WithElem<Tp, T>['normal'];

Type parameters

NameConstraintsDescription
TFT

Parameters

NameTypeDescription
pred(entry: readonly [T, number], index: number) => entry is [TF, number]a predicate function receiving:
- entry: the next entry consisting of the value and its count
- index: the entry index
- halt: a function that, when called, ensures no next entries are passed
options{
    negate?: false | undefined;
  }
(optional) an object containing the following properties:
- negate: (default: false) when true will negate the predicate
note

if the predicate is a type guard, the return type is automatically inferred

example
HashMultiSet.of(1, 2, 2, 3)
.filterEntries(entry => entry[1] > 1)
.toArray()
// => [[2, 2]]

Overrides

VariantMultiSetBase.filterEntries

forEach

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

Definition

forEach(f: (value: T, index: number, halt: () => void) => void, options?: {
    state?: TraverseState;
  }): void;

Parameters

NameTypeDescription
f(value: T, index: number, halt: () => void) => voidthe function to perform for each value, receiving:
- value: the next value
- index: the index of the value
- halt: a function that, if called, ensures that no new values are passed
options{
    state?: TraverseState;
  }
(optional) an object containing the following properties:
- state: (optional) the traversal state
example
HashMultiSet.of(1, 2, 2, 3).forEach((entry, i, halt) => {
console.log(entry)
if (i >= 1) halt()
})
// => logs [1, 1] [2, 2]

Overrides

VariantMultiSetBase.forEach

has

Returns true if the given value exists in the collection.

Definition

has<U = T>(value: RelatedTo<T, U>): boolean;

Type parameters

NameDefaultDescription
UT

Parameters

NameTypeDescription
valueRelatedTo<T, U>the value to look for
example
const m = HashMultiSet.of(1, 2, 2)
m.has(5) // => false
m.has(2) // => true

Overrides

VariantMultiSetBase.has

modifyCount

Returns the collection where the count of the given value is modified according to the given update function.

Definition

modifyCount(value: T, update: (currentCount: number) => number): WithElem<Tp, T>['normal'];

Parameters

NameTypeDescription
valueTthe value of which to modify the count
update(currentCount: number) => numbera function taking the current count and returning a new count.
note

if the given value does not exists, the update function is called with 0. @note if the result of update is <= 0, the value will be removed (or not added)

example
const m = HashMultiSet.of(1, 2, 2)
m.modifyCount(1, v => v + 1).toArray() // => [1, 1, 2, 2]
m.modifyCount(3, v => v + 1).toArray() // => [1, 2, 2, 3]

Overrides

MultiSetBase.modifyCount

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 WithElem<Tp, T>['nonEmpty'];

example
const m: HashMultiSet<number> = HashMultiSet.of(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

VariantMultiSetBase.nonEmpty

remove

Returns the collection where the given amount (default: 'ALL') of the given value are removed.

Definition

remove<U = T>(value: RelatedTo<T, U>, options?: {
    amount?: number | 'ALL';
  }): WithElem<Tp, T>['normal'];

Type parameters

NameDefaultDescription
UT

Parameters

NameTypeDescription
valueRelatedTo<T, U>the value to remove
options{
    amount?: number | 'ALL';
  }
(optional) an object containing the following properties:
- amount: (default: 'ALL') the amount of values to remove, or 'ALL' to remove all values.
example
const m = HashMultiSet.of(1, 2, 2)
m.remove(5).toArray() // => [1, 2, 2]
m.remove(2).toArray() // => [1]
m.remove(2, 1).toArray() // => [1, 2]

Overrides

VariantMultiSetBase.remove

removeAllEvery

Returns the collection where for every value from given values StreamSource, all values in the collection are removed.

Definition

removeAllEvery<U = T>(values: StreamSource<RelatedTo<T, U>>): WithElem<Tp, T>['normal'];

Type parameters

NameDefaultDescription
UT

Parameters

NameTypeDescription
valuesStreamSource<RelatedTo<T, U>>a StreamSource containing values to remove.
example
const m = HashMultiSet.of(1, 2, 2)
m.removeAllEvery([5, 6]).toArray() // => [1, 2, 2]
m.removeAllEvery([2, 3]).toArray() // => [1]

Overrides

VariantMultiSetBase.removeAllEvery

removeAllSingle

Returns the collection where every single value from given values StreamSource is removed.

Definition

removeAllSingle<U = T>(values: StreamSource<RelatedTo<T, U>>): WithElem<Tp, T>['normal'];

Type parameters

NameDefaultDescription
UT

Parameters

NameTypeDescription
valuesStreamSource<RelatedTo<T, U>>a StreamSource containing values to remove.
example
const m = HashMultiSet.of(1, 2, 2)
m.removeAllSingle([5, 6]).toArray() // => [1, 2, 2]
m.removeAllSingle([2, 3]).toArray() // => [1, 2]
m.removeAllSingle([2, 3, 2]).toArray() // => [1]

Overrides

VariantMultiSetBase.removeAllSingle

setCount

Returns the collection where the amount of values of value if set to amount.

Definition

setCount(value: T, amount: number): WithElem<Tp, T>['normal'];

Parameters

NameTypeDescription
valueTthe value of which to set the amount
amountnumberthe new amount of values
note

if amount <= 0, the value will be removed

example
const m = HashMultiSet.of(1, 2, 2)
m.setCount(1, 2).toArray() // => [1, 1, 2, 2]
m.setCount(2, 0).toArray() // => [1]

Overrides

MultiSetBase.setCount

stream

Returns a Stream containing all values of this collection.

Definition

stream(): Stream<T>;

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

Overrides

VariantMultiSetBase.stream

streamDistinct

Returns a Stream containing all distinct values of this collection.

Definition

streamDistinct(): Stream<T>;

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

Overrides

VariantMultiSetBase.streamDistinct

toArray

Returns an array containing all values in this collection.

Definition

toArray(): T[];

example
HashMultiSet.of(1, 2, 2).toArray()  // => [1, 2, 2]
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

VariantMultiSetBase.toArray

toBuilder

Returns a builder object containing the entries of this collection.

Definition

toBuilder(): WithElem<Tp, T>['builder'];

example
const builder: HashMultiSet.Builder<number>
= HashMultiSet.of(1, 2, 2).toBuilder()

Overrides

MultiSetBase.toBuilder

toJSON

Returns a JSON representation of this collection.

Definition

toJSON(): ToJSON<(readonly [T, number])[]>;

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

Overrides

VariantMultiSetBase.toJSON

toString

Returns a string representation of this collection.

Definition

toString(): string;

example
HashMultiSet.of(1, 2, 2).toString()  // => HashMultiSet(1, 2, 2)

Overrides

VariantMultiSetBase.toString