An implementation of ListMultimap that supports deterministic iteration order for both keys and items. The iteration order is preserved across non-distinct key items. For example, for the following multimap definition:

value multimap = LinkedListMultimap<K, I>();
multimap.put(key1, foo);
multimap.put(key2, bar);
multimap.put(key1, baz);

… the iteration order for keyMultiset (TODO) is key1, key2, key1, and similarly for entries. Unlike LinkedHashMultimap (TODO), the iteration order is kept consistent between keys, entries and items. For example, calling:

multimap.remove(key1, foo);

changes the entries iteration order to key2=bar, key1=baz and the key iteration order to key2, key1.

The collections returned by keys and asMap iterate through the keys in the order they were first added to the multimap. Similarly, get(), removeAll(), and replaceItems() return collections that iterate through the items in the order they were added. The collections generated by entries, keyMultiset (TODO), and items iterate across the key->item mappings in the order they were added to the multimap.

no subtypes hierarchy

LinkedListMultimapshared LinkedListMultimap({<Key->Item>*} entries = [])
  • entries = []
asMapshared actual Map<Key,MutableList<Item>> asMap

Returns a view of this multimap as a Map from each distinct key to the nonempty collection of that key's associated values. Note that this.asMap.get(k) is equivalent to this.get(k) only when k is a key contained in the multimap; otherwise it returns null as opposed to an empty collection.

The returned map is a view of the underlying multimap.

Refines MutableListMultimap.asMap ultimately refines Multimap.asMap
entriesshared MutableList<Key->Item> entries
hashshared actual Integer hash

The hash value of the value, which allows the value to be an element of a hash-based set or key of a hash-based map. Implementations must respect the constraint that:

  • if x==y then x.hash==y.hash.

Therefore, a class which refines equals must also refine hash.

In general, hash values vary between platforms and between executions of the same program.

Note that when executing on a Java Virtual Machine, the 64-bit Integer value returned by an implementation of hash is truncated to a 32-bit integer value by taking the exclusive disjunction of the 32 lowest-order bits with the 32 highest-order bits, before returning the value to the caller.

Refines Identifiable.hash ultimately refines Object.hash
itemsshared actual List<Item> items

Returns a view collection containing the item from each key-item pair contained in this multimap, without collapsing duplicates (so items.size == size).

keysshared actual MutableSet<Key> keys

The Category of all keys for which a value is defined by this Correspondence.

Refines MutableListMultimap.keys ultimately refines Correspondence.keys
sizeshared actual Integer size

The number of elements returned by the iterator of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates.

Refines Multimap.size ultimately refines Iterable.size
Inherited Attributes
Attributes inherited from: Object
hash, string
Attributes inherited from: Collection<Element>
empty, permutations, string
Attributes inherited from: Correspondence<Key,Item>
Attributes inherited from: Iterable<Element,Absent>
coalesced, cycled, distinct, empty, exceptLast, first, indexed, last, paired, rest, size, string
Attributes inherited from: ListMultimap<Key,Item>
Attributes inherited from: ListMultimapMutator<Key,Item>
Attributes inherited from: Multimap<Key,Item>
Attributes inherited from: MultimapMutator<Key,Item>
Attributes inherited from: MutableListMultimap<Key,Item>
Attributes inherited from: MutableMultimap<Key,Item>
clearshared actual void clear()

Removes all key->item pairs from the multimap, leaving it Multimap.empty.

Refines MutableMultimap.clear ultimately refines MultimapMutator.clear
cloneshared actual ListMultimap<Key,Item> clone()

A shallow copy of this collection, that is, a collection with identical elements which does not change if this collection changes. If this collection is immutable, it is acceptable to return a reference to this collection. If this collection is mutable, a newly instantiated collection must be returned.

Refines ListMultimap.clone ultimately refines Collection.clone
definesshared actual Boolean defines(Key key)

Determines if there is a value defined for the given key.

