A fastmap object provides a key-value store where the keys are strings and the values are any R objects.
fastmap(missing_default = NULL)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.
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.
# 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")
#> [1] 100
m$get("numbers")
#> [1] 10 20 30
m$mget(c("letters", "numbers"))
#> $letters
#> [1] "a" "b" "c"
#>
#> $numbers
#> [1] 10 20 30
#>
# Missing keys return NULL by default, but this can be customized
m$get("xyz")
#> NULL
# Check for existence of keys
m$has("x")
#> [1] TRUE
m$has("nothing")
#> [1] TRUE
m$has("xyz")
#> [1] FALSE
# Remove one or more items
m$remove(c("letters", "x"))
# Return number of items
m$size()
#> [1] 2
# Get all keys
m$keys()
#> [1] "nothing" "numbers"
# Return named list that represents all key-value pairs
str(m$as_list())
#> List of 2
#> $ nothing: NULL
#> $ numbers: num [1:3] 10 20 30
# Clear the map
m$reset()
# Specify missing value when get() is called
m <- fastmap()
m$get("x", missing = key_missing())
#> <Key Missing>
#> <Key Missing>
# Specify the default missing value
m <- fastmap(missing_default = key_missing())
m$get("x")
#> <Key Missing>
#> <Key Missing>