Data Engineering and BI courses are free this week!
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 = FALSE,
.check = 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 = FALSE,
.sep = NULL,
.last = NULL,
.check = TRUE,
.help = NULL,
.collapse = NULL,
.namespace = NULL
)
stvec(
...,
.cmat = FALSE,
.nmat = FALSE,
.df = FALSE,
.df.convert = TRUE,
.delim = c("{", "}"),
.envir = parent.frame(),
.split = TRUE,
.protect.vars = FALSE,
.sep = NULL,
.last = NULL,
.check = TRUE,
.help = NULL,
.collapse = NULL,
.namespace = NULL
)
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.
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.
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.
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.
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.
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.
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
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. You can escape the splitting symbol with a backslash right before it.
Ex: by default string_vec("hi, there") leads to the vector c("hi", "there").
Logical scalar, default is FALSE. 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.
Logical scalar, default is TRUE. Whether to enable error-handling (i.e.
human readable error messages).
Without error-handling you can save something of the order of 40us. Useful only
in long loops.
Character scalar or NULL (default). If not NULL, the function
base::paste() is applied to the resulting vector with sep = .sep.
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.
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).
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.
Character scalar or TRUE, default is NULL. This argument
is used to generate a dynamic help on the console. If TRUE, the user can select which
topic to read from the main documentation, with the possibility to search for keywords and
navigate the help pages. If a character scalar, then a regex search is perfomed on the main
documentation and any section containining a match is displayed. The user can easily
navigate across matches.
string_vec_alias(): Create string_vec aliases with custom defaults
stvec(): Alias to string_vec
Laurent Berge
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. To avoid unwanted
comma-splitting and interpolations on variables, set it to TRUE.
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().
Other tools with aliases:
cat_magic_alias(),
string_clean_alias(),
string_magic(),
string_magic_alias(),
string_ops_alias()
# illustrating comma-splitting and interpolation
string_vec("x1, y2, z{4:5}")
# variable protection
x = "x{1:5}"
# without protection (default) => interpolation takes place
string_vec(x, "y{1:2}")
# with protection => no interpolation for x
string_vec(x, "y{1:2}", .protect.vars = TRUE)
# removing comma splitting
string_vec("Hi, said Charles.", "Hi, said {girl}.", girl = "Julia", .split = FALSE)
# changing the delimiters for interpolation
pkg = "\\usepackage[usenames,dvipsnames]{xcolor}"
string_vec("\\usepackage{.[S!graphicx, fourier, standalone]}",
pkg, .delim = ".[ ]")
#
# 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")
Run the code above in your browser using DataLab