hashtable {r2r}

Hash maps and sets

Description

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.

Usage

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
)

Arguments

...

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

hash_fn

the (string valued) hash function applied to keys. Required for advanced use only; see Details.

compare_fn

the (boolean valued) comparison function used for testing key equality. Required for advanced use only; see Details.

key_preproc_fn

key pre-processing function applied to keys before hashing and comparison. Required for advanced use only; see Details.

on_missing_key

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

default value associated with missing keys. This will be returned only if on_missing_key is equal to "default".

Details

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.

Value

a hashmap and a hashset class object for hashmap() and hashset(), respectively.

Author(s)

Valerio Gherardi

See Also

hashtable_methods

Examples

m <- hashmap(
        list("foo", 1),
        list("bar", 1:5),
        list(data.frame(x = letters, y = LETTERS), "baz")
        )
m[[ data.frame(x = letters, y = LETTERS) ]]

# Set of character keys, case insensitive.
s <- hashset("A", "B", "C", key_preproc = tolower)
s[["a"]]