MutableScatterMap

Artifact: androidx.collection:collection

Added in 1.4.0

Kotlin |Java

Cmn

class MutableScatterMap<K : Any?, V : Any?> : ScatterMap

kotlin.Any
↳	androidx.collection.ScatterMap
	↳	androidx.collection.MutableScatterMap

MutableScatterMap is a container with a Map-like interface based on a flat hash table implementation (the key/value mappings are not stored by nodes but directly into arrays). The underlying implementation is designed to avoid all allocations on insertion, removal, retrieval, and iteration. Allocations may still happen on insertion when the underlying storage needs to grow to accommodate newly added entries to the table. In addition, this implementation minimizes memory usage by avoiding the use of separate objects to hold key/value pairs.

This implementation makes no guarantee as to the order of the keys and values stored, nor does it make guarantees that the order remains constant over time.

This implementation is not thread-safe: if multiple threads access this container concurrently, and one or more threads modify the structure of the map (insertion or removal for instance), the calling code must provide the appropriate synchronization. Multiple threads are safe to read from this map concurrently if no write is happening.

Note: when a Map is absolutely necessary, you can use the method asMap to create a thin wrapper around a MutableScatterMap. Please refer to asMap for more details and caveats.

Note: when a MutableMap is absolutely necessary, you can use the method asMutableMap to create a thin wrapper around a MutableScatterMap. Please refer to asMutableMap for more details and caveats.

MutableScatterMap and SimpleArrayMap: like SimpleArrayMap, MutableScatterMap is designed to avoid the allocation of extra objects when inserting new entries in the map. However, the implementation of MutableScatterMap offers better performance characteristics compared to SimpleArrayMap and is thus generally preferable. If memory usage is a concern, SimpleArrayMap automatically shrinks its storage to avoid using more memory than necessary. You can also control memory usage with MutableScatterMap by manually calling MutableScatterMap.trim.

Note: For the JS target the implementation delegates to a regular map.

See also
`Map`

Summary

Public constructors
`<K : Any?, V : Any?> MutableScatterMap(initialCapacity: Int)` Creates a new `MutableScatterMap`	Cmn android N JS

