StormByte-String 1.0.0
C++26 string module of the StormByte suite
 
Loading...
Searching...
No Matches
StormByte::String::String Class Reference

Owned UTF-8 text composed of StormByte::CString. More...

#include <StormByte/string/string.hxx>

Collaboration diagram for StormByte::String::String:

Public Types

using value_type = char
 Byte type.
 
using const_iterator = const char *
 Contiguous observer.
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 Reverse observer.
 

Public Member Functions

void swap (String &other) noexcept
 Swaps buffers with other.
 
Life
 String () noexcept
 Null text.
 
 String (const char *str) noexcept
 Copies a C string.
 
 String (std::string_view str) noexcept
 Copies a view into an owned NUL-terminated buffer.
 
 String (CString text) noexcept
 Takes an owned buffer.
 
 String (const WString &other) noexcept
 UTF-8 from wide text.
 
 String (const String &other) noexcept
 Copy constructor.
 
 String (String &&other) noexcept
 Move constructor.
 
 ~String () noexcept=default
 Releases the buffer.
 
String & operator= (const String &other) noexcept
 Copy assignment.
 
String & operator= (String &&other) noexcept
 Move assignment.
 
Range
const_iterator begin () const noexcept
 First character, or null.
 
const_iterator end () const noexcept
 One past the last character, or null.
 
const_iterator cbegin () const noexcept
 First character, or null.
 
const_iterator cend () const noexcept
 One past the last character, or null.
 
const_reverse_iterator rbegin () const noexcept
 Reverse begin.
 
const_reverse_iterator rend () const noexcept
 Reverse end.
 
const_reverse_iterator crbegin () const noexcept
 Reverse begin.
 
const_reverse_iterator crend () const noexcept
 Reverse end.
 
const char * data () const noexcept
 Contiguous pointer; null when the buffer is null.
 
Size size () const noexcept
 Character count; 0 when null or empty.
 
Size length () const noexcept
 Same as size.
 
bool empty () const noexcept
 Whether size is zero.
 
char operator[] (const Size &index) const noexcept
 Character at index.
 
 operator bool () const noexcept
 Whether a buffer is held.
 
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 noexcept
 Wide text (UTF-8 decoded in the module).
 
const CString & Bytes () const noexcept
 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.
 
std::strong_ordering operator<=> (const String &other) const noexcept
 Content order.
 
std::strong_ordering operator<=> (const char *str) const noexcept
 Content order against a C string.
 

Lookup

static constexpr Size npos {~0ull}
 Not found. Not a size_t.
 
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.
 
char front () const noexcept
 First byte.
 
char back () const noexcept
 Last byte.
 

Helpers

String ToLower () const noexcept
 ASCII-letter lower case of this text.
 
String ToUpper () const noexcept
 ASCII-letter upper case of this text.
 
String SanitizeNewlines () const noexcept
 CR LF to LF on this text.
 
String RemoveWhitespace () const noexcept
 Drops isspace bytes from this text.
 
bool IsInteger () const noexcept
 Whether this text is an integer token.
 
STORMBYTE_FORCE_INLINE std::vector< String > Split () const noexcept
 Whitespace-separated tokens.
 
STORMBYTE_FORCE_INLINE std::queue< String > Explode (char delimiter) const noexcept
 Tokens on delimiter.
 
static String ToLower (std::string_view str) noexcept
 ASCII-letter lower case; UTF-8 otherwise copied.
 
static String ToUpper (std::string_view str) noexcept
 ASCII-letter upper case; UTF-8 otherwise copied.
 
static String SanitizeNewlines (std::string_view str) noexcept
 Turns CR LF into LF.
 
static String RemoveWhitespace (std::string_view str) noexcept
 Drops isspace bytes.
 
static bool IsInteger (std::string_view str) noexcept
 Optional sign plus ASCII digits.
 
static STORMBYTE_FORCE_INLINE void Split (std::string_view str, std::vector< String > &out) noexcept
 Whitespace-separated tokens.
 
static STORMBYTE_FORCE_INLINE void Explode (std::string_view str, char delimiter, std::queue< String > &out) noexcept
 Tokens on delimiter.
 

Detailed Description

Owned UTF-8 text composed of StormByte::CString.

UTF-8 counterpart of WString.

Not a std::string. Iterators are constant and contiguous so algorithms that read a range of char work. In-place mutating algorithms do not: helpers return a new String.

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 → 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 (starts_with, ends_with, contains, find, substr, …) follow std::string_view. They do not throw and they do not mutate. In-place edit is still a new String.

