2019-12-05 18:52:31 +00:00
|
|
|
.. _chapter-pw-string:
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
.. default-domain:: cpp
|
|
|
|
|
|
|
|
.. highlight:: sh
|
|
|
|
|
|
|
|
---------
|
|
|
|
pw_string
|
|
|
|
---------
|
2020-03-03 22:37:52 +00:00
|
|
|
String manipulation is a very common operation, but the standard C and C++
|
|
|
|
string libraries have drawbacks. The C++ functions are easy-to-use and powerful,
|
|
|
|
but require too much flash and memory for many embedded projects. The C string
|
|
|
|
functions are lighter weight, but can be difficult to use correctly. Mishandling
|
|
|
|
of null terminators or buffer sizes can result in serious bugs.
|
|
|
|
|
2020-03-13 20:06:24 +00:00
|
|
|
The ``pw_string`` module provides the flexibility, ease-of-use, and safety of
|
2020-03-03 22:37:52 +00:00
|
|
|
C++-style string manipulation, but with no dynamic memory allocation and a much
|
2020-03-13 20:06:24 +00:00
|
|
|
smaller binary size impact. Using ``pw_string`` in place of the standard C
|
|
|
|
functions eliminates issues related to buffer overflow or missing null
|
|
|
|
terminators.
|
2019-11-20 01:10:20 +00:00
|
|
|
|
2019-12-05 18:52:31 +00:00
|
|
|
Compatibility
|
2019-11-20 01:10:20 +00:00
|
|
|
=============
|
|
|
|
C++17
|
|
|
|
|
2019-12-05 18:52:31 +00:00
|
|
|
Dependencies
|
|
|
|
============
|
2020-03-13 20:06:24 +00:00
|
|
|
* ``pw_preprocessor``
|
|
|
|
* ``pw_status``
|
|
|
|
* ``pw_span``
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
Features
|
|
|
|
========
|
|
|
|
|
|
|
|
pw::string::Format
|
|
|
|
------------------
|
2020-01-24 01:40:10 +00:00
|
|
|
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.
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
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``.
|
|
|
|
|
2020-03-19 20:37:10 +00:00
|
|
|
.. include:: format_size_report
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
pw::StringBuilder
|
|
|
|
-----------------
|
2020-03-13 20:06:24 +00:00
|
|
|
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.
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
Size report: replacing snprintf with pw::StringBuilder
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The fixed code size cost of StringBuilder is significant, though smaller than
|
2020-03-13 20:06:24 +00:00
|
|
|
``std::snprintf``. Using StringBuilder's << and append methods exclusively in
|
|
|
|
place of ``snprintf`` reduces code size, but ``snprintf`` may be difficult to
|
|
|
|
avoid.
|
2019-11-20 01:10:20 +00:00
|
|
|
|
2020-03-13 20:06:24 +00:00
|
|
|
The incremental code size cost of StringBuilder is comparable to ``snprintf`` if
|
2019-11-20 01:10:20 +00:00
|
|
|
errors are handled. Each argument to StringBuilder's << expands to a function
|
2020-03-13 20:06:24 +00:00
|
|
|
call, but one or two StringBuilder appends may have a smaller code size impact
|
|
|
|
than a single ``snprintf`` call.
|
2019-11-20 01:10:20 +00:00
|
|
|
|
2020-03-19 20:37:10 +00:00
|
|
|
.. include:: string_builder_size_report
|
2019-11-20 01:10:20 +00:00
|
|
|
|
|
|
|
Future work
|
|
|
|
^^^^^^^^^^^
|
|
|
|
* StringBuilder's fixed size cost can be dramatically reduced by limiting
|
|
|
|
support for 64-bit integers.
|
|
|
|
* Consider integrating with the tokenizer module.
|