lv2v: List of (atomic) Vectors to (atomic) Vector

In str2str: Convert R Objects from One Structure to Another

List of (atomic) Vectors to (atomic) Vector

Description

lv2v converts a list of (atomic) vectors to an (atomic) vector. lv2v is simply a wrapper function for unlist that allows for more control over the names of the returned (atomic) vector.

Usage

lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE, sep = "_", check = TRUE)

Arguments

lv	list of (atomic) vectors.
use.listnames	logical vector of length 1 specifying whether the names of lv should be used to construct names for the returned vector. If lv does not have names and use.listnames = TRUE, then the list positions will be used as names (i.e., "1","2","3", etc.).
use.vecnames	logical vector of length 1 specifying whether the names of each vector within lv should be used to construct names for the returned vector. If any vectors within lv do not have names and use.vecnames = TRUE, then the vector positions will be used as names (i.e., "1","2","3", etc.).
sep	character vector of length 1 specifying what string to use to separate list names from vector element names. Only used if use.listnames = TRUE.
check	logical vector of length 1 specifying whether to check the structure of the input arguments. For example, check whether lv is a list of atomic vectors. This argument is available to allow flexibility in whether the user values informative error messages (TRUE) vs. computational efficiency (FALSE).

Details

There are four different scenarios. Each scenario is given as well as the structure of the returned object when both use.listnames and use.vecnames are TRUE (default): 1) if both lv and its vectors have names, then the names of the return object will be a pasted combination of the lv element's name and the vector element's name separated by sep; 2) if only lv has names and its vectors do not, then the names of the returned vector will be a pasted combination of the lv element's name and the vector element's position separated by sep; 3) if the vectors have names and lv does not, then the names of the returned vector will be a pasted combination of the lv positions and vector names separated by sep; 4) if both lv and its vectors do not have names, then the names of the returned vector will be the pasted combination of the lv positions and vector element's positions separated by sep.

If you want to convert a list of vectors where each vector has length = 1 and the list has names, then you probably want to specify use.vecnames = FALSE. This will replicate the functionality of unlist(lv). See the last example.

If you want have a list of vectors where each vector has length > 1 and you want to convert it to a list vector (i.e., all vectors with length = 1), then you can combine lv2v with v2lv via v2lv(lv2v(v)).

Value

atomic vector with length = sum of the lengths of the atomic vectors in lv and typeof = the highest typeof present in the atomic vectors in lv (i.e., from high to low: character > double > integer > logical). See the argument use.listnames for how names are created.

Examples

# 1) both `lv` and its atomic vectors have names
lv <- setNames(object = Map(object = 1:26, nm = letters, f = setNames), nm = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 2) only `lv` has names
lv <- list("lower" = letters, "upper" = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE) # FYI - results in repeat names
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 3) only the atomic vectors have names
lv <- list(setNames(object = 1:26, nm = letters), setNames(object = 1:26, nm = LETTERS))
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 4) neither `lv` nor its atomic vectors have names
lv <- as.list(1:26)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE) # FYI - results in repeat names
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# common use case for when vectors are all length 1 and list has names
lv <- setNames(as.list(letters), nm = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE) # FYI - probably what you want
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
identical(unlist(lv), lv2v(lv, use.vecnames = FALSE)) # identical to unlist()

str2str documentation built on Nov. 21, 2023, 1:08 a.m.