container (version 1.1.0)

OpsExtract: Extract Parts of a Container

Description

Operators that extract parts of a Container. The behavior is similar to base R lists and includes convenient extensions for interactive work.

Usage

# S3 method for Container
[(x, i, ..., .default = NULL)
# S3 method for Container
[[(x, i)

Value

For [ a Container. For [[ the extracted value or NULL.

Arguments

x

A Container from which to extract elements.

i, ...

Indices specifying elements to extract. Indices may be numeric, character, logical, NULL, or empty. Logical vectors are recycled as needed. Negative integers drop by position. Negative character indices drop by name. Range expressions such as a:b, 1:c, or d:2 are supported for convenience and are resolved in the calling environment.

.default

A value used to fill missing items when extracting. If given, unknown names and out-of-bounds positive indices are kept and filled with this value.

Warning

Range expressions such as x[a:b] are intended for interactive use, where the resulting indices can be easily inspected and corrected by the user. They are convenient for quick exploration and data analysis, but not intended for programming, where explicit indices should be used instead to avoid unexpected results.

Details

The [ operator selects one or more elements and returns a Container. Order is preserved and duplicates are kept. Logical indices recycle to the container length with a warning when lengths do not match. NA in logical indices is treated as FALSE with a warning. Positive and negative numeric indices cannot be mixed in a single call and will raise an error. Out-of-bounds negative indices are ignored. Character indices match names. Unknown names are ignored unless .default is supplied, in which case they are kept and filled. Comma-separated indices and list(...) are accepted and behave like a single combined index.

The [[ operator selects a single element and returns the value or NULL if the element is not present.

See Also

peek_at for lenient extraction with defaults, at and at2 for strict programmatic access, and base [, [[, and $ for general indexing semantics.

Examples

co <- container(a = 1, b = 2, c = 3, d = 4)

# Numeric
co[c(1, 4)]                          # [a = 1, d = 4]
co[1, 4]                             # same (comma-sugar)
co[1, 1]                             # duplicates kept -> [a = 1, a = 1]
co[0:5]                              # unknowns ignored -> [a = 1, b = 2, c = 3, d = 4]
co[5]                                # [] (unknown positive index)

# Negative numeric
co[-c(1:2)]                          # [c = 3, d = 4]
co[-1, -4]                           # [b = 2, c = 3]
try(co[-1, 3])                       # error: cannot mix positive & negative
co[-5]                               # out-of-bounds negatives ignored -> full container

# Character
co[c("a", "d")]                      # [a = 1, d = 4]
co["a", "d"]                         # same
co[letters[1:5]]                     # unknown names dropped -> [a = 1, b = 2, c = 3, d = 4]
co["x"]                              # []

# Negative character (drop by name)
co[-c("a", "d")]                     # [b = 2, c = 3]
co[-"a", -"d"]                       # [b = 2, c = 3]

# Logical
co[c(TRUE, FALSE, TRUE, FALSE)]      # [a = 1, c = 3]
co[TRUE, FALSE]                      # [a = 1, c = 3] (recycled)
co[c(TRUE, NA)]                      # [a = 1, c = 3] (NA -> FALSE, warning)

# Mixed numeric and character
co[list(1, "d")]                     # [a = 1, d = 4]
co[1, "d"]                           # same

# Alphanumeric ranges (NSE)
co[a:b]                              # [a = 1, b = 2]
co[a:b, d:c]                         # [a = 1, b = 2, d = 4, c = 3]
co[1:c]                              # [a = 1, b = 2, c = 3]
co[d:2]                              # [d = 4, c = 3, b = 2]
co[-(a:c)]                           # [d = 4]

# Default-filling of missing items
co[1:5, 0, .default = 0]             # [a = 1, b = 2, c = 3, d = 4, 0]
co["a", "b", "z", .default = 0]      # [a = 1, b = 2, z = 0]
co[1:2, "z", .default = 3:4]         # [a = 1, b = 2, z = (3L 4L)]


co = container(a = 1, b = 2)
co[[1]]
co[["a"]]
co[["x"]]