dictS3: A Dictionary

In rpahl/container: Extending Base 'R' Lists

A Dictionary

Description

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.

Usage

dict(...)

as.dict(x)

is.dict(x)

Arguments

...	elements put into the Dict.
x	R object of ANY type for as.dict() and is.dict() or of class Dict for the S3 methods.

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 class Dict

• as.dict(x) coerces x to a dictionary

• is.dict(x) returns TRUE if x is of class Dict and FALSE otherwise.

• x + y combines x and y into a new dict by updating x by y (see also ⁠[update()]⁠).

• x - y removes all keys from x that appear in y.

• x & y returns a copy of x keeping only the keys that are common in both (key intersection), that is, all keys in x that do not exist in y are removed.

• x | y returns a copy of x extended by all elements of y that are stored at keys (or names) that do not exist in x, thereby combining the keys of both objects (set union of keys).

• add(.x, ...) and ref_add(.x, ...) adds key = value pairs to .x. If any of the keys already exists, an error is given.

• replace(.x, old, new) and ref_replace(.x, old) try to find element old and replace it with element new. If old does not exist, an error is raised.

• update(object, other) and ref_update(object, other) adds elements of other dict for keys not yet in object 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)
names(d)

try(dict(a = 1, 2))   # all elements must be named

# Coercion
as.dict(list(A = 1:3, B = "b"))
as.dict(c(x = 1, y = "x", z = 2 + 3))
# Math
d = dict(a = rnorm(1), b = rnorm(1))
abs(d)
cumsum(d)
round(d)
exp(d)

# Summary
range(d)
min(d)
max(d)

d1 = dict(a = 1, b = list(1, 2))
d2 = dict(a = 2, b = list(1, 2))
d1 + d2      # same as update(d, d2)
d2 + d1      # same as update(d2, d)
try({
c(d1, d2)    # duplicated keys are not allowed for Dict
})
d1 - d2
d2 - d1
d1 - d1

d1 = dict(a = 1, b = 2)
d2 = dict(a = 10, x = 4)
d1 & d2      # {a = 1}

d1 | d2      # {a = 1, b = 2, x = 4}


d = dict(a = 1)
add(d, b = 2, co = container(1:3))

try(add(d, a = 7:9))  # key 'a' already in Dict

d = dict(a = 1, b = "z")
replace(d, 1, 1:5)
replace(d, "z", "a")

try({
replace(d, "a", 2)              # 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}
update(d2, d1)  # {a = 1, b = 2, c = 3}

rpahl/container documentation built on Nov. 10, 2023, 6:31 p.m.