class byteset_tThe C++ layer lives in namespace ashvardanian::stringzilla, conventionally aliased as sz, and is built on the types below plus a 256-bit byteset.
sz::string_slice<char_type>— a non-owning, length-bounded view overcharorchar const. Two aliases exist: the read-onlysz::string_view_t = string_slice<char const>and the mutablesz::string_span_t = string_slice<char>.sz::string<allocator = std::allocator<char>>— an owning, Small-String-Optimizedcharcontainer; the aliassz::string_tuses the defaultstd::allocator. A stateful allocator travels with the string under the usualstd::allocator_traitspropagation rules, and an empty one costs no bytes.sz::strings_view_t— a borrowed column of strings, wrapping asz_strings_view_tin any of its layouts.sz::strings<allocator = sz::heap_alloc<char>>— an owned, move-only column, asz_strings_span_ttape and the allocator of its blocks; the aliassz::strings_tuses the default.sz::byteset_t— the C++ wrapper aroundsz_byteset_t, constructible from an initializer list, a(pointer, count)pair, or astd::array, and composable withoperator|.sz::status_t— a scoped enum mirroringsz_status_twithsuccess_k,bad_alloc_k,invalid_utf8_k,contains_duplicates_k, and the rest, returned by the fallible free functions and the string’s allocating verbs.
sz::string_view_t is implicitly constructible from a char const *, a (pointer, length) pair, std::string, and std::string_view, and converts back to both; sz::string_t adds construction from repeats, sub-ranges, initializer lists, and lazy sz::concatenate(...) expressions.
Both satisfy the std::string/std::string_view member surface — data, size, length, empty, at, front, back, iterators, substr, compare, the relational operators, and on C++20 operator<=> — so they are drop-in for most code.
Both also stream through operator<<, and std::hash<sz::string_t> / std::hash<sz::string_view_t> specializations are provided so they work as unordered-container keys out of the box.
User-defined literals live in sz::literals:
using namespace sz::literals;
sz::string_view_t v = "needle"_sv; // a view, no allocation
sz::byteset_t s = " \t\n\r"_bs; // a byte-set from a literalConvenience byte-sets are available as free functions: sz::whitespaces_set(), sz::newlines_set(), sz::digits_set(), sz::hexdigits_set(), sz::octdigits_set(), and sz::ascii_letters_set().
API
Types
byteset_tA set of characters represented as a bitset with 256 slots.
string_view_forExtracts the view type of a string-like type: the nested string_view_t typedef of StringZilla types, or the type itself for STL types like std::string_view.
template <typename string_type_>
struct string_view_forreversed_iterator_forA reverse iterator for mutable and immutable character buffers.
template <typename value_type_>
class reversed_iterator_forReplaces std::reverse_iterator to avoid including <iterator>.
concatenation_operandInfers how an operand is stored inside a concatenation expression.
template <typename type_>
struct concatenation_operandThe concatenate function and operator| take forwarding references, so an lvalue sz::string_t deduces to sz::string_t & and a literal deduces to char const (&)[N]. Neither exposes the value_type, size() and copy() interface the expression template relies on, which is why baking the deduced type straight into concatenation fails to compile. Everything that is not already a nested expression is therefore normalized into a string_view_t, matching what the string_slice::operator| overloads produce.
concatenationAn "expression template" for lazy concatenation of strings using the operator|.
template <typename first_type_,
typename second_type_>
struct concatenationFields
first | first_type_ | |
|---|---|---|
second | second_type_ |
See also
- https://en.wikipedia.org/wiki/Expression_templates
- concatenate function for usage examples.
concatenation_resultSFINAE-type used to infer the resulting type of concatenating multiple string together.
template <typename... args_types_>
struct concatenation_resultstatus_tWhy a call failed, in the vocabulary the C ABI and every binding share.
enum status_tEvery enumerator takes its value from sz_status_t in types.h, so the C++ mirror and the ABI cannot drift, and the crossing is a cast rather than a table.
Statuses fall into four categories, with no interruptions to report. Resources: bad_alloc_k, missing_gpu_k, device_code_mismatch_k, missing_kernel_k and missing_library_k. Input: invalid_utf8_k, contains_duplicates_k, unexpected_dimensions_k, device_memory_mismatch_k and authentication_failed_k. State: overflow_risk_k. Defects: unknown_k. Any verb that allocates, binds a device or touches a file may also return a Resources status. A verb's own block lists only what its contract adds.
Values
success_k | sz_success_k | Finished without error. |
|---|---|---|
bad_alloc_k | sz_bad_alloc_k | An allocation failed. |
invalid_utf8_k | sz_invalid_utf8_k | The input is not valid UTF-8. |
contains_duplicates_k | sz_contains_duplicates_k | A collection that must hold unique elements holds duplicates. |
overflow_risk_k | sz_overflow_risk_k | The input is too large for the counters or the offsets holding it. |
unexpected_dimensions_k | sz_unexpected_dimensions_k | Operand sizes contradict each other, like an output span shorter than the input. |
missing_gpu_k | sz_missing_gpu_k | No GPU of the vendor this build targets answers. |
device_code_mismatch_k | sz_device_code_mismatch_k | The device code lacks the kernel, or it failed to build, launch or finish. |
device_memory_mismatch_k | sz_device_memory_mismatch_k | An operand lies in memory the device cannot address. |
authentication_failed_k | sz_authentication_failed_k | An authenticated decryption saw a tag that does not match its ciphertext. |
missing_kernel_k | sz_missing_kernel_k | No capability in the capability mask has this kernel. |
missing_library_k | sz_missing_library_k | A dispatch point or finder called from a header-only build, which links no library. |
unknown_k | sz_status_unknown_k | A failure no other status describes. |
expectedA result paired with the status_t explaining it; the value is only meaningful on success_k.
template <typename value_type_>
struct expectedFields
value | value_type_ | |
|---|---|---|
status | status_t |
indexed_container_iteratorRandom access iterator for any immutable container with indexed element lookup support.
template <typename container_type_>
struct indexed_container_iteratorNotes
Designed for strings_view_t and strings compatibility with STL algorithms and ranges.
head_body_tail_tHelper structure for dividing a range of data into three parts: head, body, and tail, generally used to minimize misaligned (split) stores and operate on aligned pages.
vectorSafer alternative to std::vector, that avoids exceptions and copy constructors: every member that allocates returns a status_t instead of throwing.
template <typename value_type_,
typename allocator_type_ = heap_alloc<value_type_>>
class vectorClassstringMemory-owning string class with a Small String Optimization.65
template <typename allocator_type_ = std::allocator<char>>
class stringAPI
Some APIs are different from string_slice:
lstrip,rstrip,stripmodify the string in-place, instead of returning a new view.sat,sub, and element access have non-const overloads returning mutable references.
Functions defined for string, but not present in string_slice:
replace,insert,erase,append,push_back,pop_back,resize,insert_at,replace_sliceanderase_slicetwins over signed offsets,replace_allanderase_allsimilar to Boost,translatefor character mapping,fill_randomfor fast random string generation.
Functions defined for string_slice, but not present in string:
partition,rpartition,split,rsplit,find_allandrfind_all, left out to enforce lifetimes over long operations,remove_prefixandremove_suffix.
Errors
Nothing throws. The default constructor is constexpr, and moves are noexcept. Copies and conversions go through copy, make and assign, and every allocating verb returns a status_t, or an expected beside an iterator. Positions past the end clamp to it, like Python's slices, and at checks its position with a debug assertion only.
nposSpecial value for missing matches.
size_type npos;We take the largest 63-bit unsigned integer on 64-bit machines. We take the largest 31-bit unsigned integer on 32-bit machines.
min_capacityThe number of characters that can be stored in the internal buffer.
size_type min_capacity;Depends on the size of the internal buffer for the "Small String Optimization".
stringCopies go through copy and assign, which report a failed allocation.
constexpr string() noexcept;constexpr string(allocator_type_ const & allocator) noexcept;string(string && other) noexcept;string(string const &)=delete;Copies go through copy and assign, which report a failed allocation.
string(std::nullptr_t)=delete;*× 2
operator=Steals the buffer, so the allocators must propagate on move or always compare equal; any other pair copies through assign, which reports a failed allocation.
requires (allocator_traits_t::propagate_on_container_move_assignment::value || allocator_traits_t::is_always_equal::value)
string & operator=(string && other) noexcept;string & operator=(string const &)=delete;copyA copy of this string, in memory of the allocator that select_on_container_copy_construction picks.
expected<string> copy() const noexcept;size_type copy(value_type *destination) const noexcept;Exports this entire view.
size_type copy(
value_type *destination,
size_type count,
size_type skip = 0) const noexcept;Exports at most count bytes after the first skip, and none at all when skip passes the end of the string.
Not an STL function, but useful for concatenations. The STL variant expects at least two arguments.
swapExchanges the string contents witt the other string.
void swap(string & other) noexcept;operator[]Equivalent to Python's "abc"[-3:-1].
reference operator[](size_type pos) noexcept;const_reference operator[](size_type pos) const noexcept;string_view_t operator[](
std::initializer_list<difference_type> offsets) const noexcept;Equivalent to Python's "abc"[-3:-1].
string_span_t operator[](
std::initializer_list<difference_type> offsets) noexcept;Exception-safe, unlike STL's substr. Supports signed and unsigned intervals.
frontThe opposite operation to remove_prefix, that does no bounds checking.
reference front() noexcept;const_reference front() const noexcept;string_view_t front(difference_type n) const noexcept;The opposite operation to remove_prefix, that does no bounds checking.
string_span_t front(difference_type n) noexcept;Warnings
The behavior is undefined if n > size().
backThe opposite operation to remove_prefix, that does no bounds checking.
reference back() noexcept;const_reference back() const noexcept;string_view_t back(difference_type n) const noexcept;The opposite operation to remove_prefix, that does no bounds checking.
string_span_t back(difference_type n) noexcept;Warnings
The behavior is undefined if n > size().
atElement access checked by a debug assertion, as operator[] is unchecked.
reference at(size_type pos) noexcept;const_reference at(size_type pos) const noexcept;satSigned alternative to at().
value_type sat(difference_type offset) const noexcept;reference sat(difference_type offset) noexcept;Handy if you often write str[str.size() - 2].
Warnings
The behavior is undefined if the position is beyond bounds.
subEquivalent to Python's "abc"[-3:-1].
string_view_t sub(
difference_type start,
difference_type end = npos) const noexcept;string_span_t sub(
difference_type start,
difference_type end = npos) noexcept;Exception-safe, unlike STL's substr. Supports signed and unsigned intervals. Doesn't copy or allocate memory!
remove_prefixRemoves the first n characters from the view.
void remove_prefix(size_type n) noexcept;Warnings
The behavior is undefined if n > size().
remove_suffixRemoves the last n characters from the view.
void remove_suffix(size_type n) noexcept;Warnings
The behavior is undefined if n > size().
compareCompares two strings lexicographically.
int compare(string_view_t other) const noexcept;int compare(
size_type pos1,
size_type count1,
string_view_t other) const noexcept;Compares up to count1 bytes at pos1 with other, lexicographically, then by length on a common prefix.
int compare(
size_type pos1,
size_type count1,
string_view_t other,
size_type pos2,
size_type count2) const noexcept;Compares up to count1 bytes at pos1 with up to count2 bytes at pos2 of other, lexicographically, then by length on a common prefix.
int compare(const_pointer other) const noexcept;int compare(
size_type pos1,
size_type count1,
const_pointer other) const noexcept;Compares up to count1 bytes at pos1 with other, lexicographically, then by length on a common prefix.
int compare(
size_type pos1,
size_type count1,
const_pointer other,
size_type count2) const noexcept;Compares up to count1 bytes at pos1 with the first count2 bytes of other, lexicographically, then by length on a common prefix.
If prefix matches, lengths are compared.
Returns
0 if equal, negative if *this is less than other, positive if *this is greater than other.
Notes
- A
pos1past the end compares an empty slice. - A position past the end compares an empty slice.
operator==Checks if the string is equal to the other string.
bool operator==(string const & other) const noexcept;bool operator==(string_view_t other) const noexcept;bool operator==(const_pointer other) const noexcept;operator<=>Computes the lexicographic ordering between this and the other string.
std::strong_ordering operator<=>(string const & other) const noexcept;std::strong_ordering operator<=>(string_view_t other) const noexcept;std::strong_ordering operator<=>(const_pointer other) const noexcept;starts_withChecks if the string starts with the other string.
bool starts_with(string_view_t other) const noexcept;bool starts_with(const_pointer other) const noexcept;bool starts_with(value_type other) const noexcept;Checks if the string starts with the other character.
ends_withChecks if the string ends with the other string.
bool ends_with(string_view_t other) const noexcept;bool ends_with(const_pointer other) const noexcept;bool ends_with(value_type other) const noexcept;Checks if the string ends with the other character.
containsChecks if the string contains the given substring.
bool contains(string_view_t other) const noexcept;bool contains(value_type character) const noexcept;bool contains(const_pointer other) const noexcept;Checks if the string contains the given null-terminated substring.
Returns
Always true for an empty other, as std::string_view::find(v) != npos is.
findFind the first occurrence of a substring, skipping the first skip characters.
size_type find(string_view_t other, size_type skip = 0) const noexcept;size_type find(value_type character, size_type skip = 0) const noexcept;Find the first occurrence of a character, skipping the first skip characters.
size_type find(
const_pointer other,
size_type pos,
size_type count) const noexcept;size_type find(byteset_t set) const noexcept;Find the first occurrence of a character from a set.
Returns
The offset of the first character of the match, or npos if not found.
Returns
rfindFind the last occurrence of a substring.
size_type rfind(string_view_t other) const noexcept;size_type rfind(string_view_t other, size_type until) const noexcept;Find the last occurrence of a substring, within first until characters.
size_type rfind(value_type character) const noexcept;Find the last occurrence of a character.
size_type rfind(value_type character, size_type until) const noexcept;Find the last occurrence of a character, within first until characters.
size_type rfind(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a substring, within first until characters.
size_type rfind(byteset_t set) const noexcept;Find the last occurrence of a character from a set.
Returns
The offset of the first character of the match, or npos if not found.
Returns
size()for an emptyother, matchingstd::string_view::rfind.- For an empty
other,min(until, size()), matchingstd::string_view::rfind. - For an empty
other,min(until, size()); consistent with thestring_view_toverload above.
find_first_ofFind the first occurrence of a character from a set.
size_type find_first_of(
byteset_t set,
size_type skip = 0) const noexcept;size_type find_first_of(
string_view_t other,
size_type skip = 0) const noexcept;Find the first occurrence of a character from the other string.
size_type find_first_of(
const_pointer other,
size_type skip,
size_type count) const noexcept;Find the first occurrence of a character from a set.
Parameters
set | in | The characters to match. |
|---|---|---|
skip | in | Number of characters to skip before the search. |
other | in | The characters to match. |
count | in | Number of characters at other. |
Returns
npos if skip > size().
find_first_not_ofFind the first occurrence of a character outside a set.
size_type find_first_not_of(
byteset_t set,
size_type skip = 0) const noexcept;size_type find_first_not_of(
string_view_t other,
size_type skip = 0) const noexcept;Find the first occurrence of a character outside the other string.
size_type find_first_not_of(
const_pointer other,
size_type skip,
size_type count) const noexcept;Find the first occurrence of a character outside a set.
Parameters
set | in | The characters to avoid. |
|---|---|---|
skip | in | The number of first characters to be skipped. |
other | in | The characters to avoid. |
count | in | Number of characters at other. |
Returns
npos if skip > size().
find_last_ofFind the last occurrence of a character from a set.
size_type find_last_of(byteset_t set) const noexcept;size_type find_last_of(byteset_t set, size_type until) const noexcept;size_type find_last_of(
string_view_t other,
size_type until = npos) const noexcept;Find the last occurrence of a character from the other string.
size_type find_last_of(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a character from a set.
Parameters
until | in | The offset of the last character to be considered. |
|---|---|---|
other | in | The characters to match. |
count | in | Number of characters at other. |
find_last_not_ofFind the last occurrence of a character outside a set.
size_type find_last_not_of(byteset_t set) const noexcept;size_type find_last_not_of(
byteset_t set,
size_type until) const noexcept;size_type find_last_not_of(
string_view_t other,
size_type until = npos) const noexcept;Find the last occurrence of a character outside the other string.
size_type find_last_not_of(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a character outside a set.
Parameters
until | in | The offset of the last character to be considered. |
|---|---|---|
other | in | The characters to avoid. |
count | in | Number of characters at other. |
*× 2Python-like convenience function, dropping prefix formed of given characters.
string & lstrip(byteset_t set) noexcept;Notes
Similar to boost::algorithm::trim_left_if(str, is_any_of(set)).
*× 2Python-like convenience function, dropping suffix formed of given characters.
string & rstrip(byteset_t set) noexcept;Notes
Similar to boost::algorithm::trim_right_if(str, is_any_of(set)).
*× 2Python-like convenience function, stripping characters from the set off both ends.
string & strip(byteset_t set) noexcept;Notes
Similar to boost::algorithm::trim_if(str, is_any_of(set)).
resizeResizes the string to a specified number of characters, padding with the specified character if needed.
status_t resize(size_type count, value_type character = '\0') noexcept;Parameters
count | in | The new size of the string. |
|---|---|---|
character | in | The character to fill new elements with, if expanding, by default the null character. |
Statuses
overflow_risk_kAcountpastmax_size.
shrink_to_fitReduces memory usage by freeing unused memory.
status_t shrink_to_fit() noexcept;reserveReserves enough space for a specified number of characters.
status_t reserve(size_type capacity) noexcept;Parameters
capacity | in | The new capacity to reserve. |
|---|
Statuses
overflow_risk_kAcapacitypastmax_size.
assignAssigns a new value to the string, replacing its current contents.
status_t assign(string_view_t other) noexcept;template <typename first_type_, typename second_type_>
status_t assign(
concatenation<first_type_, second_type_> const & other) noexcept;Assigns a concatenated sequence to the string, replacing its current contents.
status_t assign(size_type repeats, char_type character) noexcept;Overwrites the string with character repeated repeats times.
status_t assign(const_pointer other, size_type length) noexcept;Overwrites the string with length characters from other.
status_t assign(
string_view_t str,
size_type pos,
size_type count = npos) noexcept;Overwrites the string with at most count characters of str after its first pos, clamping pos to its end.
template <typename input_iterator>
status_t assign(input_iterator first, input_iterator last) noexcept;Overwrites the string with the characters between first and last.
status_t assign(std::initializer_list<char_type> list) noexcept;Overwrites the string with the characters of list.
Parameters
other | in | The string view whose contents to assign. |
|---|
Statuses
overflow_risk_kPastmax_size.
push_backAdds a single character to the end of the string.
status_t push_back(char_type c) noexcept;Parameters
c | in | The character to add. |
|---|
appendAppends a given character array to the string.
status_t append(const_pointer str, size_type length) noexcept;status_t append(string_view_t str) noexcept;Appends a string view to the string.
status_t append(
string_view_t str,
size_type pos,
size_type length = npos) noexcept;Appends at most length characters of str after its first pos, clamping pos to its end.
status_t append(const_pointer str) noexcept;Appends the null-terminated str.
status_t append(size_type repeats, char_type character) noexcept;Appends character repeated repeats times.
status_t append(std::initializer_list<char_type> other) noexcept;Appends the characters of other.
template <typename input_iterator>
status_t append(input_iterator first, input_iterator last) noexcept;Appends the characters between first and last.
Parameters
str | in | The pointer to the array of characters to append. |
|---|---|---|
length | in | The number of characters to append. |
Statuses
overflow_risk_kPastmax_size.
erase_sliceErases (in-place) the characters between two signed offsets, counted from the end when negative, like Python's del text[start:end].
size_type erase_slice(
difference_type signed_start_offset = 0,
difference_type signed_end_offset = npos) noexcept;Returns
Number of characters removed.
insert_atInserts (in-place) string at a signed offset, counted from the end when negative, like Python's text[offset:offset] = string.
status_t insert_at(
difference_type signed_offset,
string_view_t string) noexcept;Statuses
overflow_risk_kPastmax_size.
replace_sliceReplaces (in-place) the characters between two signed offsets, counted from the end when negative, like Python's text[start:end] = replacement.
status_t replace_slice(
difference_type signed_start_offset,
difference_type signed_end_offset,
string_view_t replacement) noexcept;Statuses
overflow_risk_kPastmax_size.
resize_and_overwriteResizes the string to a specified number of characters without initializing new elements, calling the provided callback to overwrite the resized contents.
template <typename operation_type_>
status_t resize_and_overwrite(
size_type count,
operation_type_ operation) noexcept;Parameters
count | in | The new size of the string. |
|---|---|---|
operation | in | A callback that receives a pointer and the new size, and returns the actual new size. |
See also
Statuses
overflow_risk_kAcountpastmax_size.
clearClears the string contents, but no deallocations happen.
void clear() noexcept;eraseErases ( in-place ) the given range of characters.
iterator erase(const_iterator first, const_iterator last) noexcept;iterator erase(const_iterator pos) noexcept;Erases (in-place) the one character at a given position.
string & erase(size_type pos = 0, size_type count = npos) noexcept;Erases (in-place) at most count characters from pos, none when pos passes the end.
Returns
Iterator following the erased character, or end() if no such character exists.
insertInserts (in-place) character repeats times at offset, clamped to the end.
status_t insert(
size_type offset,
size_type repeats,
char_type character) noexcept;status_t insert(size_type offset, string_view_t other) noexcept;Inserts (in-place) other at offset, clamped to the end.
status_t insert(
size_type offset,
const_pointer start,
size_type length) noexcept;Inserts (in-place) length characters from start at offset, clamped to the end.
status_t insert(
size_type offset,
string_view_t other,
size_type other_index,
size_type count = npos) noexcept;Inserts (in-place) at most count characters of other after its first other_index at offset, clamping both positions to their ends.
expected<iterator> insert(
const_iterator it,
char_type character) noexcept;Inserts (in-place) character before it.
expected<iterator> insert(
const_iterator it,
size_type repeats,
char_type character) noexcept;Inserts (in-place) character repeats times before it.
template <typename input_iterator>
expected<iterator> insert(
const_iterator it,
input_iterator first,
input_iterator last) noexcept;Inserts (in-place) the characters between first and last before it.
expected<iterator> insert(
const_iterator it,
std::initializer_list<char_type> list) noexcept;Inserts (in-place) the characters of list before it.
Statuses
overflow_risk_kPastmax_size.
replaceReplaces (in-place) at most count characters from pos with str, clamping pos to the end, where the replacement appends.
status_t replace(
size_type pos,
size_type count,
string_view_t const & str) noexcept;status_t replace(
const_iterator first,
const_iterator last,
string_view_t const & str) noexcept;Replaces (in-place) the characters between first and last with str.
status_t replace(
size_type pos,
size_type count,
string_view_t const & str,
size_type pos2,
size_type count2 = npos) noexcept;Replaces (in-place) at most count characters from pos with at most count2 characters of str after its first pos2, clamping every position to its end.
status_t replace(
size_type pos,
size_type count,
const_pointer cstr,
size_type count2) noexcept;Replaces (in-place) at most count characters from pos with count2 characters from cstr.
status_t replace(
const_iterator first,
const_iterator last,
const_pointer cstr,
size_type count2) noexcept;Replaces (in-place) the characters between first and last with count2 characters from cstr.
status_t replace(
size_type pos,
size_type count,
const_pointer cstr) noexcept;Replaces (in-place) at most count characters from pos with the null-terminated cstr.
status_t replace(
const_iterator first,
const_iterator last,
const_pointer cstr) noexcept;Replaces (in-place) the characters between first and last with the null-terminated cstr.
status_t replace(
size_type pos,
size_type count,
size_type count2,
char_type character) noexcept;Replaces (in-place) at most count characters from pos with character repeated count2 times, clamping pos to the end.
status_t replace(
const_iterator first,
const_iterator last,
size_type count2,
char_type character) noexcept;Replaces (in-place) the characters between first and last with character repeated count2 times.
template <typename input_iterator>
status_t replace(
const_iterator first,
const_iterator last,
input_iterator first2,
input_iterator last2) noexcept;Replaces (in-place) the characters between first and last with those between first2 and last2.
status_t replace(
const_iterator first,
const_iterator last,
std::initializer_list<char_type> list) noexcept;Replaces (in-place) the characters between first and last with those of list.
Statuses
overflow_risk_kPastmax_size.
pop_backRemoves the last character from the string.
void pop_back() noexcept;Warnings
The behavior is undefined if the string is empty.
hashHashes the string, equivalent to std::hash<string_view_t>{}(str).
size_type hash() const noexcept;*× 2Aggregates the values of individual bytes of a string.
size_type bytesum() const noexcept;fill_randomOverwrites the string with random binary data.
string & fill_random(std::uint64_t nonce) noexcept;string & fill_random() noexcept;This overload produces the nonce from a static variable, incrementing it each time. In this case the undefined behaviour in concurrent environments may play in our favor, but it's recommended to use the other overload in such cases.
Parameters
nonce | in | "Number used once" seeding the random number generator, never repeat it! |
|---|
See also
replace_allReplaces (in-place) all occurrences of a given string with the replacement.
status_t replace_all(
string_view_t pattern,
string_view_t replacement) noexcept;status_t replace_all(
byteset_t pattern,
string_view_t replacement) noexcept;Replaces (in-place) all occurrences of a given character set with the replacement string.
The implementation is less composable than search ranges combined with a replacing mapping for matches, and may be suboptimal when exporting the cleaned-up string to another buffer, or when this string is made exclusively of the pattern.
Notes
Similar to boost::algorithm::replace_all and Python's str.replace.
lookupReplaces (in-place) all characters in the string using the provided lookup table.
string & lookup(look_up_table_t const & table) noexcept;void lookup(
look_up_table_t const & table,
pointer output) const noexcept;Maps all characters in the current string into the output buffer using the provided lookup table.
Parameters
output | out | The buffer to write the transformed string into. |
|---|
See also
utf8_countCount UTF-8 characters in the string (not bytes).
size_type utf8_count() const noexcept;Returns
The number of UTF-8 codepoints.
utf8_seekFind the byte offset of the nth UTF-8 character.
size_type utf8_seek(size_type n) const noexcept;Parameters
n | in | The character index (0-based). |
|---|
Returns
The byte offset, or npos if n >= character count.
utf8_*_runes× 2Iterate over UTF-8 characters (codepoints) in the string.
utf8_runes_view<string_view_t> utf8__runes() const noexcept;Returns
A range view over UTF-32 codepoints decoded from UTF-8 bytes.
utf8_split_newlinesLazily splits into the lines between Unicode newlines, while utf8_newlines yields the newline runs.
utf8_split_newlines_view<string_view_t> utf8_split_newlines() const noexcept;utf8_*_newlines× 2Lazily yields the Unicode newline runs themselves (LF, CR, CRLF, NEL, LS, PS, ...).
utf8_newlines_view<string_view_t> utf8__newlines() const noexcept;utf8_split_whitespacesLazily splits into the tokens between Unicode whitespace runs (empties kept; .skip_empty() drops).
utf8_split_whitespaces_view<string_view_t> utf8_split_whitespaces() const noexcept;utf8_*_whitespaces× 2Lazily yields the Unicode whitespace runs themselves.
utf8_whitespaces_view<string_view_t> utf8__whitespaces() const noexcept;utf8_split_delimitersLazily splits into the fields between any Unicode delimiter (P/S/Z); the superset of utf8_split_whitespaces().
utf8_split_delimiters_view<string_view_t> utf8_split_delimiters() const noexcept;utf8_*_delimiters× 2Lazily yields the Unicode delimiter runs themselves (punctuation, symbols, separators).
utf8_delimiters_view<string_view_t> utf8__delimiters() const noexcept;utf8_wordbreaksLazily yields the UAX-29 word segments, in order (words + the separators between them; they tile).
utf8_wordbreaks_view<string_view_t> utf8_wordbreaks() const noexcept;utf8_uncased_foldApply Unicode case folding to the string in-place.
status_t utf8_uncased_fold() noexcept;Case folding normalizes text for uncased comparisons by mapping uppercase letters to their lowercase equivalents and handling special expansions defined in Unicode CaseFolding.txt.
Notes
The string may grow due to expansions, like U+00DF → "ss", by 3× in the worst case.
utf8_find_*_find_denormalized× 2Return a pointer to the first byte violating the given Unicode normalization form.
sz_cptr_t utf8_find__find_denormalized(sz_normal_form_t form) const noexcept;Parameters
form | in | One of sz_normal_form_nfd_k, sz_normal_form_nfc_k, sz_normal_form_nfkd_k, or sz_normal_form_nfkc_k. |
|---|
Returns
STRINGZILLA_NULL_CHAR if the string is already in form; otherwise a pointer into this string at the first offending byte.
is_*_normalized× 2Check whether the string is already in the given Unicode normalization form.
bool is__normalized(sz_normal_form_t form) const noexcept;Parameters
form | in | One of sz_normal_form_nfd_k, sz_normal_form_nfc_k, sz_normal_form_nfkd_k, or sz_normal_form_nfkc_k. |
|---|
Returns
true if the string is in form, false otherwise.
utf8_normalizeTransform the string in-place into the given Unicode normalization form.
status_t utf8_normalize(sz_normal_form_t form) noexcept;Normalization may expand the byte length (e.g., NFC → NFD decomposes composed characters). Worst-case output is 18× the input length.
Parameters
form | in | One of sz_normal_form_nfd_k, sz_normal_form_nfc_k, sz_normal_form_nfkd_k, or sz_normal_form_nfkc_k. |
|---|
makeA new string holding content, in memory of allocator.
expected<string> make(
string_view_t content,
allocator_type_ const & allocator = allocator_type_()) noexcept;template <typename first_type_, typename second_type_>
expected<string> make(
concatenation<first_type_, second_type_> const & expression,
allocator_type_ const & allocator = allocator_type_()) noexcept;A new string holding a lazy concatenation, like name | "\@" | domain, in one allocation.
Classstring_sliceA string slice (view/span) class implementing a superset of C++23 functionality with much faster SIMD-accelerated substring search and approximate matching.48
template <typename char_type_>
class string_sliceConstructors are constexpr enabling _sz literals.
nposSpecial value for missing matches.
size_type npos;We take the largest 63-bit unsigned integer on 64-bit machines. We take the largest 31-bit unsigned integer on 32-bit machines.
string_slice
constexpr string_slice() noexcept;constexpr string_slice(pointer c_string) noexcept;constexpr string_slice(pointer c_string, size_type length) noexcept;string_slice(string_slice const & other) noexcept=default;string_slice(std::nullptr_t)=delete;operator=
string_slice & operator=(string_slice const & other) noexcept=default;swapExchanges the view with that of the other.
void swap(string_slice_t & other) noexcept;operator[]Equivalent to Python's "abc"[-3:-1].
reference operator[](size_type pos) const noexcept;string_slice_t operator[](
std::initializer_list<difference_type> signed_offsets) const noexcept;Equivalent to Python's "abc"[-3:-1].
Exception-safe, unlike STL's substr. Supports signed and unsigned intervals.
frontThe slice that would be dropped by remove_prefix, that accepts signed arguments and does no bounds checking.
reference front() const noexcept;string_slice_t front(difference_type signed_offset) const noexcept;The slice that would be dropped by remove_prefix, that accepts signed arguments and does no bounds checking.
Equivalent to Python's "abc"[:2] and "abc"[:-1].
Warnings
Undefined behavior if signed_offset is above size(), below −size(), or −0.
backThe slice that would be dropped by remove_suffix, that accepts signed arguments and does no bounds checking.
reference back() const noexcept;string_slice_t back(difference_type signed_offset) const noexcept;The slice that would be dropped by remove_suffix, that accepts signed arguments and does no bounds checking.
Equivalent to Python's "abc"[2:] and "abc"[-1:].
Warnings
Undefined behavior if signed_offset is above size(), below −size(), or −0.
satSigned alternative to at().
reference sat(difference_type signed_offset) const noexcept;Handy if you often write str[str.size() - 2].
Warnings
The behavior is undefined if the position is beyond bounds.
subEquivalent to Python's "abc"[-3:-1].
string_slice_t sub(
difference_type signed_start_offset,
difference_type signed_end_offset = npos) const noexcept;Exception-safe, unlike STL's substr. Supports signed and unsigned intervals.
copyExports this entire view.
size_type copy(value_type *destination) const noexcept;size_type copy(
value_type *destination,
size_type count,
size_type n = 0) const noexcept;Exports at most count bytes of this view after the first n, none when n passes the end.
Not an STL function, but useful for concatenations. The STL variant expects at least two arguments.
remove_prefixRemoves the first n bytes from the view.
void remove_prefix(size_type n) noexcept;string_slice_t remove_prefix(string_view_t other) const noexcept;Python-like convenience function, dropping the matching prefix.
Warnings
The behavior is undefined if n > size().
remove_suffixRemoves the last n bytes from the view.
void remove_suffix(size_type n) noexcept;string_slice_t remove_suffix(string_view_t other) const noexcept;Python-like convenience function, dropping the matching suffix.
Warnings
The behavior is undefined if n > size().
substrAdded for STL compatibility.
string_slice_t substr() const noexcept;string_slice_t substr(size_type n) const noexcept;Return a slice of this view after first n bytes, empty when n passes the end, like Python's text[n:].
string_slice_t substr(size_type n, size_type count) const noexcept;Return a slice of this view after first n bytes, taking at most count bytes, empty when n passes the end, like Python's text[n:n + count].
compareCompares two strings lexicographically.
int compare(string_view_t other) const noexcept;int compare(
size_type pos1,
size_type count1,
string_view_t other) const noexcept;Compares up to count1 bytes at pos1 with other, lexicographically, then by length on a common prefix.
int compare(
size_type pos1,
size_type count1,
string_view_t other,
size_type pos2,
size_type count2) const noexcept;Compares up to count1 bytes at pos1 with up to count2 bytes at pos2 of other, lexicographically, then by length on a common prefix.
int compare(const_pointer other) const noexcept;int compare(
size_type pos1,
size_type count1,
const_pointer other) const noexcept;Compares up to count1 bytes at pos1 with other, lexicographically, then by length on a common prefix.
int compare(
size_type pos1,
size_type count1,
const_pointer other,
size_type count2) const noexcept;Compares up to count1 bytes at pos1 with the first count2 bytes of other, lexicographically, then by length on a common prefix.
If prefix matches, lengths are compared.
Returns
0 if equal, negative if *this is less than other, positive if *this is greater than other.
Notes
- A
pos1past the end compares an empty slice. - A position past the end compares an empty slice.
operator==Checks if the string is equal to the other string.
bool operator==(string_view_t other) const noexcept;bool operator==(
concatenation<string_view_t, string_view_t> const & other) const noexcept;Checks if the string is equal to a concatenation of two strings.
operator<=>Computes the lexicographic ordering between this and the ::other string.
std::strong_ordering operator<=>(string_view_t other) const noexcept;starts_withChecks if the string starts with the other string.
bool starts_with(string_view_t other) const noexcept;bool starts_with(const_pointer other) const noexcept;bool starts_with(value_type other) const noexcept;Checks if the string starts with the other character.
ends_withChecks if the string ends with the other string.
bool ends_with(string_view_t other) const noexcept;bool ends_with(const_pointer other) const noexcept;bool ends_with(value_type other) const noexcept;Checks if the string ends with the other character.
containsChecks if the string contains the given substring.
bool contains(string_view_t other) const noexcept;bool contains(value_type character) const noexcept;bool contains(const_pointer other) const noexcept;Checks if the string contains the given null-terminated substring.
Returns
Always true for an empty other, as std::string_view::find(v) != npos is.
findFind the first occurrence of a substring, skipping the first skip characters.
size_type find(string_view_t other, size_type skip = 0) const noexcept;size_type find(value_type character, size_type skip = 0) const noexcept;Find the first occurrence of a character, skipping the first skip characters.
size_type find(
const_pointer other,
size_type pos,
size_type count) const noexcept;size_type find(byteset_t set) const noexcept;Find the first occurrence of a character from a set.
Returns
The offset of the first character of the match, or npos if not found.
Returns
rfindFind the last occurrence of a substring.
size_type rfind(string_view_t other) const noexcept;size_type rfind(string_view_t other, size_type until) const noexcept;Find the last occurrence of a substring, within first until characters.
size_type rfind(value_type character) const noexcept;Find the last occurrence of a character.
size_type rfind(value_type character, size_type until) const noexcept;Find the last occurrence of a character, within first until characters.
size_type rfind(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a substring, within first until characters.
size_type rfind(byteset_t set) const noexcept;Find the last occurrence of a character from a set.
Returns
The offset of the first character of the match, or npos if not found.
Returns
size()for an emptyother.- For an empty
other,min(until, size()). - For an empty
other,min(until, size()); delegates to and is consistent with thestring_view_toverload above.
partitionSplit the string into three parts, before the match, the match itself, and after it.
partition_type partition(string_view_t pattern) const noexcept;partition_type partition(value_type pattern) const noexcept;partition_type partition(byteset_t pattern) const noexcept;rpartitionSplit the string into three parts, before the last match, the last match itself, and after it.
partition_type rpartition(string_view_t pattern) const noexcept;partition_type rpartition(value_type pattern) const noexcept;partition_type rpartition(byteset_t pattern) const noexcept;operator|Lazily concatenates two slices into an expression template, without allocating.
concatenation<string_view_t, string_view_t> operator|(
string_view_t other) const noexcept;See also
concatenate for the variadic form, and the converting constructor of string that materializes the expression.
find_first_ofFind the first occurrence of a character from a set.
size_type find_first_of(
byteset_t set,
size_type skip = 0) const noexcept;size_type find_first_of(
string_view_t other,
size_type skip = 0) const noexcept;Find the first occurrence of a character from the other string.
size_type find_first_of(
const_pointer other,
size_type skip,
size_type count) const noexcept;Find the first occurrence of a character from the other string.
Parameters
set | in | The characters to match. |
|---|---|---|
skip | in | Number of characters to skip before the search. |
other | in | The characters to match. |
count | in | Number of characters at other. |
Returns
npos if skip > size().
find_first_not_ofFind the first occurrence of a character outside a set.
size_type find_first_not_of(
byteset_t set,
size_type skip = 0) const noexcept;size_type find_first_not_of(
string_view_t other,
size_type skip = 0) const noexcept;Find the first occurrence of a character missing in the other string.
size_type find_first_not_of(
const_pointer other,
size_type skip,
size_type count) const noexcept;Find the first occurrence of a character missing in the other string.
Parameters
set | in | The characters to avoid. |
|---|---|---|
skip | in | The number of first characters to be skipped. |
other | in | The characters to avoid. |
count | in | Number of characters at other. |
Returns
npos if skip > size().
find_last_ofFind the last occurrence of a character from a set.
size_type find_last_of(byteset_t set) const noexcept;size_type find_last_of(byteset_t set, size_type until) const noexcept;size_type find_last_of(
string_view_t other,
size_type until = npos) const noexcept;Find the last occurrence of a character from the other string.
size_type find_last_of(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a character from the other string.
Parameters
until | in | The offset of the last character to be considered. |
|---|---|---|
other | in | The characters to match. |
count | in | Number of characters at other. |
find_last_not_ofFind the last occurrence of a character outside a set.
size_type find_last_not_of(byteset_t set) const noexcept;size_type find_last_not_of(
byteset_t set,
size_type until) const noexcept;size_type find_last_not_of(
string_view_t other,
size_type until = npos) const noexcept;Find the last occurrence of a character missing in the other string.
size_type find_last_not_of(
const_pointer other,
size_type until,
size_type count) const noexcept;Find the last occurrence of a character missing in the other string.
Parameters
until | in | The offset of the last character to be considered. |
|---|---|---|
other | in | The characters to avoid. |
count | in | Number of characters at other. |
utf8_countCount the number of UTF-8 characters (not bytes) in the string.
utf8_seekFind the byte offset of the Nth UTF-8 character.
size_type utf8_seek(size_type n) const noexcept;Parameters
n | in | Zero-indexed character position. |
|---|
Returns
Byte offset of the Nth character, or npos if string has fewer than n characters.
utf8_uncased_orderCompares two strings lexicographically ignoring case, with lengths breaking ties.
int utf8_uncased_order(string_view_t other) const noexcept;Returns
0 if equal, negative if *this is less than other, positive if *this is greater than other.
utf8_uncased_searchFind the byte offset of the first occurrence of a substring.
sized_match_t utf8_uncased_search(string_view_t other) const noexcept;sized_match_t utf8_uncased_search(
utf8_uncased_needle_t const & needle) const noexcept;Find the byte offset of the first occurrence of a prepared uncased needle.
Parameters
needle | in | A needle prepared once for repeated searches. |
|---|
Returns
Offset of the first occurrence or npos if not found.
utf8_uncased_matchesLazily yields all non-overlapping case-insensitive matches of a prepared needle.
find_matches_view<string_view_t, matcher_utf8_uncased_search<string_view_t>> utf8_uncased_matches(
utf8_uncased_needle_t const & needle) const noexcept;find_matches_view<string_view_t, matcher_utf8_uncased_search<string_view_t>> utf8_uncased_matches(
string_view_t needle) const noexcept;A lazy view of all non-overlapping case-insensitive matches of a UTF-8 needle.
Parameters
needle | in | A needle prepared once, reused across the whole scan. |
|---|
Returns
A find_matches_view yielding each match as a string_view_t.
Notes
An empty needle matches at every codepoint boundary, the end included.
utf8_split_newlinesLazily splits the string into the lines between Unicode newlines (UTF-8 aware).
utf8_split_newlines_view<string_slice_t> utf8_split_newlines() const noexcept;Returns
A range of the segments between all 7 Unicode newlines + the CRLF sequence.
See also
utf8_newlines() for the newline runs themselves.
utf8_split_whitespacesLazily splits the UTF-8 string into the tokens between Unicode whitespace runs.
utf8_split_whitespaces_view<string_slice_t> utf8_split_whitespaces() const noexcept;Returns
A range of the segments between all 25 Unicode White_Space characters, keeping empty ones unless .skip_empty() asks for str.split_whitespace() behavior.
See also
utf8_whitespaces() for the whitespace runs themselves.
utf8_split_delimitersLazily splits the string into the fields between any Unicode delimiter (punctuation/symbol/separator).
utf8_split_delimiters_view<string_slice_t> utf8_split_delimiters() const noexcept;Returns
A range of the segments between every P/S/Z codepoint - the superset of utf8_split_whitespaces().
See also
utf8_delimiters() for the delimiter runs themselves.
utf8_wordbreaksLazily yields the UAX-29 word segments in order, both the words and the separators.
utf8_wordbreaks_view<string_slice_t> utf8_wordbreaks() const noexcept;The segments tile the input contiguously - each yielded slice is the span between consecutive TR29 word boundaries, so concatenating them reconstructs the input.
utf8_graphemesLazily splits the string into UAX-29 grapheme clusters, in order.
utf8_graphemes_view<string_slice_t> utf8_graphemes() const noexcept;Unlike utf8_split_whitespaces(), the graphemes tile the input contiguously, with no empty segments: each yielded slice spans two consecutive TR29 grapheme cluster boundaries.
utf8_sentencesLazily splits the string into UAX-29 sentences, in order.
utf8_sentences_view<string_slice_t> utf8_sentences() const noexcept;Unlike utf8_split_whitespaces(), the sentences tile the input contiguously (no empty segments). Each yielded slice is the span between consecutive TR29 sentence boundaries.
utf8_linebreaksLazily splits the string into UAX-14 line-breakable segments, in order.
utf8_linebreaks_view<string_slice_t> utf8_linebreaks() const noexcept;Distinct from utf8_split_newlines(), which splits only on hard (mandatory) Unicode newline characters. Here every byte belongs to exactly one segment ending at an allowed line break opportunity, including both the mandatory hard breaks and the soft wrap points.
find_allFind all potentially overlapping occurrences of a given string.
find_all_type find_all(
string_view_t needle,
include_overlaps_t = {}) const noexcept;find_disjoint_type find_all(
string_view_t needle,
exclude_overlaps_t) const noexcept;Find all non-overlapping occurrences of a given string.
find_all_chars_type find_all(byteset_t set) const noexcept;Find all occurrences of given characters.
Notes
- For an empty
needle, yieldssize() + 1empty matches - one per validfind(needle, skip)offset from0tosize()inclusive. - For an empty
needle, yieldssize() + 1empty matches.
See also
rfind_allFind all potentially overlapping occurrences of a string in reverse order.
rfind_all_type rfind_all(
string_view_t needle,
include_overlaps_t = {}) const noexcept;rfind_disjoint_type rfind_all(
string_view_t needle,
exclude_overlaps_t) const noexcept;Find all non-overlapping occurrences of a given string in reverse order.
rfind_all_chars_type rfind_all(byteset_t set) const noexcept;Find all occurrences of given characters in reverse order.
Notes
For an empty needle, yields size() + 1 empty matches.
See also
splitSplit around occurrences of a given string.
split_type split(string_view_t delimiter) const noexcept;split_chars_type split(
byteset_t set = whitespaces_set()) const noexcept;Split around occurrences of given characters.
Notes
An empty delimiter never splits, yielding the whole string as the only segment.
rsplitSplit around occurrences of a given string in reverse order.
rsplit_type rsplit(string_view_t delimiter) const noexcept;rsplit_chars_type rsplit(
byteset_t set = whitespaces_set()) const noexcept;Split around occurrences of given characters in reverse order.
Notes
An empty delimiter never splits, yielding the whole string as the only segment.
See also
splitlinesSplit around the occurrences of all newline characters.
split_chars_type splitlines() const noexcept;hashHashes the string, equivalent to std::hash<string_view_t>{}(str).
size_type hash(std::uint64_t seed = 0) const noexcept;hash_multiseedHashes the string under each of seeds at once, writing one hash per seed into hashes.
void hash_multiseed(
std::span<std::uint64_t const> seeds,
std::span<std::uint64_t> hashes) const noexcept;Notes
Equivalent to hashes[i] = hash(seeds[i]), but amortizes the input loading.
See also
as_setPopulate a character set with characters present in this string.
byteset_t as_set() const noexcept;StructstringsAn owned column: the C span and the allocator its blocks came from, the twin of string.7
template <typename allocator_type_ = heap_alloc<char>>
struct stringsOnly the conversions of strings_view_t and the splits fill one, so it never grows and moves without copies. Its offsets are 32-bit while the payload fits in 4 GiB and 64-bit beyond.
rawThe tape, zeroed while empty.
allocatorWhere both blocks of raw come from and return to.
allocator_type_ allocator;strings
strings() noexcept=default;strings(allocator_type_ allocator) noexcept;strings(strings const &)=delete;strings(strings && other) noexcept;operator=
strings & operator=(strings const &)=delete;strings & operator=(strings && other) noexcept;viewDefined once string_slice is complete: inside the class, nvcc's front end, emulating Clang, asserts resolving the strings_view_t span constructor against the incomplete slice.
strings_view_t view() const noexcept;splitSplits text at the bytes of delimiters into its parts, like bytes.split.
expected<strings> split(
string_view_t text,
byteset_t const & delimiters,
sz_split_kind_t kind,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) noexcept;See also
split_linesSplits text into lines without their breaks, like str.splitlines.
expected<strings> split_lines(
string_view_t text,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) noexcept;See also
Structstrings_view_tA borrowed column in any layout of sz_strings_view_t, the twin of string_view_t.12
struct strings_view_tEvery conversion reads the whole column into a fresh strings, whose blocks come from the given allocator, and leaves it empty on failure.
rawThe C view every member reads.
strings_view_tWraps a C view, like one over records or NUL-padded rows.
strings_view_t(sz_strings_view_t raw) noexcept;strings_view_t(
char const *data,
sz_u32_t const *offsets,
std::size_t count) noexcept;An Apache Arrow String column: string i is [offsets[i], offsets[i + 1]) of data.
strings_view_t(
char const *data,
sz_u64_t const *offsets,
std::size_t count) noexcept;An Apache Arrow LargeString column, the same with 64-bit offsets.
strings_view_t(std::span<string_view_t const> strings) noexcept;Views strings through an accessor, copying no bytes, so they must outlive the view.
template <typename allocator_type_>
strings_view_t(strings<allocator_type_> const & strings) noexcept;Views the tape of strings.
findFinds needle in every string, like a LIKE 'needle' filter over a column.
status_t find(
string_view_t needle,
std::span<std::size_t> positions,
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;Parameters
needle | in | The bytes to look for. |
|---|---|---|
positions | out | The offset of each string's first match, or STRINGZILLA_SIZE_MAX. |
capabilities | in | Capabilities to pick from. |
stream | in | Null on the CPU, or the stream of the device capabilities describes. |
See also
Statuses
unexpected_dimensions_kpositionsis too short.
hashesHashes every string under one seed, each as string_view_t::hash would.
status_t hashes(
std::span<u64_t> hashes,
u64_t seed = 0,
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;See also
Statuses
unexpected_dimensions_khashesis too short.
utf8_countValidates every string as UTF-8 and, unless runes is empty, counts its runes.
status_t utf8_count(
std::span<std::size_t> runes,
std::size_t & malformed_index,
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;Parameters
runes | out | Empty, or each string's runes, unspecified from the first ill-formed one. |
|---|---|---|
malformed_index | out | The first ill-formed string, or size() if none is ill-formed. |
capabilities | in | Capabilities to pick from. |
stream | in | Null on the CPU, or the stream of the device capabilities describes. |
See also
Statuses
invalid_utf8_kA string is ill-formed.unexpected_dimensions_krunesis too short.
to_rowsWrites every string into a NUL-padded row of width bytes, truncating longer ones.
expected<std::size_t> to_rows(
std::span<char> rows,
std::size_t width,
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;Returns
The length of the longest string, to retry with wider rows, or unexpected_dimensions_k when rows holds fewer than size() rows.
See also
gatherCopies every string into one tape, whatever the layout.
template <typename allocator_type_ = heap_alloc<char>>
expected<strings<allocator_type_>> gather(
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;See also
escapeEscapes every string for kind, like JSON or CSV.
template <typename allocator_type_ = heap_alloc<char>>
expected<strings<allocator_type_>> escape(
sz_escape_kind_t kind,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;See also
unescapeUnescapes every string from kind, checking all of them before writing any.
template <typename allocator_type_ = heap_alloc<char>>
expected<strings<allocator_type_>> unescape(
sz_escape_kind_t kind,
std::size_t & malformed_index,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;Parameters
kind | in | The text format the strings are in. |
|---|---|---|
malformed_index | out | The first malformed string, set on invalid_utf8_k. |
allocator | in | Source of the result's blocks. |
capabilities | in | Capabilities to pick from. |
stream | in | Null on the CPU, or the stream of the device capabilities describes. |
See also
lookupMaps every byte through table, like tolower does.
template <typename allocator_type_ = heap_alloc<char>>
expected<strings<allocator_type_>> lookup(
look_up_table_t const & table,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;See also
normalizeBrings every string into the Unicode form, like NFC.
template <typename allocator_type_ = heap_alloc<char>>
expected<strings<allocator_type_>> normalize(
sz_normal_form_t form,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;See also
joinJoins every string with between into one, like Python's str.join.
template <typename allocator_type_ = std::allocator<char>>
expected<string<allocator_type_>> join(
string_view_t between,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) const noexcept;template <typename allocator_type_ = std::allocator<char>>
expected<string<allocator_type_>> join(
std::span<sz_strings_view_t const> columns,
std::span<sz_string_view_t const> frames,
string_view_t between,
allocator_type_ allocator = {},
sz_capability_t capabilities = default_capabilities(),
sz_stream_t stream = nullptr) noexcept;Writes row r of columns as frames[0] + columns[0][r] + frames[1] + … + frames[n], with between between rows, like CSV lines or JSON arrays.
See also
Statuses
unexpected_dimensions_kUneven columns orframesis not one longer.
Functions
ascii_lettersThe concatenation of ascii_lowercase and ascii_uppercase, independent of locale.
ascii_lowercaseThe lowercase letters "abcdefghijklmnopqrstuvwxyz".
carray<26> const & ascii_lowercase() noexcept;This value is not locale-dependent.
See also
ascii_uppercaseThe uppercase letters "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
carray<26> const & ascii_uppercase() noexcept;This value is not locale-dependent.
See also
ascii_printablesPrintable ASCII characters, including: digits, ascii_letters, punctuation, and whitespace.
ascii_controlsNon-printable ASCII control characters.
carray<33> const & ascii_controls() noexcept;Includes all codes from 0 to 31 and 127.
digitsThe digits "0123456789".
hexdigitsThe letters "0123456789abcdefABCDEF".
octdigitsThe letters "01234567".
punctuationThe 32 ASCII punctuation characters of the C locale: every printable character that is neither a letter, a digit, nor whitespace.
whitespacesWhitespace ASCII characters: space, tab, linefeed, return, formfeed, and vertical tab.
newlinesASCII characters that are considered line delimiters.
base64ASCII characters forming the BASE64 encoding alphabet: a-z, A-Z, 0-9, +, and /.
concatenateConcatenates two strings into a template expression.
template <typename first_type_, typename second_type_>
concatenation<typename concatenation_operand<first_type_>::type, typename concatenation_operand<second_type_>::type> concatenate(
first_type_ && first,
second_type_ && second) noexcept;template <typename first_type_, typename second_type_, typename... following_types_>
concatenation_result<first_type_, second_type_, following_types_...>::type concatenate(
first_type_ && first,
second_type_ && second,
following_types_ &&... following) noexcept;Concatenates two or more strings into a template expression.
See also
concatenation class for more details.
succeededWhether status reports success.
bool succeeded(status_t status) noexcept;failedWhether status reports failure.
bool failed(status_t status) noexcept;status_nameStatic, English description of status.
char const * status_name(status_t status) noexcept;Never returns nullptr, never allocates.
divide_round_upDivides x by divisor and rounds up to the nearest integer.
template <typename scalar_type_>
scalar_type_ divide_round_up(scalar_type_ x, scalar_type_ divisor);Notes
This is equivalent to ceil(x / divisor), but avoids floating-point arithmetic.
round_up_to_multipleRounds x up to the nearest multiple of divisor.
template <typename scalar_type_>
scalar_type_ round_up_to_multiple(scalar_type_ x, scalar_type_ divisor);bit_widthThe number of significant bits in x, or zero when x is zero.
template <typename scalar_type_>
int bit_width(scalar_type_ x) noexcept;Widens to u64_t first, so one body serves every unsigned width - shifting a 32-bit value by 32 would be undefined even on a branch that never runs.
Notes
Unrolled rather than delegating to sz_u64_clz, which is an intrinsic wrapper and not constexpr.
integer_square_rootExact ⌊√x⌋ over integers, without floating-point arithmetic and without a loop.
template <typename scalar_type_>
scalar_type_ integer_square_root(scalar_type_ x) noexcept;Seeds a power of two at or above the root, then runs five Newton steps: each doubles the count of correct bits, and a 64-bit input has a 32-bit root, so 1 → 2 → 4 → 8 → 16 → 32 covers every width. Newton converges from above, so one clamp lands on the floor. Unlike std::sqrt, it is constexpr, which keeps it callable from CUDA device code.
non_zero_ifEquivalent to (condition ? value : 0), but avoids branching.
template <typename value_type_>
value_type_ non_zero_if(
value_type_ value,
value_type_ condition) noexcept;trivial_swapAnalog to std::swap from <utility>, but also generates device code, unlike STL.
template <typename value_type_>
void trivial_swap(value_type_ & x, value_type_ & y) noexcept;TypesMember types47
string::traits_type | std::char_traits<char_type> |
|---|---|
string::value_type | char_type |
string::pointer | char_type * |
string::const_pointer | char_type const * |
string::reference | char_type & |
string::const_reference | char_type const & |
string::const_iterator | const_pointer |
string::iterator | pointer |
string::const_reverse_iterator | reversed_iterator_for<char_type const> |
string::reverse_iterator | reversed_iterator_for<char_type> |
string::size_type | std::size_t |
string::difference_type | std::ptrdiff_t |
string::allocator_type | allocator_type_ |
string::string_span_t | string_slice<char_type> |
string::string_view_t | string_slice<typename std::add_const<char_type>::type> |
string::partition_type | string_partition_result<string_view_t> |
string_slice::traits_type | std::char_traits<mutable_char_type> |
string_slice::value_type | mutable_char_type |
string_slice::pointer | char_type * |
string_slice::const_pointer | immutable_char_type * |
string_slice::reference | char_type & |
string_slice::const_reference | immutable_char_type & |
string_slice::const_iterator | const_pointer |
string_slice::iterator | pointer |
string_slice::reverse_iterator | reversed_iterator_for<char_type> |
string_slice::const_reverse_iterator | reversed_iterator_for<immutable_char_type> |
string_slice::size_type | std::size_t |
string_slice::difference_type | std::ptrdiff_t |
string_slice::string_slice_t | string_slice<char_type> |
string_slice::string_span_t | string_slice<mutable_char_type> |
string_slice::string_view_t | string_slice<immutable_char_type> |
string_slice::partition_type | string_partition_result<string_slice_t> |
string_slice::find_all_type | find_matches_view<string_slice_t, matcher_find<string_view_t, include_overlaps_t>> |
string_slice::rfind_all_type | rfind_matches_view<string_slice_t, matcher_rfind<string_view_t, include_overlaps_t>> |
string_slice::find_disjoint_type | find_matches_view<string_slice_t, matcher_find<string_view_t, exclude_overlaps_t>> |
string_slice::rfind_disjoint_type | rfind_matches_view<string_slice_t, matcher_rfind<string_view_t, exclude_overlaps_t>> |
string_slice::find_all_chars_type | find_matches_view<string_slice_t, matcher_find_first_of<string_view_t>> |
string_slice::rfind_all_chars_type | rfind_matches_view<string_slice_t, matcher_find_last_of<string_view_t>> |
string_slice::split_type | find_splits_view<string_slice_t, matcher_find<string_view_t, exclude_overlaps_t>> |
string_slice::rsplit_type | rfind_splits_view<string_slice_t, matcher_rfind<string_view_t, exclude_overlaps_t>> |
string_slice::split_chars_type | find_splits_view<string_slice_t, matcher_find_first_of<string_view_t>> |
string_slice::rsplit_chars_type | rfind_splits_view<string_slice_t, matcher_find_last_of<string_view_t>> |
strings::allocator_type | allocator_type_ |
strings::value_type | string_view_t |
strings::iterator | indexed_container_iterator<strings> |
strings_view_t::value_type | string_view_t |
strings_view_t::iterator | indexed_container_iterator<strings_view_t> |