third_party/pigweed/repo/pw_string/docs.rst

   1 .. _module-pw_string:
   2
   3 ---------
   4 pw_string
   5 ---------
   6 String manipulation is a very common operation, but the standard C and C++
   7 string libraries have drawbacks. The C++ functions are easy-to-use and powerful,
   8 but require too much flash and memory for many embedded projects. The C string
   9 functions are lighter weight, but can be difficult to use correctly. Mishandling
  10 of null terminators or buffer sizes can result in serious bugs.
  11
  12 The ``pw_string`` module provides the flexibility, ease-of-use, and safety of
  13 C++-style string manipulation, but with no dynamic memory allocation and a much
  14 smaller binary size impact. Using ``pw_string`` in place of the standard C
  15 functions eliminates issues related to buffer overflow or missing null
  16 terminators.
  17
  18 Compatibility
  19 =============
  20 C++17
  21
  22 Dependencies
  23 ============
  24 * ``pw_preprocessor``
  25 * ``pw_status``
  26 * ``pw_span``
  27
  28 Features
  29 ========
  30
  31 pw::string::Format
  32 ------------------
  33 The ``pw::string::Format`` and ``pw::string::FormatVaList`` functions provide
  34 safer alternatives to ``std::snprintf`` and ``std::vsnprintf``. The snprintf
  35 return value is awkward to interpret, and misinterpreting it can lead to serious
  36 bugs.
  37
  38 Size report: replacing snprintf with pw::string::Format
  39 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  40 The ``Format`` functions have a small, fixed code size cost. However, relative
  41 to equivalent ``std::snprintf`` calls, there is no incremental code size cost to
  42 using ``Format``.
  43
  44 .. include:: format_size_report
  45
  46 pw::StringBuilder
  47 -----------------
  48 StringBuilder facilitates building formatted strings in a fixed-size buffer. It
  49 is designed to give the flexibility of ``std::string`` and
  50 ``std::ostringstream``, but with a small footprint. However, applications
  51 sensitive to code size should use StringBuilder with care.
  52
  53 Size report: replacing snprintf with pw::StringBuilder
  54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  55 The fixed code size cost of StringBuilder is significant, though smaller than
  56 ``std::snprintf``. Using StringBuilder's << and append methods exclusively in
  57 place of ``snprintf`` reduces code size, but ``snprintf`` may be difficult to
  58 avoid.
  59
  60 The incremental code size cost of StringBuilder is comparable to ``snprintf`` if
  61 errors are handled. Each argument to StringBuilder's << expands to a function
  62 call, but one or two StringBuilder appends may have a smaller code size impact
  63 than a single ``snprintf`` call.
  64
  65 .. include:: string_builder_size_report
  66
  67 Future work
  68 ^^^^^^^^^^^
  69 * StringBuilder's fixed size cost can be dramatically reduced by limiting
  70   support for 64-bit integers.
  71 * Consider integrating with the tokenizer module.