Class MultiMap

data_structures/unstable_multimap.ts:60–791

 * ```
 */
export class MultiMap<K, V> implements Iterable<[K, V]> {
  #map = new Map<K, V[]>();
  #valueCount = 0;

  /**
   * Creates a new instance.
   *
   * @experimental **UNSTABLE**: New API, yet to be vetted.
   *
   * @param entries An iterable of key-value pairs for the initial entries.
   * Duplicate values for the same key are preserved in insertion order.
   *
   * @example Creating an empty map
   * ```ts
   * import { MultiMap } from "@std/data-structures/unstable-multimap";
   * import { assertEquals } from "@std/assert";
   *
   * const map = new MultiMap<string, number>();
   * assertEquals(map.size, 0);
   * ```
   *
   * @example Creating a map from an iterable
   * ```ts
   * import { MultiMap } from "@std/data-structures/unstable-multimap";
   * import { assertEquals } from "@std/assert";
   *
   * const map = new MultiMap([["a", 1], ["a", 2], ["b", 3]]);
   * assertEquals(map.get("a"), [1, 2]);
   * ```
   */
  constructor(entries?: Iterable<readonly [K, V]> | null) {
    if (entries) {
      for (const [key, value] of entries) {
        this.add(key, value);
      }
    }
  }

  /**
   * The number of distinct keys in the map.
   *
   * @experimental **UNSTABLE**: New API, yet to be vetted.
   *
   * @returns The number of distinct keys in the map.
   *
   * @example Usage
   * ```ts
   * import { MultiMap } from "@std/data-structures/unstable-multimap";
   * import { assertEquals } from "@std/assert";
   *
   * const map = new MultiMap([["a", 1], ["a", 2], ["b", 3]]);
   * assertEquals(map.size, 2);
   * ```
   */
  get size(): number {
    return this.#map.size;
  }