cast_shallow2atomic: Cast Shallow List to Atomic Object

In broadcast: Broadcasted Array Operations Like 'NumPy'

Cast Shallow List to Atomic Object

Description

cast_shallow2atomic() casts a shallow (i.e. non-nested) list to an atomic vector/array.

Usage

cast_shallow2atomic(x, ...)

## Default S3 method:
cast_shallow2atomic(x, arrangement = 0L, padding = NA, comnames_from = 1L, ...)

Arguments

x	a shallow (i.e. non-nested) list. The attributes of the objects inside the list will be ignored, except for names.
...	further arguments passed to or from methods.
arrangement	see the Details and Examples sections.
padding	an atomic scalar, and only relevant if arrangement is 1 or -1. This gives the padding value to use when padding is required. Padding is used to ensure every all slices of the same dimension in the output have equal number of elements (for example, all rows must have the same number of columns).
comnames_from	an integer scalar or NULL, and only relevant if arrangement is 1 or -1. This gives which element of x to use for the communal names. If NULL, no communal names will be given. For example: If x is a 1d (or dimensionless) list, cast_shallow2atomic(x, 1, arrangement = 1) will produce an atomic matrix. The column names of the matrix will be names(x). The row names, however, will be taken from names(x[[comnames_from]]), provided that x[[comnames_from]] has the proper length. See also the Examples section.

Details

If arrangement = 0L,
cast_shallow2atomic() works like unlist(), except that cast_shallow2atomic() guarantees an atomic vector result.

If arrangement = 1L,
cast_shallow2atomic() will produce an atomic array, with the elements arranged such that the dimensions are c(max(lengths(x)), dim(x)).
If x has no dimensions, dim(x) is replaced with length(x), thus treating x as an 1d array.
This will therefore always produce an atomic array with at least 2 dimensions.
The dimnames, if possible to construct, will be c(dimnames(x[[comnames_from]]), dimnames(x)).

If arrangement = -1L,
cast_shallow2atomic() will produce an atomic array, with the elements arranged such that the dimensions are c(dim(x), max(lengths(x))).
If x has no dimensions, dim(x) is replaced with length(x), thus treating x as an 1d array.
This will therefore always produce an atomic array with at least 2 dimensions.
The dimnames, if possible to construct, will be c(dimnames(x), names(x[[comnames_from]])).

In all cases, the result will be atomic.

Value

If arrangement = 0L:
An atomic vector.

If arrangement = 1L:
An atomic array.

If arrangement = -1L:
An atomic array.

The type of the result is determined from the highest atomic type of any of the list elements (including elements of length zero).
The hierarchy of atomic types is:
raw < logical < integer < double < complex < character.
List elements that are not atomic but language expressions, like formulas, will be coerced to type of character.

Back transformation

From the casted atomic object,
out <- cast_shallow2atomic(x, ...),
one can get an approximation of the original shallow list back using just base 'R' functions.
This section describes how to do so.

If arrangement = 0L,
one can transform an atomic object out back to a shallow list using:
back <- as.list(out)
names(back) <- names(out)

If arrangement = 1L,
one can transform an atomic object out back to a shallow list using:
asplit(out, seq(2, ndim(out)))

If arrangement = -1L,
one can transform an atomic object out back to a shallow list using:
asplit(out, seq(1, ndim(out) - 1L))

See Also

broadcast_casting

Examples

# recursive vector ====
x <- list(
  setNames(1:11, letters[1:11]), 1:10, 1:9, 1:8, 1:7, 1:6, 1:5, 1:4, 1:3, 1:2, 1L, integer(0L)
)
names(x) <- month.abb
print(x)

cast_shallow2atomic(x, 0L)
cast_shallow2atomic(x, 1L, comnames_from = 1L)
cast_shallow2atomic(x, -1L, comnames_from = 1L)


# recursive matrix ====
x <- list(
  setNames(1:11, letters[1:11]), 1:10, 1:9, 1:8, 1:7, 1:6, 1:5, 1:4, 1:3, 1:2, 1L, integer(0L)
) |> rev()
dim(x) <- c(3, 4)
dimnames(x) <- list(month.abb[1:3], month.name[1:4])
print(x)

cast_shallow2atomic(x, 0L)
cast_shallow2atomic(x, 1L, comnames_from = length(x))
cast_shallow2atomic(x, -1L, comnames_from = length(x))

broadcast documentation built on Aug. 20, 2026, 9:08 a.m.