Refines Multimap.defines ultimately refines Correspondence.defines
equalsshared actual Boolean equals(Object that)

Determine if two values are equal.

For any two non-null objects x and y, x.equals(y) may be written as:

x == y 

Implementations should respect the constraints that:

  • if x===y then x==y (reflexivity),
  • if x==y then y==x (symmetry),
  • if x==y and y==z then x==z (transitivity).

Furthermore it is recommended that implementations ensure that if x==y then x and y have the same concrete class.

A class which explicitly refines equals() is said to support value equality, and the equality operator == is considered much more meaningful for such classes than for a class which simply inherits the default implementation of identity equality from Identifiable.

Note that an implementation of equals() that always returns false does satisfy the constraints given above, as long as the class does not inherit Identifiable. Therefore, in very rare cases where there is no reasonable definition of value equality for a class, for example, function references (Callable), it is acceptable for equals() to be defined to return false for every argument.

Refines Identifiable.equals ultimately refines Object.equals
getshared actual MutableList<Item> get(Key key)

Returns the value defined for the given key, or null if there is no value defined for the given key.

For any instance c of Correspondence, c.get(key) may be written using the item operator:

Refines MutableListMultimap.get ultimately refines Correspondence.get
iteratorshared actual Iterator<Key->Item> iterator()

An iterator for the elements belonging to this stream.

If this is a nonempty stream with type {Element+}, the iterator must produce at least one element.

Refines Multimap.iterator ultimately refines Iterable.iterator
putshared actual Boolean put(Key key, Item item)

Stores a key->item pair in this multimap.

Some multimap implementations allow duplicate key->item pairs, in which case put always adds a new key->item pair and increases the multimap size by 1. Other implementations prohibit duplicates, and storing a key->item pair that's already in the multimap has no effect.

Returns true if the method increased the size of the multimap, or false if the multimap already contained the key->item pair and doesn't allow duplicates

Refines MutableMultimap.put ultimately refines MultimapMutator.put
removeshared actual Boolean remove(Key key, Item item)

Removes a single key->item pair with the key key and the item item from this multimap, if such exists. If multiple key->item pairs in the multimap fit this description, which one is removed is unspecified.

Returns true if the multimap changed

removeAllshared actual List<Item> removeAll(Key key)

Removes all items associated with the key key.

Once this method returns, key will not be mapped to any items, so it will not appear in keys, asMap, or any other views.

Returns the items that were removed (possibly empty). The returned collection may be modifiable, but updating it will have no effect on the multimap.

replaceItemsshared actual List<Item> replaceItems(Key key, {Item*} items)

Stores a collection of items with the same key, replacing any existing items for that key.

If items is empty, this is equivalent to removeAll(key).

Returns the collection of replaced items, or an empty collection if no items were previously associated with the key. The collection may be modifiable, but updating it will have no effect on the multimap.

Inherited Methods
Methods inherited from: Object
Methods inherited from: Category<Element>
contains, containsAny, containsEvery
Methods inherited from: Collection<Element>
clone, combinations, contains
Methods inherited from: Correspondence<Key,Item>
defines, definesAny, definesEvery, get, getAll
Methods inherited from: Iterable<Element,Absent>
any, by, chain, collect, contains, count, defaultNullElements, each, every, filter, find, findLast, flatMap, fold, follow, frequencies, getFromFirst, group, indexes, interpose, iterator, locate, locateLast, locations, longerThan, map, max, narrow, partition, product, reduce, repeat, scan, select, sequence, shorterThan, skip, skipWhile, sort, spread, summarize, tabulate, take, takeWhile
Methods inherited from: ListMultimap<Key,Item>
Methods inherited from: ListMultimapMutator<Key,Item>
Methods inherited from: Multimap<Key,Item>
Methods inherited from: MultimapMutator<Key,Item>
Methods inherited from: MutableListMultimap<Key,Item>
Methods inherited from: MutableMultimap<Key,Item>