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

Wide counterpart of String. More...

#include <StormByte/string/wstring.hxx>

Collaboration diagram for StormByte::String::WString:

Public Types

using value_type = wchar_t
 Code unit type.
 
using const_iterator = const wchar_t *
 Contiguous observer.
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 Reverse observer.
 

Public Member Functions

void swap (WString &other) noexcept
 Swaps buffers with other.
 
Life
 WString () noexcept
 Null text.
 
 WString (const wchar_t *str) noexcept
 Copies a wide C string.
 
 WString (std::wstring_view str) noexcept
 Copies a view into an owned NUL-terminated buffer.
 
 WString (WCString text) noexcept
 Takes an owned buffer.
 
 WString (const String &other) noexcept
 Wide text from UTF-8.
 
 WString (const WString &other) noexcept
 Copy constructor.
 
 WString (WString &&other) noexcept
 Move constructor.
 
 ~WString () noexcept=default
 Releases the buffer.
 
WString & operator= (const WString &other) noexcept
 Copy assignment.
 
WString & operator= (WString &&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 wchar_t * data () const noexcept
 Contiguous pointer; null when the buffer is null.
 
Size size () const noexcept
 Code-unit count; 0 when null or empty.
 
Size length () const noexcept
 Same as size.
 
bool empty () const noexcept
 Whether size is zero.
 
wchar_t operator[] (const Size &index) const noexcept
 Code unit at index.
 
 operator bool () const noexcept
 Whether a buffer is held.
 
Conversions
 operator std::wstring_view () const noexcept
 Non-owning view of the text.
 
STORMBYTE_FORCE_INLINE operator std::wstring () const
 Copy of the text in the caller’s heap.
 
 operator const wchar_t * () const noexcept
 View of the owned buffer.
 
 operator String () const noexcept
 UTF-8 text (wide encoded in the module).
 
const WCString & Bytes () const noexcept
 Owned code units.
 
Comparison
bool operator== (const WString &other) const noexcept
 Content equality.
 
bool operator!= (const WString &other) const noexcept
 Content inequality.
 
bool operator== (const wchar_t *str) const noexcept
 Content equality with a wide C string.
 
bool operator!= (const wchar_t *str) const noexcept
 Content inequality with a wide C string.
 
std::strong_ordering operator<=> (const WString &other) const noexcept
 Content order.
 
std::strong_ordering operator<=> (const wchar_t *str) const noexcept
 Content order against a wide C string.
 

Lookup

static constexpr Size npos {~0ull}
 Not found. Not a size_t.
 
bool starts_with (std::wstring_view text) const noexcept
 Whether the text begins with text.
 
bool starts_with (wchar_t ch) const noexcept
 Whether the text begins with ch.
 
bool ends_with (std::wstring_view text) const noexcept
 Whether the text ends with text.
 
bool ends_with (wchar_t ch) const noexcept
 Whether the text ends with ch.
 
bool contains (std::wstring_view text) const noexcept
 Whether text occurs.
 
bool contains (wchar_t ch) const noexcept
 Whether ch occurs.
 
Size find (std::wstring_view text, Size pos={}) const noexcept
 First occurrence of text at or after pos.
 
Size find (wchar_t ch, Size pos={}) const noexcept
 First occurrence of ch at or after pos.
 
Size find (const wchar_t *text, Size pos, Size count) const noexcept
 First occurrence of count units of text.
 
Size rfind (std::wstring_view text, Size pos=npos) const noexcept
 Last occurrence of text at or before pos.
 
Size rfind (wchar_t ch, Size pos=npos) const noexcept
 Last occurrence of ch at or before pos.
 
Size rfind (const wchar_t *text, Size pos, Size count) const noexcept
 Last occurrence of count units of text.
 
Size find_first_of (std::wstring_view text, Size pos={}) const noexcept
 First unit that is in text, at or after pos.
 
Size find_first_of (wchar_t ch, Size pos={}) const noexcept
 First ch at or after pos.
 
Size find_last_of (std::wstring_view text, Size pos=npos) const noexcept
 Last unit that is in text, at or before pos.
 
Size find_last_of (wchar_t ch, Size pos=npos) const noexcept
 Last ch at or before pos.
 
Size find_first_not_of (std::wstring_view text, Size pos={}) const noexcept
 First unit that is not in text, at or after pos.
 
Size find_first_not_of (wchar_t ch, Size pos={}) const noexcept
 First unit other than ch, at or after pos.
 
Size find_last_not_of (std::wstring_view text, Size pos=npos) const noexcept
 Last unit that is not in text, at or before pos.
 
Size find_last_not_of (wchar_t ch, Size pos=npos) const noexcept
 Last unit other than ch, at or before pos.
 
WString substr (Size pos={}, Size count=npos) const noexcept
 Copy of a slice.
 
int compare (std::wstring_view text) const noexcept
 Same order as std::wstring_view::compare.
 
wchar_t front () const noexcept
 First code unit.
 
wchar_t back () const noexcept
 Last code unit.
 

Helpers

WString ToLower () const noexcept
 ASCII-letter lower case of this text.
 
WString ToUpper () const noexcept
 ASCII-letter upper case of this text.
 
WString SanitizeNewlines () const noexcept
 CR LF to LF on this text.
 
WString RemoveWhitespace () const noexcept
 Drops iswspace code units from this text.
 
bool IsInteger () const noexcept
 Whether this text is an integer token.
 
STORMBYTE_FORCE_INLINE std::vector< WString > Split () const noexcept
 Whitespace-separated tokens.
 
STORMBYTE_FORCE_INLINE std::queue< WString > Explode (wchar_t delimiter) const noexcept
 Tokens on delimiter.
 
static WString ToLower (std::wstring_view str) noexcept
 ASCII-letter lower case; other code points copied.
 
static WString ToUpper (std::wstring_view str) noexcept
 ASCII-letter upper case; other code points copied.
 
static WString SanitizeNewlines (std::wstring_view str) noexcept
 Turns CR LF into LF.
 
static WString RemoveWhitespace (std::wstring_view str) noexcept
 Drops iswspace code units.
 
static bool IsInteger (std::wstring_view str) noexcept
 Optional sign plus ASCII digits.
 
static STORMBYTE_FORCE_INLINE void Split (std::wstring_view str, std::vector< WString > &out) noexcept
 Whitespace-separated tokens.
 
static STORMBYTE_FORCE_INLINE void Explode (std::wstring_view str, wchar_t delimiter, std::queue< WString > &out) noexcept
 Tokens on delimiter.
 

Detailed Description

Wide counterpart of String.

Owned wide text composed of StormByte::WCString.

Defined in wstring.hxx.

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

operator std::wstring_view is implicit and inline. operator std::wstring is explicit and STORMBYTE_FORCE_INLINE (caller heap).

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

ToUpper / ToLower map only ASCII A–Z / a–z (as wchar_t). Other code points are copied. On 16-bit wchar_t, a well-formed surrogate pair is copied together.

Observers (starts_with, ends_with, contains, find, substr, …) follow std::wstring_view. They do not throw and they do not mutate. In-place edit is still a new WString.

Member Typedef Documentation

◆ const_iterator

Contiguous observer.

◆ const_reverse_iterator

Reverse observer.

◆ value_type

Code unit type.

Constructor & Destructor Documentation

◆ WString() [1/7]

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

Null text.

◆ WString() [2/7]

StormByte::String::WString::WString ( const wchar_t *  str)
explicitnoexcept

Copies a wide C string.

Parameters
strSource; may be null.

◆ WString() [3/7]

StormByte::String::WString::WString ( std::wstring_view  str)
explicitnoexcept

Copies a view into an owned NUL-terminated buffer.

Parameters
strSource.

◆ WString() [4/7]

StormByte::String::WString::WString ( WCString  text)
explicitnoexcept

Takes an owned buffer.

Parameters
textBuffer.

◆ WString() [5/7]

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

Wide text from UTF-8.

Parameters
otherUTF-8 source.

◆ WString() [6/7]

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

Copy constructor.

Parameters
otherText to copy.

◆ WString() [7/7]

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

Move constructor.

Parameters
otherText to take. other becomes null.

◆ ~WString()

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

Releases the buffer.

Member Function Documentation

◆ back()

wchar_t StormByte::String::WString::back ( ) const
inlinenoexcept

Last code unit.

Returns
Unit.
Note
Empty is undefined, same as std::wstring::back.

◆ begin()

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

First character, or null.

Returns
Iterator.

◆ Bytes()

const WCString & StormByte::String::WString::Bytes ( ) const
inlinenoexcept

Owned code units.

Returns
Internal WCString.

◆ cbegin()

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

First character, or null.

Returns
Iterator.

◆ cend()

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

One past the last character, or null.

Returns
Iterator.

◆ compare()

int StormByte::String::WString::compare ( std::wstring_view  text) const
inlinenoexcept

Same order as std::wstring_view::compare.

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

◆ contains() [1/2]

bool StormByte::String::WString::contains ( std::wstring_view  text) const
inlinenoexcept

Whether text occurs.

Parameters
textNeedle.
Returns
Match. Empty needle matches.

◆ contains() [2/2]

bool StormByte::String::WString::contains ( wchar_t  ch) const
inlinenoexcept

Whether ch occurs.

Parameters
chCode unit.
Returns
Match.

◆ crbegin()

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

Reverse begin.

Returns
Reverse iterator.

◆ crend()

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

Reverse end.

Returns
Reverse iterator.

◆ data()

const wchar_t * StormByte::String::WString::data ( ) const
inlinenoexcept

Contiguous pointer; null when the buffer is null.

Returns
Pointer to the first code unit.

◆ empty()

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

Whether size is zero.

Returns
Emptiness. A null buffer is empty.

◆ end()

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

One past the last character, or null.

Returns
Iterator.

◆ ends_with() [1/2]

bool StormByte::String::WString::ends_with ( std::wstring_view  text) const
inlinenoexcept

Whether the text ends with text.

Parameters
textSuffix.
Returns
Match. Empty suffix matches.

◆ ends_with() [2/2]

bool StormByte::String::WString::ends_with ( wchar_t  ch) const
inlinenoexcept

Whether the text ends with ch.

Parameters
chSuffix code unit.
Returns
Match.

◆ Explode() [1/2]

static STORMBYTE_FORCE_INLINE void StormByte::String::WString::Explode ( std::wstring_view  str,
wchar_t  delimiter,
std::queue< WString > &  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.

◆ Explode() [2/2]

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

Tokens on delimiter.

The queue is built in the caller.

Parameters
delimiterSeparator.
Returns
Tokens, including empty ones.

◆ find() [1/3]

Size StormByte::String::WString::find ( const wchar_t *  text,
Size  pos,
Size  count 
) const
inlinenoexcept

First occurrence of count units of text.

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

◆ find() [2/3]

Size StormByte::String::WString::find ( std::wstring_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() [3/3]

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

First occurrence of ch at or after pos.

Parameters
chCode unit.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_not_of() [1/2]

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

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

Parameters
textSet of code units.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_not_of() [2/2]

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

First unit other than ch, at or after pos.

Parameters
chCode unit.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_of() [1/2]

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

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

Parameters
textSet of code units.
posStart, in code units.
Returns
Index, or npos.

◆ find_first_of() [2/2]

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

First ch at or after pos.

Parameters
chCode unit.
posStart, in code units.
Returns
Index, or npos.

◆ find_last_not_of() [1/2]

Size StormByte::String::WString::find_last_not_of ( std::wstring_view  text,
Size  pos = npos 
) const
inlinenoexcept

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

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

◆ find_last_not_of() [2/2]

Size StormByte::String::WString::find_last_not_of ( wchar_t  ch,
Size  pos = npos 
) const
inlinenoexcept

Last unit other than ch, at or before pos.

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

◆ find_last_of() [1/2]

Size StormByte::String::WString::find_last_of ( std::wstring_view  text,
Size  pos = npos 
) const
inlinenoexcept

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

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

◆ find_last_of() [2/2]

Size StormByte::String::WString::find_last_of ( wchar_t  ch,
Size  pos = npos 
) const
inlinenoexcept

Last ch at or before pos.

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

◆ front()

wchar_t StormByte::String::WString::front ( ) const
inlinenoexcept

First code unit.

Returns
Unit.
Note
Empty is undefined, same as std::wstring::front.

◆ IsInteger() [1/2]

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

Whether this text is an integer token.

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

◆ IsInteger() [2/2]

static bool StormByte::String::WString::IsInteger ( std::wstring_view  str)
staticnoexcept

Optional sign plus ASCII digits.

Parameters
strSource.
Returns
Whether str is an integer token.

◆ length()

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

Same as size.

Returns
Length as StormByte::Size.

◆ operator bool()

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

Whether a buffer is held.

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

◆ operator const wchar_t *()

StormByte::String::WString::operator const wchar_t * ( ) const
inlineexplicitnoexcept

View of the owned buffer.

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

◆ operator std::wstring()

STORMBYTE_FORCE_INLINE StormByte::String::WString::operator std::wstring ( ) const
inlineexplicit

Copy of the text in the caller’s heap.

Returns
Empty string when the buffer is null.

◆ operator std::wstring_view()

StormByte::String::WString::operator std::wstring_view ( ) const
inlinenoexcept

Non-owning view of the text.

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

◆ operator String()

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

UTF-8 text (wide encoded in the module).

Returns
Owned String.

◆ operator!=() [1/2]

bool StormByte::String::WString::operator!= ( const wchar_t *  str) const
inlinenoexcept

Content inequality with a wide C string.

Parameters
strMay be null.
Returns
Whether the texts differ.

◆ operator!=() [2/2]

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

Content inequality.

Parameters
otherOther text.
Returns
Whether the texts differ.

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

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

Content order against a wide C string.

Parameters
strMay be null.
Returns
Ordering.

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

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

Content order.

Null is less than any text.

Parameters
otherOther text.
Returns
Ordering.

◆ operator=() [1/2]

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

Copy assignment.

Parameters
otherText to copy.
Returns
*this.

◆ operator=() [2/2]

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

Move assignment.

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

◆ operator==() [1/2]

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

Content equality with a wide C string.

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

◆ operator==() [2/2]

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

Content equality.

Parameters
otherOther text.
Returns
Whether the texts are equal.

◆ operator[]()

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

Code unit 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::WString::rbegin ( ) const
inlinenoexcept

Reverse begin.

Returns
Reverse iterator.

◆ RemoveWhitespace() [1/2]

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

Drops iswspace code units from this text.

Returns
New text.

◆ RemoveWhitespace() [2/2]

static WString StormByte::String::WString::RemoveWhitespace ( std::wstring_view  str)
staticnoexcept

Drops iswspace code units.

Parameters
strSource.
Returns
New text.

◆ rend()

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

Reverse end.

Returns
Reverse iterator.

◆ rfind() [1/3]

Size StormByte::String::WString::rfind ( const wchar_t *  text,
Size  pos,
Size  count 
) const
inlinenoexcept

Last occurrence of count units of text.

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

◆ rfind() [2/3]

Size StormByte::String::WString::rfind ( std::wstring_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.

◆ rfind() [3/3]

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

Last occurrence of ch at or before pos.

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

◆ SanitizeNewlines() [1/2]

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

CR LF to LF on this text.

Returns
New text.

◆ SanitizeNewlines() [2/2]

static WString StormByte::String::WString::SanitizeNewlines ( std::wstring_view  str)
staticnoexcept

Turns CR LF into LF.

Parameters
strSource.
Returns
New text.

◆ size()

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

Code-unit count; 0 when null or empty.

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

◆ Split() [1/2]

STORMBYTE_FORCE_INLINE std::vector< WString > StormByte::String::WString::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::WString::Split ( std::wstring_view  str,
std::vector< WString > &  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::WString::starts_with ( std::wstring_view  text) const
inlinenoexcept

Whether the text begins with text.

Parameters
textPrefix.
Returns
Match. Empty prefix matches.

◆ starts_with() [2/2]

bool StormByte::String::WString::starts_with ( wchar_t  ch) const
inlinenoexcept

Whether the text begins with ch.

Parameters
chPrefix code unit.
Returns
Match.

◆ substr()

WString StormByte::String::WString::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::WString::swap ( WString &  other)
noexcept

Swaps buffers with other.

Parameters
otherOther text.

◆ ToLower() [1/2]

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

ASCII-letter lower case of this text.

Returns
New text.

◆ ToLower() [2/2]

static WString StormByte::String::WString::ToLower ( std::wstring_view  str)
staticnoexcept

ASCII-letter lower case; other code points copied.

Parameters
strSource.
Returns
New text.

◆ ToUpper() [1/2]

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

ASCII-letter upper case of this text.

Returns
New text.

◆ ToUpper() [2/2]

static WString StormByte::String::WString::ToUpper ( std::wstring_view  str)
staticnoexcept

ASCII-letter upper case; other code points copied.

Parameters
strSource.
Returns
New text.

Member Data Documentation

◆ npos

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

Not found. Not a size_t.


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