Map

interface Map<K, out V> (source)

A collection that holds pairs of objects (keys and values) and supports efficiently retrieving the value corresponding to each key. Map keys are unique; the map holds only one value for each key. Methods in this interface support only read-only access to the map; read-write access is supported through the MutableMap interface.

Parameters

K - the type of map keys. The map is invariant on its key type, as it can accept key as a parameter (of containsKey for example) and return it in keys set.

V - the type of map values. The map is covariant on its value type.

Types

Entry

interface Entry<out K, out V>

Represents a key/value pair held by a Map.

Properties

entries

abstract val entries: Set<Entry<K, V>>

Returns a read-only Set of all key/value pairs in this map.

keys

abstract val keys: Set<K>

Returns a read-only Set of all keys in this map.

size

abstract val size: Int

Returns the number of key/value pairs in the map.

values

abstract val values: Collection<V>

Returns a read-only Collection of all values in this map. Note that this collection may contain duplicate values.

Functions

containsKey

abstract fun containsKey(key: K): Boolean

Returns true if the map contains the specified key.

containsValue

abstract fun containsValue(value: V): Boolean

Returns true if the map maps one or more keys to the specified value.

get

abstract operator fun get(key: K): V?

Returns the value corresponding to the given key, or null if such a key is not present in the map.

getOrDefault

open fun getOrDefault(key: K, defaultValue: V): V

Returns the value corresponding to the given key, or defaultValue if such a key is not present in the map.

isEmpty

abstract fun isEmpty(): Boolean

Returns true if the map is empty (contains no elements), false otherwise.

Inherited Functions

equals

open operator fun equals(other: Any?): Boolean

Indicates whether some other object is "equal to" this one. Implementations must fulfil the following requirements:

hashCode

open fun hashCode(): Int

Returns a hash code value for the object. The general contract of hashCode is:

toString

open fun toString(): String

Returns a string representation of the object.

Extension Functions

all

fun <K, V> Map<out K, V>.all(
    predicate: (Entry<K, V>) -> Boolean
): Boolean

Returns true if all entries match the given predicate.

any

fun <K, V> Map<out K, V>.any(): Boolean

Returns true if map has at least one entry.

fun <K, V> Map<out K, V>.any(
    predicate: (Entry<K, V>) -> Boolean
): Boolean

Returns true if at least one entry matches the given predicate.

asIterable

fun <K, V> Map<out K, V>.asIterable(): Iterable<Entry<K, V>>

Creates an Iterable instance that wraps the original map returning its entries when being iterated.

asSequence

fun <K, V> Map<out K, V>.asSequence(): Sequence<Entry<K, V>>

Creates a Sequence instance that wraps the original map returning its entries when being iterated.

contains

operator fun <K, V> Map<out K, V>.contains(key: K): Boolean

Checks if the map contains the given key.

containsKey

fun <K> Map<out K, *>.containsKey(key: K): Boolean

Returns true if the map contains the specified key.

containsValue

fun <K, V> Map<K, V>.containsValue(value: V): Boolean

Returns true if the map maps one or more keys to the specified value.

count

fun <K, V> Map<out K, V>.count(): Int

Returns the number of entries in this map.

fun <K, V> Map<out K, V>.count(
    predicate: (Entry<K, V>) -> Boolean
): Int

Returns the number of entries matching the given predicate.

filter

fun <K, V> Map<out K, V>.filter(
    predicate: (Entry<K, V>) -> Boolean
): Map<K, V>

Returns a new map containing all key-value pairs matching the given predicate.

filterKeys

fun <K, V> Map<out K, V>.filterKeys(
    predicate: (K) -> Boolean
): Map<K, V>

Returns a map containing all key-value pairs with keys matching the given predicate.

filterNot

fun <K, V> Map<out K, V>.filterNot(
    predicate: (Entry<K, V>) -> Boolean
): Map<K, V>

Returns a new map containing all key-value pairs not matching the given predicate.

filterNotTo

fun <K, V, M : MutableMap<in K, in V>> Map<out K, V>.filterNotTo(
    destination: M,
    predicate: (Entry<K, V>) -> Boolean
): M

Appends all entries not matching the given predicate into the given destination.

filterTo

fun <K, V, M : MutableMap<in K, in V>> Map<out K, V>.filterTo(
    destination: M,
    predicate: (Entry<K, V>) -> Boolean
): M

Appends all entries matching the given predicate into the mutable map given as destination parameter.

filterValues

fun <K, V> Map<out K, V>.filterValues(
    predicate: (V) -> Boolean
): Map<K, V>

