ScatterMap

Artifact: androidx.collection:collection

Added in 1.4.0

Kotlin |Java

Cmn

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

Known direct subclasses

MutableScatterMap

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).

ScatterMap 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.

This implementation is read-only and only allows data to be queried. A mutable implementation is provided by MutableScatterMap.

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

ScatterMap and SimpleArrayMap: like SimpleArrayMap, ScatterMap/MutableScatterMap is designed to avoid the allocation of extra objects when inserting new entries in the map. However, the implementation of ScatterMap/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
`MutableScatterMap`

Summary

Protected constructors
`<K : Any?, V : Any?> ScatterMap()`	N
`<K : Any?, V : Any?> ScatterMap(delegate: MutableMap<K, V>)`	JS

Public functions
`inline Boolean`	`all(predicate: (K, V) -> Boolean)` Returns true if all entries match the given `predicate`.	Cmn N JS
`Boolean`	`any()` Returns `true` if this map has at least one entry.	Cmn N JS
`inline Boolean`	`any(predicate: (K, V) -> Boolean)` Returns true if at least one entry matches the given `predicate`.	Cmn N JS
`Map<K, V>`	`asMap()` Wraps this `ScatterMap` with a `Map` interface.	Cmn N JS
`operator Boolean`	`contains(key: K)` Returns true if the specified `key` is present in this hash map, false otherwise.	Cmn N JS
`Boolean`	`containsKey(key: K)` Returns true if the specified `key` is present in this hash map, false otherwise.	Cmn N JS
`Boolean`	`containsValue(value: V)` Returns true if the specified `value` is present in this hash map, false otherwise.	Cmn N JS
`Int`	`count()` Returns the number of entries in this map.	Cmn N JS
`inline Int`	`count(predicate: (K, V) -> Boolean)` Returns the number of entries matching the given `predicate`.	Cmn N JS
`open operator Boolean`	`equals(other: Any?)` Compares the specified object `other` with this hash map for equality.	Cmn 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 N JS
`inline Unit`	`forEachKey(block: (key) -> Unit)` Iterates over every key stored in this map by invoking the specified `block` lambda.	Cmn N JS
`inline Unit`	`forEachValue(block: (value) -> Unit)` Iterates over every value stored in this map by invoking the specified `block` lambda.	Cmn 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 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 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 N JS
`open Int`	`hashCode()` Returns the hash code value for this map.	Cmn N JS
`Boolean`	`isEmpty()` Indicates whether this map is empty.	Cmn N JS
`Boolean`	`isNotEmpty()` Returns `true` if this map is not empty.	Cmn 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 N JS
`Boolean`	`none()` Returns `true` if this map has no entries.	Cmn N JS
`open String`	`toString()` Returns a string representation of this map.	Cmn N JS

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

Protected constructors

ScatterMap

protected <K : Any?, V : Any?> ScatterMap()

ScatterMap

protected <K : Any?, V : Any?> ScatterMap(delegate: MutableMap<K, V>)

Public functions

all

Cmn N JS

Added in 1.4.0

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

Returns true if all entries match the given predicate.

any

Cmn N JS

Added in 1.4.0

fun any(): Boolean

Returns true if this map has at least one entry.

any

Cmn N JS

Added in 1.4.0

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

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

asMap

Cmn N JS

Added in 1.4.0

fun asMap(): Map<K, V>

Wraps this ScatterMap with a Map interface. The Map is backed by the ScatterMap, so changes to the ScatterMap are reflected in the Map. If the ScatterMap is modified while an iteration over the Map is in progress, the results of the iteration are undefined.

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

contains

Cmn N JS

Added in 1.4.0

operator fun contains(key: K): Boolean

Returns true if the specified key is present in this hash map, false otherwise.

containsKey

Cmn N JS

Added in 1.4.0

fun containsKey(key: K): Boolean

Returns true if the specified key is present in this hash map, false otherwise.

containsValue

Cmn N JS

Added in 1.4.0

fun containsValue(value: V): Boolean

Returns true if the specified value is present in this hash map, false otherwise.

count

Cmn N JS

Added in 1.4.0

fun count(): Int

Returns the number of entries in this map.

count

Cmn N JS

Added in 1.4.0

inline fun count(predicate: (K, V) -> Boolean): Int

Returns the number of entries matching the given predicate.

equals

Cmn N JS

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

Compares the specified object other with this hash map for equality. The two objects are considered equal if other:

Is a ScatterMap
Has the same size as this map
Contains key/value pairs equal to this map's pair

forEach

Cmn N JS

Added in 1.4.0

inline fun forEach(block: (key, value) -> Unit): Unit

Iterates over every key/value pair stored in this map by invoking the specified block lambda.

forEachKey

Cmn N JS

Added in 1.4.0

inline fun forEachKey(block: (key) -> Unit): Unit

Iterates over every key stored in this map by invoking the specified block lambda.

forEachValue

Cmn N JS

Added in 1.4.0

inline fun forEachValue(block: (value) -> Unit): Unit

Iterates over every value stored in this map by invoking the specified block lambda.

get

Cmn N JS

Added in 1.4.0

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

Cmn N JS

Added in 1.4.0

fun 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

Cmn N JS

Added in 1.4.0

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

Returns the value for the given key if the value is present and not null. Otherwise, returns the result of the defaultValue function.

hashCode

Cmn N JS

open fun hashCode(): Int

Returns the hash code value for this map. The hash code the sum of the hash codes of each key/value pair.

isEmpty

Cmn N JS

Added in 1.4.0

fun isEmpty(): Boolean

Indicates whether this map is empty.

isNotEmpty

Cmn N JS

Added in 1.4.0

fun isNotEmpty(): Boolean

Returns true if this map is not empty.

joinToString

Cmn N JS

fun joinToString(
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((key, value) -> CharSequence)? = null
): String

Creates a String from the elements separated by separator and using prefix before and postfix after, if supplied.

When a non-negative value of limit is provided, a maximum of limit items are used to generate the string. If the collection holds more than limit items, the string is terminated with truncated.

transform may be supplied to convert each element to a custom String.

none

Cmn N JS

Added in 1.4.0

fun none(): Boolean

Returns true if this map has no entries.

toString

Cmn N JS

open fun toString(): String

Returns a string representation of this map. The map is denoted in the string by the {}. Each key/value pair present in the map is represented inside '{}by a substring of the form key=value, and pairs are separated by , `.

Public properties

capacity

Cmn N JS

Added in 1.4.0

val capacity: Int

Returns the number of key-value pairs that can be stored in this map without requiring internal storage reallocation.

size

Cmn N JS

Added in 1.4.0

val size: Int

Returns the number of key-value pairs in this map.