StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::String Class Reference

Owned UTF-8 text. More...

#include <StormByte/safe/string.hxx>

Collaboration diagram for StormByte::Safe::String:

Public Types

using value_type = char
 Byte type.
using size_type = Size
 Byte count and position type.
using difference_type = std::ptrdiff_t
 Iterator distance type.
using pointer = char*
 Mutable buffer pointer.
using const_pointer = const char*
 Read-only buffer pointer.
using reference = char&
 Mutable character reference.
using const_reference = const char&
 Read-only character reference.
using iterator = char*
 Mutable contiguous iterator.
using const_iterator = const char*
 Contiguous observer.
using reverse_iterator = std::reverse_iterator<iterator>
 Mutable reverse observer.
using const_reverse_iterator = std::reverse_iterator<const_iterator>
 Reverse observer.

Public Member Functions

void swap (String &other) noexcept
 Swaps storage with other.
Life
 String () noexcept
 Empty text.
 String (const char *str)
 Copies a C string.
 String (std::string_view str)
 Copies a view into owned storage.
 String (size_type count, char character)
 Construct count copies of character.
 String (const String &other, size_type pos, size_type count=npos)
 Copy a slice of other.
template<std::input_iterator InputIt>
 String (InputIt first, InputIt last)
 Copy the byte range [first, last).
 String (const WString &other)
 UTF-8 from wide text.
 String (const String &other)
 Copy constructor.
 String (String &&other) noexcept
 Move constructor.
 ~String () noexcept
 Releases a long SDS buffer.
String & operator= (const String &other)
 Copy assignment.
String & operator= (String &&other) noexcept
 Move assignment.
String & operator= (std::string_view text)
 Copy text from a caller-owned view.
Conversions
 operator std::string_view () const noexcept
 Non-owning view of the text.
STORMBYTE_FORCE_INLINE operator std::string () const
 Copy of the text in the caller’s heap.
 operator const char * () const noexcept
 View of the owned buffer.
 operator WString () const
 Wide text (UTF-8 decoded in the module).
const char * Bytes () const noexcept
 Non-owning view of the owned bytes.
Comparison
bool operator== (const String &other) const noexcept
 Content equality.
bool operator!= (const String &other) const noexcept
 Content inequality.
bool operator== (const char *str) const noexcept
 Content equality with a C string.
bool operator!= (const char *str) const noexcept
 Content inequality with a C string.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const String &other) const noexcept
 Content order.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const char *str) const noexcept
 Content order against a C string.

Static Public Attributes

static constexpr std::size_t SSO_CAPACITY = 32
 Short-text capacity, excluding the trailing NUL.

Lookup

static constexpr size_type npos {~0ull}
 Not found.
bool starts_with (std::string_view text) const noexcept
 Whether the text begins with text.
bool starts_with (char ch) const noexcept
 Whether the text begins with ch.
bool ends_with (std::string_view text) const noexcept
 Whether the text ends with text.
bool ends_with (char ch) const noexcept
 Whether the text ends with ch.
bool contains (std::string_view text) const noexcept
 Whether text occurs.
bool contains (char ch) const noexcept
 Whether ch occurs.
Size find (std::string_view text, Size pos={}) const noexcept
 First occurrence of text at or after pos.
Size find (char ch, Size pos={}) const noexcept
 First occurrence of ch at or after pos.
Size find (const char *text, Size pos, Size count) const noexcept
 First occurrence of count bytes of text.
Size rfind (std::string_view text, Size pos=npos) const noexcept
 Last occurrence of text at or before pos.
Size rfind (char ch, Size pos=npos) const noexcept
 Last occurrence of ch at or before pos.
Size rfind (const char *text, Size pos, Size count) const noexcept
 Last occurrence of count bytes of text.
Size find_first_of (std::string_view text, Size pos={}) const noexcept
 First byte that is in text, at or after pos.
Size find_first_of (char ch, Size pos={}) const noexcept
 First ch at or after pos.
Size find_last_of (std::string_view text, Size pos=npos) const noexcept
 Last byte that is in text, at or before pos.
Size find_last_of (char ch, Size pos=npos) const noexcept
 Last ch at or before pos.
Size find_first_not_of (std::string_view text, Size pos={}) const noexcept
 First byte that is not in text, at or after pos.
Size find_first_not_of (char ch, Size pos={}) const noexcept
 First byte other than ch, at or after pos.
Size find_last_not_of (std::string_view text, Size pos=npos) const noexcept
 Last byte that is not in text, at or before pos.
Size find_last_not_of (char ch, Size pos=npos) const noexcept
 Last byte other than ch, at or before pos.
String substr (Size pos={}, Size count=npos) const noexcept
 Copy of a slice.
int compare (std::string_view text) const noexcept
 Same order as std::string_view::compare.
int compare (size_type pos, size_type count, std::string_view text) const noexcept
 Compare a slice with text.
char & front () noexcept
 First byte.
char front () const noexcept
 Read the first byte.
char & back () noexcept
 Last byte.
char back () const noexcept
 Read the last byte.

Range

iterator begin () noexcept
 First character.
