Utilities

Oveview

Safer alternatives to C++ standard library string functions.

Functions
StatusWithSize	pw::string::Format (span< char > buffer, const char *format,...)
StatusWithSize	pw::string::FormatVaList (span< char > buffer, const char *format, va_list args)
Status	pw::string::Format (InlineString<> &string, const char *format,...)
Status	pw::string::FormatVaList (InlineString<> &string, const char *format, va_list args)
Status	pw::string::FormatOverwrite (InlineString<> &string, const char *format,...)
Status	pw::string::FormatOverwriteVaList (InlineString<> &string, const char *format, va_list args)
constexpr std::string_view	pw::string::ClampedCString (span< const char > str)
	Safe alternative to the string_view constructor that avoids the risk of an unbounded implicit or explicit use of strlen.
constexpr std::string_view	pw::string::ClampedCString (const char *str, size_t max_len)
constexpr Result< size_t >	pw::string::NullTerminatedLength (span< const char > str)
	pw::string::NullTerminatedLength is a safer alternative to strlen for calculating the null-terminated length of the string within the specified span, excluding the null terminator.
constexpr Result< size_t >	pw::string::NullTerminatedLength (const char *str, size_t max_len)
template<typename Span >
StatusWithSize	pw::string::Copy (std::string_view source, Span &&dest)
	pw::string::Copy is a safer alternative to std::strncpy as it always null-terminates whenever the destination buffer has a non-zero size.
template<typename Span >
StatusWithSize	pw::string::Copy (const char *source, Span &&dest)
StatusWithSize	pw::string::Copy (const char *source, char *dest, size_t num)
Status	pw::string::Assign (InlineString<> &string, std::string_view view)
Status	pw::string::Assign (InlineString<> &string, const char *c_string)
Status	pw::string::Append (InlineString<> &string, std::string_view view)
Status	pw::string::Append (InlineString<> &string, const char *c_string)
StatusWithSize	pw::string::PrintableCopy (std::string_view source, span< char > dest)
	Provides a safe, printable copy of a string.

Function Documentation

Append()

Status pw::string::Append ( InlineString<> &  string, std::string_view  view  )

inline

Appends a std::string_view to a pw::InlineString, truncating if it does not fit. The append() function of pw::InlineString asserts if the string's requested size exceeds its capacity; pw::string::Append() returns a Status instead.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The entire ``std::string_view`` was assigned.
* 
*     RESOURCE_EXHAUSTED: The ``std::string_view`` was truncated to fit.
* 
*  

Assign()

Status pw::string::Assign ( InlineString<> &  string, std::string_view  view  )

inline

Assigns a std::string_view to a pw::InlineString, truncating if it does not fit. The assign() function of pw::InlineString asserts if the string's requested size exceeds its capacity; pw::string::Assign() returns a Status instead.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The entire ``std::string_view`` was copied to the end of the
*     ``pw::InlineString``.
* 
*     RESOURCE_EXHAUSTED: The ``std::string_view`` was truncated to fit.
* 
*  

ClampedCString()

constexpr std::string_view pw::string::ClampedCString ( span< const char >  str )

constexpr

Safe alternative to the string_view constructor that avoids the risk of an unbounded implicit or explicit use of strlen.

This is strongly recommended over using something like C11's strnlen_s as a string_view does not require null-termination.

Copy()

template<typename Span >

StatusWithSize pw::string::Copy ( std::string_view  source, Span &&  dest  )

inline

pw::string::Copy is a safer alternative to std::strncpy as it always null-terminates whenever the destination buffer has a non-zero size.

Copies the source string to the dest, truncating if the full string does not fit. Always null terminates if dest.size() or num is greater than 0.

Precondition

The destination and source shall not overlap. The source shall be a valid pointer.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns the number of characters written, excluding the null
*     terminator.
* 
*     RESOURCE_EXHAUSTED: The string is truncated.
* 
*  

Format() [1/2]

Status pw::string::Format	(	InlineString<> &	string,
		const char *	format,
			...
	)

Appends a printf-style formatted string to the provided pw::InlineString, similarly to std::snprintf().

Returns

See pw::string::Format().

Format() [2/2]

StatusWithSize pw::string::Format	(	span< char >	buffer,
		const char *	format,
			...
	)

Writes a printf-style formatted string to the provided buffer, similarly to std::snprintf().

The std::snprintf() return value is awkward to interpret, and misinterpreting it can lead to serious bugs.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns the number of characters written, excluding the null
*     terminator. The buffer is always null-terminated unless it is empty.
* 
*     RESOURCE_EXHAUSTED: The buffer was too small to fit the output.
* 
*     INVALID_ARGUMENT: There was a formatting error.
* 
*  

FormatOverwrite()

Status pw::string::FormatOverwrite	(	InlineString<> &	string,
		const char *	format,
			...
	)

Writes a printf-style format string to the provided InlineString, overwriting any contents.

Returns

See pw::string::Format().

FormatOverwriteVaList()

Status pw::string::FormatOverwriteVaList ( InlineString<> &  string, const char *  format, va_list  args  )

inline

Writes a printf-style formatted string with va_list-packed arguments to the provided InlineString, overwriting any contents.

Returns

See pw::string::Format().

FormatVaList() [1/2]

Status pw::string::FormatVaList	(	InlineString<> &	string,
		const char *	format,
		va_list	args
	)

Appends a printf-style formatted string with va_list-packed arguments to the provided InlineString, similarly to std::vsnprintf().

Returns

See pw::string::Format().

FormatVaList() [2/2]

StatusWithSize pw::string::FormatVaList	(	span< char >	buffer,
		const char *	format,
		va_list	args
	)

Writes a printf-style formatted string with va_list-packed arguments to the provided buffer, similarly to std::vsnprintf().

Returns

See pw::string::Format().

NullTerminatedLength()

constexpr Result< size_t > pw::string::NullTerminatedLength ( span< const char >  str )

constexpr

pw::string::NullTerminatedLength is a safer alternative to strlen for calculating the null-terminated length of the string within the specified span, excluding the null terminator.

Like strnlen_s in C11, the scan for the null-terminator is bounded.

Precondition

The string shall be at a valid pointer.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns the null-terminated length of the string excluding the null
*     terminator.
* 
*     OUT_OF_RANGE: The string is not null-terminated.
* 
*  

PrintableCopy()

StatusWithSize pw::string::PrintableCopy ( std::string_view  source, span< char >  dest  )

inline

Provides a safe, printable copy of a string.

Copies the source string to the dest string with same behavior as pw::string::Copy, with the difference that any non-printable characters are changed to ..