pw_string/docs.rst

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