Essentials

cstr

A byte string with familiar string operations and concise text, conversion, and hashing helpers.

C++23 mc/cstr.h

#include <mc/cstr.h>

Indices and lengths count bytes. Use complete UTF-8 boundaries when slicing text.

The standard-style interface follows std::string; .std() exposes the underlying string. Exceptions escaping wrapper operations are translated to CError.

Jump to a declaration · 151

cConcise cFmix64_ cFromBinary cFromHex cFromOctal cGetLine cHash cHash128 cHash64 CHashDefaultSeed cHashMix_ cIsSymbol cJoin cLower cLowerAll cRethrowError cRotl64_ cstr cStr cstr::after cstr::allocator_type cstr::append cstr::append_range cstr::assign cstr::assign_range cstr::at cstr::back cstr::before cstr::begin cstr::c_str cstr::capacity cstr::cbegin cstr::cend cstr::clear cstr::compare cstr::const_iterator cstr::const_pointer cstr::const_reference cstr::const_reverse_iterator cstr::contains cstr::copy cstr::crbegin cstr::crend cstr::cstr cstr::data cstr::difference_type cstr::empty cstr::end cstr::ends_with cstr::endStr cstr::endsWith cstr::erase cstr::escape cstr::find cstr::find_first_not_of cstr::find_first_of cstr::find_last_not_of cstr::find_last_of cstr::findCount cstr::findReplace cstr::front cstr::get cstr::get_allocator cstr::getLine cstr::getLineIndex cstr::insert cstr::insert_range cstr::intoAllLower cstr::intoAllUpper cstr::intoLower cstr::intoUpper cstr::isAlpha cstr::isAlphaNum cstr::isDigit cstr::isLower cstr::isUpper cstr::iterator cstr::length cstr::max_size cstr::multiReplace cstr::npos cstr::operator const std::string& cstr::operator std::string& cstr::operator std::string_view cstr::operator!= cstr::operator+ cstr::operator+= cstr::operator< cstr::operator<= cstr::operator<=> cstr::operator= cstr::operator== cstr::operator> cstr::operator>= cstr::operator[] cstr::pointer cstr::pop_back cstr::popBack cstr::popFront cstr::push_back cstr::pushBack cstr::pushFront cstr::rbegin cstr::reference cstr::rend cstr::replace cstr::replace_with_range cstr::reserve cstr::resize cstr::resize_and_overwrite cstr::reverse_iterator cstr::rfind cstr::shrink_to_fit cstr::size cstr::size_type cstr::span cstr::split cstr::splitOnSpace cstr::starts_with cstr::startsWith cstr::std cstr::String cstr::strip cstr::substr cstr::swap cstr::toAllLower cstr::toAllUpper cstr::toLower cstr::toUpper cstr::traits_type cstr::unescape cstr::unescapeUTF8 cstr::value_type cstr::~cstr CStrViewLike cUpper cUpperAll erase erase_if getline operator+ operator<< operator>> swap MC_ALPHA MC_LOWER MC_NUM MC_UPPER MC_WHITE std::hash std::hash::operator()

Free functions & types

Types, constants & data

template<class T> concept CStrViewLike = std::is_convertible_v<const T&, std::string_view> && !std::is_convertible_v<const T&, const char*>;

inline constexpr uint64_t CHashDefaultSeed = 18446744073707359709ULL;

Functions

cRethrowError

inline void cRethrowError();

operator<<

inline std::ostream& operator<<(std::ostream& ostr, const cstr& v);

operator>>

inline std::istream& operator>>(std::istream& istr, cstr& str);

operator+

inline constexpr cstr operator+(const char* s, const cstr& str);

inline constexpr cstr operator+(char first, const cstr& second);

inline constexpr cstr operator+(const char* first, cstr&& second);

inline constexpr cstr operator+(char first, cstr&& second);

swap

inline constexpr void swap(cstr& first, cstr& second) noexcept;

erase

template<class U> constexpr cstr::size_type erase(cstr& value, const U& character);

Removes all elements equal to the supplied value and returns the number removed.

erase_if

template<class Predicate> constexpr cstr::size_type erase_if(cstr& value, Predicate predicate);

Removes every element for which the predicate returns true and returns the number removed.

getline

