Objects of class hashmap and hashset store
collections of key/value pairs (hashmap), or just keys
(hashset), providing constant time read and write operations. Both
the keys and the optional values can be arbitrary R objects. hashmaps
and hashsets provide an R implementation of
hash tables.
See hashtable_methods for an overview of the available methods
for hashmap and hashset class objects. Note that both these
classes have a common parent class hashtable, from which they can also
inherit S3 methods.
hashmap(
...,
hash_fn = default_hash_fn,
compare_fn = identical,
key_preproc_fn = identity,
on_missing_key = "default",
default = NULL
)
hashset(
...,
hash_fn = default_hash_fn,
compare_fn = identical,
key_preproc_fn = identity
)these arguments can be used to specify a set of initial elements
to be inserted in the hashmap or hashset. For hashmap(),
each of these should be a list of two elements (a key-value pair).
the (string valued) hash function applied to keys. Required for advanced use only; see Details.
the (boolean valued) comparison function used for testing key equality. Required for advanced use only; see Details.
key pre-processing function applied to keys before hashing and comparison. Required for advanced use only; see Details.
either "throw" or "default".
In the second case, an exception is thrown upon query of a missing key; otherwise, a default value
(specified through the default argument) is returned.
default value associated with missing keys. This will be
returned only if on_missing_key is equal to "default".
a hashmap and a hashset class object for
hashmap() and hashset(), respectively.
hashmaps and hashsets implement hash tables,
building on top of base R built-in environments,
which by themselves are, essentially, string -> R object hash maps.
In order to handle keys of non-string type, a string valued hash function
default_hash_fn() is provided, which leverages on
digest() for handling arbitrary R object keys.
By default, key equality is tested through identical().
For some use cases, it may be sensible to employ a different comparison
function, which can be assigned through the compare_fn argument. In this
case, one must also make sure that equal (in the sense of
compare_fn())
keys get also assigned the same hashes by hash_fn(). A simple way to
ensure this is to use to use a key pre-processing function, to be applied
before both key hashing and comparison. The key_preproc_fn
argument provides a short-cut to this, by automatically composing both the
provided hash_fn() and compare_fn() functions with
key_preproc_fn() function. This is illustrated in an example below.
One might also want to set set specific hash and/or key comparison functions
for efficiency reasons, e.g. if the default_hash_fn() function produces
many collisions between inequivalent keys.
When on_missing_key is equal to "throw", querying a missing
key will cause an error. In this case, an rlang abort
condition of class "r2r_missing_key" is returned, which can be useful
for testing purposes.
m <- hashmap(
list("foo", 1),
list("bar", 1:5),
list(data.frame(x = letters, y = LETTERS), "baz")
)
m[[ data.frame(x = letters, y = LETTERS) ]]
#> [1] "baz"
# Set of character keys, case insensitive.
s <- hashset("A", "B", "C", key_preproc = tolower)
s[["a"]]
#> [1] FALSE