container (version 1.0.5)

ContainerS3: Container - Enhancing R's list

Description

A container is a data structure with typical member functions to insert, delete and access elements from the container object. It can be considered as a base R list with extended functionality. The Container class also serves as the base class for Deque, Set, and Dict objects.

Usage

container(...)
cont(...)
as.container(x)
as.cont(x)
is.container(x)
# S3 method for Container
as.list(x, ...)
# S3 method for Container
length(x)
# S3 method for Container
names(x)
# S3 method for Container
names(x) <- value

Arguments

...

(possibly named) elements to be put into or removed from the Container, or additional arguments passed from and to methods.

x

R object of ANY type for as.container and is.container or of class Container for the S3 methods.

value

character vector of names.

Details

Methods that alter Container 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().

• container(...) initializes and returns a Container object.

• cont(...) is a short cut for container(...).

• as.container(x) or as.cont(x) coerce x to a Container

• is.container(x) check if x is a Container

• as.list(x) converts container x to a base R list. All of the container's elements are copied (deeply) during the conversion.

• length(x) return the number of elements contained in x.

• names(x) return the names of the elements contained in x.

• names(x) <- value sets the names of x.

• x + y combines x and y into a new container by appending y to x.

• x - y element-wise discards all items of y from x, given the element was contained in x. The result is always a container.

• x == y is TRUE if the contents of x and y are lexicographically equal.

• x != y is TRUE if the contents of x and y are not equal.

• x < y is TRUE if the contents of x are lexicographically less than the contents of y.

• x <= y is TRUE if the contents of x are lexicographically less than or equal to the contents of y.

• add(.x, ...) and ref_add(.x, ...) add elements to .x.

• at(.x, ...,) returns the value at the given indices. Indices can be letters or numbers or both. All indices must exist.

• at2(x, index) returns the value at the given index or signals an error if not found.

• clear(x) and ref_clear(x) remove all elements from x.

• clone(x) create a copy of x.

• count(x, elem) count how often elem occurs in x.

• delete(.x, ...) and ref_delete(.x, ...) find and remove elements. If one or more elements don't exist, an error is signaled.

• delete_at(.x, ...) and ref_delete_at(.x, ...) find and remove values at given indices. If any given index is invalid, an error is signaled.

• discard(.x, ...) and ref_discard(.x, ...) find and discard elements. Elements that don't exist, are ignored.

• discard_at(.x, ...) and ref_discard_at(.x, ...) find and discard values at given indices. Invalid indices are ignored.

• has(x, elem) TRUE if element is in x and otherwise FALSE.

• has_name(x, name) check if name is in x

• is_empty(x) TRUE if object is empty otherwise FALSE

• peek_at(x, ..., .default = NULL) returns the value at the given indices or (if not found) the given default value.

• peek_at2(x, index, default) returns the value at the given index or (if not found) the given default value.

• ref_pop(.x, index) return element at given index and remove it from the container object.

• rename(.x, old, new) and ref_rename(.x, old, new) rename one or more keys from old to new, respectively, by copy and in place (i.e. by reference).

• replace(.x, old, new, add = FALSE) and ref_replace(.x, old, new, add = FALSE) try to find element old and replace it with element new. If old does not exist, an error is raised, unless add was set to TRUE.

• replace_at(.x, .., .add = FALSE) and ref_replace_at(.x, ..., .add = FALSE) replace values at given indices. If a given index is invalid, an error is signaled unless .add was set to TRUE.

See Also

For the class documentation see Container. Objects of the derived classes can be created by deque, setnew, and dict.

Examples

co = container(1:5, c = container("a", 1), l = list())
is.container(co)
print(co)
length(co)
names(co)

unpack(co)   # flatten recursively similar to unlist

# Math
co = container(1, 2, -(3:5))
co
abs(co)
cumsum(co)
round(co)
exp(co)

# Summary
range(co)
min(co)
max(co)

# Arithmetic
c1 = container(1, 1:2)
c2 = container(2, 1:2)
c1 + c2     # same as c(c1, c2)
c2 + c1     # same as c(c2, c1)

c1 - c2
c2 - c1
c1 - c1

# Comparison
c1 = container(1, 2, 3)
c2 = container(1, 3, 2)
c1 == c1            # TRUE
c1 != c2            # TRUE
c1 <= c1            # TRUE
c1 == c2            # FALSE
c1 < c2             # TRUE
c1 < container(2)   # TRUE
c1 < container()    # FALSE