const_iterator begin () const noexcept
 First character.
iterator end () noexcept
 One past the last character.
const_iterator end () const noexcept
 One past the last character.
const_iterator cbegin () const noexcept
 First character.
const_iterator cend () const noexcept
 One past the last character.
reverse_iterator rbegin () noexcept
 Reverse begin.
const_reverse_iterator rbegin () const noexcept
 Reverse begin.
reverse_iterator rend () noexcept
 Reverse end.
const_reverse_iterator rend () const noexcept
 Reverse end.
const_reverse_iterator crbegin () const noexcept
 Reverse begin.
const_reverse_iterator crend () const noexcept
 Reverse end.
char * data () noexcept
 Contiguous pointer to the first byte, or to the trailing NUL when empty.
const char * data () const noexcept
 Read-only contiguous pointer to the first byte, or to the trailing NUL when empty.
const char * c_str () const noexcept
 Same pointer as data.
Size size () const noexcept
 Byte count, excluding the trailing NUL.
Size capacity () const noexcept
 Allocated byte capacity, excluding the trailing NUL.
Size max_size () const noexcept
 Largest representable byte count.
Size length () const noexcept
 Same as Size.
bool empty () const noexcept
 Whether Size is zero.
String & append (std::string_view text)
 Append UTF-8 bytes.
String & append (size_type count, char character)
 Append count copies of a byte.
template<std::input_iterator InputIt>
String & append (InputIt first, InputIt last)
 Append the byte range [first, last).
template<std::ranges::input_range R>
String & append_range (R &&range)
 Append a copy of range.
String & assign (std::string_view text)
 Replace the contents with a text view.
String & assign (size_type count, char character)
 Replace the contents with count copies of a byte.
template<std::input_iterator InputIt>
String & assign (InputIt first, InputIt last)
 Replace the contents with [first, last).
template<std::ranges::input_range R>
String & assign_range (R &&range)
 Replace the contents with a copy of range.
String & operator+= (std::string_view text)
 Append a view.
String & operator+= (char character)
 Append one byte.
void push_back (char character)
 Append one byte.
void pop_back ()
 Remove the final byte.
void clear ()
 Replace the contents with an empty string, retaining long-path capacity.
void reserve (size_type new_capacity)
 Reserve storage for at least new_capacity UTF-8 bytes.
void shrink_to_fit ()
 Drop unused long-path capacity.
void resize (size_type count, char character=char{})
 Resize the byte sequence, filling new bytes with character.
String & insert (size_type position, std::string_view text)
 Insert bytes at a byte position.
String & insert (size_type position, size_type count, char character)
 Insert count copies of character at position.
template<std::input_iterator InputIt>
iterator insert (const_iterator pos, InputIt first, InputIt last)
 Insert [first, last) before pos.
iterator insert (const_iterator pos, std::initializer_list< char > values)
 Insert an initializer list before pos.
template<std::ranges::input_range R>
iterator insert_range (const_iterator pos, R &&range)
 Insert a copy of range before pos.
String & erase (size_type position={}, size_type count=npos)
 Erase bytes starting at position.
iterator erase (const_iterator pos)
 Erase the byte at pos.
iterator erase (const_iterator first, const_iterator last)
 Erase [first, last).
String & replace (size_type position, size_type count, std::string_view text)
 Replace a byte range with text.
String & replace (const_iterator first, const_iterator last, std::string_view text)
 Replace [first, last) with text.
char & operator[] (const Size &index) noexcept
 Character at index.
char operator[] (const Size &index) const noexcept
 Read-only character at index.
char & at (size_type index)
 Byte at index.
const char & at (size_type index) const
 Read-only byte at index.
size_type copy (char *dest, size_type count, size_type pos={}) const
 Copy at most count bytes into dest, starting at pos.
 operator bool () const noexcept
 Whether the text is non-empty.
template<class... Args>
requires (sizeof...(Args) >= 1)
static String ReplaceToken (std::string_view text, Args &&... args)
 Copy text with each field replaced, in order, by one argument.

Helpers

String ToLower () const
 ASCII-letter lower case of this text.
String ToUpper () const
 ASCII-letter upper case of this text.
String SanitizeNewlines () const
 CR LF to LF on this text.
String RemoveWhitespace () const
 Drops isspace bytes from this text.
bool IsInteger () const noexcept
 Whether this text is an integer token.
Vector< String > Split () const
 Whitespace-separated tokens of this text.
Queue< String > Explode (char delimiter) const
 Tokens of this text on delimiter, including empty ones.
static String ToLower (std::string_view str)
 ASCII-letter lower case; UTF-8 otherwise copied.
static String ToUpper (std::string_view str)
 ASCII-letter upper case; UTF-8 otherwise copied.
static String SanitizeNewlines (std::string_view str)
 Turns CR LF into LF.
static String RemoveWhitespace (std::string_view str)
 Drops isspace bytes.
static bool IsInteger (std::string_view str) noexcept
 Optional sign plus ASCII digits.
static Vector< String > Split (std::string_view str)
 Whitespace-separated tokens.
