A Supplementary Collections Module for Ceylon.

This module was inspired by and adapted from Google Guava under the Apache License Version 2.0.

Currently implemented types are:

  • ArrayListMultimap: a mutable Collection<Key->Item> and Correspondence from Key to MutableList<Item> that supports deterministic iteration order for both keys and items.

  • LinkedListMultimap: a mutable Collection<Key->Item> and Correspondence from Key to MutableList<Item> that supports deterministic iteration order for both keys and items.

  • HashMultimap: a mutable Collection<Key->Item> and Correspondence from Key to MutableSet<Item> that does not store duplicate key->item entries.

Packages
com.vasileff.ceylon.structures
Dependencies
ceylon.collection1.3.3
Interfaces
ListMultimapshared ListMultimap<Key,out Item>
given Key satisfies Object
ListMultimapMutatorshared ListMultimapMutator<Key,in Item>
given Key satisfies Object
Multimapshared Multimap<Key,out Item>
given Key satisfies Object

A collection that maps keys to values, similar to Map, but in which each key may be associated with multiple values. You can visualize the contents of a multimap either as a map from keys to nonempty collections of values:

  • a → 1, 2
  • b → 3

… or as a single “flattened” collection of key-value pairs:

  • a → 1
  • a → 2
  • b → 3

Important: although the first interpretation resembles how most multimaps are implemented, the design of the Multimap API is based on the second form. So, using the multimap shown above as an example, the Multimap.size is 3, not 2, and the Multimap.items collection is { 1, 2, 3 }, not { {1, 2}, {3} }. For those times when the first style is more useful, use the multimap's Multimap.asMap view (or create a Map<K, Collection<I>> in the first place).

MultimapMutatorshared MultimapMutator<Key,in Item>
given Key satisfies Object
MutableListMultimapshared MutableListMultimap<Key,Item>
given Key satisfies Object
MutableMultimapshared MutableMultimap<Key,Item>
given Key satisfies Object
MutableSetMultimapshared MutableSetMultimap<Key,Item>
given Key satisfies Object
given Item satisfies Object
SetMultimapshared SetMultimap<Key,out Item>
given Key satisfies Object
given Item satisfies Object
SetMultimapMutatorshared SetMultimapMutator<Key,in Item>
given Key satisfies Object
given Item satisfies Object
Classes
ArrayListMultimapshared ArrayListMultimap<Key,Item>
given Key satisfies Object

Implementation of Multimap that uses an ArrayList to store the items for a given key. A HashMap associates each key with an ArrayList of items.

When iterating through the collections supplied by this class, the ordering of items for a given key agrees with the order in which the items were added.

This multimap allows duplicate key-item pairs. After adding a new key-item pair equal to an existing key-item pair, the ArrayListMultimap will contain entries for both the new item and the old item.

HashMultimapshared HashMultimap<Key,Item>
given Key satisfies Object
given Item satisfies Object

Implementation of Multimap using hash tables.

The multimap does not store duplicate key->item pairs. Adding a new key->item pair equal to an existing key->item pair has no effect.

Keys and items may be null.

LinkedListMultimapshared LinkedListMultimap<Key,Item>
given Key satisfies Object

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