inline std::istream& getline(std::istream& stream, cstr& value);

inline std::istream& getline(std::istream& stream, cstr& value, char delimiter);

inline std::istream& getline(std::istream&& stream, cstr& value);

inline std::istream& getline(std::istream&& stream, cstr& value, char delimiter);

Reads a line into the string, replacing its previous contents and consuming the delimiter. The default delimiter is newline; inspect the returned stream to distinguish EOF and read failures.

cStr

template<class T> inline cstr cStr(T&& x);

Converts a value to display text using its supported string or stream representation. It does not guarantee a round-trippable CSON/JSON encoding.

cIsSymbol

template<CString T> inline bool cIsSymbol(const T& str);

Tests whether the complete string is a valid Catalyst symbol spelling. It does not resolve the symbol or look up a variable.

cHashMix_

inline constexpr uint64_t cHashMix_(uint64_t h) noexcept;

cRotl64_

static constexpr uint64_t cRotl64_(uint64_t x, int8_t r) noexcept;

cFmix64_

static constexpr uint64_t cFmix64_(uint64_t k) noexcept;

cHash128

template<size_t N> inline constexpr chash128 cHash128(const char(&buf)[N], uint64_t seed = CHashDefaultSeed) noexcept;

inline chash128 cHash128(const void* buf, size_t len, uint64_t seed) noexcept;

Computes a 128-bit hash using the supplied seed. Counted byte forms include embedded NUL bytes; string-literal forms omit the terminating NUL.

cHash64

template<size_t N> inline constexpr chash64 cHash64(const char(&buf)[N], uint64_t seed = CHashDefaultSeed) noexcept;

inline chash64 cHash64(const void* buf, size_t len, uint64_t seed) noexcept;

template<CArithmetic T> inline chash64 cHash64(T x, uint64_t seed = CHashDefaultSeed) noexcept;

inline chash64 cHash64(void* p, uint64_t seed = CHashDefaultSeed) noexcept;

inline chash64 cHash64(const cstr& str, uint64_t seed = CHashDefaultSeed) noexcept;

Computes a 64-bit hash using the supplied seed. Pointer hashing uses the address; it does not hash the pointee.

cHash

template<size_t N> inline constexpr chash cHash(const char(&buf)[N], uint64_t seed = CHashDefaultSeed) noexcept;

inline chash cHash(const void* buf, size_t len, uint64_t seed) noexcept;

template<CArithmetic T> inline chash cHash(T x, uint64_t seed = CHashDefaultSeed) noexcept;

inline chash cHash(void* p, uint64_t seed = CHashDefaultSeed) noexcept;

inline chash cHash(const cstr& str, uint64_t seed = CHashDefaultSeed) noexcept;

Computes a Catalyst hash. Choose the explicit byte-count overload for binary data.

cLowerAll

inline void cLowerAll(cstr& s) noexcept;

Converts each byte to lowercase using the current C locale. This does not perform Unicode case mapping.

cLower

inline void cLower(cstr& s) noexcept;

Converts the first byte of a nonempty string to lowercase using the current C locale. Later bytes are unchanged.

cUpperAll

inline void cUpperAll(cstr& s) noexcept;

Converts each byte to uppercase using the current C locale. This does not perform Unicode case mapping.

cUpper

inline void cUpper(cstr& s) noexcept;

Converts the first byte of a nonempty string to uppercase using the current C locale. Later bytes are unchanged.

cJoin

template<CItems T, CString D = cstr> inline cstr cJoin(const T& v, const D& delimiter = "");

Joins the input elements with the requested separator.

cGetLine

inline bool cGetLine(std::istream& in, cstr& str);

Reads a line into the destination and reports whether one was read.

cConcise

template<class T> cstr cConcise(T x, int p = 3);

Formats a number in fixed notation with p digits after the decimal point, defaulting to three. Trailing zeros are retained.

cFromBinary

template<class T> T cFromBinary(const cstr& s);

Accumulates a binary digit string into the requested integer type. Supply digits without a prefix or sign; this helper does not validate digits or check overflow.

cFromHex

template<class T> T cFromHex(const cstr& s);

Accumulates hexadecimal digits into the requested integer type, accepting either letter case. Supply an unprefixed, unsigned digit sequence; invalid digits and overflow are not reported.