static Vector< String > Split (const std::vector< String > &parts)
 Copy caller-owned tokens into Base storage.
static Queue< String > Explode (std::string_view str, char delimiter)
 Tokens on delimiter, including empty ones.
static String Implode (const Vector< String > &parts, std::string_view delimiter)
 Join parts with delimiter.
static String Implode (const Queue< String > &parts, std::string_view delimiter)
 Join parts with delimiter, in queue order.

Detailed Description

Owned UTF-8 text.

Not a std::string. Up to 32 bytes live in the object, NUL-terminated, with an explicit size. Longer text is an SDS buffer freed in Base. There is no null state: a moved-from string is empty. data() and c_str() are never null.

Classic and ranges algorithms can read or modify existing bytes; they cannot change the owned size. operator std::string_view is implicit and inline. operator std::string is explicit and STORMBYTE_FORCE_INLINE (caller heap).

Conversion to WString is explicit and runs in the module (UTF-8 to wide). Conversion from WString copies UTF-8 in the module.

ToUpper / ToLower map only ASCII A–Z / a–z. Other well-formed UTF-8 code points are copied. Ill-formed bytes are copied one-by-one so a sequence is never split in the middle of a valid character.

Observers follow std::string_view. Size-changing modifiers follow std::string value semantics. capacity() and reserve(Size) count UTF-8 bytes excluding NUL; reserve never shrinks. size_type is Size. There is no allocator.

Text construction, copying, conversion and transformations may allocate and throw. Default construction, moves and observers do not allocate and remain noexcept.

Member Typedef Documentation

◆ const_iterator

Contiguous observer.

◆ const_pointer

Read-only buffer pointer.

◆ const_reference

Read-only character reference.

◆ const_reverse_iterator

Reverse observer.

◆ difference_type

Iterator distance type.

◆ iterator

Mutable contiguous iterator.

◆ pointer

Mutable buffer pointer.

◆ reference

Mutable character reference.

◆ reverse_iterator

using StormByte::Safe::String::reverse_iterator = std::reverse_iterator<iterator>

Mutable reverse observer.

◆ size_type

Byte count and position type.

◆ value_type

Byte type.

Constructor & Destructor Documentation

◆ String() [1/9]

StormByte::Safe::String::String ( )
noexcept

Empty text.

Not null.

◆ String() [2/9]

StormByte::Safe::String::String ( const char * str)

Copies a C string.

A null pointer becomes empty.

Parameters
strSource; may be null.

◆ String() [3/9]

StormByte::Safe::String::String ( std::string_view str)

Copies a view into owned storage.

Parameters
strSource. Embedded NUL counts.

◆ String() [4/9]

StormByte::Safe::String::String ( size_type count,
char character )

Construct count copies of character.

Parameters
countByte count.
characterFill byte.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ String() [5/9]

StormByte::Safe::String::String ( const String & other,
size_type pos,
size_type count = npos )

Copy a slice of other.

Parameters
otherSource text.
posStart, in bytes.
countLength. npos means through the end.
Exceptions
OutOfBoundsErrorpos is past other.size().
AllocationErrorThe long path could not be allocated.

◆ String() [6/9]

template<std::input_iterator InputIt>
StormByte::Safe::String::String ( InputIt first,
InputIt last )
inline

Copy the byte range [first, last).

Template Parameters
InputItInput iterator of bytes.
Parameters
firstStart.
lastEnd.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ String() [7/9]

StormByte::Safe::String::String ( const WString & other)
explicit

UTF-8 from wide text.

Parameters
otherWide source.

◆ String() [8/9]

StormByte::Safe::String::String ( const String & other)

Copy constructor.

Parameters
otherText to copy.

◆ String() [9/9]

StormByte::Safe::String::String ( String && other)
noexcept

Move constructor.

Parameters
otherText to take. other becomes empty.

◆ ~String()

StormByte::Safe::String::~String ( )
noexcept

Releases a long SDS buffer.

A short string has nothing to free.

Member Function Documentation

◆ append() [1/3]

template<std::input_iterator InputIt>
String & StormByte::Safe::String::append ( InputIt first,
InputIt last )
inline

Append the byte range [first, last).

Template Parameters
InputItInput iterator of bytes.
Parameters
firstStart.
lastEnd.
Returns
This string.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ append() [2/3]

String & StormByte::Safe::String::append ( size_type count,
char character )

Append count copies of a byte.

Parameters
countNumber of copies.
characterByte to append.
Returns
This string.

◆ append() [3/3]

String & StormByte::Safe::String::append ( std::string_view text)

Append UTF-8 bytes.

Parameters
textText to append.
Returns
This string.

◆ append_range()

template<std::ranges::input_range R>
String & StormByte::Safe::String::append_range ( R && range)
inline

Append a copy of range.

Template Parameters
RInput range of bytes.
Parameters
rangeSource range.
Returns
This string.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ assign() [1/3]

template<std::input_iterator InputIt>
String & StormByte::Safe::String::assign ( InputIt first,
InputIt last )
inline

Replace the contents with [first, last).

Template Parameters
InputItInput iterator of bytes.
Parameters
firstStart.
lastEnd.
Returns
This string.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ assign() [2/3]