Defined in string.hxx.

Member Typedef Documentation

◆ const_iterator

Contiguous observer.

◆ const_reverse_iterator

Reverse observer.

◆ value_type

Byte type.

Constructor & Destructor Documentation

◆ String() [1/7]

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

Null text.

◆ String() [2/7]

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

Copies a C string.

Parameters
strSource; may be null.

◆ String() [3/7]

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

Copies a view into an owned NUL-terminated buffer.

Parameters
strSource.

◆ String() [4/7]

StormByte::String::String::String ( CString  text)
explicitnoexcept

Takes an owned buffer.

Parameters
textBuffer.

◆ String() [5/7]

StormByte::String::String::String ( const WString &  other)
explicitnoexcept

UTF-8 from wide text.

Parameters
otherWide source.

◆ String() [6/7]

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

Copy constructor.

Parameters
otherText to copy.

◆ String() [7/7]

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

Move constructor.

Parameters
otherText to take. other becomes null.

◆ ~String()

StormByte::String::String::~String ( )
defaultnoexcept

Releases the buffer.

Member Function Documentation

◆ back()

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

Last byte.

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

◆ begin()

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

First character, or null.

Returns
Iterator.

◆ Bytes()

const CString & StormByte::String::String::Bytes ( ) const
inlinenoexcept

Owned bytes.

Returns
Internal CString.

◆ cbegin()

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

First character, or null.

Returns
Iterator.

◆ cend()

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

One past the last character, or null.

Returns
Iterator.

◆ compare()

int StormByte::String::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::String::String::contains ( char  ch) const
inlinenoexcept

Whether ch occurs.

Parameters
chByte.
Returns
Match.

◆ contains() [2/2]

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

Whether text occurs.

Parameters
textNeedle.
Returns
Match. Empty needle matches.

◆ crbegin()

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

Reverse begin.

Returns
Reverse iterator.

◆ crend()

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

Reverse end.

Returns
Reverse iterator.

◆ data()

const char * StormByte::String::String::data ( ) const
inlinenoexcept

Contiguous pointer; null when the buffer is null.

Returns
Pointer to the first character.

◆ empty()

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

Whether size is zero.

Returns
Emptiness. A null buffer is empty.

◆ end()

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

One past the last character, or null.

Returns
Iterator.

◆ ends_with() [1/2]

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

Whether the text ends with ch.

Parameters
chSuffix byte.
Returns
Match.

◆ ends_with() [2/2]

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

Whether the text ends with text.

Parameters
textSuffix.
Returns
Match. Empty suffix matches.

◆ Explode() [1/2]

STORMBYTE_FORCE_INLINE std::queue< String > StormByte::String::String::Explode ( char  delimiter) const
inlinenoexcept

Tokens on delimiter.

The queue is built in the caller.

Parameters
delimiterSeparator.
Returns
Tokens, including empty ones.

◆ Explode() [2/2]

static STORMBYTE_FORCE_INLINE void StormByte::String::String::Explode ( std::string_view  str,
char  delimiter,
std::queue< String > &  out 
)
inlinestaticnoexcept

Tokens on delimiter.

out is the caller’s container.

Parameters
strSource.
delimiterSeparator.
[out]outTokens, including empty ones.
Note
STORMBYTE_FORCE_INLINE so the container nodes are allocated in the caller.

◆ find() [1/3]

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

First occurrence of ch at or after pos.

Parameters
chByte.
posStart, in code units.
Returns
Index, or npos.

◆ find() [2/3]

Size StormByte::String::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 code units.
countBytes of text to use.
Returns
Index, or npos.

◆ find() [3/3]

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

First occurrence of text at or after pos.

Parameters
textNeedle.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_not_of() [1/2]

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

First byte other than ch, at or after pos.

Parameters
chByte.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_not_of() [2/2]

Size StormByte::String::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 code units.
Returns
Index, or npos.

◆ find_first_of() [1/2]

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

First ch at or after pos.

Parameters
chByte.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_of() [2/2]

Size StormByte::String::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 code units.
Returns
Index, or npos.

◆ find_last_not_of() [1/2]

Size StormByte::String::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::String::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::String::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::String::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()

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

First byte.

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

◆ IsInteger() [1/2]

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

Whether this text is an integer token.

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

◆ IsInteger() [2/2]

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

Optional sign plus ASCII digits.

Parameters
strSource.
Returns
Whether str is an integer token.

◆ length()

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