Public functions
`MutableMap<K, V>`	`asMutableMap()` Wraps this `ScatterMap` with a `MutableMap` interface.	Cmn android N JS
`Unit`	`clear()` Removes all mappings from this map.	Cmn android N JS
`inline V`	`compute(key: K, computeBlock: (key, value?) -> V)` Retrieves a value for `key` and computes a new value based on the existing value (or `null` if the key is not in the map).	Cmn android N JS
`inline V`	`getOrPut(key: K, defaultValue: () -> V)` Returns the value to which the specified `key` is mapped, if the value is present in the map and not `null`.	Cmn android N JS
`inline operator Unit`	`minusAssign(key: K)` Removes the specified `key` and its associated value from the map.	Cmn android N JS
`inline operator Unit`	`minusAssign(keys: Array<K>)` Removes the specified `keys` and their associated value from the map.	Cmn android N JS
`inline operator Unit`	`minusAssign(keys: Iterable<K>)` Removes the specified `keys` and their associated value from the map.	Cmn android N JS
`inline operator Unit`	`minusAssign(keys: ObjectList<K>)` Removes the specified `keys` and their associated value from the map.	Cmn android N JS
`inline operator Unit`	`minusAssign(keys: ScatterSet<K>)` Removes the specified `keys` and their associated value from the map.	Cmn android N JS
`inline operator Unit`	`minusAssign(keys: Sequence<K>)` Removes the specified `keys` and their associated value from the map.	Cmn android N JS
`inline operator Unit`	`plusAssign(from: Map<K, V>)` Puts all the key/value mappings in the `from` map into this map.	Cmn android N JS
`inline operator Unit`	`plusAssign(from: ScatterMap<K, V>)` Puts all the key/value mappings in the `from` map into this map.	Cmn android N JS
`inline operator Unit`	`plusAssign(pair: Pair<K, V>)` Puts the key/value mapping from the `pair` in this map, using the first element as the key, and the second element as the value.	Cmn android N JS
`inline operator Unit`	`plusAssign(pairs: Array<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`inline operator Unit`	`plusAssign(pairs: Iterable<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`inline operator Unit`	`plusAssign(pairs: Sequence<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`V?`	`put(key: K, value: V)` Creates a new mapping from `key` to `value` in this map.	Cmn android N JS
`Unit`	`putAll(from: Map<K, V>)` Puts all the key/value mappings in the `from` map into this map.	Cmn android N JS
`Unit`	`putAll(from: ScatterMap<K, V>)` Puts all the key/value mappings in the `from` map into this map.	Cmn android N JS
`Unit`	`putAll(pairs: Array<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`Unit`	`putAll(pairs: Iterable<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`Unit`	`putAll(pairs: Sequence<Pair<K, V>>)` Puts all the `pairs` into this map, using the first component of the pair as the key, and the second component as the value.	Cmn android N JS
`V?`	`remove(key: K)` Removes the specified `key` and its associated value from the map.	Cmn android N JS
`Boolean`	`remove(key: K, value: V)` Removes the specified `key` and its associated value from the map if the associated value equals `value`.	Cmn android N JS
`inline Unit`	`removeIf(predicate: (K, V) -> Boolean)` Removes any mapping for which the specified `predicate` returns true.	Cmn android N JS
`operator Unit`	`set(key: K, value: V)` Creates a new mapping from `key` to `value` in this map.	Cmn android N JS
`Int`	`trim()` Trims this `MutableScatterMap`'s storage so it is sized appropriately to hold the current mappings.	Cmn android N JS

Inherited functions

From androidx.collection.ScatterMap

`inline Boolean`	`all(predicate: (K, V) -> Boolean)` Returns true if all entries match the given `predicate`.	Cmn android N JS
`Boolean`	`any()` Returns `true` if this map has at least one entry.	Cmn android N JS
`inline Boolean`	`any(predicate: (K, V) -> Boolean)` Returns true if at least one entry matches the given `predicate`.	Cmn android N JS
`Map<K, V>`	`asMap()` Wraps this `ScatterMap` with a `Map` interface.	Cmn android N JS
`operator Boolean`	`contains(key: K)` Returns true if the specified `key` is present in this hash map, false otherwise.	Cmn android N JS
`Boolean`	`containsKey(key: K)` Returns true if the specified `key` is present in this hash map, false otherwise.	Cmn android N JS
`Boolean`	`containsValue(value: V)` Returns true if the specified `value` is present in this hash map, false otherwise.	Cmn android N JS
`Int`	`count()` Returns the number of entries in this map.	Cmn android N JS
`inline Int`	`count(predicate: (K, V) -> Boolean)` Returns the number of entries matching the given `predicate`.	Cmn android N JS
`open operator Boolean`	`equals(other: Any?)` Compares the specified object `other` with this hash map for equality.	Cmn android N JS
`inline Unit`	`forEach(block: (key, value) -> Unit)` Iterates over every key/value pair stored in this map by invoking the specified `block` lambda.	Cmn android N JS
`inline Unit`	`forEachKey(block: (key) -> Unit)` Iterates over every key stored in this map by invoking the specified `block` lambda.	Cmn android N JS
`inline Unit`	`forEachValue(block: (value) -> Unit)` Iterates over every value stored in this map by invoking the specified `block` lambda.	Cmn android N JS
`operator V?`	`get(key: K)` Returns the value corresponding to the given `key`, or `null` if such a key is not present in the map.	Cmn android N JS
`V`	`getOrDefault(key: K, defaultValue: V)` Returns the value to which the specified `key` is mapped, or `defaultValue` if this map contains no mapping for the key.	Cmn android N JS
`inline V`	`getOrElse(key: K, defaultValue: () -> V)` Returns the value for the given `key` if the value is present and not null.	Cmn android N JS
`open Int`	`hashCode()` Returns the hash code value for this map.	Cmn android N JS
`Boolean`	`isEmpty()` Indicates whether this map is empty.	Cmn android N JS
`Boolean`	`isNotEmpty()` Returns `true` if this map is not empty.	Cmn android N JS
`String`	`joinToString( separator: CharSequence, prefix: CharSequence, postfix: CharSequence, limit: Int, truncated: CharSequence, transform: ((key, value) -> CharSequence)? )` Creates a String from the elements separated by `separator` and using `prefix` before and `postfix` after, if supplied.	Cmn android N JS
`Boolean`	`none()` Returns `true` if this map has no entries.	Cmn android N JS
`open String`	`toString()` Returns a string representation of this map.	Cmn android N JS

Inherited properties

From androidx.collection.ScatterMap

`Int`	`capacity` Returns the number of key-value pairs that can be stored in this map without requiring internal storage reallocation.	Cmn android N JS
`Int`	`size` Returns the number of key-value pairs in this map.	Cmn android N JS

Public constructors

MutableScatterMap

Cmn android N JS

<K : Any?, V : Any?> MutableScatterMap(
    initialCapacity: Int = DefaultScatterCapacity
)

Creates a new MutableScatterMap

Parameters
`initialCapacity: Int = DefaultScatterCapacity`	The initial desired capacity for this container. The container will honor this value by guaranteeing its internal structures can hold that many entries without requiring any allocations. The initial capacity can be set to 0.

Public functions

asMutableMap

Cmn android N JS

Added in 1.4.0

fun asMutableMap(): MutableMap<K, V>

Wraps this ScatterMap with a MutableMap interface. The MutableMap is backed by the ScatterMap, so changes to the ScatterMap are reflected in the MutableMap and vice-versa. If the ScatterMap is modified while an iteration over the MutableMap is in progress (and vice- versa), the results of the iteration are undefined.

Note: while this method is useful to use this MutableScatterMap with APIs accepting MutableMap interfaces, it is less efficient to do so than to use MutableScatterMap's APIs directly. While the MutableMap implementation returned by this method tries to be as efficient as possible, the semantics of MutableMap may require the allocation of temporary objects for access and iteration.

clear

Cmn android N JS

Added in 1.4.0

fun clear(): Unit

Removes all mappings from this map.

compute

Cmn android N JS

Added in 1.4.0

inline fun compute(key: K, computeBlock: (key, value?) -> V): V

Retrieves a value for key and computes a new value based on the existing value (or null if the key is not in the map). The computed value is then stored in the map for the given key.

Returns
`V`	value computed by `computeBlock`.

getOrPut

Cmn android N JS

Added in 1.4.0

inline fun getOrPut(key: K, defaultValue: () -> V): V

Returns the value to which the specified key is mapped, if the value is present in the map and not null. Otherwise, calls defaultValue() and puts the result in the map associated with key.

minusAssign

Cmn android N JS

Added in 1.4.0

inline operator fun minusAssign(key: K): Unit

Removes the specified key and its associated value from the map.

minusAssign

Cmn android N JS

Added in 1.4.0

inline operator fun minusAssign(keys: Array<K>): Unit

Removes the specified keys and their associated value from the map.

minusAssign

Cmn android N JS

inline operator fun minusAssign(keys: Iterable<K>): Unit

Removes the specified keys and their associated value from the map.

minusAssign

Cmn android N JS

Added in 1.4.0

inline operator fun minusAssign(keys: ObjectList<K>): Unit

Removes the specified keys and their associated value from the map.

minusAssign

Cmn android N JS

Added in 1.4.0

inline operator fun minusAssign(keys: ScatterSet<K>): Unit

Removes the specified keys and their associated value from the map.

minusAssign

Cmn android N JS

inline operator fun minusAssign(keys: Sequence<K>): Unit

Removes the specified keys and their associated value from the map.

plusAssign

Cmn android N JS

inline operator fun plusAssign(from: Map<K, V>): Unit

Puts all the key/value mappings in the from map into this map.

plusAssign

Cmn android N JS

Added in 1.4.0

inline operator fun plusAssign(from: ScatterMap<K, V>): Unit

Puts all the key/value mappings in the from map into this map.

plusAssign

Cmn android N JS

inline operator fun plusAssign(pair: Pair<K, V>): Unit

Puts the key/value mapping from the pair in this map, using the first element as the key, and the second element as the value.

plusAssign

Cmn android N JS

inline operator fun plusAssign(pairs: Array<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

plusAssign

Cmn android N JS

inline operator fun plusAssign(pairs: Iterable<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

plusAssign

Cmn android N JS

inline operator fun plusAssign(pairs: Sequence<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

put

Cmn android N JS

Added in 1.4.0

fun put(key: K, value: V): V?

Creates a new mapping from key to value in this map. If key is already present in the map, the association is modified and the previously associated value is replaced with value. If key is not present, a new entry is added to the map, which may require to grow the underlying storage and cause allocations. Return the previous value associated with the key, or null if the key was not present in the map.

putAll

Cmn android N JS

fun putAll(from: Map<K, V>): Unit

Puts all the key/value mappings in the from map into this map.

putAll

Cmn android N JS

Added in 1.4.0

fun putAll(from: ScatterMap<K, V>): Unit

Puts all the key/value mappings in the from map into this map.

putAll

Cmn android N JS

fun putAll(pairs: Array<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

putAll

Cmn android N JS

fun putAll(pairs: Iterable<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

putAll

Cmn android N JS

fun putAll(pairs: Sequence<Pair<K, V>>): Unit

Puts all the pairs into this map, using the first component of the pair as the key, and the second component as the value.

remove

Cmn android N JS

Added in 1.4.0

fun remove(key: K): V?

Removes the specified key and its associated value from the map. If the key was present in the map, this function returns the value that was present before removal.

remove

Cmn android N JS

Added in 1.4.0

fun remove(key: K, value: V): Boolean

Removes the specified key and its associated value from the map if the associated value equals value. Returns whether the removal happened.

removeIf

Cmn android N JS

Added in 1.4.0

inline fun removeIf(predicate: (K, V) -> Boolean): Unit

Removes any mapping for which the specified predicate returns true.

set

Cmn android N JS

Added in 1.4.0

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

trim

Cmn android N JS

Added in 1.4.0

fun trim(): Int

Trims this MutableScatterMap's storage so it is sized appropriately to hold the current mappings.

Returns the number of empty entries removed from this map's storage. Returns be 0 if no trimming is necessary or possible.