hashtable: Hash maps and sets
In r2r: R-Object to R-Object Hash Maps

Description Usage Arguments Details Value Author(s) See Also Examples

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

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.

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

Valerio Gherardi

hashtable_methods

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"]]