String & StormByte::Safe::String::assign ( size_type count,
char character )

Replace the contents with count copies of a byte.

Parameters
countNumber of copies.
characterByte to assign.
Returns
This string.

◆ assign() [3/3]

String & StormByte::Safe::String::assign ( std::string_view text)

Replace the contents with a text view.

Parameters
textSource bytes.
Returns
This string.

◆ assign_range()

template<std::ranges::input_range R>
String & StormByte::Safe::String::assign_range ( R && range)
inline

Replace the contents with a copy of range.

Template Parameters
RInput range of bytes.
Parameters
rangeSource range.
Returns
This string.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ at() [1/2]

char & StormByte::Safe::String::at ( size_type index)

Byte at index.

Parameters
indexByte offset.
Returns
Byte.
Exceptions
OutOfBoundsErrorindex is not less than Size.

◆ at() [2/2]

const char & StormByte::Safe::String::at ( size_type index) const

Read-only byte at index.

Parameters
indexByte offset.
Returns
Byte.
Exceptions
OutOfBoundsErrorindex is not less than Size.

◆ back() [1/2]

char StormByte::Safe::String::back ( ) const
inlinenoexcept

Read the last byte.

Returns
Byte copy.
Note
Empty is undefined, same as std::string::back.

◆ back() [2/2]

char & StormByte::Safe::String::back ( )
inlinenoexcept

Last byte.

Returns
Byte.
Note
Empty is undefined, same as std::string::back.

◆ begin() [1/2]

const_iterator StormByte::Safe::String::begin ( ) const
inlinenoexcept

First character.

Returns
Read-only iterator. Never null.

◆ begin() [2/2]

iterator StormByte::Safe::String::begin ( )
inlinenoexcept

First character.

Returns
Iterator. Never null.

◆ Bytes()

const char * StormByte::Safe::String::Bytes ( ) const
inlinenoexcept

Non-owning view of the owned bytes.

Returns
data(). Never null.

◆ c_str()

const char * StormByte::Safe::String::c_str ( ) const
inlinenoexcept

Same pointer as data.

The byte at size() is NUL and is not part of the length.

Returns
Never null.

◆ capacity()

Size StormByte::Safe::String::capacity ( ) const
noexcept

Allocated byte capacity, excluding the trailing NUL.

Returns
32 for a short string; SDS capacity for a long one.

◆ cbegin()

const_iterator StormByte::Safe::String::cbegin ( ) const
inlinenoexcept

First character.

Returns
Iterator.

◆ cend()

const_iterator StormByte::Safe::String::cend ( ) const
inlinenoexcept

One past the last character.

Returns
Iterator.

◆ clear()

void StormByte::Safe::String::clear ( )

Replace the contents with an empty string, retaining long-path capacity.

◆ compare() [1/2]

int StormByte::Safe::String::compare ( size_type pos,
size_type count,
std::string_view text ) const
inlinenoexcept

Compare a slice with text.

Parameters
posStart, in bytes.
countSlice length.
textOther text.
Returns
Negative, zero, or positive.

◆ compare() [2/2]

int StormByte::Safe::String::compare ( std::string_view text) const
inlinenoexcept

Same order as std::string_view::compare.

Parameters
textOther text.
Returns
Negative, zero, or positive.

◆ contains() [1/2]

bool StormByte::Safe::String::contains ( char ch) const
inlinenoexcept

Whether ch occurs.

Parameters
chByte.
Returns
Match.

◆ contains() [2/2]

bool StormByte::Safe::String::contains ( std::string_view text) const
inlinenoexcept

Whether text occurs.

Parameters
textNeedle.
Returns
Match. Empty needle matches.

◆ copy()

size_type StormByte::Safe::String::copy ( char * dest,
size_type count,
size_type pos = {} ) const

Copy at most count bytes into dest, starting at pos.

Parameters
destCaller buffer.
countBuffer capacity.
posStart, in bytes.
Returns
Bytes copied.
Exceptions
OutOfBoundsErrorpos is past Size.

◆ crbegin()

const_reverse_iterator StormByte::Safe::String::crbegin ( ) const
inlinenoexcept

Reverse begin.

Returns
Reverse iterator.

◆ crend()

const_reverse_iterator StormByte::Safe::String::crend ( ) const
inlinenoexcept

Reverse end.

Returns
Reverse iterator.

◆ data() [1/2]

const char * StormByte::Safe::String::data ( ) const
noexcept

Read-only contiguous pointer to the first byte, or to the trailing NUL when empty.

Returns
Never null.

◆ data() [2/2]

char * StormByte::Safe::String::data ( )
noexcept

Contiguous pointer to the first byte, or to the trailing NUL when empty.

Returns
Never null.

◆ empty()

bool StormByte::Safe::String::empty ( ) const
inlinenoexcept

Whether Size is zero.

Returns
Emptiness. An empty string still has a pointer.

◆ end() [1/2]

const_iterator StormByte::Safe::String::end ( ) const
inlinenoexcept

One past the last character.

Returns
Read-only iterator. Never null.