Same as size.

Returns
Length as StormByte::Size.

◆ operator bool()

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

Whether a buffer is held.

Returns
false only for a null CString. "" is valid and empty.

◆ operator const char *()

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

View of the owned buffer.

Returns
Buffer, or null.
Note
Same lifetime as std::string::c_str().

◆ operator std::string()

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

Copy of the text in the caller’s heap.

Returns
Empty string when the buffer is null.

◆ operator std::string_view()

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

Non-owning view of the text.

Returns
Empty view when the buffer is null.
Note
Same lifetime as std::string::c_str().

◆ operator WString()

StormByte::String::String::operator WString ( ) const
explicitnoexcept

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

Returns
Owned WString.

◆ operator!=() [1/2]

bool StormByte::String::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::String::String::operator!= ( const String &  other) const
inlinenoexcept

Content inequality.

Parameters
otherOther text.
Returns
Whether the texts differ.

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

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

Content order against a C string.

Parameters
strMay be null.
Returns
Ordering.

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

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

Content order.

Null is less than any text.

Parameters
otherOther text.
Returns
Ordering.

◆ operator=() [1/2]

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

Copy assignment.

Parameters
otherText to copy.
Returns
*this.

◆ operator=() [2/2]

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

Move assignment.

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

◆ operator==() [1/2]

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

Content equality with a C string.

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

◆ operator==() [2/2]

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

Content equality.

Parameters
otherOther text.
Returns
Whether the texts are equal.

◆ operator[]()

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

Character at index.

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

◆ rbegin()

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

Reverse begin.

Returns
Reverse iterator.

◆ RemoveWhitespace() [1/2]

String StormByte::String::String::RemoveWhitespace ( ) const
inlinenoexcept

Drops isspace bytes from this text.

Returns
New text.

◆ RemoveWhitespace() [2/2]

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

Drops isspace bytes.

Parameters
strSource.
Returns
New text.

◆ rend()

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

Reverse end.

Returns
Reverse iterator.

◆ rfind() [1/3]

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

Last occurrence of ch at or before pos.

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

◆ rfind() [2/3]

Size StormByte::String::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 code units.
countBytes of text to use.
Returns
Index, or npos.

◆ rfind() [3/3]

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

Last occurrence of text at or before pos.

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

◆ SanitizeNewlines() [1/2]

String StormByte::String::String::SanitizeNewlines ( ) const
inlinenoexcept

CR LF to LF on this text.

Returns
New text.

◆ SanitizeNewlines() [2/2]

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

Turns CR LF into LF.

Parameters
strSource.
Returns
New text.

◆ size()

Size StormByte::String::String::size ( ) const
inlinenoexcept

Character count; 0 when null or empty.

Returns
Length as StormByte::Size (code units, not bytes).

◆ Split() [1/2]

STORMBYTE_FORCE_INLINE std::vector< String > StormByte::String::String::Split ( ) const
inlinenoexcept

Whitespace-separated tokens.

The vector is built in the caller.

Returns
Tokens.

◆ Split() [2/2]

static STORMBYTE_FORCE_INLINE void StormByte::String::String::Split ( std::string_view  str,
std::vector< String > &  out 
)
inlinestaticnoexcept

Whitespace-separated tokens.

out is the caller’s container.

Parameters
strSource.
[out]outTokens.
Note
STORMBYTE_FORCE_INLINE so the container nodes are allocated in the caller.

◆ starts_with() [1/2]

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

Whether the text begins with ch.

Parameters
chPrefix byte.
Returns
Match.

◆ starts_with() [2/2]

bool StormByte::String::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::String::String::substr ( Size  pos = {},
Size  count = npos 
) const
inlinenoexcept

Copy of a slice.

Not a view.

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

◆ swap()

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

Swaps buffers with other.

Parameters
otherOther text.

◆ ToLower() [1/2]

String StormByte::String::String::ToLower ( ) const
inlinenoexcept

ASCII-letter lower case of this text.

Returns
New text.

◆ ToLower() [2/2]

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

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

Parameters
strSource.
Returns
New text.

◆ ToUpper() [1/2]

String StormByte::String::String::ToUpper ( ) const
inlinenoexcept

ASCII-letter upper case of this text.

Returns
New text.

◆ ToUpper() [2/2]

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

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

Parameters
strSource.
Returns
New text.

Member Data Documentation

◆ npos

constexpr Size StormByte::String::String::npos {~0ull}
staticconstexpr

Not found. Not a size_t.


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