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

Wide counterpart of String. More...

#include <StormByte/safe/wstring.hxx>

Collaboration diagram for StormByte::Safe::WString:

Public Types

using value_type = wchar_t
 Code unit type.
using size_type = Size
 Unit count and position type.
using difference_type = std::ptrdiff_t
 Iterator distance type.
using pointer = wchar_t*
 Mutable buffer pointer.
using const_pointer = const wchar_t*
 Read-only buffer pointer.
using reference = wchar_t&
 Mutable unit reference.
using const_reference = const wchar_t&
 Read-only unit reference.
using iterator = wchar_t*
 Mutable contiguous iterator.
using const_iterator = const wchar_t*
 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 (WString &other) noexcept
 Swaps storage with other.
Life
 WString () noexcept
 Empty text.
 WString (const wchar_t *str)
 Copies a wide C string.
 WString (std::wstring_view str)
 Copies a view into owned storage.
 WString (size_type count, wchar_t character)
 Construct count copies of character.
 WString (const WString &other, size_type pos, size_type count=npos)
 Copy a slice of other.
template<std::input_iterator InputIt>
 WString (InputIt first, InputIt last)
 Copy the unit range [first, last).
 WString (const String &other)
 Wide text from UTF-8, including an empty source.
 WString (const WString &other)
 Copy constructor.
 WString (WString &&other) noexcept
 Move constructor.
 ~WString () noexcept
 Releases a long buffer.
WString & operator= (const WString &other)
 Copy assignment.
WString & operator= (WString &&other) noexcept
 Move assignment.
WString & operator= (std::wstring_view text)
 Copy text from a caller-owned view.
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
 UTF-8 text decoded in the module.
const wchar_t * Bytes () const noexcept
 Non-owning view of the owned 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.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const WString &other) const noexcept
 Content order.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const wchar_t *str) const noexcept
 Content order against a wide C string.

Static Public Attributes

static constexpr std::size_t SSO_CAPACITY = 11
 Short capacity, excluding the trailing NUL.

Lookup

static constexpr size_type npos {~0ull}
 Not found.
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.
int compare (size_type pos, size_type count, std::wstring_view text) const noexcept
 Compare a slice with text.
wchar_t & front () noexcept
 First unit.
wchar_t front () const noexcept
 Read the first unit.
wchar_t & back () noexcept
 Last unit.
wchar_t back () const noexcept
 Read the last unit.

Range

iterator begin () noexcept
 First unit.
const_iterator begin () const noexcept
 First unit.
iterator end () noexcept
 One past the last unit.
const_iterator end () const noexcept
 One past the last unit.
const_iterator cbegin () const noexcept
 First unit.
const_iterator cend () const noexcept
 One past the last unit.
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.
wchar_t * data () noexcept
 Contiguous pointer to the first unit, or to the trailing NUL when empty.
const wchar_t * data () const noexcept
 Read-only contiguous pointer to the first unit, or to the trailing NUL when empty.
const wchar_t * c_str () const noexcept
 Same pointer as data.
Size size () const noexcept
 Unit count, excluding the trailing NUL.
Size capacity () const noexcept
 Allocated unit capacity, excluding the trailing NUL.
Size max_size () const noexcept
 Largest representable unit count.
Size length () const noexcept
 Same as Size.
bool empty () const noexcept
 Whether Size is zero.
WString & append (std::wstring_view text)
 Append wide code units.
WString & append (size_type count, wchar_t character)
 Append count copies of a wide code unit.
template<std::input_iterator InputIt>
WString & append (InputIt first, InputIt last)
 Append the unit range [first, last).
template<std::ranges::input_range R>
WString & append_range (R &&range)
 Append a copy of range.
WString & assign (std::wstring_view text)
 Replace the contents with a wide text view.
WString & assign (size_type count, wchar_t character)
 Replace the contents with count copies of a wide code unit.
template<std::input_iterator InputIt>
WString & assign (InputIt first, InputIt last)
 Replace the contents with [first, last).
template<std::ranges::input_range R>
WString & assign_range (R &&range)
 Replace the contents with a copy of range.
WString & operator+= (std::wstring_view text)
 Append a wide view.
WString & operator+= (wchar_t character)
 Append one wide code unit.
void push_back (wchar_t character)
 Append one wide code unit.
void pop_back ()
 Remove the final code unit.
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 code units.
void shrink_to_fit ()
 Drop unused long-path capacity.
void resize (size_type count, wchar_t character=wchar_t{})
 Resize the unit sequence, filling new units with character.