cFromOctal

template<class T> T cFromOctal(const cstr& s);

Accumulates an octal digit string into the requested integer type. Supply digits without a prefix or sign; this helper does not validate digits or check overflow.

cstr

class cstr

Types, constants & data

using String = std::string;

using traits_type = typename String::traits_type;

using value_type = typename String::value_type;

using allocator_type = typename String::allocator_type;

using size_type = typename String::size_type;

using difference_type = typename String::difference_type;

using reference = typename String::reference;

using const_reference = typename String::const_reference;

using pointer = typename String::pointer;

using const_pointer = typename String::const_pointer;

using iterator = typename String::iterator;

using const_iterator = typename String::const_iterator;

using reverse_iterator = typename String::reverse_iterator;

using const_reverse_iterator = typename String::const_reverse_iterator;

static constexpr size_type npos = String::npos;

Methods

cstr

constexpr cstr() noexcept;

constexpr explicit cstr(const allocator_type& a) noexcept;

constexpr cstr(const cstr& value);

constexpr cstr(cstr&& value) noexcept;

constexpr cstr(const cstr& value, const allocator_type& a);

constexpr cstr(cstr&& value, const allocator_type& a);

constexpr cstr(const cstr& value, size_type pos, const allocator_type& a = allocator_type());

constexpr cstr(const cstr& value, size_type pos, size_type count, const allocator_type& a = allocator_type());

constexpr cstr(cstr&& value, size_type pos, const allocator_type& a = allocator_type());

constexpr cstr(cstr&& value, size_type pos, size_type count, const allocator_type& a = allocator_type());

constexpr cstr(const String& value);

constexpr cstr(String&& value) noexcept;

constexpr cstr(const String& value, const allocator_type& a);

constexpr cstr(String&& value, const allocator_type& a);

constexpr cstr(const String& value, size_type pos, const allocator_type& a = allocator_type());

constexpr cstr(const String& value, size_type pos, size_type count, const allocator_type& a = allocator_type());

constexpr cstr(String&& value, size_type pos, const allocator_type& a = allocator_type());

constexpr cstr(String&& value, size_type pos, size_type count, const allocator_type& a = allocator_type());

constexpr cstr(const char* value, const allocator_type& a = allocator_type());

constexpr cstr(const char* value, size_type count, const allocator_type& a = allocator_type());

constexpr cstr(size_type count, char value, const allocator_type& a = allocator_type());

constexpr cstr(std::initializer_list<char> values, const allocator_type& a = allocator_type());

template<CInputIterator I> constexpr cstr(I first, I last, const allocator_type& a = allocator_type());

template<CContainerRange<char> R> constexpr cstr(std::from_range_t, R&& range, const allocator_type& a = allocator_type());

template<CStrViewLike V> constexpr explicit cstr(const V& value, const allocator_type& a = allocator_type());

template<CStrViewLike V> constexpr cstr(const V& value, size_type pos, size_type count, const allocator_type& a = allocator_type());

cstr(std::nullptr_t) = delete;

Constructs an owned byte string. Pointer-plus-count and range forms preserve embedded NUL bytes; a bare C-string pointer ends at the first NUL.

~cstr

constexpr ~cstr() = default;

operator=

constexpr cstr& operator=(const cstr& str);

constexpr cstr& operator=(cstr&& str) noexcept;

constexpr cstr& operator=(std::initializer_list<char> il);

cstr& operator=(std::nullptr_t) = delete;

constexpr cstr& operator=(const char* value);

constexpr cstr& operator=(char value);

template<CStrViewLike V> constexpr cstr& operator=(const V& value);

assign

constexpr cstr& assign(const cstr& str);

constexpr cstr& assign(cstr&& str) noexcept;

constexpr cstr& assign(const cstr& str, size_t pos, size_t n = npos);

constexpr cstr& assign(const char* s, size_t n);

constexpr cstr& assign(const char* s);

constexpr cstr& assign(size_t n, char c);

template<CInputIterator InputIterator> constexpr cstr& assign(InputIterator first, InputIterator last);

constexpr cstr& assign(std::initializer_list<char> il);

template<CStrViewLike V> constexpr cstr& assign(const V& value);

