StormByte::Safe::CString Class Reference

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

#include <StormByte/safe/cstring.hxx>

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

Detailed Description

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

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

operator const char* is the analogue of std::string::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::string_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 "" is empty (Length() == 0) and valid. A default-constructed object is null.

Construction from std::string / std::string_view copies onto Base's heap. It is not a heap steal. An empty source yields "", 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 "". Null orders before any text.

operator std::string 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::string.

Constructor & Destructor Documentation

CString() [1/7]

StormByte::Safe::CString::CString ( )

noexcept

Empty (null) buffer.

CString() [2/7]

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

explicitnoexcept

Copies str.

Parameters

str	Source; may be null.

CString() [3/7]

StormByte::Safe::CString::CString ( std::string_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 "".

CString() [4/7]

StormByte::Safe::CString::CString ( const std::string &  str )

explicitnoexcept

Copies str onto Base's heap.

Parameters

str	Source. Remains valid and unchanged.

Note

Not a heap steal. Empty yields "".

CString() [5/7]

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

explicitnoexcept

Copies text as UTF-8.

Parameters

text	Wide text. Null stays null.

CString() [6/7]

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

noexcept

Copy constructor.

Parameters

other

Buffer to copy.

CString() [7/7]

StormByte::Safe::CString::CString ( CString &&  other )

noexcept

Move constructor.

Parameters

other

Buffer to take. other becomes null.

~CString()

StormByte::Safe::CString::~CString ( )

noexcept

Releases the buffer.

Member Function Documentation

Length()

Size StormByte::Safe::CString::Length ( ) const

noexcept

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

Returns

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

operator bool()

StormByte::Safe::CString::operator bool ( ) const

inlineexplicitnoexcept

true when the buffer pointer is not null.

Note

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

Returns

Whether a buffer is held.

operator const char *()

StormByte::Safe::CString::operator const char * ( ) const

explicitnoexcept

View of the owned buffer.

Returns

Buffer, or null.

Note

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

operator std::string()

STORMBYTE_FORCE_INLINE StormByte::Safe::CString::operator std::string ( ) const

inline

Copy of the text in the caller’s heap.

Returns

Empty string when the buffer is null.

operator std::string_view()

StormByte::Safe::CString::operator std::string_view ( ) const

inlineexplicitnoexcept

Non-owning view of the text.

Returns

Empty view when the buffer is null.

Note

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

operator!=() [1/2]

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

inlinenoexcept

Content inequality with a C string.

Parameters

str	May be null.

Returns

Whether the texts differ.

operator!=() [2/2]

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

inlinenoexcept

Content inequality.

Parameters

other

Other buffer.

Returns

Whether the texts differ.

operator<<()

STORMBYTE_FORCE_INLINE std::ostream & StormByte::Safe::CString::operator<< ( std::ostream &  stream ) const

inline

Writes the text to stream.

Parameters

stream

Destination.

Returns

stream.

operator<=>() [1/2]

std::strong_ordering StormByte::Safe::CString::operator<=> ( const char *  str ) const

noexcept

Content order against a C string.

Parameters

str	May be null.

Returns

Ordering.

operator<=>() [2/2]

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

noexcept

Content order.

Null is less than any text.

Parameters

other

Other buffer.

Returns

Ordering.

operator=() [1/2]

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

noexcept

Copy assignment.

Parameters

other

Buffer to copy.

Returns

*this.

operator=() [2/2]

CString & StormByte::Safe::CString::operator= ( CString &&  other )

noexcept

Move assignment.

Parameters

other

Buffer to take. other becomes null.

Returns

*this.

operator==() [1/2]

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

noexcept

Content equality with a C string.

Parameters

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

Returns

Whether the texts are equal.

operator==() [2/2]

bool StormByte::Safe::CString::operator== ( const CString &  other ) const

noexcept

Content equality.

Parameters

other

Other buffer.

Returns

Whether the texts are equal.

operator[]()

char StormByte::Safe::CString::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::Safe::CString::Reset ( const char *  str = nullptr )

noexcept

Replaces the buffer with a copy of str.

Parameters

str	Source; may be null.

swap()

void StormByte::Safe::CString::swap ( CString &  other )

noexcept

Swaps buffers with other.

Parameters

other

Other buffer.

---

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

• lib/public/StormByte/safe/cstring.hxx