#include <cstdarg>
#include "pw_preprocessor/compiler.h"
#include "pw_span/span.h"
#include "pw_status/status_with_size.h"
#include "pw_string/string.h"

Namespaces
namespace	pw
	Provides basic helpers for reading and writing UTF-8 encoded strings.

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)

Detailed Description

The pw::string::Format functions are safer alternatives to std::snprintf and std::vsnprintf. The snprintf return value is awkward to interpret, and misinterpreting it can lead to serious bugs.

These functions return a pw::StatusWithSize. The pw::Status is set to reflect any errors and the return value is always the number of characters written before the null terminator.

Function Documentation

◆ 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().

Namespaces

Functions