◆ end() [2/2]

iterator StormByte::Safe::String::end ( )
inlinenoexcept

One past the last character.

Returns
Iterator. Never null.

◆ ends_with() [1/2]

bool StormByte::Safe::String::ends_with ( char ch) const
inlinenoexcept

Whether the text ends with ch.

Parameters
chSuffix byte.
Returns
Match.

◆ ends_with() [2/2]

bool StormByte::Safe::String::ends_with ( std::string_view text) const
inlinenoexcept

Whether the text ends with text.

Parameters
textSuffix.
Returns
Match. Empty suffix matches.

◆ erase() [1/3]

iterator StormByte::Safe::String::erase ( const_iterator first,
const_iterator last )

Erase [first, last).

Parameters
firstStart.
lastEnd.
Returns
Iterator following the erased range.
Exceptions
OutOfBoundsErrorThe range is outside this string.

◆ erase() [2/3]

iterator StormByte::Safe::String::erase ( const_iterator pos)

Erase the byte at pos.

Parameters
posByte to erase.
Returns
Iterator following the erased byte.
Exceptions
OutOfBoundsErrorpos is outside this string.

◆ erase() [3/3]

String & StormByte::Safe::String::erase ( size_type position = {},
size_type count = npos )

Erase bytes starting at position.

Parameters
positionFirst byte to erase.
countMaximum bytes to erase.
Returns
This string.

◆ Explode() [1/2]

Queue< String > StormByte::Safe::String::Explode ( char delimiter) const

Tokens of this text on delimiter, including empty ones.

Parameters
delimiterSeparator.
Returns
Owned tokens.

◆ Explode() [2/2]

Queue< String > StormByte::Safe::String::Explode ( std::string_view str,
char delimiter )
static

Tokens on delimiter, including empty ones.

Nodes are allocated in Base.

Parameters
strSource.
delimiterSeparator.
Returns
Owned tokens.

◆ find() [1/3]

Size StormByte::Safe::String::find ( char ch,
Size pos = {} ) const
inlinenoexcept

First occurrence of ch at or after pos.

Parameters
chByte.
posStart, in bytes.
Returns
Index, or npos.

◆ find() [2/3]

Size StormByte::Safe::String::find ( const char * text,
Size pos,
Size count ) const
inlinenoexcept

First occurrence of count bytes of text.

Parameters
textNeedle. May be null when count is zero.
posStart, in bytes.
countBytes of text to use.
Returns
Index, or npos.

◆ find() [3/3]

Size StormByte::Safe::String::find ( std::string_view text,
Size pos = {} ) const
inlinenoexcept

First occurrence of text at or after pos.

Parameters
textNeedle.
posStart, in bytes.
Returns
Index, or npos.

◆ find_first_not_of() [1/2]

Size StormByte::Safe::String::find_first_not_of ( char ch,
Size pos = {} ) const
inlinenoexcept

First byte other than ch, at or after pos.

Parameters
chByte.
posStart, in bytes.
Returns
Index, or npos.

◆ find_first_not_of() [2/2]

Size StormByte::Safe::String::find_first_not_of ( std::string_view text,
Size pos = {} ) const
inlinenoexcept

First byte that is not in text, at or after pos.

Parameters
textSet of bytes.
posStart, in bytes.
Returns
Index, or npos.

◆ find_first_of() [1/2]

Size StormByte::Safe::String::find_first_of ( char ch,
Size pos = {} ) const
inlinenoexcept

First ch at or after pos.

Parameters
chByte.
posStart, in bytes.
Returns
Index, or npos.

◆ find_first_of() [2/2]

Size StormByte::Safe::String::find_first_of ( std::string_view text,
Size pos = {} ) const
inlinenoexcept

First byte that is in text, at or after pos.

Parameters
textSet of bytes.
posStart, in bytes.
Returns
Index, or npos.

◆ find_last_not_of() [1/2]

Size StormByte::Safe::String::find_last_not_of ( char ch,
Size pos = npos ) const
inlinenoexcept

Last byte other than ch, at or before pos.

Parameters
chByte.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ find_last_not_of() [2/2]

Size StormByte::Safe::String::find_last_not_of ( std::string_view text,
Size pos = npos ) const
inlinenoexcept

Last byte that is not in text, at or before pos.

Parameters
textSet of bytes.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ find_last_of() [1/2]

Size StormByte::Safe::String::find_last_of ( char ch,
Size pos = npos ) const
inlinenoexcept

Last ch at or before pos.

Parameters
chByte.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ find_last_of() [2/2]

Size StormByte::Safe::String::find_last_of ( std::string_view text,
Size pos = npos ) const
inlinenoexcept

Last byte that is in text, at or before pos.

Parameters
textSet of bytes.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ front() [1/2]

char StormByte::Safe::String::front ( ) const
inlinenoexcept

Read the first byte.

Returns
Byte copy.
Note
Empty is undefined, same as std::string::front.

◆ front() [2/2]

char & StormByte::Safe::String::front ( )
inlinenoexcept

First byte.

Returns
Byte.
Note
Empty is undefined, same as std::string::front.

