StormByte::WCString Class Reference

Owned NUL-terminated wide buffer, safe to use across a DLL boundary. More...

#include <StormByte/wcstring.hxx>

Public Member Functions
Life
	WCString () noexcept
	Empty (null) buffer.
	WCString (const wchar_t *str) noexcept
	Copies str.
	WCString (std::wstring_view sv) noexcept
	Copies sv onto Base's heap.
	WCString (const std::wstring &str) noexcept
	Copies str onto Base's heap.
	WCString (const CString &text) noexcept
	Copies text as wide characters.
	WCString (const WCString &other) noexcept
	Copy constructor.
	WCString (WCString &&other) noexcept
	Move constructor.
	~WCString () noexcept
	Releases the buffer.
WCString &	operator= (const WCString &other) noexcept
	Copy assignment.
WCString &	operator= (WCString &&other) noexcept
	Move assignment.
Modifiers
void	Reset (const wchar_t *str=nullptr) noexcept
	Replaces the buffer with a copy of str.
void	swap (WCString &other) noexcept
	Swaps buffers with other.
Observers
Size	Length () const noexcept
	Character count (wcslen), or 0 when empty or null.
wchar_t	operator[] (const Size &index) const noexcept
	Character at index.
	operator bool () const noexcept
	true when the buffer pointer is not null.
Conversions
	operator const wchar_t * () const noexcept
	View of the owned buffer.
	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.
STORMBYTE_FORCE_INLINE std::wostream &	operator<< (std::wostream &stream) const
	Writes the text to stream.
Comparison
bool	operator== (const WCString &other) const noexcept
	Content equality.
bool	operator!= (const WCString &other) const noexcept
	Content inequality.
bool	operator== (const wchar_t *str) const noexcept
	Content equality with a C wide string.
bool	operator!= (const wchar_t *str) const noexcept
	Content inequality with a C wide string.
std::strong_ordering	operator<=> (const WCString &other) const noexcept
	Content order.
std::strong_ordering	operator<=> (const wchar_t *str) const noexcept
	Content order against a C wide string.

Detailed Description

Owned NUL-terminated wide buffer, safe to use across a DLL boundary.

This is not a replacement or reimplementation of std::wstring. The class is minimal on purpose: copy, move, reset, a C wide-string view, Length, subscript, equality, ordering, swap and conversions.

operator const wchar_t* is the analogue of std::wstring::c_str(). The pointer is valid only until this object is destroyed, moved from, assigned or Reset. Using it afterwards is use-after-free.

operator std::wstring_view is explicit and follows the same lifetime. A null buffer yields an empty view. The view covers [0, Length()) and does not include the trailing NUL.

operator bool is true when the pointer is not null. A buffer constructed from L"" is empty (Length() == 0) and valid. A default-constructed object is null.

Construction from std::wstring / std::wstring_view copies onto Base's heap. It is not a heap steal. An empty source yields L"", not a null buffer.

operator[] is an observer. Valid indices are [0, Length()]; Length() is the trailing NUL. A null buffer or an index past Length() is undefined and asserts when assertions are on.

Equality and <=> compare text, not addresses. Two nulls are equal. Null is not equal to L"". Null orders before any text.

operator std::wstring and operator<< are STORMBYTE_FORCE_INLINE so the caller CRT owns the string and the stream buffer. inline on an exported class can still be a call into this DLL.

If the text never leaves the module that created it, or the program is not built for Windows, use std::wstring.

Constructor & Destructor Documentation

WCString() [1/7]

StormByte::WCString::WCString ( )

noexcept

Empty (null) buffer.

WCString() [2/7]

StormByte::WCString::WCString ( const wchar_t *  str )

explicitnoexcept

Copies str.

Parameters

str	Source; may be null.

WCString() [3/7]

StormByte::WCString::WCString ( std::wstring_view  sv )

explicitnoexcept

Copies sv onto Base's heap.

Parameters

sv	Source view. Copied up to the first NUL, then terminated.

Note

Not a heap steal. Empty yields L"".

WCString() [4/7]

StormByte::WCString::WCString ( const std::wstring &  str )

explicitnoexcept

Copies str onto Base's heap.

Parameters

str	Source. Remains valid and unchanged.

Note

