WeakMap

interface WeakMap<in K, V>

A weak map is a map in which elements can be garbage-collected at any moment.

The exact timing in which elements can be garbage-collected is implementation-defined. Some implementations may allow garbage-collection of keys, some may allow garbage-collection of values, or some entirely different behavior.

This class expresses that an association between two values exists, but we may be capable of regenerating it if it disappears, or we simply don't have an important enough need for it to keep memory.

Unlike regular Map, this interface doesn't allow iteration. It is not possible to observe the contents of this map, since they are ever mutable and elements may disappear at any time. Some implementations may provide such observability features.

Obtain instances

The default implementation is available via the top-level WeakMap function. Other implementations are available in the algorithms subpackage.

Thread-safety

Implementations of this interface are not thread-safe.

Constructors

WeakMap

common

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
expect fun <KKKKK, VVVVV> WeakMap(): WeakMap<K, V>

js

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(): WeakMap<K, V>

jvmnativewasmJs

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(): WeakMap<K, V>

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(): WeakMap<K, V>

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(): WeakMap<K, V>

commonjsjvmnativewasmJs

Instantiates a new, empty WeakMap.

The map returned by this function has weak keys: keys of the map may be freed if they are not referred to elsewhere in the program. When a key is freed, its value is freed as well.

Values are strongly held: until a key is removed from the map, it may never be freed by the garbage-collector.

The way the map decides whether two keys are identical is implementation-defined. For example, some implementations may use referential equality, some others may use the Any.equals function.

Instantiates a new, empty WeakMap.

This implementation is backed by a JS WeakMap.

Instantiates a new, empty WeakMap.

This implementation is backed by a Java WeakHashMap.

Instantiates a new, empty WeakMap.

This implementation uses WeakKeyArrayMap.

Instantiates a new, empty WeakMap.

This implementation uses WeakKeyArrayMap.

common

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
expect fun <KKKKK, VVVVV> WeakMap(values: Map<K, V>): WeakMap<K, V>

js

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(values: Map<K, V>): WeakMap<K, V>

jvmnativewasmJs

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(values: Map<K, V>): WeakMap<K, V>

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(values: Map<K, V>): WeakMap<K, V>

@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
@ExperimentalWeakApi
actual fun <KKKKK, VVVVV> WeakMap(values: Map<K, V>): WeakMap<K, V>

commonjsjvmnativewasmJs

Instantiates a new WeakMap by copying values.

The map returned by this function has weak keys: keys of the map may be freed if they are not referred to elsewhere in the program. When a key is freed, its value is freed as well.

Values are strongly held: until a key is removed from the map, it may never be freed by the garbage-collector.

The way the map decides whether two keys are identical is implementation-defined. For example, some implementations may use referential equality, some others may use the Any.equals function.

Instantiates a new WeakMap by copying values.

This implementation is backed by a JS WeakMap.

Instantiates a new WeakMap by copying values.

This implementation is backed by a Java WeakHashMap.

Instantiates a new WeakMap by copying values.

This implementation uses WeakKeyArrayMap.

Instantiates a new WeakMap by copying values.

This implementation uses WeakKeyArrayMap.

Types

Companion

object Companion

Functions

contains

@ExperimentalWeakApi
abstract operator fun contains(key: K): Boolean

Checks whether a value is currently associated with key.

Note. Values may be removed at any-time. It is possible that a get call returns null, even if it is directly following a contains call that returned true.

See also

• Map.contains: Equivalent method for regular maps.

get

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

Gets the value associated with key in this map.

If no value is currently associated with key, null is returned.

See also

• Map.get: Equivalent method for regular maps.

getOrDefault

@ExperimentalWeakApi
inline fun <K, V> WeakMap<K, V>.getOrDefault(key: K, defaultValue: V): V

Attempts to find the value associated with key, returning defaultValue if none is found.

getOrElse

@ExperimentalWeakApi
inline fun <K, V> WeakMap<K, V>.getOrElse(key: K, defaultValue: () -> V): V

Attempts to find the value associated with key, returning the result of defaultValue if none is found.

See also

• Map.getOrElse: Equivalent method for regular maps.

getOrPut

@ExperimentalWeakApi
inline fun <K, V> WeakMap<K, V>.getOrPut(key: K, defaultValue: () -> V): V

Attempts to find the value associated with key.

If no value is associated with key, calls defaultValue, stores its result back into the map as well as returns it.

In a way, this is a sort of simple cache, where a new value is recomputed if the previous one has been deleted.

See also

• MutableMap.getOrPut: Equivalent method for regular maps.

getValue

@ExperimentalWeakApi
inline operator fun <V> WeakMap<String, V>.getValue(thisRef: Any?, property: KProperty<*>): V?

Allows to use a weak map for data-oriented usage.

Example

val map = WeakMap<String, Int>()

var score by map
var age by map

score = 5
println(age)

See also

• Map.getValue: Equivalent method for regular maps.

remove

@ExperimentalWeakApi
abstract fun remove(key: K): V?

Removes key from this map and returns the previously-stored value.

If no value was previously stored, null is returned (same behavior as get, but in a single operation).

See also

• MutableMap.remove: Equivalent method for regular maps.

remove

@ExperimentalWeakApi
fun <K, V> WeakMap<K, V>.remove(key: K, value: V)

Removes the association of key to value from this map.

If key is associated to another value than value, nothing happens.

removeAll

@ExperimentalWeakApi
fun <K, V> WeakMap<K, V>.removeAll(from: Iterable<K>)

Removes the specified keys from this map.

@ExperimentalWeakApi
fun <K, V> WeakMap<K, V>.removeAll(from: Map<out K, V>)

Removes the specified associations from this map.

set

abstract operator fun set(key: K, value: V)

Associates value to the key.

An implementation may remove this association at any time.

See also

• MutableMap.set: Equivalent method for regular maps.

setAll

@ExperimentalWeakApi
fun <K, V> WeakMap<K, in V>.setAll(from: Map<out K, V>)

Sets all the values from the provided map into the current one.

See also

• MutableMap.putAll: Equivalent method for regular maps.

setValue

@ExperimentalWeakApi
inline operator fun <V> WeakMap<String, V>.setValue(
    thisRef: Any?, 
    property: KProperty<*>, 
    value: V
)

Allows to use a weak map for data-oriented usage.

Example

val map = WeakMap<String, Int>()

var score by map
var age by map

score = 5
println(age)

See also

• MutableMap.setValue: Equivalent method for regular maps.