◆ Implode() [1/2]

String StormByte::Safe::String::Implode ( const Queue< String > & parts,
std::string_view delimiter )
static

Join parts with delimiter, in queue order.

Parameters
partsTokens. Not modified.
delimiterSeparator inserted between tokens. Not copied.
Returns
One string. Empty when parts is empty.

◆ Implode() [2/2]

String StormByte::Safe::String::Implode ( const Vector< String > & parts,
std::string_view delimiter )
static

Join parts with delimiter.

Parts are not copied before the result is built.

Parameters
partsTokens. Not modified.
delimiterSeparator inserted between tokens. Not copied. Empty joins them directly.
Returns
One string. Empty when parts is empty. A short result stays in SSO.

◆ insert() [1/4]

template<std::input_iterator InputIt>
iterator StormByte::Safe::String::insert ( const_iterator pos,
InputIt first,
InputIt last )
inline

Insert [first, last) before pos.

Template Parameters
InputItInput iterator of bytes.
Parameters
posInsertion point.
firstStart.
lastEnd.
Returns
Iterator to the first inserted byte, or pos when the range is empty.
Exceptions
OutOfBoundsErrorpos is outside this string.
AllocationErrorThe long path could not be allocated.

◆ insert() [2/4]

iterator StormByte::Safe::String::insert ( const_iterator pos,
std::initializer_list< char > values )

Insert an initializer list before pos.

Parameters
posInsertion point.
valuesBytes to insert.
Returns
Iterator to the first inserted byte.
Exceptions
OutOfBoundsErrorpos is outside this string.
AllocationErrorThe long path could not be allocated.

◆ insert() [3/4]

String & StormByte::Safe::String::insert ( size_type position,
size_type count,
char character )

Insert count copies of character at position.

Parameters
positionInsertion position.
countCopy count.
characterFill byte.
Returns
This string.
Exceptions
OutOfBoundsErrorposition is past Size.
AllocationErrorThe long path could not be allocated.

◆ insert() [4/4]

String & StormByte::Safe::String::insert ( size_type position,
std::string_view text )

Insert bytes at a byte position.

Parameters
positionInsertion position.
textBytes to insert.
Returns
This string.

◆ insert_range()

template<std::ranges::input_range R>
iterator StormByte::Safe::String::insert_range ( const_iterator pos,
R && range )
inline

Insert a copy of range before pos.

Template Parameters
RInput range of bytes.
Parameters
posInsertion point.
rangeSource range.
Returns
Iterator to the first inserted byte.
Exceptions
OutOfBoundsErrorpos is outside this string.
AllocationErrorThe long path could not be allocated.

◆ IsInteger() [1/2]

bool StormByte::Safe::String::IsInteger ( ) const
inlinenoexcept

Whether this text is an integer token.

Returns
Whether it matches IsInteger(std::string_view).

◆ IsInteger() [2/2]

bool StormByte::Safe::String::IsInteger ( std::string_view str)
staticnoexcept

Optional sign plus ASCII digits.

Parameters
strSource.
Returns
Whether str is an integer token.

◆ length()

Size StormByte::Safe::String::length ( ) const
inlinenoexcept

Same as Size.

Returns
Length as StormByte::Size.

◆ max_size()

Size StormByte::Safe::String::max_size ( ) const
noexcept

Largest representable byte count.

Returns
Maximum size.

◆ operator bool()

StormByte::Safe::String::operator bool ( ) const
inlineexplicitnoexcept

Whether the text is non-empty.

Returns
false for empty text. A pointer is always held.

◆ operator const char *()

StormByte::Safe::String::operator const char * ( ) const
inlineexplicitnoexcept

View of the owned buffer.

Returns
c_str(). Never null.
Note
Same lifetime as std::string::c_str().

◆ operator std::string()

STORMBYTE_FORCE_INLINE StormByte::Safe::String::operator std::string ( ) const
inlineexplicit

Copy of the text in the caller’s heap.

Returns
Caller-owned std::string.

◆ operator std::string_view()

StormByte::Safe::String::operator std::string_view ( ) const
inlinenoexcept

Non-owning view of the text.

Returns
View of size() bytes. Embedded NUL is preserved. Never a null buffer.
Note
Same lifetime as std::string::c_str(). Invalidated by a mutating operation that reallocates.

◆ operator WString()

StormByte::Safe::String::operator WString ( ) const
explicit

Wide text (UTF-8 decoded in the module).

Returns
Owned WString.

◆ operator!=() [1/2]

bool StormByte::Safe::String::operator!= ( const char * str) const
inlinenoexcept

Content inequality with a C string.

Parameters
strMay be null.
Returns
Whether the texts differ.

◆ operator!=() [2/2]

bool StormByte::Safe::String::operator!= ( const String & other) const
inlinenoexcept

Content inequality.

Parameters
otherOther text.
Returns
Whether the texts differ.

◆ operator+=() [1/2]

String & StormByte::Safe::String::operator+= ( char character)

Append one byte.

Parameters
characterByte to append.
Returns
This string.

◆ operator+=() [2/2]

