Collections

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 `Entry`s, 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 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()`.

See also `Entry`, `Iterable.map()`, `forKey()`, `forItem()`, `byItem()`, `byKey()`

no type hierarchy

- `Map`
  - `Collection`
    - `Iterable`
      - `Category`
  - `Correspondence`

- `Map`
  - `emptyMap`

Attributes
`coalescedMap` | Source Code `shared default Map<Key,Item&Object> coalescedMap` A map with every entry of this map whose item is non-null. See also `defaultNullItems()`
`distinct` | Source Code `shared 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. Refines `Iterable.distinct`
`hash` | Source Code `shared 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`. Because the `Integer` type is platform-dependent a compiler for a given platform is permitted to further manipulate the calculated hash for an object, and the resulting hash may differ between platforms. Refines `Object.hash`
`items` | Source Code `shared 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.
`keys` | Source Code `shared actual default Collection<Key> keys` A `Collection` containing the keys of this map. Refines `Correspondence.keys`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`
Attributes inherited from: `Collection<Element>` `empty`, `permutations`, `string`
Attributes inherited from: `Correspondence<Key,Item>` `keys`
Attributes inherited from: `Iterable<Element,Absent>` `coalesced`, `cycled`, `distinct`, `empty`, `exceptLast`, `first`, `indexed`, `last`, `paired`, `rest`, `size`, `string`

Methods
`clone` | Source Code `shared formal 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. Refines `Collection.clone`
`contains` | Source Code `shared 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`
`defaultNullElements` | Source Code `shared 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 }`. Refines `Iterable.defaultNullElements`
`defaultNullItems` | Source Code `shared 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. Parameters: `defaultValue` A default value that replaces `null` items. See also `coalescedMap`
`defines` | Source Code `shared formal Boolean defines(Object key)` Determines if there is an entry in this map with the given `key`. See also `contains()` Refines `Correspondence.defines`
`equals` | Source Code `shared 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 `Entry`s 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. Refines `Object.equals`
`filterKeys` | Source Code `shared 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. Parameters: `filtering` The predicate function that filters the keys of this map, determining if there is a corresponding entry in the resulting map.
`get` | Source Code `shared 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. See also `getOrDefault()` Refines `Correspondence.get`
`getOrDefault` | Source Code `shared 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()`
`inverse` | Source Code `shared 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" }
       .tabulate(String.size)
       .inverse()
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.
`mapItems` | Source Code `shared 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. Parameters: `mapping` The function that transforms a key/item pair of this map, producing the item of the resulting map.
`patch` | Source Code `shared 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.

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Collection<Element>` `clone()`, `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()`