Efficient creation of string vectors with optional interpolation

Source: R/aliases.R, R/string_tools.R

Create string vectors in multiple ways: 1) add successive string elements (like in c()), or 2) write a character string that will be broken with respect to commas ("hi, there" becomes c("hi", "there")), or 3) interpolate variables in character strings ("x{1:2}" becomes c("x1", "x2")) with full access to string_magic() operations, or any combination of the three.

string_vec_alias(
  .cmat = FALSE,
  .nmat = FALSE,
  .df = FALSE,
  .df.convert = TRUE,
  .last = NULL,
  .delim = c("{", "}"),
  .split = TRUE,
  .protect.vars = TRUE,
  .sep = NULL,
  .collapse = NULL,
  .namespace = NULL
)

string_vec(
  ...,
  .cmat = FALSE,
  .nmat = FALSE,
  .df = FALSE,
  .df.convert = TRUE,
  .delim = c("{", "}"),
  .envir = parent.frame(),
  .split = TRUE,
  .protect.vars = TRUE,
  .sep = NULL,
  .last = NULL,
  .collapse = NULL,
  .namespace = NULL
)

stvec(
  ...,
  .cmat = FALSE,
  .nmat = FALSE,
  .df = FALSE,
  .df.convert = TRUE,
  .delim = c("{", "}"),
  .envir = parent.frame(),
  .split = TRUE,
  .protect.vars = TRUE,
  .sep = NULL,
  .last = NULL,
  .collapse = NULL,
  .namespace = NULL
)

Arguments

.cmat

Logical scalar (default is FALSE), integer or complex with integer values. If TRUE, we try to coerce the result into a character matrix. The number of rows and columns is deduced from the look of the arguments. An integer indicates the number of rows. If a complex, the imaginary part represents the number of columns. Ex: 5i means 5 columns, 3 + 2i means 3 rows and 2 columns.

The matrix is always filled by row.

.nmat

Logical scalar (default is FALSE), integer or complex with integer values. If TRUE, we try to coerce the result into a numeric matrix. The number of rows and columns is deduced from the look of the arguments. An integer indicates the number of rows. If a complex, the imaginary part represents the number of columns. Ex: 5i means 5 columns, 3 + 2i means 3 rows and 2 columns.

The matrix is always filled by row. Non numbers are silently turned to NA.

.df

Logical scalar (default is FALSE), integer, complex with integer values, or character vector. If TRUE, we try to coerce the result into a data.frame. The number of rows and columns is deduced from the look of the arguments. An integer indicates the number of rows. If a complex, the imaginary part represents the number of columns. Ex: 5i means 5 columns, 3 + 2i means 3 rows and 2 columns.

If a character vector: it should give the column names. Note that if the vector is of length 1, its values are comma separated (i.e. the value "id, name" is identical to c("id", "name")).

Note that the columns that can be converted to numeric are converted to numeric. The other columns are in string form. Monitor this behavior with .df.convert.

.df.convert

Logical scalar, default is TRUE. Only used when the result is to be converted to a data frame (with the argument .df). If TRUE, any column looking like a numeric vector is converted to numeric. Otherwise all columns are character strings.

.last

Character scalar, a function, or NULL (default). If provided and character: it must be an string_magic chain of operations of the form "'arg1'op1, op2, etc". All these operations are applied just before returning the vector. If a function, it will be applied to the resulting vector.

.delim

Character vector of length 1 or 2. Default is c("{", "}"). Defines the opening and the closing delimiters for interpolation.

If of length 1, it must be of the form: 1) the opening delimiter, 2) a single space, 3) the closing delimiter. Ex: ".[ ]" is equivalent to c(".[", "]"). The default value is equivalent to "{ }".

[ ]: R:%20 [", "]: R:%22,%20%22

.split

Logical or a character symbol, default is TRUE. If TRUE, the character vectors are split with respect to commas (default). If FALSE, no splitting is performed. If a character symbol, the string vector will be split according to this symbol. Note that any space after the symbol (including tabs and newlines) is discarded.

Ex: by default string_vec("hi, there") leads to the vector c("hi", "there").

.protect.vars