String & StormByte::Safe::String::operator+= ( std::string_view text)

Append a view.

A String converts to this view.

Parameters
textText to append.
Returns
This string.

◆ operator<=>() [1/2]

STORMBYTE_FORCE_INLINE std::strong_ordering StormByte::Safe::String::operator<=> ( const char * str) const
inlinenoexcept

Content order against a C string.

A null pointer compares as empty.

Parameters
strMay be null.
Returns
Ordering.

◆ operator<=>() [2/2]

STORMBYTE_FORCE_INLINE std::strong_ordering StormByte::Safe::String::operator<=> ( const String & other) const
inlinenoexcept

Content order.

Parameters
otherOther text.
Returns
Ordering.

◆ operator=() [1/3]

String & StormByte::Safe::String::operator= ( const String & other)

Copy assignment.

Parameters
otherText to copy.
Returns
*this.

◆ operator=() [2/3]

String & StormByte::Safe::String::operator= ( std::string_view text)

Copy text from a caller-owned view.

Parameters
textSource bytes.
Returns
This string.

◆ operator=() [3/3]

String & StormByte::Safe::String::operator= ( String && other)
noexcept

Move assignment.

Parameters
otherText to take. other becomes empty.
Returns
*this.

◆ operator==() [1/2]

bool StormByte::Safe::String::operator== ( const char * str) const
inlinenoexcept

Content equality with a C string.

A null pointer compares equal to empty.

Parameters
strMay be null.
Returns
Whether the texts are equal.

◆ operator==() [2/2]

bool StormByte::Safe::String::operator== ( const String & other) const
inlinenoexcept

Content equality.

Parameters
otherOther text.
Returns
Whether the texts are equal.

◆ operator[]() [1/2]

char StormByte::Safe::String::operator[] ( const Size & index) const
inlinenoexcept

Read-only character at index.

Parameters
indexPosition in [0, size()]. size() is the trailing NUL.
Returns
Character copy.
Note
index > size() is undefined and asserts when assertions are on.

◆ operator[]() [2/2]

char & StormByte::Safe::String::operator[] ( const Size & index)
inlinenoexcept

Character at index.

Parameters
indexPosition in [0, size()]. size() is the trailing NUL.
Returns
Character.
Note
index > size() is undefined and asserts when assertions are on.

◆ pop_back()

void StormByte::Safe::String::pop_back ( )

Remove the final byte.

Empty use follows std::string preconditions.

◆ push_back()

void StormByte::Safe::String::push_back ( char character)

Append one byte.

Parameters
characterByte to append.

◆ rbegin() [1/2]

const_reverse_iterator StormByte::Safe::String::rbegin ( ) const
inlinenoexcept

Reverse begin.

Returns
Read-only reverse iterator.

◆ rbegin() [2/2]

reverse_iterator StormByte::Safe::String::rbegin ( )
inlinenoexcept

Reverse begin.

Returns
Reverse iterator.

◆ RemoveWhitespace() [1/2]

String StormByte::Safe::String::RemoveWhitespace ( ) const
inline

Drops isspace bytes from this text.

Returns
New text.

◆ RemoveWhitespace() [2/2]

String StormByte::Safe::String::RemoveWhitespace ( std::string_view str)
static

Drops isspace bytes.

Parameters
strSource.
Returns
New text.

◆ rend() [1/2]

const_reverse_iterator StormByte::Safe::String::rend ( ) const
inlinenoexcept

Reverse end.

Returns
Read-only reverse iterator.

◆ rend() [2/2]

reverse_iterator StormByte::Safe::String::rend ( )
inlinenoexcept

Reverse end.

Returns
Reverse iterator.

◆ replace() [1/2]

String & StormByte::Safe::String::replace ( const_iterator first,
const_iterator last,
std::string_view text )

Replace [first, last) with text.

Parameters
firstStart.
lastEnd.
textReplacement.
Returns
This string.
Exceptions
OutOfBoundsErrorThe range is outside this string.
AllocationErrorThe long path could not be allocated.

◆ replace() [2/2]

String & StormByte::Safe::String::replace ( size_type position,
size_type count,
std::string_view text )

Replace a byte range with text.

Parameters
positionFirst byte to replace.
countMaximum bytes to erase.
textReplacement bytes.
Returns
This string.

◆ ReplaceToken()

template<class... Args>
requires (sizeof...(Args) >= 1)
String StormByte::Safe::String::ReplaceToken ( std::string_view text,
Args &&... args )
inlinestatic

Copy text with each field replaced, in order, by one argument.

Template Parameters
ArgsText, a bool, a number, a pointer, or a type that converts to std::string. A view is not copied. A bool is true or false. A char* is text. Any other raw pointer is its address (0x and hex). Safe::Unique and Safe::Shared print the address of the object they hold, or 0x0 when empty. Size and ByteSize use their text conversion for {} (digits, or the IEC length) and their integer count for a numeric field. A number with a bare {} uses std::to_string. A field may be {:[0][width][.precision][type]} with type d, f, g, G, x or X.
Parameters
textPattern. A long pattern is not stored; only the result is owned.
argsReplacements. At least one. Extra arguments are ignored. A leftover field stays. A brace run that is not a supported field stays literal and does not consume an argument.
Returns
New Base-owned string. No field yields an owned copy of text.
Exceptions
AllocationErrorThe result could not be allocated.

