util.h File Reference

The pw::string::* functions provide safer alternatives to C++ standard library string functions. More...

#include <cctype>
#include <cstddef>
#include <string_view>
#include "pw_assert/assert.h"
#include "pw_polyfill/language_feature_macros.h"
#include "pw_result/result.h"
#include "pw_span/span.h"
#include "pw_status/status.h"
#include "pw_status/status_with_size.h"
#include "pw_string/internal/length.h"
#include "pw_string/string.h"

Go to the source code of this file.

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

Functions
StatusWithSize	pw::string::internal::CopyToSpan (std::string_view source, span< char > dest)
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.

Detailed Description

The pw::string::* functions provide safer alternatives to C++ standard library string functions.

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.
* 
*  

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 ..