stringi-arguments: Passing Arguments to Functions in stringi

Description

Below we explain how stringi deals (in almost all cases) with its functions' arguments.

Coercion of Arguments

When a character vector argument is expected, factors and other vectors coercible to characters vectors are silently converted with as.character, otherwise an error is generated.

When a logical, numeric or integer vector argument is expected, factors are converted with as.*(as.character(...)), and other coercible vectors are converted with as.*, otherwise an error is generated.

See the links below for the description of internal methods used in all functions from the stringi package (just to get more insight, in case you are interested in technical details). Anyway, we hope that everything works as you intuitively expect.

Vectorization

Almost all functions are vectorized with respect to all their arguments; This may sometimes lead to strange results - we assume you know what you are doing. However, thanks to this property you may e.g. search for one pattern in each given string, or search for each pattern in one given string.

We of course took great care of performance issues: e.g. in regular expression searching, regex matchers are reused from iteration to iteration, as long it is possible.

Functions with some non-vectorized arguments are rare: e.g. regular expression matcher's settings are established once per each call.

Some functions assume that a vector with one element is given as an argument (like collapse in stri_join). In such cases, if an empty vector is given you will get an error and for vectors with more than 1 elements - a warning will be generator (only the first element will be used).

You may find details on vectorization behavior in the man pages on each particular function of your interest.

Handling Missing Values (<code>NA</code>s)

stringi handles missing values consistently. For any vectorized operation, if at least one vector element is missing, then the corresponding resulting value is also set to NA.

Preserving Input Objects' Attributes

Generally, all our functions drop input objects' attributes (e.g. names, dim, etc.). This is generally because of advanced vectorization and for efficiency reasons. Currently, there is only one exception to this rule: the stri_sort function. Thus, if this is needed, please remember to copy important attributes manually or use e.g. the subsetting operation like x[] <- stri_...(x, ...).

Description

Coercion of Arguments

Vectorization

Handling Missing Values (<code>NA</code>s)

Preserving Input Objects' Attributes

See Also