Returns a map containing all key-value pairs with values matching the given predicate.

flatMap

fun <K, V, R> Map<out K, V>.flatMap(
    transform: (Entry<K, V>) -> Iterable<R>
): List<R>

Returns a single list of all elements yielded from results of transform function being invoked on each entry of original map.

flatMapTo

fun <K, V, R, C : MutableCollection<in R>> Map<out K, V>.flatMapTo(
    destination: C,
    transform: (Entry<K, V>) -> Iterable<R>
): C

Appends all elements yielded from results of transform function being invoked on each entry of original map, to the given destination.

forEach

fun <K, V> Map<out K, V>.forEach(
    action: (Entry<K, V>) -> Unit)

Performs the given action on each entry.

get

operator fun <K, V> Map<out K, V>.get(key: K): V?

Returns the value corresponding to the given key, or null if such a key is not present in the map.

getOrDefault

fun <K, V> Map<out K, V>.getOrDefault(
    key: K,
    defaultValue: V
): V

Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.

getOrElse

fun <K, V> Map<K, V>.getOrElse(
    key: K,
    defaultValue: () -> V
): V

Returns the value for the given key, or the result of the defaultValue function if there was no entry for the given key.

getValue

operator fun <V, V1 : V> Map<in String, V>.getValue(
    thisRef: Any?,
    property: KProperty<*>
): V1

Returns the value of the property for the given object from this read-only map.

fun <K, V> Map<K, V>.getValue(key: K): V

Returns the value for the given key or throws an exception if there is no such key in the map.

isNotEmpty

fun <K, V> Map<out K, V>.isNotEmpty(): Boolean

Returns true if this map is not empty.

iterator

operator fun <K, V> Map<out K, V>.iterator(): Iterator<Entry<K, V>>

Returns an Iterator over the entries in the Map.

map

fun <K, V, R> Map<out K, V>.map(
    transform: (Entry<K, V>) -> R
): List<R>

Returns a list containing the results of applying the given transform function to each entry in the original map.

mapKeys

fun <K, V, R> Map<out K, V>.mapKeys(
    transform: (Entry<K, V>) -> R
): Map<R, V>

Returns a new Map with entries having the keys obtained by applying the transform function to each entry in this Map and the values of this map.

mapKeysTo

fun <K, V, R, M : MutableMap<in R, in V>> Map<out K, V>.mapKeysTo(
    destination: M,
    transform: (Entry<K, V>) -> R
): M

Populates the given destination map with entries having the keys obtained by applying the transform function to each entry in this Map and the values of this map.

mapNotNull

fun <K, V, R : Any> Map<out K, V>.mapNotNull(
    transform: (Entry<K, V>) -> R?
): List<R>

Returns a list containing only the non-null results of applying the given transform function to each entry in the original map.

mapNotNullTo

fun <K, V, R : Any, C : MutableCollection<in R>> Map<out K, V>.mapNotNullTo(
    destination: C,
    transform: (Entry<K, V>) -> R?
): C

Applies the given transform function to each entry in the original map and appends only the non-null results to the given destination.

mapTo

fun <K, V, R, C : MutableCollection<in R>> Map<out K, V>.mapTo(
    destination: C,
    transform: (Entry<K, V>) -> R
): C

Applies the given transform function to each entry of the original map and appends the results to the given destination.

mapValues

fun <K, V, R> Map<out K, V>.mapValues(
    transform: (Entry<K, V>) -> R
): Map<K, R>

Returns a new map with entries having the keys of this map and the values obtained by applying the transform function to each entry in this Map.

mapValuesTo

fun <K, V, R, M : MutableMap<in K, in R>> Map<out K, V>.mapValuesTo(
    destination: M,
    transform: (Entry<K, V>) -> R
): M

Populates the given destination map with entries having the keys of this map and the values obtained by applying the transform function to each entry in this Map.

maxBy

fun <K, V, R : Comparable<R>> Map<out K, V>.maxBy(
    selector: (Entry<K, V>) -> R
): Entry<K, V>?

Returns the first entry yielding the largest value of the given function or null if there are no entries.

maxWith

fun <K, V> Map<out K, V>.maxWith(
    comparator: Comparator<in Entry<K, V>>
): Entry<K, V>?
fun <K, V> Map<out K, V>.maxWith(
    comparator: Comparator<in Entry<K, V>>
): Entry<K, V>?

Returns the first entry having the largest value according to the provided comparator or null if there are no entries.

minBy

fun <K, V, R : Comparable<R>> Map<out K, V>.minBy(
    selector: (Entry<K, V>) -> R
): Entry<K, V>?

