pw::StringBuilder Class Reference

Overview

pw::StringBuilder facilitates creating formatted strings in a fixed-sized buffer or in a pw::InlineString. It is designed to give the flexibility of std::ostringstream, but with a small footprint.

pw::StringBuilder instances are always null-terminated (unless they are constructed with an empty buffer) and never overflow. Status is tracked for each operation and an overall status is maintained, which reflects the most recent error.

pw::StringBuilder does not own the buffer it writes to. It can be used to write strings to any buffer. The pw::StringBuffer template class, defined below, allocates a buffer alongside a pw::StringBuilder.

pw::StringBuilder supports C++-style << output, similar to std::ostringstream. It also supports append functions like std::string and printf-style output.

Support for custom types is added by overloading operator<< in the same namespace as the custom type. For example:

namespace my_project {
 
struct MyType {
  int foo;
  const char* bar;
};
 
pw::StringBuilder& operator<<(pw::StringBuilder& sb, const MyType& value)
{
  return sb << "MyType(" << value.foo << ", " << value.bar << ')';
}
 
}  // namespace my_project

The ToString template function can be specialized to support custom types with pw::StringBuilder, though overloading operator<< is generally preferred. For example:

namespace pw {
 
template <>
StatusWithSize ToString<MyStatus>(MyStatus value, span<char> buffer) {
  return Copy(MyStatusString(value), buffer);
}
 
}  // namespace pw

Inheritance diagram for pw::StringBuilder:

Public Member Functions
constexpr	StringBuilder (span< char > buffer)
	Creates an empty pw::StringBuilder.
	StringBuilder (span< std::byte > buffer)
constexpr	StringBuilder (InlineString<> &string)
	StringBuilder (const StringBuilder &)=delete
StringBuilder &	operator= (const StringBuilder &)=delete
const char *	data () const
	Returns the contents of the string buffer. Always null-terminated.
const char *	c_str () const
	Returns the contents of the string buffer. Always null-terminated.
std::string_view	view () const
	operator std::string_view () const
span< const std::byte >	as_bytes () const
Status	status () const
StatusWithSize	status_with_size () const
	Returns status() and size() as a StatusWithSize.
Status	last_status () const
	The status from the last operation. May be OK while status() is not OK.
bool	ok () const
	True if status() is OkStatus().
bool	empty () const
	True if the string is empty.
size_t	size () const
	Returns the current length of the string, excluding the null terminator.
size_t	max_size () const
	Returns the maximum length of the string, excluding the null terminator.
void	clear ()
	Clears the string and resets its error state.
void	clear_status ()
	Sets the statuses to OkStatus();.
void	push_back (char ch)
void	pop_back ()
StringBuilder &	append (size_t count, char ch)
	Appends the provided character count times.
StringBuilder &	append (const char *str, size_t count)
StringBuilder &	append (const char *str)
StringBuilder &	append (std::string_view str)
	Appends a std::string_view to the end of the StringBuilder.
StringBuilder &	append (std::string_view str, size_t pos, size_t count=std::string_view::npos)
template<typename T >
StringBuilder &	operator<< (const T &value)
StringBuilder &	operator<< (bool value)
	Provide a few additional operator<< overloads that reduce code size.
StringBuilder &	operator<< (char value)
StringBuilder &	operator<< (std::nullptr_t)
StringBuilder &	operator<< (Status status)
StringBuilder &	Format (const char *format,...)
StringBuilder &	FormatVaList (const char *format, va_list args)
void	resize (size_t new_size)

Protected Member Functions
constexpr	StringBuilder (span< char > buffer, const StringBuilder &other)
	Functions to support StringBuffer copies.
void	CopySizeAndStatus (const StringBuilder &other)

Constructor & Destructor Documentation

StringBuilder()

pw::StringBuilder::StringBuilder ( const StringBuilder &  )

delete

Disallow copy/assign to avoid confusion about where the string is actually stored. pw::StringBuffer instances may be copied into one another.

Member Function Documentation

append() [1/3]

