mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-21 22:28:10 +00:00
64 lines
2.0 KiB
ReStructuredText
64 lines
2.0 KiB
ReStructuredText
|
.. _chapter-string:
|
||
|
|
||
|
.. default-domain:: cpp
|
||
|
|
||
|
.. highlight:: sh
|
||
|
|
||
|
---------
|
||
|
pw_string
|
||
|
---------
|
||
|
The string module provides utilities for working with strings.
|
||
|
|
||
|
Requirements
|
||
|
=============
|
||
|
C++17
|
||
|
|
||
|
Module 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.
|
||
|
StringBuilder is safe, flexible, and results in much smaller code size than
|
||
|
using std::ostringstream. 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.
|