A Dictionary
Source:R/0-DictS3.R
, R/GroupGenericMath.R
, R/GroupGenericSummary.R
, and 5 more
dictS3.Rd
The Dict initially was developed to resemble Python's dict type, but by now offers both more features and flexibility, for example, by providing both associative key-value pair as well as positional array semantics. It is implemented as a specialized associative Container thus sharing all Container methods with some of them being adapted to account for the key-value pair semantic. All elements must be named.
Details
Internally, all key-value pairs are stored in a hash-table and the
elements are sorted lexicographically by their keys.
Methods that alter Dict
objects usually come in two versions
providing either copy or reference semantics where the latter start with
'ref_'
to note the reference semantic, for example, add()
and ref_add()
.
dict(...)
initializes and returns an object of classDict
as.dict(x)
coercesx
to a dictionary
is.dict(x)
returnsTRUE
ifx
is of classDict
andFALSE
otherwise.
x + y
combinesx
andy
into a new dict by updatingx
byy
(see also[update()]
).
x - y
removes all keys fromx
that appear iny
.
x
&
y
returns a copy ofx
keeping only the keys that are common in both (key intersection), that is, all keys inx
that do not exist iny
are removed.
x
|
y
returns a copy ofx
extended by all elements ofy
that are stored at keys (or names) that do not exist inx
, thereby combining the keys of both objects (set union of keys).
add(.x, ...)
andref_add(.x, ...)
addskey = value
pairs to.x
. If any of the keys already exists, an error is given.
replace(.x, old, new)
andref_replace(.x, old)
try to find elementold
and replace it with elementnew
. Ifold
does not exist, an error is raised.
update(object, other)
andref_update(object, other)
adds elements ofother
dict for keys not yet inobject
and replaces the values of existing keys.
See also
See container()
for all inherited methods. For the full class
documentation see Dict and it's superclass Container.
Examples
d = dict(b = "one", a = 1, f = mean, na = NA)
print(d)
#> {a = 1, b = "one", f = <<function>>, na = NA}
names(d)
#> [1] "a" "b" "f" "na"
try(dict(a = 1, 2)) # all elements must be named
#> Error : all elements must be named
# Coercion
as.dict(list(A = 1:3, B = "b"))
#> {A = (1L 2L 3L), B = "b"}
as.dict(c(x = 1, y = "x", z = 2 + 3))
#> {x = "1", y = "x", z = "5"}
# Math
d = dict(a = rnorm(1), b = rnorm(1))
abs(d)
#> {a = 1.400044, b = 0.2553171}
cumsum(d)
#> {a = -1.400044, b = -1.144726}
round(d)
#> {a = -1, b = 0}
exp(d)
#> {a = 0.2465862, b = 1.290871}
# Summary
range(d)
#> [1] -1.4000435 0.2553171
min(d)
#> [1] -1.400044
max(d)
#> [1] 0.2553171
d1 = dict(a = 1, b = list(1, 2))
d2 = dict(a = 2, b = list(1, 2))
d1 + d2 # same as update(d, d2)
#> {a = 2, b = list(1, 2)}
d2 + d1 # same as update(d2, d)
#> {a = 1, b = list(1, 2)}
try({
c(d1, d2) # duplicated keys are not allowed for Dict
})
#> Error : duplicated keys are not allowed
d1 - d2
#> {}
d2 - d1
#> {}
d1 - d1
#> {}
d1 = dict(a = 1, b = 2)
d2 = dict(a = 10, x = 4)
d1 & d2 # {a = 1}
#> {a = 1}
d1 | d2 # {a = 1, b = 2, x = 4}
#> {a = 1, b = 2, x = 4}
d = dict(a = 1)
add(d, b = 2, co = container(1:3))
#> {a = 1, b = 2, co = [(1L 2L 3L)]}
try(add(d, a = 7:9)) # key 'a' already in Dict
#> Error : name 'a' exists already
d = dict(a = 1, b = "z")
replace(d, 1, 1:5)
#> {a = (1L 2L 3L 4L ...), b = "z"}
replace(d, "z", "a")
#> {a = 1, b = "a"}
try({
replace(d, "a", 2) # old element ("a") is not in Dict
})
#> Error : old element ("a") is not in Dict
d1 = dict(a = 1, b = 2)
d2 = dict( b = 0, c = 3)
update(d1, d2) # {a = 1, b = 0, c = 3}
#> {a = 1, b = 0, c = 3}
update(d2, d1) # {a = 1, b = 2, c = 3}
#> {a = 1, b = 2, c = 3}