A collection which maps keys to items, where a key can map to at most one item. Each such mapping may be represented by an Entry. Thus, each distinct key occurs in at most one entry. Two non-identical keys are considered distinct only if they are unequal, according to their own definition of value equality.

A Map is a Collection of its Entrys, and a Correspondence from keys to items.

A new Map may be obtained by calling the function map().

value settings = map { "lang"->"en_AU", "loc"->"ES" };

The emptyMap is a Map with no entries.

The presence of an entry in a map may be tested using the in operator:

if ("lang"->"en_AU" in settings) { ... }

The entries of the map may be iterated using for:

for (key->item in settings) { ... }

The item for a key may be obtained using the item operator:

String lang = settings["lang"] else "en_US";

An implementation of Map may compare keys for equality using Object.equals() or Comparable.compare().

no type hierarchy

coalescedMapSource Codeshared default Map<Key,Item&Object> coalescedMap

A map with every entry of this map whose item is non-null.

Since 1.2.0
distinctSource Codeshared actual {<Key->Item>*} distinct

A stream that produces every element produced by this stream exactly once. Duplicate elements of this stream are eliminated. Two elements are considered distinct unless they are both null, or unless they are both non-null and equal.

For example:

String("hello world".distinct)

is the string "helo wrd".

This is a lazy operation and the resulting stream reflects changes to this stream.

hashSource Codeshared actual default 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 Object.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 Object.hash
itemsSource Codeshared default Collection<Item> items

A Collection containing the items stored in this map. An element can be stored under more than one key in the map, and so it can occur more than once in the resulting collection.

Since 1.1.0
keysSource Codeshared actual default Collection<Key> keys

A Collection containing the keys of this map.

Inherited Attributes
Attributes inherited from: Object
Attributes inherited from: Collection<Element>
Attributes inherited from: Correspondence<Key,Item>
Attributes inherited from: Iterable<Element,Absent>
cloneSource Codeshared actual default Map<Key,Item> clone()

A shallow copy of this map, that is, a map with the same entries as this map, which do not change if the entries in this map change.

containsSource Codeshared actual default Boolean contains(Object entry)

Determines if the given value is an Entry belonging to this map.

See also defines()
Refines Collection.contains ultimately refines Category.contains
defaultNullElementsSource Codeshared actual {<Key->Item>*} defaultNullElements<Default>(Default defaultValue)
given Default satisfies Object

Produces a stream containing the elements of this stream, in the order in which they occur in this stream, after replacing every null element in the stream with the given default value. The value null does not ocur in the resulting stream.

For example, the expression

{ "123", "abc", "456" }.map(parseInteger).defaultNullElements(0)

results in the stream { 123, 0, 456 }.

defaultNullItemsSource Codeshared default Map<Key,Item&Object|Default> defaultNullItems<Default>(Default defaultValue)
given Default satisfies Object

Produces a map containing the elements of this map, after replacing every null item in the map with the given default value. The item null does not ocur in the resulting map.

  • defaultValue

    A default value that replaces null items.

See also coalescedMap
Since 1.2.0
definesSource Codeshared formal Boolean defines(Object key)

Determines if there is an entry in this map with the given key.

See also contains()
equalsSource Codeshared actual default Boolean equals(Object that)

Two maps are considered equal iff they have the same entry sets. The entry set of a Map is the set of Entrys belonging to the map. Therefore, the maps are equal iff they have same set of keys, and for every key in the key set, the maps have equal items.

filterKeysSource Codeshared default Map<Key,Item> filterKeys(Boolean filtering(Key key))

Produces a map by applying a filtering() function to the keys of this map. This is a lazy operation, returning a view of this map.

  • filtering

    The predicate function that filters the keys of this map, determining if there is a corresponding entry in the resulting map.

Since 1.1.0
getSource Codeshared formal Item? get(Object key)

Returns the item of the entry with the given key, or null if there is no entry with the given key in this map.

getOrDefaultSource Codeshared default Item|Default getOrDefault<Default>(Object key, Default default)

Returns the item of the entry with the given key, or the given default if there is no entry with the given key in this map.

For maps with non-null items, the expression:

map.getOrDefault(key, def)

is equivalent to this common idiom:

map[key] else def

However, when the map has null items, getOrDefault() will preserve them.

Note that high-quality implementations of Map should refine this default implementation.

See also get()
Since 1.2.0
inverseSource Codeshared default Map<Item&Object,[Key+]> inverse()

Invert this map, producing a new immutable map where the keys of the new map are the non-null items of this map, and each item of the new map is a nonempty sequence of keys of this map.

For example, the expression:

{ "fee", "fi", "fo", "fum", "foo" }

produces the map { 2->["fo", "fi"], 3->[ "fum", "fee", "foo"] }.

The order of keys in the key sequences is not defined and should not be relied upon.

This is an eager operation, and the resulting map does not reflect changes to this map.

Since 1.2.0
mapItemsSource Codeshared default Map<Key,Result> mapItems<Result>(Result mapping(Key key, Item item))
given Result satisfies Object

Produces a map with the same keys as this map. For every key, the item is the result of applying the given transformation function to its associated item in this map. This is a lazy operation, returning a view of this map.

  • mapping

    The function that transforms a key/item pair of this map, producing the item of the resulting map.

patchSource Codeshared default Map<Key|OtherKey,Item|OtherItem> patch<OtherKey, OtherItem>(Map<OtherKey,OtherItem> other)
given OtherKey satisfies Object

Produces a map whose keys are the union of the keys of this map, with the keys of the given map. For any given key in the resulting map, its associated item is the item associated with the key in the given map, if any, or the item associated with the key in this map otherwise.

That is, for any key in the resulting patched map:

map.patch(other)[key] == other.getOrDefault(key, map[key])

This is a lazy operation producing a view of this map and the given map.

Since 1.1.0
Inherited Methods
Methods inherited from: Object
Methods inherited from: Category<Element>
Methods inherited from: Collection<Element>
Methods inherited from: Correspondence<Key,Item>
Methods inherited from: Iterable<Element,Absent>