In PeteHaitch/rope: Syntactic Sugar for Strings in Rcpp

As explained in the introductory vignette, most of rope's functionality centres around direct string manipulation, and that's what this vignette documents. Documentation for each group of functions takes the form of a block showing the various input and output permutations, and then long-form documentation of what the functions are used for and any caveats there might be.

Upper and lower-casing

```{Rcpp eval = FALSE} std::string string_tolower(std::string str) std::vector < string > string_tolower(std::vector < std::string > strs) std::string string_toupper(std::string str) std::vector < string > string_toupper(std::vector < std::string > strs)

`string_toupper` and `string_tolower` upper- and lower-case a string, respectively. They come in both vectorised and non-vectorised forms, and because of how C++ is designed, you don't need to refer to different functions to select the right one: just call `string_tolower` and if you provide it a vector as an input argument, it'll know to select the vectorised version.

In each case, the output is either a string or a vector of strings, upper/lower-cased. So, `string_tolower("TURNIP");` provides a string containing "turnip".

## Pasting

```{Rcpp eval = FALSE}
std::string string_paste(std::string x, std::string y, std::string sep = "")
std::vector < std::string > string_paste(std::vector < std::string > x, std::vector < std::string > y, std::string sep = "")

R provides the wonderful paste() function, which lets you paste together strings in a vectorised way. C++ doesn't have the same functionality, although you can just go x = x + sep + y; to achieve the same thing with single elements.

rope contains string_paste, which lets you paste together individual strings (or a vector of strings) with an optional separator. The vectorised version requires either (a) x and y to be the same length, in which case each pair of elements will be pasted together, or (b) y to be a single element - in which case each element of x will have the separator and the single element of y appended to it.

Substring removal

```{Rcpp eval = FALSE} std::string string_remove(std::string str, std::string to_remove) std::vector < std::string > string_remove(std::vector < std::string > strs, std::string to_remove) std::string string_remove_first(std::string str, std::string to_remove) std::vector < std::string > string_remove_first(std::vector < std::string > strs, std::string to_remove)

If you want to remove a particular substring from a string, no problem! Just use `string_remove()`, which accepts a string (or vector of strings) and a set of characters to remove, removing each instance of that set from the strings provided. If you only want to remove the
first element, you can use `string_remove_first()` instead.

At the moment these don't accept regular expressions, due to a desire to avoid depending on C++11 (since a lot of useRs don't have that
yet). As soon as people trend towards using versions of R that support C++11, this functionality will be introduced.

## Substring replacement

```{Rcpp eval = FALSE}
std::string string_replace(std::string str, std::string to_replace, std::string replace_with)
std::vector < std::string > string_replace(std::vector < std::string > strs, std::string to_replace, std::string replace_with)
std::string string_replace_first(std::string str, std::string to_replace, std::string replace_with)
std::vector < std::string > string_replace_first(std::vector < std::string > strs, std::string to_replace, std::string replace_with)

Similar to string_remove, string_replace lets you identify particular substrings in a string and, instead of removing them, replace them with another string of any length. Again, it has string_replace_first() to let you just replace the first instance of the substring.

Reversal

```{Rcpp eval = FALSE} std::string string_reverse(std::string str) std::vector < std::string > string_reverse(std::vector < std::string > strs)

If you want to reverse a string, character by character, `string_reverse()` is for you; it comes in a vectorised form again, and accepts a single string (or vector of strings), spitting out the same object but with each string reversed.

## Splitting

```{Rcpp eval = FALSE}
std::vector < std::string > string_split(std::string str, std::string delimiter)
std::list < std::vector < std::string > > string_split(std::vector < std::string > str, std::string delimiter)

If you want to split a string by a delimiter, as in the introductory example, you can use string_split(). This accepts a single string (or vector of strings) and a delimiter, and returns a vector containing each delimiter-separated chunk of the input string. If the vectorised version is used, a list will be returned instead of a vector.

Multi-character delimiters can be happily used; again, due to the lack of C++11, regular expressions are not currently supported.

PeteHaitch/rope documentation built on May 8, 2019, 1:32 a.m.