Returns the first entry yielding the smallest value of the given function or null if there are no entries.

minWith

fun <K, V> Map<out K, V>.minWith(
    comparator: Comparator<in Entry<K, V>>
): Entry<K, V>?
fun <K, V> Map<out K, V>.minWith(
    comparator: Comparator<in Entry<K, V>>
): Entry<K, V>?

Returns the first entry having the smallest value according to the provided comparator or null if there are no entries.

minus

operator fun <K, V> Map<out K, V>.minus(key: K): Map<K, V>

Returns a map containing all entries of the original map except the entry with the given key.

operator fun <K, V> Map<out K, V>.minus(
    keys: Iterable<K>
): Map<K, V>

Returns a map containing all entries of the original map except those entries the keys of which are contained in the given keys collection.

operator fun <K, V> Map<out K, V>.minus(
    keys: Array<out K>
): Map<K, V>

Returns a map containing all entries of the original map except those entries the keys of which are contained in the given keys array.

operator fun <K, V> Map<out K, V>.minus(
    keys: Sequence<K>
): Map<K, V>

Returns a map containing all entries of the original map except those entries the keys of which are contained in the given keys sequence.

none

fun <K, V> Map<out K, V>.none(): Boolean

Returns true if the map has no entries.

fun <K, V> Map<out K, V>.none(
    predicate: (Entry<K, V>) -> Boolean
): Boolean

Returns true if no entries match the given predicate.

onEach

fun <K, V, M : Map<out K, V>> M.onEach(
    action: (Entry<K, V>) -> Unit
): M

Performs the given action on each entry and returns the map itself afterwards.

orEmpty

fun <K, V> Map<K, V>?.orEmpty(): Map<K, V>

Returns the Map if its not null, or the empty Map otherwise.

plus

operator fun <K, V> Map<out K, V>.plus(
    pair: Pair<K, V>
): Map<K, V>

Creates a new read-only map by replacing or adding an entry to this map from a given key-value pair.

operator fun <K, V> Map<out K, V>.plus(
    pairs: Iterable<Pair<K, V>>
): Map<K, V>

Creates a new read-only map by replacing or adding entries to this map from a given collection of key-value pairs.

operator fun <K, V> Map<out K, V>.plus(
    pairs: Array<out Pair<K, V>>
): Map<K, V>

Creates a new read-only map by replacing or adding entries to this map from a given array of key-value pairs.

operator fun <K, V> Map<out K, V>.plus(
    pairs: Sequence<Pair<K, V>>
): Map<K, V>

Creates a new read-only map by replacing or adding entries to this map from a given sequence of key-value pairs.

operator fun <K, V> Map<out K, V>.plus(
    map: Map<out K, V>
): Map<K, V>

Creates a new read-only map by replacing or adding entries to this map from another map.

toList

fun <K, V> Map<out K, V>.toList(): List<Pair<K, V>>

Returns a List containing all key-value pairs.

toMap

fun <K, V> Map<out K, V>.toMap(): Map<K, V>

Returns a new read-only map containing all key-value pairs from the original map.

fun <K, V, M : MutableMap<in K, in V>> Map<out K, V>.toMap(
    destination: M
): M

Populates and returns the destination mutable map with key-value pairs from the given map.

toMutableMap

fun <K, V> Map<out K, V>.toMutableMap(): MutableMap<K, V>

Returns a new mutable map containing all key-value pairs from the original map.

toProperties

fun Map<String, String>.toProperties(): Properties

Converts this Map to a Properties object.

toSortedMap

fun <K : Comparable<K>, V> Map<out K, V>.toSortedMap(): SortedMap<K, V>

Converts this Map to a SortedMap so iteration order will be in key order.

fun <K, V> Map<out K, V>.toSortedMap(
    comparator: Comparator<in K>
): SortedMap<K, V>

Converts this Map to a SortedMap using the given comparator so that iteration order will be in the order defined by the comparator.

withDefault

fun <K, V> Map<K, V>.withDefault(
    defaultValue: (key: K) -> V
): Map<K, V>

Returns a wrapper of this read-only map, having the implicit default value provided with the specified function defaultValue.

Inheritors

AbstractMap

abstract class AbstractMap<K, out V> : Map<K, V>

Provides a skeletal implementation of the read-only Map interface.

LinkedHashMap

LinkedHashMap

MutableMap

interface MutableMap<K, V> : Map<K, V>

A modifiable collection that holds pairs of objects (keys and values) and supports efficiently retrieving the value corresponding to each key. Map keys are unique; the map holds only one value for each key.