mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-21 14:16:26 +00:00
ee3e02f6cb
- Add missing README.md for a few modules. - Start or expand docs.rst. Change-Id: Ic13c5f71f02259205ba990c93e0403d43f7b44b1
66 lines
2.1 KiB
ReStructuredText
66 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`` functions provides 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.
|
|
|
|
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.
|