fastmap {fastmap}

Create a fastmap object

Description

A fastmap object provides a key-value store where the keys are strings and the values are any R objects.

Usage

fastmap(missing_default = NULL)

Arguments

missing_default

The value to return when get() is called with a key that is not in the map. The default is NULL, but in some cases it can be useful to return a sentinel value, such as a key_missing object.

Details

In R, it is common to use environments as key-value stores, but they can leak memory: every time a new key is used, R registers it in its global symbol table, which only grows and is never garbage collected. If many different keys are used, this can cause a non-trivial amount of memory leakage.

Fastmap objects do not use the symbol table and do not leak memory.

Unlike with environments, the keys in a fastmap are always encoded as UTF-8, so if you call $set() with two different strings that have the same Unicode values but have different encodings, the second call will overwrite the first value. If you call $keys(), it will return UTF-8 encoded strings, and similarly, $as_list() will return a list with names that have UTF-8 encoding.

Note that if you call $mset() with a named argument, where the name is non-ASCII, R will convert the name to the native encoding before fastmap has the chance to convert them to UTF-8, and the keys may get mangled in the process. However, if you use $mset(.list = x), then R will not convert the keys to the native encoding, and the keys will be correctly converted to UTF-8. With $mget(), the keys will be converted to UTF-8 before they are fetched.

fastmap objects have the following methods:

set(key, value)

Set a key-value pair. key must be a string. Returns value.

mset(..., .list = NULL)

Set multiple key-value pairs. The key-value pairs are named arguments, and/or a list passed in as .list. Returns a named list where the names are the keys, and the values are the values.

get(key, missing = missing_default)

Get a value corresponding to key. If the key is not in the map, return missing.

mget(keys, missing = missing_default)

Get values corresponding to keys, which is a character vector. The values will be returned in a named list where the names are the same as the keys passed in, in the same order. For keys not in the map, they will have missing for their value.

has(keys)

Given a vector of keys, returns a logical vector reporting whether each key is contained in the map.

remove(keys)

Given a vector of keys, remove the key-value pairs from the map. Returns a logical vector reporting whether each item existed in (and was removed from) the map.

keys(sort = FALSE)

Returns a character vector of all the keys. By default, the keys will be in arbitrary order. Note that the order can vary across platforms and is not guaranteed to be consistent. With sort=TRUE, the keys will be sorted according to their Unicode code point values.

size()

Returns the number of items in the map.

clone()

Returns a copy of the fastmap object. This is a shallow clone; objects in the fastmap will not be copied.

as_list(sort = FALSE)

Return a named list where the names are the keys from the map, and the values are the values. By default, the keys will be in arbitrary order. Note that the order can vary across platforms and is not guaranteed to be consistent. With sort=TRUE, the keys will be sorted according to their Unicode code point values.

reset()

Reset the fastmap object, clearing all items.

Examples

# Create the fastmap object
m <- fastmap()

# Set some key-value pairs
m$set("x", 100)
m$set("letters", c("a", "b", "c"))
m$mset(numbers = c(10, 20, 30), nothing = NULL)

# Get values using keys
m$get("x")
m$get("numbers")
m$mget(c("letters", "numbers"))

# Missing keys return NULL by default, but this can be customized
m$get("xyz")

# Check for existence of keys
m$has("x")
m$has("nothing")
m$has("xyz")

# Remove one or more items
m$remove(c("letters", "x"))

# Return number of items
m$size()

# Get all keys
m$keys()

# Return named list that represents all key-value pairs
str(m$as_list())

# Clear the map
m$reset()


# Specify missing value when get() is called
m <- fastmap()
m$get("x", missing = key_missing())
#> <Key Missing>

# Specify the default missing value
m <- fastmap(missing_default = key_missing())
m$get("x")
#> <Key Missing>