◆ reserve()

void StormByte::Safe::String::reserve ( size_type new_capacity)

Reserve storage for at least new_capacity UTF-8 bytes.

Parameters
new_capacityRequested byte capacity, excluding the NUL.
Exceptions
OutOfBoundsErrorThe request cannot be represented, including a trailing NUL.
AllocationErrorThe size is representable but the SDS allocation failed.
Note
Requests at or below capacity do not shrink or reallocate.

◆ resize()

void StormByte::Safe::String::resize ( size_type count,
char character = char{} )

Resize the byte sequence, filling new bytes with character.

Parameters
countNew byte count.
characterFill byte, default initialized to NUL.

◆ rfind() [1/3]

Size StormByte::Safe::String::rfind ( char ch,
Size pos = npos ) const
inlinenoexcept

Last occurrence of ch at or before pos.

Parameters
chByte.
posHighest start, in bytes. Default is the end.
Returns
Index, or npos.

◆ rfind() [2/3]

Size StormByte::Safe::String::rfind ( const char * text,
Size pos,
Size count ) const
inlinenoexcept

Last occurrence of count bytes of text.

Parameters
textNeedle. May be null when count is zero.
posHighest start, in bytes.
countBytes of text to use.
Returns
Index, or npos.

◆ rfind() [3/3]

Size StormByte::Safe::String::rfind ( std::string_view text,
Size pos = npos ) const
inlinenoexcept

Last occurrence of text at or before pos.

Parameters
textNeedle.
posHighest start, in bytes. Default is the end.
Returns
Index, or npos.

◆ SanitizeNewlines() [1/2]

String StormByte::Safe::String::SanitizeNewlines ( ) const
inline

CR LF to LF on this text.

Returns
New text.

◆ SanitizeNewlines() [2/2]

String StormByte::Safe::String::SanitizeNewlines ( std::string_view str)
static

Turns CR LF into LF.

Parameters
strSource.
Returns
New text.

◆ shrink_to_fit()

void StormByte::Safe::String::shrink_to_fit ( )

Drop unused long-path capacity.

A short string is unchanged.

◆ size()

Size StormByte::Safe::String::size ( ) const
noexcept

Byte count, excluding the trailing NUL.

Returns
Length as StormByte::Size.

◆ Split() [1/3]

Vector< String > StormByte::Safe::String::Split ( ) const

Whitespace-separated tokens of this text.

Returns
Owned tokens.

◆ Split() [2/3]

Vector< String > StormByte::Safe::String::Split ( const std::vector< String > & parts)
inlinestatic

Copy caller-owned tokens into Base storage.

Parameters
partsSource. Not modified.
Returns
Owned tokens.

◆ Split() [3/3]

Vector< String > StormByte::Safe::String::Split ( std::string_view str)
static

Whitespace-separated tokens.

Nodes are allocated in Base.

Parameters
strSource.
Returns
Owned tokens.

◆ starts_with() [1/2]

bool StormByte::Safe::String::starts_with ( char ch) const
inlinenoexcept

Whether the text begins with ch.

Parameters
chPrefix byte.
Returns
Match.

◆ starts_with() [2/2]

bool StormByte::Safe::String::starts_with ( std::string_view text) const
inlinenoexcept

Whether the text begins with text.

Parameters
textPrefix.
Returns
Match. Empty prefix matches.

◆ substr()

String StormByte::Safe::String::substr ( Size pos = {},
Size count = npos ) const
inlinenoexcept

Copy of a slice.

Not a view.

Parameters
posStart, in bytes.
countLength. npos means through the end.
Returns
Owned text. Empty when pos is past Size. Does not throw.

◆ swap()

void StormByte::Safe::String::swap ( String & other)
noexcept

Swaps storage with other.

Parameters
otherOther text.

◆ ToLower() [1/2]

String StormByte::Safe::String::ToLower ( ) const
inline

ASCII-letter lower case of this text.

Returns
New text.

◆ ToLower() [2/2]

String StormByte::Safe::String::ToLower ( std::string_view str)
static

ASCII-letter lower case; UTF-8 otherwise copied.

Parameters
strSource.
Returns
New text.

◆ ToUpper() [1/2]

String StormByte::Safe::String::ToUpper ( ) const
inline

ASCII-letter upper case of this text.

Returns
New text.

◆ ToUpper() [2/2]

String StormByte::Safe::String::ToUpper ( std::string_view str)
static

ASCII-letter upper case; UTF-8 otherwise copied.

Parameters
strSource.
Returns
New text.

Member Data Documentation

◆ npos

size_type StormByte::Safe::String::npos {~0ull}
staticconstexpr

Not found.

◆ SSO_CAPACITY

std::size_t StormByte::Safe::String::SSO_CAPACITY = 32
staticconstexpr

Short-text capacity, excluding the trailing NUL.


The documentation for this class was generated from the following file: