| Title: | R-Object to R-Object Hash Maps |
|---|---|
| Description: | Implementation of hash tables (hash sets and hash maps) in R, featuring arbitrary R objects as keys, arbitrary hash and key-comparison functions, and customizable behaviour upon queries of missing keys. |
| Authors: | Valerio Gherardi [aut, cre] |
| Maintainer: | Valerio Gherardi <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.2 |
| Built: | 2024-11-09 10:41:37 UTC |
| Source: | https://github.com/vgherard/r2r |
Returns the key comparison function of an hash table
(hashset or hashmap).
compare_fn(x) ## S3 method for class 'r2r_hashtable' compare_fn(x)compare_fn(x) ## S3 method for class 'r2r_hashtable' compare_fn(x)
x |
an |
a function.
Valerio Gherardi
s <- hashset() compare_fn(s)s <- hashset() compare_fn(s)
hashmap valuesThese generics are used to get or set the default value of an
hashmap, optionally returned upon query of a missing key.
default(x) default(x) <- value ## S3 method for class 'r2r_hashmap' default(x) ## S3 replacement method for class 'r2r_hashmap' default(x) <- valuedefault(x) default(x) <- value ## S3 method for class 'r2r_hashmap' default(x) ## S3 replacement method for class 'r2r_hashmap' default(x) <- value
x |
an |
value |
an arbitrary R object. Default value to be associated to missing
keys in the |
For more details, see the hashtable documentation page.
an arbitrary R object.
Valerio Gherardi
m <- hashmap() default(m) default(m) <- 840m <- hashmap() default(m) default(m) <- 840
generates string hashes for arbitrary R objects as follows.
This is the default hash function used by hashsets and hashmaps
objects.
default_hash_fn(key)default_hash_fn(key)
key |
an arbitrary R object. |
If key is an atomic vector (as tested by
is.atomic(key)) of length one, default_hash_fn(key) simply
coerces the input to character. For more complex inputs, the function calls
digest(key) from the digest package.
a character vector of length one. Hash digest of key.
Valerio Gherardi
These generics are used for deleting a single key or key/value
pair from an hashset or hashmap, respectively.
delete(x, key) ## S3 method for class 'r2r_hashmap' delete(x, key) ## S3 method for class 'r2r_hashset' delete(x, key)delete(x, key) ## S3 method for class 'r2r_hashmap' delete(x, key) ## S3 method for class 'r2r_hashset' delete(x, key)
x |
an |
key |
an arbitrary R object. Key to be deleted from the hash table. |
NULL, invisibly.
Valerio Gherardi
s <- hashset(1, 2, 3) delete(s, 3) s[[3]]s <- hashset(1, 2, 3) delete(s, 3) s[[3]]
This generics are used to check whether a key exists in a given
hashset or hashmap.
has_key(x, key) x %has_key% key ## S3 method for class 'r2r_hashmap' has_key(x, key) ## S3 method for class 'r2r_hashset' has_key(x, key)has_key(x, key) x %has_key% key ## S3 method for class 'r2r_hashmap' has_key(x, key) ## S3 method for class 'r2r_hashset' has_key(x, key)
x |
an |
key |
an arbitrary R object. Key to be checked for existence in the hash table. |
TRUE or FALSE.
Valerio Gherardi
m <- hashmap(list("a", 1), list("b", 2)) has_key(m, "a") m %has_key% "b"m <- hashmap(list("a", 1), list("b", 2)) has_key(m, "a") m %has_key% "b"
Returns the hash function used for key hashing in an hash table
(hashset or hashmap).
hash_fn(x) ## S3 method for class 'r2r_hashtable' hash_fn(x)hash_fn(x) ## S3 method for class 'r2r_hashtable' hash_fn(x)
x |
an |
a function.
Valerio Gherardi
s <- hashset() hash_fn(s)s <- hashset() hash_fn(s)
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 )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 |
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 |
default |
default value associated with missing keys. This will be
returned only if |
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
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"]]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"]]
hashmap and hashset
This page provides an overview of the available methods for
hashmap and hashset objects (and for their common parent class
hashtable). We list methods based on the general type of task
addressed.
insert()
delete()
query()
subsetting_hashtables: `[[`, `[[<-`, `[`
and `[<-`
Valerio Gherardi
These generics are used for inserting a single key or key/value
pair into an hashset or hashmap, respectively. For vectorized
insertions, see the subsetting_hashtables documentation page.
insert(x, key, ...) ## S3 method for class 'r2r_hashmap' insert(x, key, value, ...) ## S3 method for class 'r2r_hashset' insert(x, key, ...)insert(x, key, ...) ## S3 method for class 'r2r_hashmap' insert(x, key, value, ...) ## S3 method for class 'r2r_hashset' insert(x, key, ...)
x |
an |
key |
an arbitrary R object. Key to be inserted into the hash table. |
... |
further arguments passed to or from other methods. |
value |
an arbitrary R object. Value associated to |
key for the hashset method,
value for the hashmap method.
Valerio Gherardi
s <- hashset() insert(s, "foo") s[["foo"]]s <- hashset() insert(s, "foo") s[["foo"]]
These generics are used for listing all keys registered in an
hashset or hashmap, respectively.
keys(x) ## S3 method for class 'r2r_hashtable' keys(x)keys(x) ## S3 method for class 'r2r_hashtable' keys(x)
x |
an |
a list. Registered keys in the hash table x.
Valerio Gherardi
s <- hashset(1, 2, 3) keys(s)s <- hashset(1, 2, 3) keys(s)
Returns the total number of keys in an hash table.
## S3 method for class 'r2r_hashtable' length(x)## S3 method for class 'r2r_hashtable' length(x)
x |
an |
an integer. Number of keys in the hash table (or elements in a set).
Valerio Gherardi
s <- hashset() insert(s, "foo") length(s)s <- hashset() insert(s, "foo") length(s)
These generics are used to get or set the behaviour of an
hashmap upon query of a missing key (currently, only an
hashmap method is implemented).
on_missing_key(x) on_missing_key(x) <- value ## S3 method for class 'r2r_hashmap' on_missing_key(x) ## S3 replacement method for class 'r2r_hashmap' on_missing_key(x) <- valueon_missing_key(x) on_missing_key(x) <- value ## S3 method for class 'r2r_hashmap' on_missing_key(x) ## S3 replacement method for class 'r2r_hashmap' on_missing_key(x) <- value
x |
an |
value |
a string, either |
For more details, see the hashtable documentation page.
a string, either "throw" or "default".
Valerio Gherardi
m <- hashmap() on_missing_key(m) on_missing_key(m) <- "throw"m <- hashmap() on_missing_key(m) on_missing_key(m) <- "throw"
These generics are used for querying a single key from an
hashset or hashmap, respectively. For vectorized queries,
see the subsetting_hashtables documentation page.
query(x, key) ## S3 method for class 'r2r_hashmap' query(x, key) ## S3 method for class 'r2r_hashset' query(x, key)query(x, key) ## S3 method for class 'r2r_hashmap' query(x, key) ## S3 method for class 'r2r_hashset' query(x, key)
x |
an |
key |
an arbitrary R object. Key to be queried from the hash table. |
TRUE or FALSE, for hashsets. For
hashmaps, if the queried key exists in the hash table, returns the
associated value (an a priori arbitrary R object); otherwise, behaves as
specified by on_missing_key(x)
(see also hashtable).
Valerio Gherardi
s <- hashset(1, 2, 3) query(s, 3)s <- hashset(1, 2, 3) query(s, 3)
hashsets and hashmapsSubsetting operators `[[` and `[` for
hashsets and hashmaps provide an equivalent synthax for the
basic read/write operations performed by insert(),
delete() and query().
## S3 method for class 'r2r_hashmap' x[[i]] ## S3 method for class 'r2r_hashmap' x[i] ## S3 replacement method for class 'r2r_hashmap' x[[i]] <- value ## S3 replacement method for class 'r2r_hashmap' x[i] <- value ## S3 method for class 'r2r_hashset' x[[i]] ## S3 method for class 'r2r_hashset' x[i] ## S3 replacement method for class 'r2r_hashset' x[[i]] <- value ## S3 replacement method for class 'r2r_hashset' x[i] <- value## S3 method for class 'r2r_hashmap' x[[i]] ## S3 method for class 'r2r_hashmap' x[i] ## S3 replacement method for class 'r2r_hashmap' x[[i]] <- value ## S3 replacement method for class 'r2r_hashmap' x[i] <- value ## S3 method for class 'r2r_hashset' x[[i]] ## S3 method for class 'r2r_hashset' x[i] ## S3 replacement method for class 'r2r_hashset' x[[i]] <- value ## S3 replacement method for class 'r2r_hashset' x[i] <- value
x |
an |
i |
for |
value |
for |
the replacement forms ([[<- and [<-) always return value.
`[[` returns TRUE or FALSE if
x is an hashset, an arbitrary R object if x is an
hashmap and i is a valid key; when i is not a key, the
behaviour for hashmaps depends on the value of
on_missing_key(x).
The `[` operator returns a list of the same length of i, whose
k-th element is given by x[[ i[[k]] ]] (the remark on missing keys for
hashmaps applies also here).
Valerio Gherardi
This function is used to list all values associated to keys in
an hashmap. Implemented as a generic, but currently only the
hashmap method is defined.
values(x) ## S3 method for class 'r2r_hashmap' values(x)values(x) ## S3 method for class 'r2r_hashmap' values(x)
x |
an |
a list. Values associated to keys in the hash map x.
Valerio Gherardi
m <- hashmap(list("a", 1), list("b", 2)) values(m)m <- hashmap(list("a", 1), list("b", 2)) values(m)