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

Name	Description
T	the 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

Name	Type	Description
value	T	the 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

Name	Type	Description
values	StreamSource.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

Name	Type	Description
entries	StreamSource<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

Name	Default	Description
U	T

Parameters

Name	Type	Description
value	RelatedTo<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

Name	Constraints	Description
TF	T

Parameters

Name	Type	Description
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

Name	Type	Description
f	(value: T, index: number, halt: () => void) => void	the 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

Name	Default	Description
U	T

Parameters

Name	Type	Description
value	RelatedTo<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

Name	Type	Description
value	T	the value of which to modify the count
update	(currentCount: number) => number	a 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

Name	Default	Description
U	T

Parameters

Name	Type	Description
value	RelatedTo<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

Name	Default	Description
U	T

Parameters

Name	Type	Description
values	StreamSource<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

Name	Default	Description
U	T

Parameters

Name	Type	Description
values	StreamSource<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

Name	Type	Description
value	T	the value of which to set the amount
amount	number	the 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