Logical scalar, default is TRUE. If TRUE, then only arguments equal to a "natural" character scalar are comma-split and interpolated, other arguments are not touched. Ex: string_vec("x{1:5}") will lead to a vector of length 5 ("x1" to "x5"), while z = "x{1:5}" followed by string_vec(z) leads to a vector of length 1: "x{1:5}". If FALSE, comma-splitting and interpolation is performed on all variables.

.sep

Character scalar or NULL (default). If not NULL, the function base::paste() is applied to the resulting vector with sep = .sep.

.collapse

Character scalar or NULL (default). If not NULL, the function base::paste() is applied to the resulting vector with collapse = .collapse.

If so, pass the name of your package in this argument so that your function can access the new string_magic operations defined within your package.

.namespace

Character scalar or NULL (default). Only useful for package developers. As a regular end-user you shouldn't care! If your package uses string_magic, you should care. It is useful only if your package uses 'custom' string_magic operations, set with string_magic_register_fun() or string_magic_register_ops().

...

Character vectors that will be vectorized. If commas are present in the character vector, it will be split with respect to commas and following blanks. The vectors can contain any interpolation in the form "{var}" and any string_magic() operation can be applied. To change the delimiters for interpolation, see .delim. Named arguments are used in priority for variable substitution, otherwise the value of the variables to be interpolated are fetched in the calling environment (see argument .envir).

Note, importantly, that interpolation and comma splitting are performed on "natural" vectors only. That is: string_vec("x{1:5}") will lead to a vector of length 5 ("x1" to "x5"), while z = "x{1:5}" followed by string_vec(z) leads to a vector of length 1: "x{1:5}". To change this behavior and obtain equivalent results, use .protect.vars = FALSE.

.envir

An environment used to evaluate the variables in "{}". By default the variables are evaluated using the environment from where the function is called or using the named arguments passed to the function.

Value

By default this function returns a string vector, the length of which depends on the arguments.

This result can be processed with the arguments cmat, nmat and .df which will try to coerce the result into a character matrix, a numeric matrix , or a data frame, respectively.

Details

The main objective of this function is to simplify the creation of small character vectors. By default, you can pass a character string of length 1 with values separated with commas and a character vector will be returned.

You can use interpolation using curly brackets (see string_magic()). You can pass values for the interpolation directly in the arguments (this is why all arguments start with a dot).

By default character values containing commas are split with respect to the commas to create vectors. To change this behavior, see the argument .split.

The default of the argument .protect.vars is FALSE so as to avoid unwanted comma-splitting and interpolations. The main use case of this function is the creation of small string vectors, which can be written directly at function call.

Customize the default of this function with string_vec_alias().

Functions

  • string_vec_alias(): Create string_vec aliases with custom defaults

  • stvec(): Alias to string_vec

See also

Other tools with aliases: cat_magic_alias(), string_clean_alias(), string_magic(), string_magic_alias(), string_ops_alias()

Author

Laurent Berge

Examples


# illustrating comma-splitting and interpolation
string_vec("x1, y2, z{4:5}")
#> [1] "x1" "y2" "z4" "z5"

# variable protection
x = "x{1:5}"
string_vec(x, "y{1:2}")
#> [1] "x{1:5}" "y1"     "y2"    

# without protection => interpolation takes place
string_vec(x, "y{1:2}", .protect.vars = FALSE)
#> [1] "x1" "x2" "x3" "x4" "x5" "y1" "y2"

# removing comma splitting
string_vec("Hi, said Charles.", "Hi, said {girl}.", girl = "Julia", .split = FALSE)
#> [1] "Hi, said Charles." "Hi, said Julia."  

# changing the delimiters for interpolation
pkg = "\\usepackage[usenames,dvipsnames]{xcolor}"
string_vec("\\usepackage{.[S!graphicx, fourier, standalone]}", 
           pkg, .delim = ".[ ]")
#> [1] "\\usepackage{graphicx}"                   
#> [2] "\\usepackage{fourier}"                    
#> [3] "\\usepackage{standalone}"                 
#> [4] "\\usepackage[usenames,dvipsnames]{xcolor}"

#
# Customization
#

# Unhappy about the defaults? Create an alias!

# we create a "matrix generator"
matgen = string_vec_alias(.nmat = TRUE, .last = "'\n'split")

matgen("5, 4, 3
        8, 6, 2")
#>      [,1] [,2] [,3]
#> [1,]    5    4    3
#> [2,]    8    6    2