| hashtab {utils} | R Documentation |
Create and manipulate mutable hash tables.
hashtab(type = c("identical", "address"), size)
gethash(h, key, nomatch = NULL)
sethash(h, key, value)
remhash(h, key)
numhash(h)
typhash(h)
maphash(h, FUN)
clrhash(h)
is.hashtab(x)
## S3 method for class 'hashtab'
h[[key, nomatch = NULL, ...]]
## S3 replacement method for class 'hashtab'
h[[key, ...]] <- value
## S3 method for class 'hashtab'
print(x, ...)
## S3 method for class 'hashtab'
format(x, ...)
## S3 method for class 'hashtab'
length(x)
## S3 method for class 'hashtab'
str(object, ...)
type |
|
size |
an integer specifying the expected number of entries. |
h, object |
a hash table. |
key |
an R object to use as a key. |
nomatch |
value to return if |
value |
new value to associate with |
FUN |
a |
x |
object to be tested, printed, or formatted. |
... |
additional arguments. |
Hash tables are a data structure for efficiently associating keys with
values. Hash tables are similar to environments, but
keys can be arbitrary objects. Like environments, and unlike named
lists and most other objects in R, hash tables are mutable, i.e., they
are not copied when modified and assignment means just giving a
new name to the same object.
New hash tables are created by hashtab. Two variants are
available: keys can be considered to match if they are
identical() (type = "identical", the default), or
if their addresses in memory are equal (type = "address"). The
default "identical" type is almost always the right choice.
The size argument provides a hint for setting the initial
hash table size. The hash table will grow if necessary, but specifying
an expected size can be more efficient.
gethash returns the value associated with key. If
key is not present in the table, then the value of
nomatch is returned.
sethash adds a new key/value association or changes the current
value for an existing key. remhash removes the entry for
key, if there is one.
maphash calls FUN for each entry in the hash table with
two arguments, the entry key and the entry value. The order in which
the entries are processed is not predictable. The consequence of
FUN adding entries to the table or deleting entries from the
table is also not predictable, except that removing the entry
currently being processed will have the desired effect.
clrhash removes all entries from the hash table.
hashtab returns a new hash table of the specified type.
gethash returns the value associated with key, or
nomatch if there is no such value.
sethash returns value invisibly.
remhash invisibly returns TRUE if an entry for
key was found and removed, and FALSE if no entry was
found.
numhash returns the current number of entries in the table.
typhash returns a character string specifying the type of the
hash table, one of "identical" or "address".
maphash and clrhash return NULL invisibly.
The interface design is based loosely on hash table support in Common Lisp.
The hash function and equality test used for "identical" hash
tables are the same as the ones used internally by
duplicated and unique, with two
exceptions:
Closure environments are not ignored when comparing closures.
This corresponds to calling identical() with
ignore.environment = FALSE, which is the default for
identical().
External pointer objects are compared as reference objects,
corresponding to calling identical() with
extptr.as.ref = TRUE. This ensures that hash tables with
keys containing external pointers behave reasonably when
serialized and unserialized.
As an experimental feature, the element operator [[ can also be
used get or set hash table entries, and length can be used to
obtain the number of entries. It is not yet clear whether this is a
good idea.
## Create a new empty hash table.
h1 <- hashtab()
h1
## Add some key/value pairs.
sethash(h1, NULL, 1)
sethash(h1, .GlobalEnv, 2)
for (i in seq_along(LETTERS)) sethash(h1, LETTERS[i], i)
## Look up values for some keys.
gethash(h1, NULL)
gethash(h1, .GlobalEnv)
gethash(h1, "Q")
## Remove an entry.
(remhash(h1, NULL))
gethash(h1, NULL)
(remhash(h1, "XYZ"))
## Using the element operator.
h1[["ABC"]]
h1[["ABC", nomatch = 77]]
h1[["ABC"]] <- "DEF"
h1[["ABC"]]
## Integers and real numbers that are equal are considered different
## (not identical) as keys:
identical(3, 3L)
sethash(h1, 3L, "DEF")
gethash(h1, 3L)
gethash(h1, 3)
## Two variables can refer to the same hash table.
h2 <- h1
identical(h1, h2)
## set in one, see in the "other" <==> really one object with 2 names
sethash(h2, NULL, 77)
gethash(h1, NULL)
str(h1)
## An example of using maphash(): get all hashkeys of a hash table:
hashkeys <- function(h) {
val <- vector("list", numhash(h))
idx <- 0
maphash(h, function(k, v) { idx <<- idx + 1
val[idx] <<- list(k) })
val
}
## IGNORE_RDIFF_BEGIN
kList <- hashkeys(h1)
str(kList) # the *order* is "arbitrary" & cannot be "known"
## IGNORE_RDIFF_END