In maps, types of both keys and values are user-defined. Key-based access to map entries enables various map-specific processing capabilities from getting a value by key to separate filtering of keys and values. On this page, we provide descriptions of the map processing functions from the standard library.
Retrieve keys and values
For retrieving a value from a map, you must provide its key as an argument of the
get() function. The shorthand
[key] syntax is also supported. If the given key is not found, it returns
null. There is also the function
getValue() which has slightly different behavior: it throws an exception if the key is not found in the map. Additionally, you have two more options to handle the key absence:
getOrElse()works the same way as for lists: the values for non-existent keys are returned from the given lambda function.
getOrDefault()returns the specified default value if the key is not found.
To perform operations on all keys or all values of a map, you can retrieve them from the properties
keys is a set of all map keys and
values is a collection of all map values.
You can filter maps with the
filter() function as well as other collections. When calling
filter() on a map, pass to it a predicate with a
Pair as an argument. This enables you to use both the key and the value in the filtering predicate.
There are also two specific ways for filtering maps: by keys and by values. For each way, there is a function:
filterValues(). Both return a new map of entries which match the given predicate. The predicate for
filterKeys() checks only the element keys, the one for
filterValues() checks only values.
Plus and minus operators
Due to the key access to elements,
-) operators work for maps differently than for other collections.
plus returns a
Map that contains elements of its both operands: a
Map on the left and a
Pair or another
Map on the right. When the right-hand side operand contains entries with keys present in the left-hand side
Map, the result map contains the entries from the right side.
minus creates a
Map from entries of a
Map on the left except those with keys from the right-hand side operand. So, the right-hand side operand can be either a single key or a collection of keys: list, set, and so on.
Map write operations
Mutable maps offer map-specific write operations. These operations let you change the map content using the key-based access to the values.
There are certain rules that define write operations on maps:
Values can be updated. In turn, keys never change: once you add an entry, its key is constant.
For each key, there is always a single value associated with it. You can add and remove whole entries.
Below are descriptions of the standard library functions for write operations available on mutable maps.
Add and update entries
To add a new key-value pair to a mutable map, use
put(). When a new entry is put into a
LinkedHashMap (the default map implementation), it is added so that it comes last when iterating the map. In sorted maps, the positions of new elements are defined by the order of their keys.
To add multiple entries at a time, use
putAll(). Its argument can be a
Map or a group of
putAll() overwrite the values if the given keys already exist in the map. Thus, you can use them to update values of map entries.
You can also add new entries to maps using the shorthand operator form. There are two ways:
operator alias for
When called with the key present in the map, operators overwrite the values of the corresponding entries.
To remove an entry from a mutable map, use the
remove() function. When calling
remove(), you can pass either a key or a whole key-value-pair. If you specify both the key and value, the element with this key will be removed only if its value matches the second argument.
You can also remove entries from a mutable map by their keys or values. To do this, call
remove() on the map's keys or values providing the key or the value of an entry. When called on values,
remove() removes only the first entry with the given value.
-=) operator is also available for mutable maps.