mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-21 14:16:26 +00:00
2596fe5418
On Windows, sometimes the va_list overload would be used when formatting with a single argument. To avoid potential conflicts like these, the va_list versions of string::Format and StringBuilder::Format are renamed to FormatVaList. Change-Id: Id29fae21b13ed420b13841a479e3748a1d3b91ce
67 lines
2.1 KiB
ReStructuredText
67 lines
2.1 KiB
ReStructuredText
.. _chapter-pw-string:
|
|
|
|
.. default-domain:: cpp
|
|
|
|
.. highlight:: sh
|
|
|
|
---------
|
|
pw_string
|
|
---------
|
|
The string module provides efficient utilities for safely working with strings.
|
|
The pw_string functions and classes always null-terminate strings and never
|
|
overrun buffers. They do not allocate their own memory.
|
|
|
|
Compatibility
|
|
=============
|
|
C++17
|
|
|
|
Dependencies
|
|
============
|
|
* pw_preprocessor
|
|
* pw_status
|
|
* pw_span
|
|
|
|
Features
|
|
========
|
|
|
|
pw::string::Format
|
|
------------------
|
|
The ``pw::string::Format`` and ``pw::string::FormatVaList`` functions provide
|
|
safer alternatives to ``std::snprintf`` and ``std::vsnprintf``. The snprintf
|
|
return value is awkward to interpret, and misinterpreting it can lead to serious
|
|
bugs.
|
|
|
|
Size report: replacing snprintf with pw::string::Format
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The ``Format`` functions have a small, fixed code size cost. However, relative
|
|
to equivalent ``std::snprintf`` calls, there is no incremental code size cost to
|
|
using ``Format``.
|
|
|
|
.. include:: format_size_report.rst
|
|
|
|
pw::StringBuilder
|
|
-----------------
|
|
StringBuilder facilitates building formatted strings in a fixed-size buffer.
|
|
It is designed to give the flexibility of std::string and std::ostringstream,
|
|
but with a small footprint. However, applications sensitive to code size should
|
|
use StringBuilder with care.
|
|
|
|
Size report: replacing snprintf with pw::StringBuilder
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The fixed code size cost of StringBuilder is significant, though smaller than
|
|
std::snprintf. Using StringBuilder's << and append methods exclusively in
|
|
place of snprintf reduces code size, but snprintf may be difficult to avoid.
|
|
|
|
The incremental code size cost of StringBuilder is comparable to snprintf if
|
|
errors are handled. Each argument to StringBuilder's << expands to a function
|
|
call, but one or two StringBuilder appends may have a smaller code size
|
|
impact than a single snprintf call.
|
|
|
|
.. include:: string_builder_size_report.rst
|
|
|
|
Future work
|
|
^^^^^^^^^^^
|
|
* StringBuilder's fixed size cost can be dramatically reduced by limiting
|
|
support for 64-bit integers.
|
|
* Consider integrating with the tokenizer module.
|