template<CStrViewLike V> constexpr cstr& assign(const V& value, size_type pos, size_type count = npos);

Replaces the current text with the supplied bytes or range and returns this string. Counted forms can include embedded NUL bytes.

assign_range

template<CContainerRange<char> R> constexpr cstr& assign_range(R&& range);

Replaces the string with characters from a C++ range. Existing pointers, references, and iterators can be invalidated.

begin

constexpr iterator begin() noexcept;

constexpr const_iterator begin() const noexcept;

cbegin

constexpr const_iterator cbegin() const noexcept;

end

constexpr iterator end() noexcept;

constexpr const_iterator end() const noexcept;

cend

constexpr const_iterator cend() const noexcept;

rbegin

constexpr reverse_iterator rbegin() noexcept;

constexpr const_reverse_iterator rbegin() const noexcept;

crbegin

constexpr const_reverse_iterator crbegin() const noexcept;

rend

constexpr reverse_iterator rend() noexcept;

constexpr const_reverse_iterator rend() const noexcept;

crend

constexpr const_reverse_iterator crend() const noexcept;

span

cspan span() const noexcept;

cspan span(size_t start) const noexcept;

cspan span(size_t start, size_t endOffset) const noexcept;

Returns byte indices, with optional start and end exclusion.

empty

constexpr bool empty() const noexcept;

size

constexpr size_t size() const noexcept;

length

constexpr size_t length() const noexcept;

max_size

constexpr size_t max_size() const noexcept;

capacity

constexpr size_t capacity() const noexcept;

reserve

constexpr void reserve(size_t res_arg);

constexpr void reserve();

Requests character capacity without changing the string length. Growth may invalidate all pointers and views; the no-argument overload is the legacy capacity-reduction request.

shrink_to_fit

constexpr void shrink_to_fit();

Requests release of unused character capacity. The request need not reduce capacity, and relocation invalidates borrowed pointers and views.

operator[]

constexpr const char& operator[](size_t pos) const noexcept;

constexpr char& operator[](size_t pos) noexcept;

Borrows a byte at an unchecked position. Use at() when the position must be validated; indices refer to bytes, not Unicode characters.

at

constexpr const char& at(size_t pos) const;

constexpr char& at(size_t pos);

Returns a byte by zero-based index with bounds checking. An index outside the string raises COutOfRangeError.

get

template<size_t I> const char& get() const;

template<size_t I> char& get();

Returns a byte at compile-time index I. The index must be valid; the template form does not add a bounds check.

front

constexpr const char& front() const noexcept;

constexpr char& front() noexcept;

back

constexpr const char& back() const noexcept;

constexpr char& back() noexcept;

data

constexpr char* data() noexcept;

constexpr const char* data() const noexcept;

Returns borrowed contiguous byte storage with a trailing terminator. A mutable pointer may change existing characters but must not overwrite the terminator with a nonzero byte.

c_str

constexpr const char* c_str() const noexcept;

Returns a borrowed null-terminated pointer. Embedded NUL bytes are still present, so use a counted interface for binary text.

find

constexpr size_t find(const cstr& str, size_t pos = 0) const noexcept;