StringBuilder & pw::StringBuilder::append

(

const char *

str

)

Appends characters from the null-terminated string to the end of the StringBuilder. If the string's length exceeds the remaining space in the buffer, max_size() - size() characters are copied and the status is set to RESOURCE_EXHAUSTED.

This function uses string::Length instead of std::strlen to avoid unbounded reads if the string is not null-terminated.

append() [2/3]

StringBuilder & pw::StringBuilder::append	(	const char *	str,
		size_t	count
	)

Appends count characters from str to the end of the StringBuilder. If count exceeds the remaining space in the StringBuffer, max_size() - size() characters are appended and the status is set to RESOURCE_EXHAUSTED.

str is not considered null-terminated and may contain null characters.

append() [3/3]

StringBuilder & pw::StringBuilder::append	(	std::string_view	str,
		size_t	pos,
		size_t	count = std::string_view::npos
	)

Appends a substring from the std::string_view to the StringBuilder. Copies up to count characters starting from pos to the end of the StringBuilder. If pos > str.size(), sets the status to OUT_OF_RANGE.

as_bytes()

span< const std::byte > pw::StringBuilder::as_bytes ( ) const

inline

Returns a span<const std::byte> representation of this pw::StringBuffer.

c_str()

const char * pw::StringBuilder::c_str ( ) const

inline

Returns the contents of the string buffer. Always null-terminated.

Format()

StringBuilder & pw::StringBuilder::Format	(	const char *	format,
			...
	)

Appends a printf-style string to the end of the StringBuilder. If the formatted string does not fit, the results are truncated and the status is set to RESOURCE_EXHAUSTED.

Parameters

format	The format string
...	Arguments for format specification

Returns

StringBuilder&

Note

Internally, calls string::Format, which calls std::vsnprintf.

FormatVaList()

StringBuilder & pw::StringBuilder::FormatVaList	(	const char *	format,
		va_list	args
	)

Appends a vsnprintf-style string with va_list arguments to the end of the StringBuilder. If the formatted string does not fit, the results are truncated and the status is set to RESOURCE_EXHAUSTED.

Note

Internally, calls string::Format, which calls std::vsnprintf.

operator std::string_view()

pw::StringBuilder::operator std::string_view ( ) const

inline

Allow implicit conversions to std::string_view so pw::StringBuilder instances can be passed into functions that take a std::string_view.

operator<<()

template<typename T >

StringBuilder & pw::StringBuilder::operator<< ( const T &  value )

inline

Appends to the end of the StringBuilder using the << operator. This enables C++ stream-style formatted to StringBuilder instances.

For types compatible with std::string_view, use the append function, which gives smaller code size.

pop_back()

void pw::StringBuilder::pop_back ( )

inline

Removes the last character. Sets the status to OUT_OF_RANGE if the buffer is empty (in which case the unsigned overflow is intentional).

push_back()

void pw::StringBuilder::push_back ( char  ch )

inline

Appends a single character. Sets the status to RESOURCE_EXHAUSTED if the character cannot be added because the buffer is full.

resize()

void pw::StringBuilder::resize

(

size_t

new_size

)

Sets the size of the StringBuilder. This function only truncates; if new_size > size(), it sets status to OUT_OF_RANGE and does nothing.

status()

Status pw::StringBuilder::status ( ) const

inline

Returns the status of pw::StringBuilder, which reflects the most recent error that occurred while updating the string. After an update fails, the status remains non-OK until it is cleared with pw::StringBuilder::clear() or pw::StringBuilder::clear_status().

Returns

• OK: No errors have occurred.
• RESOURCE_EXHAUSTED: Output to the StringBuilder was truncated.
• INVALID_ARGUMENT: printf-style formatting failed.
• OUT_OF_RANGE: An operation outside the buffer was attempted.

view()

std::string_view pw::StringBuilder::view ( ) const

inline

Returns a std::string_view of the contents of this pw::StringBuilder. The std::string_view is invalidated if the pw::StringBuilder contents change.

---

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

• pw_string/public/pw_string/string_builder.h