WString & insert (size_type position, std::wstring_view text)
 Insert wide code units at a code-unit position.
WString & insert (size_type position, size_type count, wchar_t 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< wchar_t > 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.
WString & erase (size_type position={}, size_type count=npos)
 Erase wide code units starting at position.
iterator erase (const_iterator pos)
 Erase the unit at pos.
iterator erase (const_iterator first, const_iterator last)
 Erase [first, last).
WString & replace (size_type position, size_type count, std::wstring_view text)
 Replace a wide code-unit range with text.
WString & replace (const_iterator first, const_iterator last, std::wstring_view text)
 Replace [first, last) with text.
wchar_t & operator[] (const Size &index) noexcept
 Code unit at index.
wchar_t operator[] (const Size &index) const noexcept
 Read-only code unit at index.
wchar_t & at (size_type index)
 Unit at index.
const wchar_t & at (size_type index) const
 Read-only unit at index.
size_type copy (wchar_t *dest, size_type count, size_type pos={}) const
 Copy at most count units into dest, starting at pos.
 operator bool () const noexcept
 Whether the text is non-empty.
template<class... Args>
requires (sizeof...(Args) >= 1)
static WString ReplaceToken (std::wstring_view text, Args &&... args)
 Copy text with each field replaced, in order, by one argument.

Helpers

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

Detailed Description

Wide counterpart of String.

Owned wide text.

Defined in wstring.hxx.

Not a std::wstring. Short text lives in the object, NUL-terminated, with an explicit size. Longer text is a wide 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 units; they cannot change the owned size. 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. Conversion from String copies UTF-8 into wide units in the module.

Observers follow std::wstring_view. Size-changing modifiers follow std::wstring value semantics. capacity() and reserve(Size) count code units 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 unit reference.

◆ const_reverse_iterator

Reverse observer.

◆ difference_type

Iterator distance type.

◆ iterator

Mutable contiguous iterator.

◆ pointer

Mutable buffer pointer.

◆ reference

Mutable unit reference.

◆ reverse_iterator

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

Mutable reverse observer.

◆ size_type

Unit count and position type.

◆ value_type

Code unit type.

Constructor & Destructor Documentation

◆ WString() [1/9]

StormByte::Safe::WString::WString ( )
noexcept

Empty text.

Not null.

◆ WString() [2/9]

StormByte::Safe::WString::WString ( const wchar_t * str)

Copies a wide C string.

A null pointer becomes empty.

Parameters
strSource; may be null.

◆ WString() [3/9]

StormByte::Safe::WString::WString ( std::wstring_view str)

Copies a view into owned storage.

Parameters
strSource. Embedded NUL counts.

◆ WString() [4/9]

StormByte::Safe::WString::WString ( size_type count,
wchar_t character )

Construct count copies of character.

Parameters
countUnit count.
characterFill unit.
Exceptions
AllocationErrorThe long path could not be allocated.

◆ WString() [5/9]

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

Copy a slice of other.

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

◆ WString() [6/9]

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

Copy the unit range [first, last).

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

◆ WString() [7/9]

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

Wide text from UTF-8, including an empty source.

Parameters
otherUTF-8 source.

◆ WString() [8/9]

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

Copy constructor.

Parameters
otherText to copy.

◆ WString() [9/9]

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

Move constructor.

Parameters
otherText to take. other becomes empty.

◆ ~WString()

StormByte::Safe::WString::~WString ( )
noexcept

Releases a long buffer.

A short string has nothing to free.

Member Function Documentation

◆ append() [1/3]

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

Append the unit range [first, last).

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

◆ append() [2/3]

WString & StormByte::Safe::WString::append ( size_type count,
wchar_t character )

Append count copies of a wide code unit.

Parameters
countNumber of copies.
characterCode unit to append.
Returns
This string.

◆ append() [3/3]

WString & StormByte::Safe::WString::append ( std::wstring_view text)

Append wide code units.

Parameters
textText to append.
Returns
This string.

◆ append_range()

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

Append a copy of range.

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

◆ assign() [1/3]

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

Replace the contents with [first, last).

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

◆ assign() [2/3]

WString & StormByte::Safe::WString::assign ( size_type count,
wchar_t character )

Replace the contents with count copies of a wide code unit.

Parameters
countNumber of copies.
characterCode unit to assign.
Returns
This string.

◆ assign() [3/3]

WString & StormByte::Safe::WString::assign ( std::wstring_view text)

Replace the contents with a wide text view.

Parameters
textSource code units.
Returns
This string.

◆ assign_range()

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

Replace the contents with a copy of range.

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

◆ at() [1/2]

wchar_t & StormByte::Safe::WString::at ( size_type index)

Unit at index.

Parameters
indexUnit offset.
Returns
Unit.
Exceptions
OutOfBoundsErrorindex is not less than Size.

◆ at() [2/2]

const wchar_t & StormByte::Safe::WString::at ( size_type index) const

Read-only unit at index.

Parameters
indexUnit offset.
Returns
Unit.
Exceptions
OutOfBoundsErrorindex is not less than Size.

◆ back() [1/2]

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

Read the last unit.

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

◆ back() [2/2]

wchar_t & StormByte::Safe::WString::back ( )
inlinenoexcept

Last unit.

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

◆ begin() [1/2]

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

First unit.

Returns
Read-only iterator. Never null.

◆ begin() [2/2]

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

First unit.

Returns
Iterator. Never null.

◆ Bytes()

const wchar_t * StormByte::Safe::WString::Bytes ( ) const
inlinenoexcept

Non-owning view of the owned units.

Returns
data(). Never null.

◆ c_str()

const wchar_t * StormByte::Safe::WString::c_str ( ) const
inlinenoexcept

Same pointer as data.

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

Returns
Never null.

◆ capacity()

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

Allocated unit capacity, excluding the trailing NUL.

Returns
Short capacity, or the long-buffer capacity.

◆ cbegin()

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

First unit.

Returns
Iterator.

◆ cend()

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

One past the last unit.

Returns
Iterator.

◆ clear()

void StormByte::Safe::WString::clear ( )

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

◆ compare() [1/2]

int StormByte::Safe::WString::compare ( size_type pos,
size_type count,
std::wstring_view text ) const
inlinenoexcept

Compare a slice with text.

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

◆ compare() [2/2]

int StormByte::Safe::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::Safe::WString::contains ( std::wstring_view text) const
inlinenoexcept

Whether text occurs.

Parameters
textNeedle.
Returns
Match. Empty needle matches.

◆ contains() [2/2]

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

Whether ch occurs.

Parameters
chUnit.
Returns
Match.

◆ copy()

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

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

Parameters
destCaller buffer.
countBuffer capacity, in units.
posStart, in code units.
Returns
Units copied.
Exceptions
OutOfBoundsErrorpos is past Size.

◆ crbegin()

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

Reverse begin.

Returns
Reverse iterator.

◆ crend()

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

Reverse end.

Returns
Reverse iterator.

◆ data() [1/2]

const wchar_t * StormByte::Safe::WString::data ( ) const
noexcept

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

Returns
Never null.

◆ data() [2/2]

wchar_t * StormByte::Safe::WString::data ( )
noexcept

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

Returns
Never null.

◆ empty()

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

Whether Size is zero.

Returns
Emptiness. An empty string still has a pointer.

◆ end() [1/2]

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

One past the last unit.

Returns
Read-only iterator. Never null.

◆ end() [2/2]

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

One past the last unit.

Returns
Iterator. Never null.

◆ ends_with() [1/2]

bool StormByte::Safe::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::Safe::WString::ends_with ( wchar_t ch) const
inlinenoexcept

Whether the text ends with ch.

Parameters
chSuffix unit.
Returns
Match.

◆ erase() [1/3]

iterator StormByte::Safe::WString::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::WString::erase ( const_iterator pos)

Erase the unit at pos.

Parameters
posUnit to erase.
Returns
Iterator following the erased unit.
Exceptions
OutOfBoundsErrorpos is outside this string.

◆ erase() [3/3]

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

Erase wide code units starting at position.

Parameters
positionFirst code unit to erase.
countMaximum code units to erase.
Returns
This string.

◆ Explode() [1/2]

Queue< WString > StormByte::Safe::WString::Explode ( std::wstring_view str,
wchar_t delimiter )
static

Tokens on delimiter, including empty ones.

Nodes are allocated in Base.

Parameters
strSource.
delimiterSeparator.
Returns
Owned tokens.

◆ Explode() [2/2]

Queue< WString > StormByte::Safe::WString::Explode ( wchar_t delimiter) const

Tokens of this text on delimiter, including empty ones.

Parameters
delimiterSeparator.
Returns
Owned tokens.

◆ find() [1/3]

Size StormByte::Safe::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::Safe::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::Safe::WString::find ( wchar_t ch,
Size pos = {} ) const
inlinenoexcept

First occurrence of ch at or after pos.

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

◆ find_first_not_of() [1/2]

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

◆ find_first_not_of() [2/2]

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

First unit other than ch, at or after pos.

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

◆ find_first_of() [1/2]

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

◆ find_first_of() [2/2]

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

First ch at or after pos.

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

◆ find_last_not_of() [1/2]

Size StormByte::Safe::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 units.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ find_last_not_of() [2/2]

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

Last unit other than ch, at or before pos.

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

◆ find_last_of() [1/2]

Size StormByte::Safe::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 units.
posHighest index. Default is the end.
Returns
Index, or npos.

◆ find_last_of() [2/2]

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

Last ch at or before pos.

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

◆ front() [1/2]

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

Read the first unit.

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

◆ front() [2/2]

wchar_t & StormByte::Safe::WString::front ( )
inlinenoexcept

First unit.

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

◆ Implode() [1/2]

WString StormByte::Safe::WString::Implode ( const Queue< WString > & parts,
std::wstring_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]

WString StormByte::Safe::WString::Implode ( const Vector< WString > & parts,
std::wstring_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::WString::insert ( const_iterator pos,
InputIt first,
InputIt last )
inline

Insert [first, last) before pos.

Template Parameters
InputItInput iterator of wide units.
Parameters
posInsertion point.
firstStart.
lastEnd.
Returns
Iterator to the first inserted unit, 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::WString::insert ( const_iterator pos,
std::initializer_list< wchar_t > values )

Insert an initializer list before pos.

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

◆ insert() [3/4]

WString & StormByte::Safe::WString::insert ( size_type position,
size_type count,
wchar_t character )

Insert count copies of character at position.

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

◆ insert() [4/4]

WString & StormByte::Safe::WString::insert ( size_type position,
std::wstring_view text )

Insert wide code units at a code-unit position.

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

◆ insert_range()

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

Insert a copy of range before pos.

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

◆ IsInteger() [1/2]

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

Whether this text is an integer token.

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

◆ IsInteger() [2/2]

bool StormByte::Safe::WString::IsInteger ( std::wstring_view str)
staticnoexcept

Optional sign plus ASCII digits.

Parameters
strSource.
Returns
Whether str is an integer token.

◆ length()

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

Same as Size.

Returns
Length as StormByte::Size.

◆ max_size()

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

Largest representable unit count.

Returns
Maximum size.

◆ operator bool()

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

Whether the text is non-empty.

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

◆ operator const wchar_t *()

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

View of the owned buffer.

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

◆ operator std::wstring()

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

Copy of the text in the caller’s heap.

Returns
Caller-owned std::wstring.

◆ operator std::wstring_view()

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

Non-owning view of the text.

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

◆ operator String()

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

UTF-8 text decoded in the module.

Returns
Owned String.

◆ operator!=() [1/2]

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

Content inequality.

Parameters
otherOther text.
Returns
Whether the texts differ.

◆ operator+=() [1/2]

WString & StormByte::Safe::WString::operator+= ( std::wstring_view text)

Append a wide view.

A WString converts to this view.

Parameters
textText to append.
Returns
This string.

◆ operator+=() [2/2]

WString & StormByte::Safe::WString::operator+= ( wchar_t character)

Append one wide code unit.

Parameters
characterCode unit.
Returns
This string.

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

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

Content order against a wide 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::WString::operator<=> ( const WString & other) const
inlinenoexcept

Content order.

Parameters
otherOther text.
Returns
Ordering.

◆ operator=() [1/3]

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

Copy assignment.

Parameters
otherText to copy.
Returns
*this.

◆ operator=() [2/3]

WString & StormByte::Safe::WString::operator= ( std::wstring_view text)

Copy text from a caller-owned view.

Parameters
textSource units.
Returns
This string.

◆ operator=() [3/3]

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

Move assignment.

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

◆ operator==() [1/2]

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

Content equality with a wide 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::WString::operator== ( const WString & other) const
inlinenoexcept

Content equality.

Parameters
otherOther text.
Returns
Whether the texts are equal.

◆ operator[]() [1/2]

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

Read-only code unit at index.

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

◆ operator[]() [2/2]

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

Code unit at index.

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

◆ pop_back()

void StormByte::Safe::WString::pop_back ( )

Remove the final code unit.

Empty use follows std::wstring preconditions.

◆ push_back()

void StormByte::Safe::WString::push_back ( wchar_t character)

Append one wide code unit.

Parameters
characterCode unit.

◆ rbegin() [1/2]

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

Reverse begin.

Returns
Read-only reverse iterator.

◆ rbegin() [2/2]

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

Reverse begin.

Returns
Reverse iterator.

◆ RemoveWhitespace() [1/2]

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

Drops wide space units from this text.

Returns
New text.

◆ RemoveWhitespace() [2/2]

WString StormByte::Safe::WString::RemoveWhitespace ( std::wstring_view str)
static

Drops wide space units.

Parameters
strSource.
Returns
New text.

◆ rend() [1/2]

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

Reverse end.

Returns
Read-only reverse iterator.

◆ rend() [2/2]

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

Reverse end.

Returns
Reverse iterator.

◆ replace() [1/2]

WString & StormByte::Safe::WString::replace ( const_iterator first,
const_iterator last,
std::wstring_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]

WString & StormByte::Safe::WString::replace ( size_type position,
size_type count,
std::wstring_view text )

Replace a wide code-unit range with text.

Parameters
positionFirst code unit to replace.
countMaximum code units to erase.
textReplacement text.
Returns
This string.

◆ ReplaceToken()

template<class... Args>
requires (sizeof...(Args) >= 1)
WString StormByte::Safe::WString::ReplaceToken ( std::wstring_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::wstring or WString. A view is not copied. A bool is true or false. A wchar_t* 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 wide text conversion for {} and their integer count for a numeric field. A number with a bare {} uses std::to_wstring. 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::WString::reserve ( size_type new_capacity)

Reserve storage for at least new_capacity code units.

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

◆ resize()

void StormByte::Safe::WString::resize ( size_type count,
wchar_t character = wchar_t{} )

Resize the unit sequence, filling new units with character.

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

◆ rfind() [1/3]

Size StormByte::Safe::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.
countUnits of text to use.
Returns
Index, or npos.

◆ rfind() [2/3]

Size StormByte::Safe::WString::rfind ( std::wstring_view text,
Size pos = npos ) const
inlinenoexcept

Last occurrence of text at or before pos.

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

◆ rfind() [3/3]

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

Last occurrence of ch at or before pos.

Parameters
chUnit.
posHighest start. Default is the end.
Returns
Index, or npos.

◆ SanitizeNewlines() [1/2]

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

CR LF to LF on this text.

Returns
New text.

◆ SanitizeNewlines() [2/2]

WString StormByte::Safe::WString::SanitizeNewlines ( std::wstring_view str)
static

Turns CR LF into LF.

Parameters
strSource.
Returns
New text.

◆ shrink_to_fit()

void StormByte::Safe::WString::shrink_to_fit ( )

Drop unused long-path capacity.

A short string is unchanged.

◆ size()

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

Unit count, excluding the trailing NUL.

Returns
Length as StormByte::Size.

◆ Split() [1/3]

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

Whitespace-separated tokens of this text.

Returns
Owned tokens.

◆ Split() [2/3]

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

Copy caller-owned tokens into Base storage.

Parameters
partsSource. Not modified.
Returns
Owned tokens.

◆ Split() [3/3]

Vector< WString > StormByte::Safe::WString::Split ( std::wstring_view str)
static

Whitespace-separated tokens.

Nodes are allocated in Base.

Parameters
strSource.
Returns
Owned tokens.

◆ starts_with() [1/2]

bool StormByte::Safe::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::Safe::WString::starts_with ( wchar_t ch) const
inlinenoexcept

Whether the text begins with ch.

Parameters
chPrefix unit.
Returns
Match.

◆ substr()

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

Swaps storage with other.

Parameters
otherOther text.

◆ ToLower() [1/2]

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

ASCII-letter lower case of this text.

Returns
New text.

◆ ToLower() [2/2]

WString StormByte::Safe::WString::ToLower ( std::wstring_view str)
static

ASCII-letter lower case; other units copied.

Parameters
strSource.
Returns
New text.

◆ ToUpper() [1/2]

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

ASCII-letter upper case of this text.

Returns
New text.

◆ ToUpper() [2/2]

WString StormByte::Safe::WString::ToUpper ( std::wstring_view str)
static

ASCII-letter upper case; other units copied.

Parameters
strSource.
Returns
New text.

Member Data Documentation

◆ npos

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

Not found.

◆ SSO_CAPACITY

std::size_t StormByte::Safe::WString::SSO_CAPACITY = 11
staticconstexpr

Short capacity, excluding the trailing NUL.


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