Collections » CnxString module

CnxString is a bounds-safe string type that manages its own length and capacity, is fully cstring (aka char*) compatible, provides Cnx compatible random-access iterators over its contents, and is allocator aware. It aims to provide more modern string-handling capabilities to C, with an API and functionality comparable to C++'s std::string. CnxString is always null-terminated, so it's completely compatible with C's existing string functions, so long as those functions do not modify the length of the string or insert null terminators (other mutable access is acceptable).

CnxString provides a small size optimization (SSO). This means that for short strings, the data associated with the string will be stored on the stack, up to a certain number of characters, before resorting to heap allocation. This does not require CnxString to take up extra stack space in order to implement, sizeof(CnxString) would be the same regardless of this optimization. The optimization allows for up to 2 * sizeof(usize) + sizeof(void*) - 1 bytes to be stored on the stack. on x86_64, this translates to 23 characters, excluding the null terminator (24 including the null terminator).

Example:

#include <string.h> // for strlen
#include <Cnx/String.h>
#include <Cnx/IO.h>
let_mut string = cnx_string_from("Cnx");
cnx_string_prepend(string, "Hello World ");
cnx_string_append(string, " style!");

// `CnxString is fully compatible with non-mutating standard C string functions,
// and partially compatible with mutating standard C string functions
// (length must not be modified and null terminators must not be inserted,
// outside of `CnxString`'s own APIs)
let len_c = strlen(cnx_string_into_cstring(string));
println("string is {} chars long (c-style)", len_c);

let len = cnx_string_length(string);
println("string is {} chars long (Cnx-style)", len);

// print `string` to `stdout`, at once, followed by a newline
println("{}", string);

// range-for loop enabled by Cnx compatible iterators
// print `string` to `stdout`, one character at a time, followed by a newline
foreach(character, string) {
    print("{}", character);
}
print("\n");

Classes

struct CnxString
Cnx string type CnxString is a bounds safe, allocator aware, potentially dynamically allocated string type with significantly improved ergonomics over const char*s (aka cstrings), but maintains compatibility with them (CnxString is always null terminated). Provides similar functionality to C++'s std::string, but in C.
struct CnxStringIterator
Cnx string iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its non-const iterator type (CnxRandomAccessIterator(char_ptr))
struct CnxStringConstIterator
Cnx string const iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its const iterator type (CnxRandomAccessIterator(const_char_ptr))
struct cnx_string_vtable_t
The function vector table of methods associated with CnxString

Typedefs

using cnx_string_vtable_t = struct cnx_string_vtable_t
The function vector table of methods associated with CnxString
using CnxString = struct CnxString
Cnx string type CnxString is a bounds safe, allocator aware, potentially dynamically allocated string type with significantly improved ergonomics over const char*s (aka cstrings), but maintains compatibility with them (CnxString is always null terminated). Provides similar functionality to C++'s std::string, but in C.
using CnxStringIterator = struct CnxStringIterator
Cnx string iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its non-const iterator type (CnxRandomAccessIterator(char_ptr))
using CnxStringConstIterator = struct CnxStringConstIterator
Cnx string const iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its const iterator type (CnxRandomAccessIterator(const_char_ptr))

Functions

