convert_to_sf_vector

Description

Converts a character vector to an 'sf_vec'-backed stringfish vector 'convert_to_sf()' is a compatibility alias for 'convert_to_sf_vector()'.

Usage

convert_to_sf_vector(x, length.out = length(x))

Arguments

Details

Converts a character vector to a stringfish vector backed by 'sf_vec'. If 'length.out' is supplied, 'x' is recycled to that length before conversion. The opposite of 'materialize'.

Value

The converted character vector

Examples

x <- convert_to_sf_vector(letters)

convert_to_slice_store

Description

Converts a character vector to a slice-store-backed stringfish vector

Usage

convert_to_slice_store(x, length.out = length(x))

Arguments

Details

Converts a character vector to a stringfish vector backed by 'slice_store'. If 'length.out' is supplied, 'x' is recycled to that length before conversion. The converter pre-sizes the first 'slice_store' slice from the normalized string bytes when possible. The opposite of 'materialize'.

Value

The converted character vector

Examples

x <- convert_to_slice_store(letters)

get_string_type

Description

Returns the type of the character vector

Usage

get_string_type(x)

Arguments

Details

A function that returns the type of character vector. Possible values are "normal vector", "stringfish vector", "stringfish vector (materialized)", "stringfish slice store", "stringfish slice store (materialized)" or "other alt-rep vector"

Value

The type of vector

Examples

x <- sf_vector(10)
get_string_type(x) # returns "stringfish vector"
x <- character(10)
get_string_type(x) # returns "normal vector"

materialize

Description

Materializes an alt-rep object

Usage

materialize(x)

Arguments

Details

Materializes any alt-rep object and then returns it. Note: the object is materialized regardless of whether the return value is assigned to a variable.

Value

x

Examples

x <- sf_vector(10)
sf_assign(x, 1, "hello world")
sf_assign(x, 2, "another string")
x <- materialize(x)

random_strings

Description

A function that generates random strings

Usage

random_strings(N, string_size = 50L, charset = "abcdefghijklmnopqrstuvwxyz",
                      vector_mode = "stringfish")

Arguments

Details

A convenience function for generating test strings.

Value

A character vector of the random strings

Examples

set.seed(1)
x <- random_strings(1e6, 80L, "ACGT", vector_mode = "stringfish")
y <- random_strings(4, c(1L, 2L, 4L, 8L), "ACGT")

sf_assign

Description

Assigns a new string to a stringfish vector or any other character vector

Usage

sf_assign(x, i, e)

Arguments

Details

A function to assign a new element to an existing character vector. If the the vector is a stringfish vector, it does so without materialization.

Value

No return value, the function assigns an element to an existing stringfish vector

Examples

x <- sf_vector(10)
sf_assign(x, 1, "hello world")
sf_assign(x, 2, "another string")

sf_collapse

Description

Pastes a series of strings together separated by the 'collapse' parameter

Usage

sf_collapse(x, collapse)

Arguments

Details

This works the same way as 'paste0(x, collapse=collapse)'

Value

A single string with all values in 'x' pasted together, separated by 'collapse'.

See Also

paste0, paste

Examples

x <- c("hello", "\\xe4\\xb8\\x96\\xe7\\x95\\x8c")
Encoding(x) <- "UTF-8"
sf_collapse(x, " ") # "hello world" in Japanese
sf_collapse(letters, "") # returns the alphabet

sf_compare

Description

Returns a logical vector testing equality of strings from two string vectors

Usage

sf_compare(x, y, nthreads = getOption("stringfish.nthreads", 1L))