constexpr size_t find(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t find(const char* s, size_t pos = 0) const noexcept;

constexpr size_t find(char c, size_t pos = 0) const noexcept;

template<CStrViewLike V> constexpr size_type find(const V& value, size_type pos = 0) const noexcept(noexcept(std::string_view(value)));

Returns the first matching byte position at or after pos, or npos when absent. Counted overloads search binary data, including embedded NUL bytes.

rfind

constexpr size_t rfind(const cstr& str, size_t pos = npos) const noexcept;

constexpr size_t rfind(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t rfind(const char* s, size_t pos = npos) const noexcept;

constexpr size_t rfind(char c, size_t pos = npos) const noexcept;

template<CStrViewLike V> constexpr size_type rfind(const V& value, size_type pos = npos) const noexcept(noexcept(std::string_view(value)));

Searches backward for the last match starting no later than pos. Returns npos when absent; the default starts at the end.

find_first_of

constexpr size_t find_first_of(const cstr& str, size_t pos = 0) const noexcept;

constexpr size_t find_first_of(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t find_first_of(const char* s, size_t pos = 0) const noexcept;

constexpr size_t find_first_of(char c, size_t pos = 0) const noexcept;

template<CStrViewLike V> constexpr size_type find_first_of(const V& value, size_type pos = 0) const noexcept(noexcept(std::string_view(value)));

Returns the first byte position containing any character from the supplied set, starting at pos, or npos.

find_first_not_of

constexpr size_t find_first_not_of(const cstr& str, size_t pos = 0) const noexcept;

constexpr size_t find_first_not_of(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t find_first_not_of(const char* s, size_t pos = 0) const noexcept;

constexpr size_t find_first_not_of(char c, size_t pos = 0) const noexcept;

template<CStrViewLike V> constexpr size_type find_first_not_of(const V& value, size_type pos = 0) const noexcept(noexcept(std::string_view(value)));

Returns the first byte position containing none of the supplied characters, starting at pos, or npos.

find_last_of

constexpr size_t find_last_of(const cstr& str, size_t pos = npos) const noexcept;

constexpr size_t find_last_of(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t find_last_of(const char* s, size_t pos = npos) const noexcept;

constexpr size_t find_last_of(char c, size_t pos = npos) const noexcept;

template<CStrViewLike V> constexpr size_type find_last_of(const V& value, size_type pos = npos) const noexcept(noexcept(std::string_view(value)));

Searches backward for a byte from the supplied character set. Returns its position or npos.

find_last_not_of

constexpr size_t find_last_not_of(const cstr& str, size_t pos = npos) const noexcept;

constexpr size_t find_last_not_of(const char* s, size_t pos, size_t n) const noexcept;

constexpr size_t find_last_not_of(const char* s, size_t pos = npos) const noexcept;

constexpr size_t find_last_not_of(char c, size_t pos = npos) const noexcept;

template<CStrViewLike V> constexpr size_type find_last_not_of(const V& value, size_type pos = npos) const noexcept(noexcept(std::string_view(value)));

Searches backward for a byte outside the supplied character set. Returns its position or npos.

contains

constexpr bool contains(const cstr& str) const noexcept;

constexpr bool contains(char value) const noexcept;

constexpr bool contains(const char* value) const noexcept;

constexpr bool contains(std::string_view value) const noexcept;

findCount

size_t findCount(const cstr& str) const noexcept;

Counts non-overlapping occurrences of a nonempty substring. An empty search string is not supported.

startsWith

bool startsWith(const cstr& str) const noexcept;

Tests a prefix without changing the string. This is the Catalyst spelling of starts_with().

starts_with

constexpr bool starts_with(const cstr& str) const noexcept;

constexpr bool starts_with(char value) const noexcept;

constexpr bool starts_with(const char* value) const noexcept;

constexpr bool starts_with(std::string_view value) const noexcept;

endsWith

bool endsWith(const cstr& str) const noexcept;

Tests a suffix without changing the string. This is the Catalyst spelling of ends_with().

ends_with

constexpr bool ends_with(const cstr& str) const noexcept;

constexpr bool ends_with(char value) const noexcept;

constexpr bool ends_with(const char* value) const noexcept;

constexpr bool ends_with(std::string_view value) const noexcept;

insert

constexpr cstr& insert(size_t pos1, const cstr& str);

constexpr cstr& insert(size_t pos1, const cstr& str, size_t pos2, size_t n = npos);

constexpr cstr& insert(size_t pos1, const char* s, size_t n);

constexpr cstr& insert(size_t pos1, const char* s);

constexpr cstr& insert(size_t pos1, size_t n, char c);

constexpr iterator insert(const_iterator p, char c);

constexpr iterator insert(const_iterator p, size_t n, char c);

template<CInputIterator InputIterator> constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);

constexpr iterator insert(const_iterator position, std::initializer_list<char> values);

template<CStrViewLike V> constexpr cstr& insert(size_type pos, const V& value);

template<CStrViewLike V> constexpr cstr& insert(size_type pos, const V& value, size_type start, size_type count = npos);

Inserts bytes before a position or iterator without removing existing text. Index/count forms return this string; iterator forms return the first inserted position.

insert_range

template<CContainerRange<char> R> constexpr iterator insert_range(const_iterator position, R&& range);

Inserts characters from a C++ range before the supplied iterator. Returns an iterator to the first inserted character.

push_back

constexpr void push_back(char c);

pushBack

void pushBack(char c);

Appends one character. This is the Catalyst spelling of push_back().

append

constexpr cstr& append(const cstr& str);

constexpr cstr& append(const cstr& str, size_t pos, size_t n = npos);

constexpr cstr& append(const char* s, size_t n);

constexpr cstr& append(const char* s);

constexpr cstr& append(size_t n, char c);

template<CInputIterator InputIterator> constexpr cstr& append(InputIterator first, InputIterator last);

constexpr cstr& append(std::initializer_list<char> il);

template<CStrViewLike V> constexpr cstr& append(const V& value);

template<CStrViewLike V> constexpr cstr& append(const V& value, size_type pos, size_type count = npos);

Adds bytes at the end and returns this string. Substring and pointer/count forms let callers append a selected byte range.

append_range

template<CContainerRange<char> R> constexpr cstr& append_range(R&& range);

Appends characters from a C++ range and returns this string.

pushFront

void pushFront(char c);

Inserts a character at the beginning, shifting the existing bytes.

operator+=

constexpr cstr& operator+=(const cstr& str);

constexpr cstr& operator+=(const std::string& str);

constexpr cstr& operator+=(const char* str);

constexpr cstr& operator+=(char c);

constexpr cstr& operator+=(std::initializer_list<char> il);

template<CStrViewLike V> constexpr cstr& operator+=(const V& value);

operator+

constexpr cstr operator+(const cstr& str) const&;

constexpr cstr operator+(const char* s) const&;

constexpr cstr operator+(cstr&& value) const&;

constexpr cstr operator+(const cstr& value) &&;

constexpr cstr operator+(cstr&& value) &&;

constexpr cstr operator+(const char* value) &&;

constexpr cstr operator+(char value) const&;

constexpr cstr operator+(char value) &&;

erase

constexpr cstr& erase(size_t pos = 0, size_t n = npos);

constexpr iterator erase(const_iterator position);

constexpr iterator erase(const_iterator first, const_iterator last);

Removes a substring or half-open iterator range. Position/count forms return this string; iterator forms return the position after the erased text.

pop_back

constexpr void pop_back() noexcept;

popBack

char popBack();

Removes and returns the final character. The string must be nonempty.

popFront

char popFront();

Removes and returns the first character, shifting the remaining bytes. The string must be nonempty.

clear

constexpr void clear() noexcept;

resize

constexpr void resize(size_t n, char c);

constexpr void resize(size_t n);

Changes the byte length, truncating the suffix or appending the supplied character (NUL by default). It does not reserve space without changing the contents.

resize_and_overwrite

template<class Operation> constexpr void resize_and_overwrite(size_type count, Operation operation);

The callback must return a valid final length. Callback failure restores a valid empty string and is translated to CError.

swap

constexpr void swap(cstr& str) noexcept;

replace

constexpr cstr& replace(size_t pos, size_t n, const cstr& str);

constexpr cstr& replace(size_t pos1, size_t n1, const cstr& str, size_t pos2, size_t n2 = npos);

constexpr cstr& replace(size_t pos, size_t n1, const char* s, size_t n2);

constexpr cstr& replace(size_t pos, size_t n1, const char* s);

constexpr cstr& replace(size_t pos, size_t n1, size_t n2, char c);

template<CStrViewLike V> constexpr cstr& replace(size_type pos, size_type count, const V& value);

template<CStrViewLike V> constexpr cstr& replace(size_type pos, size_type count, const V& value, size_type start, size_type length = npos);

constexpr cstr& replace(const_iterator first, const_iterator last, const cstr& value);

constexpr cstr& replace(const_iterator first, const_iterator last, const char* value);

constexpr cstr& replace(const_iterator first, const_iterator last, const char* value, size_type count);

constexpr cstr& replace(const_iterator first, const_iterator last, size_type count, char value);

constexpr cstr& replace(const_iterator first, const_iterator last, std::initializer_list<char> values);

template<CStrViewLike V> constexpr cstr& replace(const_iterator first, const_iterator last, const V& value);

template<CInputIterator I> constexpr cstr& replace(const_iterator first, const_iterator last, I begin, I end);

Replaces a selected substring or iterator range with the supplied bytes. The replacement may have a different length and can invalidate pointers and views.

replace_with_range

template<CContainerRange<char> R> constexpr cstr& replace_with_range(const_iterator first, const_iterator last, R&& range);

Replaces the half-open iterator range with characters from a C++ range and returns this string.

compare

constexpr int compare(const cstr& value) const noexcept;

constexpr int compare(const char* value) const;

constexpr int compare(size_type pos, size_type count, const cstr& value) const;

constexpr int compare(size_type pos, size_type count, const char* value) const;

constexpr int compare(size_type pos, size_type count, const cstr& value, size_type start, size_type length = npos) const;

constexpr int compare(size_type pos, size_type count, const char* value, size_type length) const;

template<CStrViewLike V> constexpr int compare(const V& value) const noexcept(noexcept(std::string_view(value)));

template<CStrViewLike V> constexpr int compare(size_type pos, size_type count, const V& value) const;

template<CStrViewLike V> constexpr int compare(size_type pos, size_type count, const V& value, size_type start, size_type length = npos) const;

Compares bytes lexicographically and returns a negative value, zero, or a positive value. Only the sign is meaningful; it is not a boolean equality result.

operator==

constexpr bool operator==(const cstr& str) const noexcept;

constexpr bool operator==(const char* value) const noexcept;

template<CStrViewLike V> constexpr bool operator==(const V& value) const noexcept(noexcept(std::string_view(value)));

operator!=

constexpr bool operator!=(const cstr& str) const noexcept;

operator<=>

constexpr auto operator<=>(const cstr& value) const noexcept;

constexpr auto operator<=>(const char* value) const noexcept;

template<CStrViewLike V> constexpr auto operator<=>(const V& value) const noexcept(noexcept(std::string_view(value)));

operator<

constexpr bool operator<(const cstr& str) const noexcept;

operator<=

constexpr bool operator<=(const cstr& str) const noexcept;

operator>

constexpr bool operator>(const cstr& str) const noexcept;

operator>=

constexpr bool operator>=(const cstr& str) const noexcept;

copy

constexpr size_t copy(char* s, size_t n, size_t pos = 0) const;

Copies at most n bytes starting at pos into caller-owned storage and returns the count copied. It does not append a NUL terminator.

substr

constexpr cstr substr(size_t pos = 0, size_t n = npos) const&;

constexpr cstr substr(size_type pos = 0, size_type count = npos) &&;

Returns the selected byte substring, clipping the requested count to the remaining length. A position beyond the end raises COutOfRangeError.

endStr

cstr endStr(size_t pos) const;

Returns the suffix beginning at byte position pos. A position equal to the length returns an empty string.

after

cstr after(const cstr& str) const;

Returns text after the last occurrence, or the entire string if absent.

before

cstr before(const cstr& str) const;

Returns text before the first occurrence, or the entire string if absent.

split

template<class T = CVector<cstr, std::allocator<cstr>>> T split(const cstr& delimiter) const;

Returns a collection of parts separated by a nonempty delimiter. Empty fields are retained.

splitOnSpace

template<class T = CVector<cstr, std::allocator<cstr>>> T splitOnSpace() const;

Splits on literal ASCII spaces rather than tabs or general whitespace. The current implementation can fail to advance on consecutive spaces; avoid this helper for such input.

findReplace

size_t findReplace(const cstr& value, const cstr& replacement, bool all = true);

size_t findReplace(const cstr& value, const cstr& replacement, bool all, size_t& pos);

Replaces occurrences in place and returns the number replaced. all = false stops after the first match; the pos overload starts searching there and updates it to the match or final npos. The search value must be nonempty.

multiReplace

void multiReplace(std::initializer_list<cstr> strings, std::initializer_list<cstr> replacements);

template<class T> void multiReplace(const T& strings, const T& replacements);

Replaces matches for multiple search strings in one scan of the original text. Earlier entries win ties at the same position and replacement text is not rescanned; supply equal-length lists of nonempty search strings and replacements.

getLineIndex

size_t getLineIndex(size_t line) const;

Returns the byte offset at the start of a one-based line number. Line 1 begins at zero; nonexistent lines return npos.

getLine

size_t getLine(size_t index) const;

Returns a one-based line count through the supplied byte index. Newlines at that index are included, so an index on a newline reports the following line; supply a valid index.

strip

void strip(bool start = true, bool end = true) noexcept;

Removes leading and/or trailing whitespace in place. start and end independently select the ends to trim.

intoAllUpper

void intoAllUpper();

Converts all characters in place; toAllUpper() returns a converted copy.

toAllUpper

cstr toAllUpper() const;

Returns a copy with all characters converted to uppercase using the C character-conversion rules. This is not Unicode case conversion.

intoAllLower

void intoAllLower();

Converts all characters in place; toAllLower() returns a converted copy.

toAllLower

cstr toAllLower() const;

Returns a copy with all characters converted to lowercase using the C character-conversion rules. This is not Unicode case conversion.

intoUpper

void intoUpper();

Converts the first character in place; toUpper() returns a converted copy. The string must be nonempty.

toUpper

cstr toUpper() const;

static int toUpper(int c) noexcept;

Returns a copy with only the first character uppercased; the string must be nonempty. The static integer overload converts one character using std::toupper.

intoLower

void intoLower();

Converts the first character in place; toLower() returns a converted copy. The string must be nonempty.

toLower

cstr toLower() const;

static int toLower(int c) noexcept;

Returns a copy with only the first character lowercased; the string must be nonempty. The static integer overload converts one character using std::tolower.

isLower

static bool isLower(int c) noexcept;

Tests for a lowercase letter through the corresponding C character-classification function. Supply EOF or a value representable as unsigned char; letter classification follows the current C locale.

isUpper

static bool isUpper(int c) noexcept;

Tests for a uppercase letter through the corresponding C character-classification function. Supply EOF or a value representable as unsigned char; letter classification follows the current C locale.

isDigit

static bool isDigit(int c) noexcept;

Tests for a digit through the corresponding C character-classification function. Supply EOF or a value representable as unsigned char; letter classification follows the current C locale.

isAlpha

static bool isAlpha(int c) noexcept;

Tests for a letter through the corresponding C character-classification function. Supply EOF or a value representable as unsigned char; letter classification follows the current C locale.

isAlphaNum

static bool isAlphaNum(int c) noexcept;

Tests for a letter or digit through the corresponding C character-classification function. Supply EOF or a value representable as unsigned char; letter classification follows the current C locale.

escape

void escape();

Replaces newline, tab, and double-quote characters with backslash escapes. It does not escape existing backslashes or implement full JSON escaping; use CSONGenerator for document output.

unescape

void unescape();

Decodes the backslash escapes for newline, tab, and double quote. Other escape forms are left alone; this is not a complete JSON or Unicode decoder.

unescapeUTF8

cstr unescapeUTF8() const;

Declared but not implemented in the current library.

std

constexpr std::string& std() noexcept;

constexpr const std::string& std() const noexcept;

Returns the underlying std::string by reference. Changes affect this string directly, and calls through the reference bypass Catalyst exception translation.

operator std::string&

constexpr operator std::string&() noexcept;

Borrows the underlying container for interoperability. This does not copy storage; references and iterators follow that container’s lifetime and invalidation rules.

operator const std::string&

constexpr operator const std::string&() const noexcept;

Borrows the underlying container for interoperability. This does not copy storage; references and iterators follow that container’s lifetime and invalidation rules.

operator std::string_view

constexpr operator std::string_view() const noexcept;

Returns a borrowed view over all bytes. Keep the string alive and avoid mutations that invalidate its storage.

get_allocator

constexpr std::allocator<char> get_allocator() const noexcept;

std::hash

template<> struct hash<mc::cstr>

template<> struct hash<pair<mc::cstr, mc::cstr>>

Methods

operator()

size_t operator()(const mc::cstr& s) const noexcept;

size_t operator()(const pair<mc::cstr, mc::cstr>& p) const noexcept;

Free functions & types

Types, constants & data

#define MC_NUM

#define MC_ALPHA

#define MC_LOWER

#define MC_UPPER

#define MC_WHITE

cstr

Free functions & types

Types, constants & data

Functions

cstr

Types, constants & data

Methods

std::hash

Methods

Free functions & types

Types, constants & data

Related headers