CnxString cnx_string_new(void)
Creates a new, empty CnxString
CnxString cnx_string_new_with_allocator(CnxAllocator allocator)
Creates a new, empty CnxString that will use the given allocator.
CnxString cnx_string_new_with_capacity(usize capacity)
Creates a new CnxString with the given initial capacity.
CnxString cnx_string_new_with_capacity_with_allocator(usize capacity, CnxAllocator allocator)
Creates a new CnxString with the given initial capacity.
CnxString cnx_string_from_cstring(restrict const_cstring string, usize length) cnx_disable_if(!string
Creates a new CnxString from the given cstring
CnxString cnx_string_from_cstring_with_allocator(restrict const_cstring string, usize length, CnxAllocator allocator) cnx_disable_if(!string
Creates a new CnxString from the given cstring
CnxString cnx_string_from_wcstring(restrict const_wcstring string, usize length) cnx_disable_if(!string
Creates a new CnxString from the given wcstring
CnxString cnx_string_from_wcstring_with_allocator(restrict const_wcstring string, usize length, CnxAllocator allocator) cnx_disable_if(!string
Creates a new CnxString from the given wcstring
CnxString cnx_string_from_stringview(const CnxStringView*restrict view) cnx_disable_if(!view
Creates a new CnxString from the given CnxStringView
CnxString cnx_string_from_stringview_with_allocator(const CnxStringView*restrict view, CnxAllocator allocator) cnx_disable_if(!view
Creates a new CnxString that will use the given memory allocator, from the given CnxStringView
const_cstring cnx_string_into_cstring(const CnxString*restrict self)
Returns the cstring representation of this CnxString
const_wcstring cnx_string_into_wcstring(const CnxString*restrict self)
Returns the wcstring converted representation of this CnxString. The result will be allocated with the same allocator used by this CnxString
const_wcstring cnx_string_into_wcstring_with_allocator(const CnxString*restrict self, CnxAllocator allocator)
Returns the wcstring converted representation of this CnxString, allocated with the given allocator;.
CnxStringView cnx_string_into_stringview(const CnxString*restrict self)
Returns a CnxStringView into this CnxString
CnxString cnx_string_clone(const CnxString*restrict self)
Creates a copy of this CnxString using the same allocator.
CnxString cnx_string_clone_with_allocator(const CnxString*restrict self, CnxAllocator allocator)
Creates a copy of this CnxString using the given allocator.
void cnx_string_free(void*restrict self)
Frees the allocated memory of the string, if it is not small string optimized.
char_ptr cnx_string_at_mut(CnxString*restrict self, usize index)
Returns a pointer to the character at the given index.
const_char_ptr cnx_string_at_const(const CnxString*restrict self, usize index)
Returns a pointer to the character at the given index.
char_ptr cnx_string_front_mut(CnxString*restrict self)
Returns the character at the beginning of the string.
const_char_ptr cnx_string_front_const(const CnxString*restrict self)
Returns the character at the beginning of the string.
char_ptr cnx_string_back_mut(CnxString*restrict self)
Returns the character at the end of the string.
const_char_ptr cnx_string_back_const(const CnxString*restrict self)
Returns the character at the end of the string.
bool cnx_string_is_empty(const CnxString*restrict self)
Returns whether the string is empty or not.
bool cnx_string_is_full(const CnxString*restrict self)
Returns whether the string contains capacity number of characters.
usize cnx_string_size(const CnxString*restrict self)
Returns the current size of the string.
usize cnx_string_length(const CnxString*restrict self)
Returns the current length of the string.
usize cnx_string_max_size(void)
Returns the maximum possible size of a CnxString
usize cnx_string_capacity(const CnxString*restrict self)
Returns the current capacity of the string.
CnxString cnx_string_first(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the first num_chars characters in the string as a new CnxString
cstring cnx_string_first_cstring(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the first num_chars characters in the string as a cstring allocated with the allocator associated with self
CnxStringView cnx_string_first_stringview(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the first num_chars characters in the string as a CnxStringView
CnxString cnx_string_last(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the last num_chars characters in the string as a new CnxString
cstring cnx_string_last_cstring(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the last num_chars characters in the string as a cstring allocated with the allocator associated with self
CnxStringView cnx_string_last_stringview(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
Returns the last num_chars characters in the string as a CnxStringView
bool cnx_string_equal(const CnxString*restrict self, const CnxString*restrict to_compare) cnx_disable_if(!to_compare
Determines if the given strings are equal.
bool cnx_string_equal_cstring(const CnxString*restrict self, restrict const_cstring to_compare, usize length) cnx_disable_if(!to_compare
Determines if the given strings are equal.
bool cnx_string_equal_stringview(const CnxString*restrict self, const CnxStringView*restrict to_compare) cnx_disable_if(!to_compare
Determines if the given strings are equal.
bool cnx_string_contains(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
Determines if the string contains the given substring.
bool cnx_string_contains_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
Determines if the string contains the given substring.
bool cnx_string_contains_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
Determines if the string contains the given substring.
bool cnx_string_starts_with(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
Determines if the string begins with the given substring.
bool cnx_string_starts_with_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
Determines if the string begins with the given substring.
bool cnx_string_starts_with_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
Determines if the string begins with the given substring.
bool cnx_string_ends_with(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
Determines if the string ends with the given substring.
bool cnx_string_ends_with_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
Determines if the string ends with the given substring.
bool cnx_string_ends_with_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
Determines if the string ends with the given substring.
CnxOption(usize) cnx_string_find_first(const CnxString *restrict self
Returns the index of the first occurrence of the given substring, or None if the substring does not occur.
CnxString cnx_string_substring(const CnxString*restrict self, usize index, usize length)
Returns the length length substring beginning at index
CnxString cnx_string_substring_with_allocator(const CnxString*restrict self, usize index, usize length, CnxAllocator allocator)
Returns the length length substring beginning at index, allocated with the given allocator.
CnxStringView cnx_string_stringview_of(const CnxString*restrict self, usize index, usize length)
Returns a CnxStringView into self of the range [index, index + length)
CnxString cnx_string_concatenate(const CnxString*restrict left, const CnxString*restrict right) cnx_disable_if(!right
Concatenates the two strings into a new one, using the allocator associated with left, if necessary.
CnxString cnx_string_concatenate_cstring(const CnxString*restrict left, restrict const_cstring right, usize right_length) cnx_disable_if(!right
Concatenates the two strings into a new one, using the allocator associated with left, if necessary.
CnxString cnx_string_concatenate_cstrings(restrict const_cstring left, usize left_length, restrict const_cstring right, usize right_length) cnx_disable_if(!left
Concatenates the two strings into a new CnxString, using the default allocator (malloc)
CnxString cnx_string_concatenate_stringview(const CnxString*restrict left, const CnxStringView*restrict right) cnx_disable_if(!left
Concatenates the two strings into a new one, using the allocator associated with left, if necessary.
CnxString cnx_string_concatenate_stringviews(const CnxStringView*restrict left, const CnxStringView*restrict right) cnx_disable_if(!left
Concatenates the two stringviews into a new CnxString, using the default allocator (malloc)
void invalid_types_passed_to_cnx_string_concatenate(void)
This function is an __INTENTIONALLY_ undefined function so that improper use of cnx_string_concatenate (passing values of invalid type(s)) will result in a build failure.
CnxString cnx_string_concatenate_with_allocator(const CnxString*restrict left, const CnxString*restrict right, CnxAllocator allocator) cnx_disable_if(!right
Concatenates the two strings into a new one, using the given allocator.
CnxString cnx_string_concatenate_cstring_with_allocator(const CnxString*restrict left, restrict const_cstring right, usize right_length, CnxAllocator allocator) cnx_disable_if(!right
Concatenates the two strings into a new one, using the given allocator.
CnxString cnx_string_concatenate_stringview_with_allocator(const CnxString*restrict left, const CnxStringView*restrict right, CnxAllocator allocator) cnx_disable_if(!right
Concatenates the two strings into a new one, using the given allocator.
CnxString cnx_string_concatenate_cstrings_with_allocator(restrict const_cstring left, usize left_length, restrict const_cstring right, usize right_length, CnxAllocator allocator) cnx_disable_if(!left
Concatenates the two strings into a new one, using the given allocator.
CnxString cnx_string_concatenate_stringviews_with_allocator(const CnxStringView*restrict left, const CnxStringView*restrict right, CnxAllocator allocator) cnx_disable_if(!left
Concatenates the two strings into a new one, using the given allocator.
void cnx_string_fill(CnxString*restrict self, char character)
Fills the string with the given character.
void cnx_string_clear(CnxString*restrict self)
Clears the string, filling it with null.
void cnx_string_shrink_to_fit(CnxString*restrict self)
Shrinks the string so its capacity equals its size.
void cnx_string_insert(CnxString*restrict self, const CnxString*restrict to_insert, usize index) cnx_disable_if(!to_insert
Inserts the given string to_insert into self at the given index
void cnx_string_insert_cstring(CnxString*restrict self, restrict const_cstring to_insert, usize to_insert_length, usize index) cnx_disable_if(!to_insert
Inserts the given string to_insert into self at the given index
void cnx_string_insert_stringview(CnxString*restrict self, const CnxStringView*restrict to_insert, usize index) cnx_disable_if(!to_insert
Inserts the given string to_insert into self at the given index
void cnx_string_erase(CnxString*restrict self, usize index)
Erases the character at the given index from the string.
void cnx_string_erase_n(CnxString*restrict self, usize index, usize num_characters)
Erases num_character characters from the string, starting at the given index.
void cnx_string_resize(CnxString*restrict self, usize new_size)
Resizes the string to the new size, null padding or truncating if necessary.
void cnx_string_reserve(CnxString*restrict self, usize new_capacity)
Reserves additional capacity in the string This will allocate enough memory to store at least new_capacity number of characters,.
void cnx_string_push_back(CnxString*restrict self, char character)
Appends the given character to the end of the string.
void cnx_string_push_front(CnxString*restrict self, char character)
Prepends the given character to the beginning of the string.
CnxOption(char)
Removes the last character in the string and returns it.
void cnx_string_append(CnxString*restrict self, const CnxString*restrict to_append) cnx_disable_if(!to_append
Appends the given string to the end of the string.
void cnx_string_append_cstring(CnxString*restrict self, restrict const_cstring to_append, usize to_append_length) cnx_disable_if(!to_append
Appends the given string to the end of the string.
void cnx_string_append_stringview(CnxString*restrict self, const CnxStringView*restrict to_append) cnx_disable_if(!to_append
Appends the given string to the end of the string.
void cnx_string_prepend(CnxString*restrict self, const CnxString*restrict to_prepend) cnx_disable_if(!to_prepend
Prepends the given string to the beginning of the string.
void cnx_string_prepend_cstring(CnxString*restrict self, restrict const_cstring to_prepend, usize to_prepend_length) cnx_disable_if(!to_prepend
Prepends the given string to the beginning of the string.
void cnx_string_prepend_stringview(CnxString*restrict self, const CnxStringView*restrict to_prepend) cnx_disable_if(!to_prepend
Prepends the given string to the beginning of the string.
void cnx_string_replace(CnxString*restrict self, const CnxString*restrict to_replace_with, usize index) cnx_disable_if(!to_replace_with
Replaces the substring beginning at index with the given one.
void cnx_string_replace_cstring(CnxString*restrict self, restrict const_cstring to_replace_with, usize to_replace_with_length, usize index) cnx_disable_if(!to_replace_with
Replaces the substring beginning at index with the given one.
void cnx_string_replace_stringview(CnxString*restrict self, const CnxStringView*restrict to_replace_with, usize index) cnx_disable_if(!to_replace_with
Replaces the substring beginning at index with the given one.
CnxRandomAccessIteratorchar_ref cnx_string_begin(CnxString*restrict self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)
CnxRandomAccessIteratorchar_ref cnx_string_end(CnxString*restrict self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)
CnxRandomAccessIteratorchar_ref cnx_string_rbegin(CnxString*restrict self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)
CnxRandomAccessIteratorchar_ref cnx_string_rend(CnxString*restrict self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)
CnxRandomAccessIteratorconst_char_ref cnx_string_cbegin(const CnxString*restrict self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)
CnxRandomAccessIteratorconst_char_ref cnx_string_cend(const CnxString*restrict self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)
CnxRandomAccessIteratorconst_char_ref cnx_string_crbegin(const CnxString*restrict self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)
CnxRandomAccessIteratorconst_char_ref cnx_string_crend(const CnxString*restrict self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)
CnxVector(CnxString) cnx_string_split_on(const CnxString *restrict self
Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.
CnxVector(CnxStringView) cnx_string_view_split_on(const CnxString *restrict self
Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector
usize cnx_string_occurrences_of_char(const CnxString*restrict self, char to_find)
Determines the total number of times the character to_find occurs in self
usize cnx_string_occurrences_of(const CnxString*restrict self, const CnxString*restrict to_find)
Determines the total number of times the string to_find occurs in self
usize cnx_string_occurrences_of_stringview(const CnxString*restrict self, const CnxStringView*restrict to_find)
Determines the total number of times the stringview to_find occurs in self
usize cnx_string_occurrences_of_cstring(const CnxString*restrict self, restrict const_cstring to_find, usize to_find_length)
Determines the total number of times the cstring to_find occurs in self
CnxVector(usize) cnx_string_find_occurrences_of_char(const CnxString *restrict self
Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector

Defines

#define cnx_string_from(string)
Creates a new CnxString from the given string-like type.
#define cnx_string_from_with_allocator(string, allocator)
Creates a new CnxString from the given string-like type, using the given CnxAllocator for memory allocations.
#define cnx_string_concatenate(left, right)
Concatenates the two strings and returns the result as a new CnxString
#define cnx_string_concatenate_with_allocator(left, right, allocator)
Concatenates the two strings and returns the result as a new CnxString
#define cnx_string_into_cstring(self)
Returns the cstring representation of the given CnxString
#define cnx_string_into_wcstring(self)
Returns the wcstring representation of the given CnxString
#define cnx_string_into_wcstring_with_allocator(self, allocator)
Returns the wcstring representation of the given CnxString
#define cnx_string_into_stringview(self)
Returns a CnxStringView into self.
#define cnx_string_clone(self)
Creates a copy of the given CnxString, self, using the CnxAllocator associated with self
#define cnx_string_clone_with_allocator(self, allocator)
Creates a copy of the given CnxString, self, using the given CnxAllocator
#define cnx_string_free(self)
Cleans up the given CnxString, freeing any allocated memory.
#define cnx_string_at(self, index)
Returns a reference to the character at the given index.
#define cnx_string_front(self)
Returns a reference to the character at the beginning of the string.
#define cnx_string_back(self)
Returns a reference to the character at the end of the string.
#define cnx_string_data(self)
Returns the raw character array of the string.
#define cnx_string_is_empty(self)
Returns whether the given CnxString is empty or not.
#define cnx_string_is_full(self)
Returns whether the given CnxString is full.
#define cnx_string_size(self)
Returns the current size of the given CnxString
#define cnx_string_length(self)
Returns the current length of the given CnxString
#define cnx_string_capacity(self)
Returns the current capacity of the given CnxString
#define cnx_string_first(self, num_chars)
Returns the first num_chars characters of self as a new CnxString, using the CnxAllocator associated with self
#define cnx_string_first_cstring(self, num_chars)
Returns the first num_chars characters of self as a new cstring, using the CnxAllocator associated with self
#define cnx_string_first_stringview(self, num_chars)
Returns the first num_chars characters of self as a CnxStringView
#define cnx_string_last(self, num_chars)
Returns the last num_chars characters of self as a new CnxString, using the CnxAllocator associated with self
#define cnx_string_last_cstring(self, num_chars)
Returns the last num_chars characters of self as a new cstring, using the CnxAllocator associated with self
#define cnx_string_last_stringview(self, num_chars)
Returns the last num_chars characters of self as a CnxStringView
#define cnx_string_equal(self, to_compare)
Determines if this string and the given one are equal.
#define cnx_string_contains(self, substring)
Determines whether the string contains the given substring.
#define cnx_string_starts_with(self, substring)
Determines whether the string starts with the given substring.
#define cnx_string_ends_with(self, substring)
Determines whether the string ends with the given substring.
#define cnx_string_find_first(self, substring)
Finds the first occurrence of the given substring in self, if any.
#define cnx_string_find_last(self, substring)
Finds the last occurrence of the given substring in self, if any.
#define cnx_string_substring(self, index, length)
Returns the substring of self starting at index with length length as a CnxString, using the CnxAllocator associated with self
#define cnx_string_substring_with_allocator(self, index, length, allocator)
Returns the substring of self starting at index with length length as a CnxString, associating the given CnxAllocator with the substring.
#define cnx_string_stringview_of(self, index, length)
Returns a CnxStringView into self beginning at index with length length
#define cnx_string_fill(self, character)
Fills the given CnxString with the given character.
#define cnx_string_clear(self)
Clears the given CnxString
#define cnx_string_shrink_to_fit(self)
Shrinks the capacity of the given CnxString to its size.
#define cnx_string_insert(self, to_insert, index)
Inserts to_insert into self at the given index.
#define cnx_string_erase(self, index)
Erases the character at the given index from self
#define cnx_string_erase_n(self, index, num_characters)
Erases num_characters characters from self, beginning at index
#define cnx_string_resize(self, new_size)
Resizes the given CnxString to the given new_size, filling the characters in the expanded size with null.
#define cnx_string_reserve(self, new_capacity)
Allocates memory such that at least new_capacity number of characters can be stored in the given CnxString
#define cnx_string_push_back(self, character)
Pushes the given character onto the end of the given CnxString
#define cnx_string_push_front(self, character)
Pushes the given character onto the beginning of the given CnxString
#define cnx_string_pop_back(self)
Removes the last character in self if cnx_string_size(self) > 0, and returns it.
#define cnx_string_pop_front(self)
Removes the first character in self if cnx_string_size(self) > 0, and returns it.
#define cnx_string_append(self, to_append)
Appends to_append to the end of self
#define cnx_string_prepend(self, to_prepend)
Prepends to_prepend to the beginning of self
#define cnx_string_replace(self, to_replace_with, index)
Replaces the contents of self with to_replace_with, beginning at the given index.
#define cnx_string_begin(self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)
#define cnx_string_end(self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)
#define cnx_string_rbegin(self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)
#define cnx_string_rend(self)
Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)
#define cnx_string_cbegin(self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)
#define cnx_string_cend(self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)
#define cnx_string_crbegin(self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)
#define cnx_string_crend(self)
Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)
#define cnx_string_split_on(self, delimiter)
Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.
#define cnx_string_split_on_with_allocator(self, delimiter, allocator)
Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.
#define cnx_string_view_split_on(self, delimiter)
Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector
#define cnx_string_view_split_on_with_allocator(self, delimiter, allocator)
Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector
#define cnx_string_occurrences_of_char(self, to_find)
Determines the total number of times the character to_find occurs in self
#define cnx_string_occurrences_of(self, to_find)
Determines the total number of times the string or string-like to_find occurs in self
#define cnx_string_find_occurrences_of_char(self, to_find)
Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector
#define cnx_string_find_occurrences_of_char_with_allocator(self, to_find, allocator)
Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector
#define cnx_string_find_occurrences_of(self, to_find)
Finds the indices at which the string or string-like to_find occurs in self, and returns them in a CnxVector
#define cnx_string_find_occurrences_of_with_allocator(self, to_find, allocator)
Finds the indices at which the string or string-like to_find occurs in self, and returns them in a CnxVector

Typedef documentation

typedef struct cnx_string_vtable_t cnx_string_vtable_t
#include <include/Cnx/String.h>

The function vector table of methods associated with CnxString

typedef struct CnxString CnxString
#include <include/Cnx/String.h>

Cnx string type CnxString is a bounds safe, allocator aware, potentially dynamically allocated string type with significantly improved ergonomics over const char*s (aka cstrings), but maintains compatibility with them (CnxString is always null terminated). Provides similar functionality to C++'s std::string, but in C.

Example:

#include <Cnx/String.h>
#include <Cnx/IO.h>
// create default allocator (malloc allocates, free frees)
let allocator = cnx_allocator_new();
// could also call cnx_string_from("This is a string") since we're using the default
// allocator
let_mut string = cnx_string_from_with_allocator("This is a string", allocator);
cnx_string_append(&string, " with some extra text");
cnx_string_prepend(&string, "Hello world!\n");
// prints to stdout:
// Hello world!
// This is a string with some extra text
println("{}", string);

typedef struct CnxStringIterator CnxStringIterator
#include <include/Cnx/String.h>

Cnx string iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its non-const iterator type (CnxRandomAccessIterator(char_ptr))

typedef struct CnxStringConstIterator CnxStringConstIterator
#include <include/Cnx/String.h>

Cnx string const iterator storage type CnxStringIterator is the underlying storage type used by CnxString for its const iterator type (CnxRandomAccessIterator(const_char_ptr))

Function documentation

CnxString cnx_string_new(void)
#include <include/Cnx/String.h>

Creates a new, empty CnxString

Returns an empty CnxString

CnxString cnx_string_new_with_allocator(CnxAllocator allocator)
#include <include/Cnx/String.h>

Creates a new, empty CnxString that will use the given allocator.

Parameters
allocator - The allocator to use for memory allocations
Returns an empty CnxString

CnxString cnx_string_new_with_capacity(usize capacity)
#include <include/Cnx/String.h>

Creates a new CnxString with the given initial capacity.

Parameters
capacity - The initial capacity of the string
Returns a CnxString with capacity initial capacity

CnxString cnx_string_new_with_capacity_with_allocator(usize capacity, CnxAllocator allocator)
#include <include/Cnx/String.h>

Creates a new CnxString with the given initial capacity.

Parameters
capacity - The initial capacity of the string
allocator - The allocator to use for memory allocations
Returns a CnxString with capacity initial capacity

CnxString cnx_string_from_cstring(restrict const_cstring string, usize length) cnx_disable_if(!string
#include <include/Cnx/String.h>

Creates a new CnxString from the given cstring

Parameters
string - The cstring to create the CnxString from
length - The length of the cstring
Returns a CnxString

CnxString cnx_string_from_cstring_with_allocator(restrict const_cstring string, usize length, CnxAllocator allocator) cnx_disable_if(!string
#include <include/Cnx/String.h>

Creates a new CnxString from the given cstring

Parameters
string - The cstring to create the CnxString from
length - The length of the cstring
allocator - The allocator to use for memory allocations
Returns a CnxString

CnxString cnx_string_from_wcstring(restrict const_wcstring string, usize length) cnx_disable_if(!string
#include <include/Cnx/String.h>

Creates a new CnxString from the given wcstring

Parameters
string - The wcstring to create the CnxString from
length - The length of the wcstring
Returns a CnxString

CnxString cnx_string_from_wcstring_with_allocator(restrict const_wcstring string, usize length, CnxAllocator allocator) cnx_disable_if(!string
#include <include/Cnx/String.h>

Creates a new CnxString from the given wcstring

Parameters
string - The wcstring to create the CnxString from
length - The length of the wcstring
allocator - The allocator to use for memory allocations
Returns a CnxString

CnxString cnx_string_from_stringview(const CnxStringView*restrict view) cnx_disable_if(!view
#include <include/Cnx/String.h>

Creates a new CnxString from the given CnxStringView

Parameters
view - The string view to create a CnxString from
Returns a CnxString

CnxString cnx_string_from_stringview_with_allocator(const CnxStringView*restrict view, CnxAllocator allocator) cnx_disable_if(!view
#include <include/Cnx/String.h>

Creates a new CnxString that will use the given memory allocator, from the given CnxStringView

Parameters
view - The CnxStringView to create the CnxStringView from
allocator - The allocator to use for memory allocations
Returns a CnxString

const_cstring cnx_string_into_cstring(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the cstring representation of this CnxString

Parameters
self - the string to get the cstring representation of
Returns the cstring representation

const_wcstring cnx_string_into_wcstring(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the wcstring converted representation of this CnxString. The result will be allocated with the same allocator used by this CnxString

Parameters
self - The string to get the wcstring converted representation of
Returns the wcstring converted representation

const_wcstring cnx_string_into_wcstring_with_allocator(const CnxString*restrict self, CnxAllocator allocator)
#include <include/Cnx/String.h>

Returns the wcstring converted representation of this CnxString, allocated with the given allocator;.

Parameters
self - The string to get the wcstring converted representation of
allocator - The allocator to allocate memory for the wcstring converted representation
Returns the wcstring converted representation

CnxStringView cnx_string_into_stringview(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxStringView into this CnxString

Parameters
self - the string to get the CnxStringView of
Returns the CnxStringview into this

CnxString cnx_string_clone(const CnxString*restrict self)
#include <include/Cnx/String.h>

Creates a copy of this CnxString using the same allocator.

Parameters
self - The CnxString to copy
Returns a copy of the CnxString

CnxString cnx_string_clone_with_allocator(const CnxString*restrict self, CnxAllocator allocator)
#include <include/Cnx/String.h>

Creates a copy of this CnxString using the given allocator.

Parameters
self - The CnxString to copy
allocator - The allocator to allocate memory with
Returns a copy of the CnxString

void cnx_string_free(void*restrict self)
#include <include/Cnx/String.h>

Frees the allocated memory of the string, if it is not small string optimized.

Parameters
self - The CnxString to free

char_ptr cnx_string_at_mut(CnxString*restrict self, usize index)
#include <include/Cnx/String.h>

Returns a pointer to the character at the given index.

Parameters
self - The CnxString to retrieve the character from
index - The index to get the character for
Returns The character at the given index

const_char_ptr cnx_string_at_const(const CnxString*restrict self, usize index)
#include <include/Cnx/String.h>

Returns a pointer to the character at the given index.

Parameters
self - The CnxString to retrieve the character from
index - The index to get the character for
Returns The character at the given index

char_ptr cnx_string_front_mut(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the character at the beginning of the string.

Parameters
self - The CnxString to retrieve the first character from
Returns The first character

const_char_ptr cnx_string_front_const(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the character at the beginning of the string.

Parameters
self - The CnxString to retrieve the first character from
Returns The first character

char_ptr cnx_string_back_mut(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the character at the end of the string.

Parameters
self - The CnxString to retrieve the last character from
Returns The last character

const_char_ptr cnx_string_back_const(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the character at the end of the string.

Parameters
self - The CnxString to retrieve the last character from
Returns The last character

bool cnx_string_is_empty(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns whether the string is empty or not.

Parameters
self - The CnxString to check for emptiness
Returns true if empty, false otherwise

bool cnx_string_is_full(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns whether the string contains capacity number of characters.

Parameters
self - The CnxString to check for fullness
Returns true if full, false otherwise

usize cnx_string_size(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the current size of the string.

Parameters
self - The CnxString to get the size of
Returns the size of the string

usize cnx_string_length(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the current length of the string.

Parameters
self - The CnxString to get the length of
Returns the length of the string

usize cnx_string_max_size(void)
#include <include/Cnx/String.h>

Returns the maximum possible size of a CnxString

Returns the maximum possible size

usize cnx_string_capacity(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns the current capacity of the string.

Parameters
self - The CnxString to get the capacity of
Returns The capacity of the string

CnxString cnx_string_first(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the first num_chars characters in the string as a new CnxString

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the first num_chars characters

cstring cnx_string_first_cstring(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the first num_chars characters in the string as a cstring allocated with the allocator associated with self

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the first num_chars characters

CnxStringView cnx_string_first_stringview(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the first num_chars characters in the string as a CnxStringView

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the first num_chars characters

CnxString cnx_string_last(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the last num_chars characters in the string as a new CnxString

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the last num_chars characters

cstring cnx_string_last_cstring(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the last num_chars characters in the string as a cstring allocated with the allocator associated with self

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the last num_chars characters

CnxStringView cnx_string_last_stringview(const CnxString*restrict self, usize num_chars) cnx_disable_if(num_chars
#include <include/Cnx/String.h>

Returns the last num_chars characters in the string as a CnxStringView

Parameters
self - The CnxString to get the characters from
num_chars - The number of characters to get
Returns the last num_chars characters

bool cnx_string_equal(const CnxString*restrict self, const CnxString*restrict to_compare) cnx_disable_if(!to_compare
#include <include/Cnx/String.h>

Determines if the given strings are equal.

Parameters
self - The first string to compare
to_compare The second string to compare
Returns true if the two strings are equal, false otherwise

bool cnx_string_equal_cstring(const CnxString*restrict self, restrict const_cstring to_compare, usize length) cnx_disable_if(!to_compare
#include <include/Cnx/String.h>

Determines if the given strings are equal.

Parameters
self - The first string to compare
to_compare - The second string to compare
length - The length of the second string to compare
Returns true if the two strings are equal, false otherwise

bool cnx_string_equal_stringview(const CnxString*restrict self, const CnxStringView*restrict to_compare) cnx_disable_if(!to_compare
#include <include/Cnx/String.h>

Determines if the given strings are equal.

Parameters
self - The first string to compare
to_compare - The second string to compare
Returns true if the two strings are equal, false otherwise

bool cnx_string_contains(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string contains the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this contains substring, false otherwise

bool cnx_string_contains_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string contains the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
substring_length - The length of the substring to search for
Returns true if this contains substring, false otherwise

bool cnx_string_contains_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string contains the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this contains substring, false otherwise

bool cnx_string_starts_with(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string begins with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this begins with substring, false otherwise

bool cnx_string_starts_with_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string begins with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
substring_length - The length of the substring to search for
Returns true if this begins with substring, false otherwise

bool cnx_string_starts_with_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string begins with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this begins with substring, false otherwise

bool cnx_string_ends_with(const CnxString*restrict self, const CnxString*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string ends with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this ends with substring, false otherwise

bool cnx_string_ends_with_cstring(const CnxString*restrict self, restrict const_cstring substring, usize substring_length) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string ends with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
substring_length - The length of the substring to search for
Returns true if this ends with substring, false otherwise

bool cnx_string_ends_with_stringview(const CnxString*restrict self, const CnxStringView*restrict substring) cnx_disable_if(!substring
#include <include/Cnx/String.h>

Determines if the string ends with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if this ends with substring, false otherwise

CnxOption(usize) cnx_string_find_first(const CnxString *restrict self
#include <include/Cnx/String.h>

Returns the index of the first occurrence of the given substring, or None if the substring does not occur.

Returns The index of the first occurrence of substring, or None

Returns the index of the last occurrence of the given substring, or None if the substring does not occur.

CnxString cnx_string_substring(const CnxString*restrict self, usize index, usize length)
#include <include/Cnx/String.h>

Returns the length length substring beginning at index

Parameters
self - The CnxString to get the substring from
index - The index the substring should begin at
length - The length of the substring to get
Returns the substring beginning at index and ending at length, exclusive (the bounds are [index, length))

CnxString cnx_string_substring_with_allocator(const CnxString*restrict self, usize index, usize length, CnxAllocator allocator)
#include <include/Cnx/String.h>

Returns the length length substring beginning at index, allocated with the given allocator.

Parameters
self - The CnxString to get the substring from
index - The index the substring should begin at
length - The length of the substring to get
allocator - The allocator to use for memory allocation
Returns the substring beginning at index and ending at length, exclusive (the bounds are [index, length))

CnxStringView cnx_string_stringview_of(const CnxString*restrict self, usize index, usize length)
#include <include/Cnx/String.h>

Returns a CnxStringView into self of the range [index, index + length)

Parameters
self - The CnxString to get the view of
index - The index of the beginning of the view
length - The length of the view
Returns a CnxStringView into self

CnxString cnx_string_concatenate(const CnxString*restrict left, const CnxString*restrict right) cnx_disable_if(!right
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the allocator associated with left, if necessary.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
Returns The concatenated string

CnxString cnx_string_concatenate_cstring(const CnxString*restrict left, restrict const_cstring right, usize right_length) cnx_disable_if(!right
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the allocator associated with left, if necessary.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
right_length - The length of the right-side string of the concatenation
Returns The concatenated string

CnxString cnx_string_concatenate_cstrings(restrict const_cstring left, usize left_length, restrict const_cstring right, usize right_length) cnx_disable_if(!left
#include <include/Cnx/String.h>

Concatenates the two strings into a new CnxString, using the default allocator (malloc)

Parameters
left - The left (beginning) string to form the concatenation
left_length - The length of the left string
right - The right (ending) string to form the concatenation
right_length - The length of the right string
Returns The concatenated string as a CnxString

CnxString cnx_string_concatenate_stringview(const CnxString*restrict left, const CnxStringView*restrict right) cnx_disable_if(!left
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the allocator associated with left, if necessary.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
Returns The concatenated string

CnxString cnx_string_concatenate_stringviews(const CnxStringView*restrict left, const CnxStringView*restrict right) cnx_disable_if(!left
#include <include/Cnx/String.h>

Concatenates the two stringviews into a new CnxString, using the default allocator (malloc)

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
Returns The concatenated string

void invalid_types_passed_to_cnx_string_concatenate(void)
#include <include/Cnx/String.h>

This function is an __INTENTIONALLY_ undefined function so that improper use of cnx_string_concatenate (passing values of invalid type(s)) will result in a build failure.

CnxString cnx_string_concatenate_with_allocator(const CnxString*restrict left, const CnxString*restrict right, CnxAllocator allocator) cnx_disable_if(!right
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the given allocator.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
allocator - The allocator to use for memory allocations
Returns The concatenated string

CnxString cnx_string_concatenate_cstring_with_allocator(const CnxString*restrict left, restrict const_cstring right, usize right_length, CnxAllocator allocator) cnx_disable_if(!right
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the given allocator.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
right_length - The length of the right-side string of the concatenation
allocator - The allocator to use for memory allocations
Returns The concatenated string

CnxString cnx_string_concatenate_stringview_with_allocator(const CnxString*restrict left, const CnxStringView*restrict right, CnxAllocator allocator) cnx_disable_if(!right
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the given allocator.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
allocator - The allocator to use for memory allocations
Returns The concatenated string

CnxString cnx_string_concatenate_cstrings_with_allocator(restrict const_cstring left, usize left_length, restrict const_cstring right, usize right_length, CnxAllocator allocator) cnx_disable_if(!left
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the given allocator.

Parameters
left - The left-side string of the concatenation
left_length - The length of the left-side string of the concatenation
right - The right-side string of the concatenation
right_length - The length of the right-side string of the concatenation
allocator - The allocator to use for memory allocations
Returns The concatenated string

CnxString cnx_string_concatenate_stringviews_with_allocator(const CnxStringView*restrict left, const CnxStringView*restrict right, CnxAllocator allocator) cnx_disable_if(!left
#include <include/Cnx/String.h>

Concatenates the two strings into a new one, using the given allocator.

Parameters
left - The left-side string of the concatenation
right - The right-side string of the concatenation
allocator - The allocator to use for memory allocations
Returns The concatenated string

void cnx_string_fill(CnxString*restrict self, char character)
#include <include/Cnx/String.h>

Fills the string with the given character.

Parameters
self - The CnxString to fill
character - The character to fill the string with

void cnx_string_clear(CnxString*restrict self)
#include <include/Cnx/String.h>

Clears the string, filling it with null.

Parameters
self - The CnxString to clear

void cnx_string_shrink_to_fit(CnxString*restrict self)
#include <include/Cnx/String.h>

Shrinks the string so its capacity equals its size.

Parameters
self - The CnxString to shrink

void cnx_string_insert(CnxString*restrict self, const CnxString*restrict to_insert, usize index) cnx_disable_if(!to_insert
#include <include/Cnx/String.h>

Inserts the given string to_insert into self at the given index

Parameters
self - The CnxString to insert into
to_insert - The string to insert
index - The index at which to insert the string

void cnx_string_insert_cstring(CnxString*restrict self, restrict const_cstring to_insert, usize to_insert_length, usize index) cnx_disable_if(!to_insert
#include <include/Cnx/String.h>

Inserts the given string to_insert into self at the given index

Parameters
self - The CnxString to insert into
to_insert - The string to insert
to_insert_length - The length of the string to insert
index - The index at which to insert the string

void cnx_string_insert_stringview(CnxString*restrict self, const CnxStringView*restrict to_insert, usize index) cnx_disable_if(!to_insert
#include <include/Cnx/String.h>

Inserts the given string to_insert into self at the given index

Parameters
self - The CnxString to insert into
to_insert - The string to insert
index - The index at which to insert the string

void cnx_string_erase(CnxString*restrict self, usize index)
#include <include/Cnx/String.h>

Erases the character at the given index from the string.

Parameters
self - The CnxString to erase from
index - The index of the character to erase

void cnx_string_erase_n(CnxString*restrict self, usize index, usize num_characters)
#include <include/Cnx/String.h>

Erases num_character characters from the string, starting at the given index.

Parameters
self - The CnxString to erase from
index - The index to start erasing at
num_characters - The number of characters to erase

void cnx_string_resize(CnxString*restrict self, usize new_size)
#include <include/Cnx/String.h>

Resizes the string to the new size, null padding or truncating if necessary.

Parameters
self - The CnxString to resize
new_size - The new size for the string

void cnx_string_reserve(CnxString*restrict self, usize new_capacity)
#include <include/Cnx/String.h>

Reserves additional capacity in the string This will allocate enough memory to store at least new_capacity number of characters,.

Parameters
self - The CnxString to reserve additional space for
new_capacity - The new capacity for the string

void cnx_string_push_back(CnxString*restrict self, char character)
#include <include/Cnx/String.h>

Appends the given character to the end of the string.

Parameters
self - The CnxString to append to
character - The character to append

void cnx_string_push_front(CnxString*restrict self, char character)
#include <include/Cnx/String.h>

Prepends the given character to the beginning of the string.

Parameters
self - The CnxString to prepends to
character - The character to prepends

CnxOption(char)
#include <include/Cnx/String.h>

Removes the last character in the string and returns it.

Returns the last character

Removes the first character in the string and returns it.

void cnx_string_append(CnxString*restrict self, const CnxString*restrict to_append) cnx_disable_if(!to_append
#include <include/Cnx/String.h>

Appends the given string to the end of the string.

Parameters
self - The CnxString to append to
to_append - The string to append

void cnx_string_append_cstring(CnxString*restrict self, restrict const_cstring to_append, usize to_append_length) cnx_disable_if(!to_append
#include <include/Cnx/String.h>

Appends the given string to the end of the string.

Parameters
self - The CnxString to append to
to_append - The string to append
to_append_length - The length of the string to append

void cnx_string_append_stringview(CnxString*restrict self, const CnxStringView*restrict to_append) cnx_disable_if(!to_append
#include <include/Cnx/String.h>

Appends the given string to the end of the string.

Parameters
self - The CnxString to append to
to_append - The string to append

void cnx_string_prepend(CnxString*restrict self, const CnxString*restrict to_prepend) cnx_disable_if(!to_prepend
#include <include/Cnx/String.h>

Prepends the given string to the beginning of the string.

Parameters
self - The CnxString to prepend to
to_prepend - The string to prepend

void cnx_string_prepend_cstring(CnxString*restrict self, restrict const_cstring to_prepend, usize to_prepend_length) cnx_disable_if(!to_prepend
#include <include/Cnx/String.h>

Prepends the given string to the beginning of the string.

Parameters
self - The CnxString to prepend to
to_prepend - The string to prepend
to_prepend_length - The length of the string to prepend

void cnx_string_prepend_stringview(CnxString*restrict self, const CnxStringView*restrict to_prepend) cnx_disable_if(!to_prepend
#include <include/Cnx/String.h>

Prepends the given string to the beginning of the string.

Parameters
self - The CnxString to prepend to
to_prepend - The string to prepend

void cnx_string_replace(CnxString*restrict self, const CnxString*restrict to_replace_with, usize index) cnx_disable_if(!to_replace_with
#include <include/Cnx/String.h>

Replaces the substring beginning at index with the given one.

Parameters
self - The CnxString to replace a portion of
to_replace_with - The substring to replace the portion with
index - The index to start replacement

void cnx_string_replace_cstring(CnxString*restrict self, restrict const_cstring to_replace_with, usize to_replace_with_length, usize index) cnx_disable_if(!to_replace_with
#include <include/Cnx/String.h>

Replaces the substring beginning at index with the given one.

Parameters
self - The CnxString to replace a portion of
to_replace_with - The substring to replace the portion with
to_replace_with_length - The length of the substring to replace the portion with
index - The index to start replacement

void cnx_string_replace_stringview(CnxString*restrict self, const CnxStringView*restrict to_replace_with, usize index) cnx_disable_if(!to_replace_with
#include <include/Cnx/String.h>

Replaces the substring beginning at index with the given one.

Parameters
self - The CnxString to replace a portion of
to_replace_with - The substring to replace the portion with
index - The index to start replacement

CnxRandomAccessIteratorchar_ref cnx_string_begin(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the iteration (pointing at the beginning of the string)

CnxRandomAccessIteratorchar_ref cnx_string_end(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the iteration (pointing at the end of the string)

CnxRandomAccessIteratorchar_ref cnx_string_rbegin(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the reversed iteration (pointing at the end of the string)

CnxRandomAccessIteratorchar_ref cnx_string_rend(CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the reversed iteration (pointing at the beginning of the string)

CnxRandomAccessIteratorconst_char_ref cnx_string_cbegin(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the iteration (pointing at the beginning of the string)

CnxRandomAccessIteratorconst_char_ref cnx_string_cend(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the iteration (pointing at the end of the string)

CnxRandomAccessIteratorconst_char_ref cnx_string_crbegin(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the reversed iteration (pointing at the end of the string)

CnxRandomAccessIteratorconst_char_ref cnx_string_crend(const CnxString*restrict self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the reversed iteration (pointing at the beginning of the string)

CnxVector(CnxString) cnx_string_split_on(const CnxString *restrict self
#include <include/Cnx/StringExt.h>

Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.

Returns a CnxVector(String) containing the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector and its contained strings will use the allocator associated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_split_on_with_allocator).

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector and its contained strings will use the given allocator for necessary memory allocations.

CnxVector(CnxStringView) cnx_string_view_split_on(const CnxString *restrict self
#include <include/Cnx/StringExt.h>

Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector

Returns a CnxVector(CnxStringView) containing views of the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector will use the allocator associated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_view_split_on_with_allocator).

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector will use the given allocator for necessary memory allocations.

usize cnx_string_occurrences_of_char(const CnxString*restrict self, char to_find)
#include <include/Cnx/StringExt.h>

Determines the total number of times the character to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The character to find in self
Returns The number of times to_find occurs in self

usize cnx_string_occurrences_of(const CnxString*restrict self, const CnxString*restrict to_find)
#include <include/Cnx/StringExt.h>

Determines the total number of times the string to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The string to find in self
Returns The number of times to_find occurs in self

usize cnx_string_occurrences_of_stringview(const CnxString*restrict self, const CnxStringView*restrict to_find)
#include <include/Cnx/StringExt.h>

Determines the total number of times the stringview to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The stringview to find in self
Returns The number of times to_find occurs in self

usize cnx_string_occurrences_of_cstring(const CnxString*restrict self, restrict const_cstring to_find, usize to_find_length)
#include <include/Cnx/StringExt.h>

Determines the total number of times the cstring to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The cstring to find in self
to_find_length - The length of the cstring to find in self
Returns The number of times to_find occurs in self

CnxVector(usize) cnx_string_find_occurrences_of_char(const CnxString *restrict self
#include <include/Cnx/StringExt.h>

Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector

Returns a CnxVector(usize) containing the indices at which to_find occurs in self

Finds the indices at which the cstring to_find occurs in self, and returns them in a CnxVector

Finds the indices at which the stringview to_find occurs in self, and returns them in a CnxVector

Finds the indices at which the string to_find occurs in self, and returns them in a CnxVector

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_char_with_allocator)

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_with_allocator)

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_with_allocator)

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_with_allocator)

The returned vector will use the given allocator for necessary memory allocations

The returned vector will use the given allocator for necessary memory allocations

The returned vector will use the given allocator for necessary memory allocations

The returned vector will use the given allocator for necessary memory allocations

Define documentation

#define cnx_string_from(string)
#include <include/Cnx/String.h>

Creates a new CnxString from the given string-like type.

Parameters
string - The string-like thing to create the CnxString from. Either a CnxStringView or a cstring (const or non-const)
Returns a CnxString

#define cnx_string_from_with_allocator(string, allocator)
#include <include/Cnx/String.h>

Creates a new CnxString from the given string-like type, using the given CnxAllocator for memory allocations.

Parameters
string - The string-like thing to create the CnxString from. Either a CnxStringView or a cstring (const or non-const)
allocator - The allocator to use for memory allocations, if necessary
Returns a CnxString

#define cnx_string_concatenate(left, right)
#include <include/Cnx/String.h>

Concatenates the two strings and returns the result as a new CnxString

Parameters
left - The string to begin the new string with
right - The string to end the new string with
Returns the concatenation of the two strings

#define cnx_string_concatenate_with_allocator(left, right, allocator)
#include <include/Cnx/String.h>

Concatenates the two strings and returns the result as a new CnxString

Parameters
left - The string to begin the new string with
right - The string to end the new string with
allocator - The CnxAllocator to allocate memory with
Returns the concatenation of the two strings

#define cnx_string_into_cstring(self)
#include <include/Cnx/String.h>

Returns the cstring representation of the given CnxString

Parameters
self - The CnxString to get the cstring view of
Returns The cstring representation of self

#define cnx_string_into_wcstring(self)
#include <include/Cnx/String.h>

Returns the wcstring representation of the given CnxString

Parameters
self - The CnxString to get the wcstring representation of
Returns The wcstring representation of self

#define cnx_string_into_wcstring_with_allocator(self, allocator)
#include <include/Cnx/String.h>

Returns the wcstring representation of the given CnxString

Parameters
self - The CnxString to get the wcstring representation of
allocator - The CnxAllocator to allocator memory for the wcstring with
Returns The wcstring representation of self

#define cnx_string_into_stringview(self)
#include <include/Cnx/String.h>

Returns a CnxStringView into self.

Parameters
self - The CnxString to get the CnxStringView of
Returns a CnxStringView into self

#define cnx_string_clone(self)
#include <include/Cnx/String.h>

Creates a copy of the given CnxString, self, using the CnxAllocator associated with self

Parameters
self - The CnxString to copy
Returns a copy of self

#define cnx_string_clone_with_allocator(self, allocator)
#include <include/Cnx/String.h>

Creates a copy of the given CnxString, self, using the given CnxAllocator

Parameters
self - The CnxString to copy
allocator - The CnxAllocator to associate with the new string
Returns a copy of self

#define cnx_string_free(self)
#include <include/Cnx/String.h>

Cleans up the given CnxString, freeing any allocated memory.

Parameters
self - The CnxString to cleanup

#define cnx_string_at(self, index)
#include <include/Cnx/String.h>

Returns a reference to the character at the given index.

Parameters
self - The CnxString to retrieve the character from
index - The index to get the character for
Returns The character at the given index

#define cnx_string_front(self)
#include <include/Cnx/String.h>

Returns a reference to the character at the beginning of the string.

Parameters
self - The CnxString to retrieve the first character from
Returns The first character

#define cnx_string_back(self)
#include <include/Cnx/String.h>

Returns a reference to the character at the end of the string.

Parameters
self - The CnxString to retrieve the last character from
Returns The last character

#define cnx_string_data(self)
#include <include/Cnx/String.h>

Returns the raw character array of the string.

Parameters
self - The CnxString to retrieve the raw array from
Returns The raw character array

#define cnx_string_is_empty(self)
#include <include/Cnx/String.h>

Returns whether the given CnxString is empty or not.

Parameters
self - The CnxString to check if empty
Returns true if self is empty, false otherwise

#define cnx_string_is_full(self)
#include <include/Cnx/String.h>

Returns whether the given CnxString is full.

Parameters
self - The CnxString to check if full
Returns true if self is full, false otherwise

#define cnx_string_size(self)
#include <include/Cnx/String.h>

Returns the current size of the given CnxString

Parameters
self - The CnxString to get the size of
Returns the size of self

#define cnx_string_length(self)
#include <include/Cnx/String.h>

Returns the current length of the given CnxString

Parameters
self - The CnxString to get the length of
Returns the length of self

#define cnx_string_capacity(self)
#include <include/Cnx/String.h>

Returns the current capacity of the given CnxString

Parameters
self - The CnxString to get the capacity of
Returns the capacity of self

#define cnx_string_first(self, num_chars)
#include <include/Cnx/String.h>

Returns the first num_chars characters of self as a new CnxString, using the CnxAllocator associated with self

Parameters
self - The CnxString to get the first num_chars characters from
num_chars - The number of chars to get from the beginning of self
Returns the first num_chars characters of self as a CnxString

#define cnx_string_first_cstring(self, num_chars)
#include <include/Cnx/String.h>

Returns the first num_chars characters of self as a new cstring, using the CnxAllocator associated with self

Parameters
self - The CnxString to get the first num_chars characters from
num_chars - The number of chars to get from the beginning of self
Returns the first num_chars characters of self as a cstring

#define cnx_string_first_stringview(self, num_chars)
#include <include/Cnx/String.h>

Returns the first num_chars characters of self as a CnxStringView

Parameters
self - The CnxString to get the first num_chars characters from
num_chars - The number of chars to get from the beginning of self
Returns the first num_chars characters of self as a CnxStringView

#define cnx_string_last(self, num_chars)
#include <include/Cnx/String.h>

Returns the last num_chars characters of self as a new CnxString, using the CnxAllocator associated with self

Parameters
self - The CnxString to get the last num_chars characters from
num_chars - The number of chars to get from the end of self
Returns the last num_chars characters of self as a CnxString

#define cnx_string_last_cstring(self, num_chars)
#include <include/Cnx/String.h>

Returns the last num_chars characters of self as a new cstring, using the CnxAllocator associated with self

Parameters
self - The CnxString to get the last num_chars characters from
num_chars - The number of chars to get from the end of self
Returns the last num_chars characters of self as a cstring

#define cnx_string_last_stringview(self, num_chars)
#include <include/Cnx/String.h>

Returns the last num_chars characters of self as a CnxStringView

Parameters
self - The CnxString to get the last num_chars characters from
num_chars - The number of chars to get from the end of self
Returns the last num_chars characters of self as a CnxStringView

#define cnx_string_equal(self, to_compare)
#include <include/Cnx/String.h>

Determines if this string and the given one are equal.

Parameters
self - The CnxString to be compared with
to_compare - The string to compare to
Returns true if the two strings are equal, false otherwise

#define cnx_string_contains(self, substring)
#include <include/Cnx/String.h>

Determines whether the string contains the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if the string contains substring, otherwise false

#define cnx_string_starts_with(self, substring)
#include <include/Cnx/String.h>

Determines whether the string starts with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if the string starts with substring, otherwise false

#define cnx_string_ends_with(self, substring)
#include <include/Cnx/String.h>

Determines whether the string ends with the given substring.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns true if the string ends with substring, otherwise false

#define cnx_string_find_first(self, substring)
#include <include/Cnx/String.h>

Finds the first occurrence of the given substring in self, if any.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns Some of the index into self at the beginning of the substring's occurrence in self, if self contains the substring, otherwise None

#define cnx_string_find_last(self, substring)
#include <include/Cnx/String.h>

Finds the last occurrence of the given substring in self, if any.

Parameters
self - The CnxString to search for substring in
substring - The substring to search for
Returns Some of the index into self at the beginning of the substring's occurrence in self, if self contains the substring, otherwise None

#define cnx_string_substring(self, index, length)
#include <include/Cnx/String.h>

Returns the substring of self starting at index with length length as a CnxString, using the CnxAllocator associated with self

Parameters
self - The CnxString to get a substring from
index - The index to start the substring at
length - The length of the substring
Returns a substring of self

#define cnx_string_substring_with_allocator(self, index, length, allocator)
#include <include/Cnx/String.h>

Returns the substring of self starting at index with length length as a CnxString, associating the given CnxAllocator with the substring.

Parameters
self - The CnxString to get a substring from
index - The index to start the substring at
length - The length of the substring
allocator - The CnxAllocator to associate with the substring
Returns a substring of self

#define cnx_string_stringview_of(self, index, length)
#include <include/Cnx/String.h>

Returns a CnxStringView into self beginning at index with length length

Parameters
self - The CnxString to get a CnxStringView into
index - The index to begin the view at
length - The length of the view
Returns a CnxStringView into self

#define cnx_string_fill(self, character)
#include <include/Cnx/String.h>

Fills the given CnxString with the given character.

Parameters
self - The CnxString to fill
character - The character to fill self with

#define cnx_string_clear(self)
#include <include/Cnx/String.h>

Clears the given CnxString

Parameters
self - The CnxString to clear

#define cnx_string_shrink_to_fit(self)
#include <include/Cnx/String.h>

Shrinks the capacity of the given CnxString to its size.

Parameters
self - The CnxString to shrink

#define cnx_string_insert(self, to_insert, index)
#include <include/Cnx/String.h>

Inserts to_insert into self at the given index.

Parameters
self - The CnxString to insert into
to_insert - The string to insert
index - The index into self at which to insert the to_insert

#define cnx_string_erase(self, index)
#include <include/Cnx/String.h>

Erases the character at the given index from self

Parameters
self - The CnxString to remove a character from
index - The index of the character to remove

#define cnx_string_erase_n(self, index, num_characters)
#include <include/Cnx/String.h>

Erases num_characters characters from self, beginning at index

Parameters
self - The CnxString to remove characters from
index - The index where removal should begin
num_characters - The number of characters to remove

#define cnx_string_resize(self, new_size)
#include <include/Cnx/String.h>

Resizes the given CnxString to the given new_size, filling the characters in the expanded size with null.

Parameters
self - The CnxString to resize
new_size - The new size of the string

#define cnx_string_reserve(self, new_capacity)
#include <include/Cnx/String.h>

Allocates memory such that at least new_capacity number of characters can be stored in the given CnxString

Parameters
self - The CnxString to reserve memory in
new_capacity - The number of characters to be able to store

#define cnx_string_push_back(self, character)
#include <include/Cnx/String.h>

Pushes the given character onto the end of the given CnxString

Parameters
self - The CnxString to append a character to
character - The character to append to self

#define cnx_string_push_front(self, character)
#include <include/Cnx/String.h>

Pushes the given character onto the beginning of the given CnxString

Parameters
self - The CnxString to prepend a character to
character - The character to prepend to self

#define cnx_string_pop_back(self)
#include <include/Cnx/String.h>

Removes the last character in self if cnx_string_size(self) > 0, and returns it.

Parameters
self - The CnxString to pop the last character from
Returns Some(char) if cnx_string_size(self) > 0, else None(char)

#define cnx_string_pop_front(self)
#include <include/Cnx/String.h>

Removes the first character in self if cnx_string_size(self) > 0, and returns it.

Parameters
self - The CnxString to pop the first character from
Returns Some(char) if cnx_string_size(self) > 0, else None(char)

#define cnx_string_append(self, to_append)
#include <include/Cnx/String.h>

Appends to_append to the end of self

Parameters
self - The CnxString to append to
to_append - The string to append

#define cnx_string_prepend(self, to_prepend)
#include <include/Cnx/String.h>

Prepends to_prepend to the beginning of self

Parameters
self - The CnxString to prepend to
to_prepend - The string to prepend

#define cnx_string_replace(self, to_replace_with, index)
#include <include/Cnx/String.h>

Replaces the contents of self with to_replace_with, beginning at the given index.

Parameters
self - The CnxString to replace a portion of
to_replace_with - The string to replace self's contents with
index - The index to start replacement at

#define cnx_string_begin(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the iteration (pointing at the beginning of the string)

#define cnx_string_end(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the iteration (pointing at the end of the string)

#define cnx_string_rbegin(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the reversed iteration (pointing at the end of the string)

#define cnx_string_rend(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the reversed iteration (pointing at the beginning of the string)

#define cnx_string_cbegin(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the iteration (pointing at the beginning of the string)

#define cnx_string_cend(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the iteration (pointing at the end of the string)

#define cnx_string_crbegin(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the beginning of the reversed iteration (pointing at the end of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the beginning of the reversed iteration (pointing at the end of the string)

#define cnx_string_crend(self)
#include <include/Cnx/String.h>

Returns a CnxRandomAccessIterator(const_char_ref) into the given CnxString, at the end of the reversed iteration (pointing at the beginning of the string)

Parameters
self - The CnxString to get an iterator into
Returns an iterator at the end of the reversed iteration (pointing at the beginning of the string)

#define cnx_string_split_on(self, delimiter)
#include <include/Cnx/StringExt.h>

Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.

Parameters
self - The string to split
delimiter - The character to split the string on
Returns a CnxVector(String) containing the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector and its contained strings will use the allocator associated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_split_on_with_allocator).

#define cnx_string_split_on_with_allocator(self, delimiter, allocator)
#include <include/Cnx/StringExt.h>

Splits the given string at each instance of the given delimiter character, returning a CnxVector of the resulting substrings.

Parameters
self - The string to split
delimiter - The character to split the string on
allocator - The allocator for the returned vector and its contained strings to use for memory allocation
Returns a CnxVector(String) containing the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector and its contained strings will use the given allocator for necessary memory allocations.

#define cnx_string_view_split_on(self, delimiter)
#include <include/Cnx/StringExt.h>

Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector

Parameters
self - The string to split
delimiter - The character to split the string on
Returns a CnxVector(CnxStringView) containing views of the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector will use the allocator associated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_view_split_on_with_allocator).

#define cnx_string_view_split_on_with_allocator(self, delimiter, allocator)
#include <include/Cnx/StringExt.h>

Splits the given string into a set of stringviews at each instance of the given delimiter character, returning them in a CnxVector

Parameters
self - The string to split
delimiter - The character to split the string on
allocator - The allocator for the returned vector to use for memory allocations
Returns a CnxVector(CnxStringView) containing views of the substrings delimited by delimiter in self

Splits the string by taking the substring within each pair of delimiters (or the beginning and/or end of the string). Only substrings of at least one character are considered; zero-length substrings are discarded. The returned vector will use the given allocator for necessary memory allocations.

#define cnx_string_occurrences_of_char(self, to_find)
#include <include/Cnx/StringExt.h>

Determines the total number of times the character to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The character to find in self
Returns The number of times to_find occurs in self

#define cnx_string_occurrences_of(self, to_find)
#include <include/Cnx/StringExt.h>

Determines the total number of times the string or string-like to_find occurs in self

Parameters
self - The string to find the occurrences of to_find in
to_find - The string to find in self
Returns The number of times to_find occurs in self

to_find my be CnxString, CnxStringView or cstring

#define cnx_string_find_occurrences_of_char(self, to_find)
#include <include/Cnx/StringExt.h>

Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector

Parameters
self - The string to find where to_find occurs in
to_find - The character to find the occurrences of in self
Returns a CnxVector(usize) containing the indices at which to_find occurs in self

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_char_with_allocator)

#define cnx_string_find_occurrences_of_char_with_allocator(self, to_find, allocator)
#include <include/Cnx/StringExt.h>

Finds the indices at which the character to_find occurs in self, and returns them in a CnxVector

Parameters
self - The string to find where to_find occurs in
to_find - The character to find the occurrences of in self
allocator - The allocator the returned vector will use for necessary memory allocations
Returns a CnxVector(usize) containing the indices at which to_find occurs in self

The returned vector will use the given allocator for necessary memory allocations

#define cnx_string_find_occurrences_of(self, to_find)
#include <include/Cnx/StringExt.h>

Finds the indices at which the string or string-like to_find occurs in self, and returns them in a CnxVector

Parameters
self - The string to find where to_find occurs in
to_find - The string to find the occurrences of in self
Returns a CnxVector(usize) containing the indices at which to_find occurs in self

The returned vector will use the allocator accociated with self for necessary memory allocations (to specify the allocator to use, use cnx_string_find_occurrences_of_with_allocator)

to_find may be a CnxString, CnxStringView, or cstring

#define cnx_string_find_occurrences_of_with_allocator(self, to_find, allocator)
#include <include/Cnx/StringExt.h>

Finds the indices at which the string or string-like to_find occurs in self, and returns them in a CnxVector

Parameters
self - The string to find where to_find occurs in
to_find - The string to find the occurrences of in self
allocator - The allocator for the returned vector to use for memory allocations
Returns a CnxVector(usize) containing the indices at which to_find occurs in self

The returned vector will use the given allocator for necessary memory allocations

to_find may be a CnxString, CnxStringView, or cstring