# Extract or replace
co = container(a = 1, b = 2, c = 3, d = 4)
co[1:2]
co[1, 4]
co["d", 2]
co[list("d", 2)]
co[0:10]

co = container(a = 1, b = 2)
co[[1]]
co[["a"]]
co[["x"]]
co = container(a = 1, b = "bar")
(co[1:2] <- 1:2)

try({
co[3] <- 3 # index out of range
})
(co[list(1, "b")] <- 3:4)   # mixed numeric/character index

co = container(a = 1, b = 2)
co[[1]] <- 9
co[["b"]] <- 8
co[["x"]] <- 7
co$z <- 99
print(co)

# Replace 8 by 0
co[[{8}]] <- 0
print(co)


co = container(a = 1, b = "bar")
co$f <- 3
co$b <- 2
co


co = container(1)
add(co, 1, b = 2, c = container(1:3))


co = container(a = 1, 2, b = 3, 4)
at(co, 1:3)
at(co, "a", "b", 2)
try(at(co, "x"))     # index 'x' not found
try(at(co, 1:10))    # index 5 exceeds length of Container

co = container(a = 1, 2, b = 3, 4)
at2(co, 1)
at2(co, "a")
at2(co, 2)
try(at2(co, "x"))     # index 'x' not found
try(at2(co, 5))       # index 5 exceeds length of Container

co = container(1, 2, mean)
clear(co)
print(co)    # Original was not touched
ref_clear(co)   # Clears original
print(co)

co = container(1, 2, 3)
co2 = clone(co)
co == co2

co = container("a", "b", "a", mean, mean)
count(co, "a")
count(co, mean)
count(co, "c")

co = container("a", 1:3, iris)
print(co)
delete(co, 1:3, "a")
delete(co, iris)
try({
delete(co, "b")   # "b" is not in Container
})

co = container(a = 1, b = 2, 3)
delete_at(co, "a", "b")          # [3]
delete_at(co, 1:2)               # [3]
delete_at(co, "a", 3)            # [b = 2]
try({
 delete_at(co, 4)                 # index out of range
 delete_at(co, "x")               # names(s) not found: 'x'
})

co = container("a", num = 1:3, data = iris)
print(co)
discard(co, 1:3, "a")
discard(co, iris)
discard(co, "b")  # ignored

co = container(a = 1, b = 2, 3)
discard_at(co, "a", "b")         # [3]
discard_at(co, 1:2)              # [3]
discard_at(co, "a", 3)           # [b = 2]
discard_at(co, "x")              # ignored

co = container(1, 2, mean)
has(co, 1)                   # TRUE
has(co, mean)                # TRUE
has(co, 1:2)                 # FALSE

co = container(a = 1, 2, f = mean)
has_name(co, "a")    # TRUE
has_name(co, "f")    # TRUE
has_name(co, "2")    # FALSE

co = container(1, 2)
is_empty(co)
is_empty(clear(co))

co = container(a = 1, 2, b = 3, 4)
peek_at(co, 1)
peek_at(co, "a")
peek_at(co, "x")
peek_at(co, "x", .default = 0)
peek_at(co, "a", "x", 2, 9, .default = -1)

co = container(a = 1, 2, b = 3, 4)
peek_at2(co, 1)
peek_at2(co, "a")
peek_at2(co, "x")
peek_at2(co, "x", default = 0)

co = container(a = 1, b = 1:3, d = "foo")
ref_pop(co, "b")
ref_pop(co, 1)

try({
ref_pop(co, "x")  # index 'x' not found
})
co = container(a = 1, b = 2, 3)
rename(co, c("a", "b"), c("a1", "y"))
print(co)
ref_rename(co, c("a", "b"), c("a1", "y"))
print(co)

co = container("x", 9)
replace(co, 9, 0)
replace(co, "x", 0)
try({
replace(co, "z", 0)              # old element ("z") is not in Container
})
replace(co, "z", 0, add = TRUE)  # ok, adds the element

co = container(a = 0, b = "z")
replace_at(co, a = 1, b = 2)
replace_at(co, 1:2, 1:2)                 # same
replace_at(co, c("a", "b"), list(1, 2))  # same

try({
replace_at(co, x = 1)                    # names(s) not found: 'x'
})
replace_at(co, x = 1, .add = TRUE)       # ok (adds x = 1)