sf_equals(x, y, nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

Note: the function tests semantic string equality. Non-byte text is normalized to a UTF-8 working representation, while 'CE_BYTES' strings are compared byte-for-byte.

Value

A logical vector

Examples

sf_compare(letters, "a")

sf_concat

Description

Appends vectors together

Usage

sf_concat(...)

sfc(...)

Arguments

Value

A concatenated stringfish vector

Examples

sf_concat(letters, 1:5)

sf_ends

Description

A function for detecting a pattern at the end of a string

Usage

sf_ends(subject, pattern, ...)

Arguments

Value

A logical vector true if there is a match, false if no match, NA is the subject was NA

See Also

endsWith, sf_starts

Examples

x <- c("alpha", "beta", "gamma", "delta", "epsilon")
sf_ends(x, "a")

sf_grepl

Description

A function that matches patterns and returns a logical vector

Usage

sf_grepl(subject, pattern, encode_mode = "auto", fixed = FALSE, 
nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

The function uses the PCRE2 library, which is also used internally by R. The encoding is based on the pattern string (or forced via the encode_mode parameter). Note: the order of paramters is switched compared to the 'grepl' base R function, with subject being first.

Value

A logical vector with the same length as subject

See Also

grepl

Examples

x <- sf_vector(10)
sf_assign(x, 1, "hello world")
pattern <- "^hello"
sf_grepl(x, pattern)

sf_gsub

Description

A function that performs pattern substitution

Usage

sf_gsub(subject, pattern, replacement, encode_mode = "auto", fixed = FALSE, 
nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

The function uses the PCRE2 library, which is also used internally by R. However, syntax may be slightly different. E.g.: capture groups: "\1" in R, but "$1" in PCRE2 (as in Perl). The encoding of the output is determined by the pattern (or forced using encode_mode parameter) and encodings should be compatible. E.g: mixing ASCII and UTF-8 is okay, but not UTF-8 and latin1. Note: the order of paramters is switched compared to the 'gsub' base R function, with subject being first.

Value

A stringfish vector of the replacement string

See Also

gsub

Examples

x <- "hello world"
pattern <- "^hello (.+)"
replacement <- "goodbye $1"
sf_gsub(x, pattern, replacement)

sf_iconv

Description

Converts encoding of one character vector to another

Usage

sf_iconv(x, from, to, nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

This is an analogue to the base R function 'iconv'. It converts a string from one encoding (e.g. latin1 or UTF-8) to another

Value

the converted character vector as a stringfish vector

See Also

iconv

Examples

x <- "fa\xE7ile"
Encoding(x) <- "latin1"
sf_iconv(x, "latin1", "UTF-8")

sf_match

Description

Returns a vector of the positions of x in table

Usage

sf_match(x, table, nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

Note: similarly to the base R function, long "table" vectors are not supported. This is due to the maximum integer value that can be returned ('.Machine$integer.max')

Value

An integer vector of the indicies of each x element's position in table

See Also

match

Examples

sf_match("c", letters)

sf_nchar

Description

Counts the number of characters in a character vector

Usage

sf_nchar(x, type = "chars", nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

Returns the number of characters per string. The type of counting only matters for UTF-8 strings, where a character can be represented by multiple bytes.

Value

An integer vector of the number of characters

See Also

nchar

Examples

x <- "fa\xE7ile"
Encoding(x) <- "latin1"
x <- sf_iconv(x, "latin1", "UTF-8")

sf_paste

Description

Pastes a series of strings together

Usage

sf_paste(..., sep = "", nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

This works the same way as 'paste0(..., sep=sep)'

Value

A character vector where elements of the arguments are pasted together

See Also

paste0, paste

Examples

x <- letters
y <- LETTERS
sf_paste(x,y, sep = ":")

sf_readLines

Description

A function that reads a file line by line

Usage

sf_readLines(file, encoding = "UTF-8")

Arguments

Details

A function for reading in text data using 'std::ifstream'.

Value

A stringfish vector of the lines in a file

See Also

readLines

Examples

file <- tempfile()
sf_writeLines(letters, file)
sf_readLines(file)

sf_split

Description

A function to split strings by a delimiter

Usage

sf_split(subject, split, encode_mode = "auto", fixed = FALSE, 
nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Value

A list of stringfish character vectors

See Also

strsplit

Examples

sf_split(datasets::state.name, "\\s") # split U.S. state names by any space character

sf_starts

Description

A function for detecting a pattern at the start of a string

Usage

sf_starts(subject, pattern, ...)

Arguments

Value

A logical vector true if there is a match, false if no match, NA is the subject was NA

See Also

startsWith, sf_ends

Examples

x <- c("alpha", "beta", "gamma", "delta", "epsilon")
sf_starts(x, "a")

sf_substr

Description

Extracts substrings from a character vector

Usage

sf_substr(x, start, stop, nthreads = getOption("stringfish.nthreads", 1L))

Arguments

Details

This works the same way as 'substr', but in addition allows negative indexing. Negative indicies count backwards from the end of the string, with -1 being the last character.

Value

A stringfish vector of substrings

See Also

substr

Examples

x <- c("fa\xE7ile", "hello world")
Encoding(x) <- "latin1"
x <- sf_iconv(x, "latin1", "UTF-8")
sf_substr(x, 4, -1) # extracts from the 4th character to the last
## [1] "ile"  "lo world"

sf_tolower

Description

A function converting a string to all lowercase

Usage

sf_tolower(x)

Arguments

Details

Note: the function only converts ASCII characters.

Value

A stringfish vector where all uppercase is converted to lowercase

See Also

tolower

Examples

x <- LETTERS
sf_tolower(x)

sf_toupper

Description

A function converting a string to all uppercase

Usage

sf_toupper(x)

Arguments

Details

Note: the function only converts ASCII characters.

Value

A stringfish vector where all lowercase is converted to uppercase

See Also

toupper

Examples

x <- letters
sf_toupper(x)

sf_trim

Description

A function to remove leading/trailing whitespace

Usage

sf_trim(subject, which = c("both", "left", "right"), whitespace = "[ \\t\\r\\n]", ...)

Arguments

Value

A stringfish vector of trimmed whitespace

See Also

trimws

Examples

x <- c(" alpha ", " beta", " gamma ", "delta ", "epsilon ")
sf_trim(x)

sf_vector

Description

Creates a new empty stringfish vector

Usage

sf_vector(len)

Arguments

Details

This is a backwards-compatible alias for 'sf_vector_create(len)'. It creates a new stringfish vector, an alt-rep character vector backed by a C++ "std::vector" as the internal memory representation. The vector type is "sfstring", which is a simple C++ class containing a "std::string" and a single byte (uint8_t) representing the encoding.

Value

A new empty stringfish vector

Examples

x <- sf_vector(10)
sf_assign(x, 1, "hello world")
sf_assign(x, 2, "another string")

sf_vector_create

Description

Creates a new empty stringfish vector

Usage

sf_vector_create(len)

Arguments

Details

This function creates a new empty 'sf_vec'-backed stringfish vector. If you want to fill the vector from character data, use 'convert_to_sf_vector'.

Value

A new stringfish vector

Examples

x <- sf_vector_create(4)

sf_writeLines

Description

A function that writes text line by line

Usage

sf_writeLines(text, file, sep = "\n", na_value = "NA", encode_mode = "UTF-8")

Arguments

Details

A function for writing text data using 'std::ofstream'.

See Also

writeLines

Examples

file <- tempfile()
sf_writeLines(letters, file)
sf_readLines(file)

slice_store_create

Description

Creates a new empty slice-store-backed stringfish vector

Usage

slice_store_create(len)

Arguments

Details

This function creates a new stringfish vector backed by 'slice_store', which stores string bytes in append-only slices plus per-element records. If you want to fill the vector from character data, use 'convert_to_slice_store'.

Value

A new slice-store-backed stringfish vector

Examples

x <- slice_store_create(4)

slice_store_create_with_size

Description

Creates a new empty slice-store-backed stringfish vector with a fixed initial slice size

Usage

slice_store_create_with_size(len, initial_slice_size)

Arguments

Details

This function creates a new stringfish vector backed by 'slice_store', and uses 'initial_slice_size' for the first slice allocation instead of the default heuristic. If you want to fill the vector from character data, use 'convert_to_slice_store'.

Value

A new slice-store-backed stringfish vector

Examples

x <- slice_store_create_with_size(4, 256)

string_identical

Description

Compare strings semantically or exactly

Usage

string_identical(x, y, mode = c("semantic", "exact"))

Arguments

Value

TRUE if strings are identical under the selected comparison mode

See Also

identical

Examples

x <- "fa\xE7ile"
Encoding(x) <- "latin1"
y <- iconv(x, "latin1", "UTF-8")
identical(x, y) # TRUE
string_identical(x, y) # TRUE
string_identical(x, y, mode = "exact") # FALSE