3f:null 40:["$","title",null,{"children":"MultiMap | Riley | Observable"}] 46:T1927,htl.html`

`new ${MultiMap.name}(entries, container = ${JSON.stringify(Set.name)})`

All arguments are optional. If provided, entries must be an iterable of entries, where an entry is an iterable such that the first item is the key, and the rest are the values. If provided, container must be ${[Set, Array].flatMap((cls, i, {length: I}) => { let e = htl.html`${JSON.stringify(cls.name)}`; if (I == 2) { if (i == 0) { return [e, " or "]; } return [e]; } switch (I - i) { case 1: // last item return [e]; case 2: // penultimate item return [e, ", or "]; default: return [e, ", "]; } })}, or it must be a container definition. This argument specifies the implementation of the internal list of values and how it behaves.

instance methods

The methods are designed to function similarly to those of ${Map.name}, but these accept a few more optional arguments.

`.${MultiMap.prototype.get.name}(key)`

This returns an iterable of the values associated with key key. An iterable is always returned, even if it is empty.

`.${MultiMap.prototype.set.name}(key, …values)`

This adds every element in values to the list associated with key key.

`.${MultiMap.prototype.has.name}(key)`

This returns whether any values are associated with key key.

`.${MultiMap.prototype.has.name}(key, value)`

This returns whether the list associated with key key contains value. If there are no values associated with that key, false is returned.

`.${MultiMap.prototype.delete.name}(key)`

This deletes all values associated with key key.

`.${MultiMap.prototype.clear.name}()`

This clears all keys and values from this ${MultiMap.name} instance.

`.${MultiMap.prototype.clear.name}(key, …values)`

Each element in values is deleted from the list associated with key key, if it exists. Whether any of the values still remain depends on the container implementation.

`.${MultiMap.prototype.entries.name}(flat = false)`

This returns an iterable of the entries in this ${MultiMap.name} instance. If flat is falsy, then each entry is an iterable of exactly two elements: the key and the associated list of values. Otherwise, each entry is an iterable of at least two elements: the key followed by all the associated values.

`.${MultiMap.prototype.keys.name}()`

This is inherited from ${Map.name}.prototype.${Map.prototype.keys.name}.

`.${MultiMap.prototype.values.name}(flat = false)`

If flat is falsy, an iterable of every list of values is returned. Otherwise, an iterable of every value is returned.

`.${MultiMap.prototype.forEach.name}((values, key, map) => {…}, this)`

This behaves identically to ${Map.name}.prototype.${Map.prototype.forEach.name}, except values is a clone of each list; this is done to prevent the lists from being mutated directly.

instance properties

`.size`

This is the number of keys with values.

`.area`

This is the total number of values stored across all keys.

custom container

A container is described by a set of functions for manipulating it. Except where otherwise noted, all methods are required to make a valid container.

`.new(…values)`

This constructs and returns a new container, already holding the elements in values.

`.add(value)`

This adds value to the container this.

`.delete(value)`

This deletes (at least one instance of) value from the container this.

`.has(value)`

This returns whether container this has the value value.

`.clear()`

This removes all values from container this. The container’s size should end at zero.

`.items()`

This returns an iterable of all of the values in container this. This is optional if the container object is itself iterable.

`.size()`

This returns the number of values stored in container this.

`.clone()`

This returns a new container with the same values as container this. This method is optional; if left out, a method will be constructed using new and items.

` // clear, items, size, clone47:T18fa,class MultiMap extends Map { #container; #contNew; #contAdd; #contDelete; #contHas; #contClear; #contItems; #contSize; #contClone; static #contArray = Object.freeze({ "new": function newArray(...items) { return items; }, add: Array.prototype.push, delete(item) { let i = this.indexOf(item); if (i >= 0) { return this.splice(i, 1)?.[0]; } }, has: Array.prototype.includes, clear() { this.length = 0; }, items: Array.prototype[Symbol.iterator], size() { return this.length; }, clone() { return [...this]; } }); static #contSet = Object.freeze({ "new": function newSet(...items) { return new Set(items); }, add: Set.prototype.add, delete: Set.prototype.delete, has: Set.prototype.has, clear: Set.prototype.clear, items: Set.prototype[Symbol.iterator], size() { return this.size; }, clone() { return new Set(this); } }); static #fallbackIterator = function* iterate(container) { yield* container; } static #containerMissing = function lacking(thing) { throw new SyntaxError(`container missing ${JSON.stringify(thing)} method`); } static #empty = Object.freeze(Object.preventExtensions([])); static #getEntries = function* entries(items, clone) { for (let [key, values] of items) { yield [key, clone.call(values)]; } } static #getEntriesFlat = function* entriesFlat(items, iter = MultiMap.#fallbackIterator) { if (iter === MultiMap.#fallbackIterator) { for (let [key, values] of items) { yield [key, ...values]; } } else { for (let [key, values] of items) { yield [key, ...iter.call(values)]; } } } static #getValues = function* values(items, clone) { for (let v of items) { yield clone.call(v); } } static #getValuesFlat = function* valuesFlat(lists, iter = MultiMap.#fallbackIterator) { if (iter === MultiMap.#fallbackIterator) { for (let list of lists) { yield* list; } } else { for (let list of lists) { yield* iter.call(list); } } } static { Object.defineProperty(MultiMap, "containers", { enumerable: true, value: Object.create(null, { [Array.name]: {value: MultiMap.#contArray, enumerable: true}, [Set.name]: {value: MultiMap.#contSet, enumerable: true} }) }); } constructor(values, container = "Set") { super(); this.#container = container; if (container !== null && (typeof container === "string" || (typeof container === "object" && container instanceof String))) { this.#container = container = String(container).toLowerCase(); switch (container) { case "set": container = MultiMap.#contSet; break; case "array": container = MultiMap.#contArray; break; default: throw new TypeError(`invalid container type: ${JSON.stringify(container)}`); } } this.#contNew = container.new ?? MultiMap.#containerMissing("new"); this.#contAdd = container.add ?? MultiMap.#containerMissing("add"); this.#contDelete = container.delete ?? MultiMap.#containerMissing("delete"); this.#contHas = container.has ?? MultiMap.#containerMissing("has"); this.#contClear = container.clear ?? MultiMap.#containerMissing("clear"); this.#contItems = container.items ?? MultiMap.#fallbackIterator ?? MultiMap.#containerMissing("items"); this.#contSize = container.size ?? MultiMap.#containerMissing("size"); this.#contClone = container.clone ?? this.#contItems === MultiMap.#fallbackIterator ? (make => function clone() { return make(...this); })(this.#contNew) : ((make, iter) => function clone() { return make(...iter.call(this)); })(this.#contNew, this.#contItems); if (values !== undefined) { for (let [key, ...value] of values) { this.set(key, ...value); } } } set(key, ...values) { let list = super.get(key); if (list) { this.#contAdd.call(list, ...values); } else { super.set(key, this.#contNew.call(null, ...values)); } } get(key) { let values = super.get(key); if (values) { return this.#contItems.call(values); } return MultiMap.#empty; } delete(...keys) { for (let key of keys) { let list = super.get(key); if (list) { this.#contClear.call(list); super.delete(key); } } return this.size; } has(key, value) { switch (arguments.length) { case 0: throw new SyntaxError("no arguments provided"); case 1: // delete all values with key return super.has(key); case 2: { // delete 0–1 values at key let values = this.get(key); if (values) { return this.#contHas.call(values, value); } return false; } default: throw new SyntaxError(`${arguments.length - 2} too many argument${arguments.length == 3 ? "" : "s"} provided`); } } clear() { switch (arguments.length) { case 0: // clear everything for (let values of super.values()) { this.#contClear.call(values); } return super.clear(); case 1: // do nothing (delete 0 values from key) return this.size; default: { // delete provided values from key let [key, ...values] = arguments; let list = super.get(key); if (list) { for (let value of values) { this.#contDelete.call(list, value); } } } } } entries(flat = false) { return (flat ? MultiMap.#getEntriesFlat(super.entries(), this.#contItems) : MultiMap.#getEntries(super.entries(), this.#contClone) ); } values(flat = false) { return (flat ? MultiMap.#getValuesFlat(super.values(), this.#contItems) : MultiMap.#getValues(super.values(), this.#contClone) ); } forEach(f, thisArg) { if (typeof f !== "function") { throw new TypeError("no function provided"); } let clone = this.#contClone; return super.forEach((list, ...args) => f.call(thisArg, clone.call(list), ...args)); } get size() { let total = 0; let getSize = this.#contSize; for (let list of super.values()) { total += getSize.call(list); } return total; } }48:[] 44:{"id":"9f0ed4a60806d8b9","slug":"multi-map","title":"MultiMap","thumbnail":"41f4f9acf9ed0f1d5bacd74877278243ed032c0f22df398e795e09f6e0bc7847","access_level":"public","create_time":"$D2023-06-27T23:36:11.143Z","update_time":"$D2023-06-29T16:06:27.693Z","view_time":null,"first_public_time":"$D2023-06-27T23:36:11.143Z","has_unpublished_edits":null,"fork":false,"stars":2,"starred":false,"owner":{"type":"team","id":"d2b7afa3a61febdf","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":"starter_2024","bio":"I enjoy spreadsheets and JavaScript way too much.","following":false},"version":164,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"817e538440b46e8a","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":null,"bio":"I enjoy spreadsheets and JavaScript way too much.\n\ntrust://Riley.science!","following":false}],"members":[{"type":"individual","id":"817e538440b46e8a","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":1,"collection":{"id":"f315bea3064cd044","slug":"imports","title":"importables","owner":{"id":"d2b7afa3a61febdf","login":"rmw4269","name":"Riley"}},"type":"notebook","body":{"titling":"auto","title":"MultiMap","cells":[{"id":0,"value":"htl.html`\n

`${MultiMap.name}`

This class represents a ${Map.name}, where each key can have multiple values. These internal value lists can be implemented as ${Set.name}s, ${Array.name}s, or any custom containers. There is no distinction between a key missing from the map and a key with no associated values.

\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":151,"value":"import {${MultiMap.name}} from ${JSON.stringify(`@${location.hostname.split(\".\").shift()}/multi-map`)}","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":49,"value":"$46","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":124,"value":"exampleMap = new MultiMap([\n [\"A\", 0],\n [\"B\", 0, 1],\n [\"C\", 0, 1, 2],\n [\"D\", 0, 1, 2, 3]\n])","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":7,"value":"{\n return exampleMap.size;\n let items = [];\n exampleMap.forEach((value, key, map) => items.push({key, value, map, val: Map.prototype.get.call(exampleMap, key)}));\n return items.every(({value, val}) => value === val);\n return items;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":36,"value":"MultiMap.containers","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":5,"value":"$47","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":54,"value":"","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"}],"files":"$W48","stdlib":"1"}} 45:"$44:body"