Not a heap steal. Empty yields L"".

WCString() [5/7]

StormByte::WCString::WCString ( const CString &  text )

explicitnoexcept

Copies text as wide characters.

Narrow text is UTF-8.

Parameters

text	Narrow text. Null stays null.

WCString() [6/7]

StormByte::WCString::WCString ( const WCString &  other )

noexcept

Copy constructor.

Parameters

other

Buffer to copy.

WCString() [7/7]

StormByte::WCString::WCString ( WCString &&  other )

noexcept

Move constructor.

Parameters

other

Buffer to take. other becomes null.

~WCString()

StormByte::WCString::~WCString ( )

noexcept

Releases the buffer.

Member Function Documentation

Length()

Size StormByte::WCString::Length ( ) const

noexcept

Character count (wcslen), or 0 when empty or null.

Returns

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

operator bool()

StormByte::WCString::operator bool ( ) const

inlineexplicitnoexcept

true when the buffer pointer is not null.

Note

L"" is valid and empty. A default object is null.

Returns

Whether a buffer is held.

operator const wchar_t *()

StormByte::WCString::operator const wchar_t * ( ) const

explicitnoexcept

View of the owned buffer.

Returns

Buffer, or null.

Note

Same lifetime rules as std::wstring::c_str().

operator std::wstring()

STORMBYTE_FORCE_INLINE StormByte::WCString::operator std::wstring ( ) const

inline

Copy of the text in the caller’s heap.

Returns

Empty string when the buffer is null.

operator std::wstring_view()

StormByte::WCString::operator std::wstring_view ( ) const

inlineexplicitnoexcept

Non-owning view of the text.

Returns

Empty view when the buffer is null.

Note

Same lifetime rules as std::wstring::c_str().

operator!=() [1/2]

bool StormByte::WCString::operator!= ( const wchar_t *  str ) const

inlinenoexcept

Content inequality with a C wide string.

Parameters

str	May be null.

Returns

Whether the texts differ.

operator!=() [2/2]

bool StormByte::WCString::operator!= ( const WCString &  other ) const

inlinenoexcept

Content inequality.

Parameters

other

Other buffer.

Returns

Whether the texts differ.

operator<<()

STORMBYTE_FORCE_INLINE std::wostream & StormByte::WCString::operator<< ( std::wostream &  stream ) const

inline

Writes the text to stream.

Parameters

stream

Destination.

Returns

stream.

operator<=>() [1/2]

std::strong_ordering StormByte::WCString::operator<=> ( const wchar_t *  str ) const

noexcept

Content order against a C wide string.

Parameters

str	May be null.

Returns

Ordering.

operator<=>() [2/2]

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

noexcept

Content order.

Null is less than any text.

Parameters

other

Other buffer.

Returns

Ordering.

operator=() [1/2]

WCString & StormByte::WCString::operator= ( const WCString &  other )

noexcept

Copy assignment.

Parameters

other

Buffer to copy.

Returns

*this.

operator=() [2/2]

WCString & StormByte::WCString::operator= ( WCString &&  other )

noexcept

Move assignment.

Parameters

other

Buffer to take. other becomes null.

Returns

*this.

operator==() [1/2]

bool StormByte::WCString::operator== ( const wchar_t *  str ) const

noexcept

Content equality with a C wide string.

Parameters

str	May be null (treated as a null WCString).

Returns

Whether the texts are equal.

operator==() [2/2]

bool StormByte::WCString::operator== ( const WCString &  other ) const

noexcept

Content equality.

Parameters

other

Other buffer.

Returns

Whether the texts are equal.

operator[]()

wchar_t StormByte::WCString::operator[] ( const Size &  index ) const

noexcept

Character at index.

Parameters

index

Position in [0, Length()]. Length() is the trailing NUL.

Returns

The character.

Note

Null or index > Length() is undefined. Checked with assert when assertions are on.

Reset()

void StormByte::WCString::Reset ( const wchar_t *  str = nullptr )

noexcept

Replaces the buffer with a copy of str.

Parameters

str	Source; may be null.

swap()

void StormByte::WCString::swap ( WCString &  other )

noexcept

Swaps buffers with other.

Parameters

other

Other buffer.

---

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

• lib/public/StormByte/wcstring.hxx