Wyatt Hepler | ee3e02f | 2019-12-05 10:52:31 -0800 | [diff] [blame] | 1 | .. _chapter-pw-string: |
Wyatt Hepler | fe85de2 | 2019-11-19 17:10:20 -0800 | [diff] [blame] | 2 | |
| 3 | .. default-domain:: cpp |
| 4 | |
| 5 | .. highlight:: sh |
| 6 | |
| 7 | --------- |
| 8 | pw_string |
| 9 | --------- |
Wyatt Hepler | ee3e02f | 2019-12-05 10:52:31 -0800 | [diff] [blame] | 10 | The string module provides efficient utilities for safely working with strings. |
| 11 | The pw_string functions and classes always null-terminate strings and never |
| 12 | overrun buffers. They do not allocate their own memory. |
Wyatt Hepler | fe85de2 | 2019-11-19 17:10:20 -0800 | [diff] [blame] | 13 | |
Wyatt Hepler | ee3e02f | 2019-12-05 10:52:31 -0800 | [diff] [blame] | 14 | Compatibility |
Wyatt Hepler | fe85de2 | 2019-11-19 17:10:20 -0800 | [diff] [blame] | 15 | ============= |
| 16 | C++17 |
| 17 | |
Wyatt Hepler | ee3e02f | 2019-12-05 10:52:31 -0800 | [diff] [blame] | 18 | Dependencies |
| 19 | ============ |
Wyatt Hepler | fe85de2 | 2019-11-19 17:10:20 -0800 | [diff] [blame] | 20 | * pw_preprocessor |
| 21 | * pw_status |
| 22 | * pw_span |
| 23 | |
| 24 | Features |
| 25 | ======== |
| 26 | |
| 27 | pw::string::Format |
| 28 | ------------------ |
| 29 | The ``pw::string::Format`` functions provides are safer alternatives to |
| 30 | ``std::snprintf`` and ``std::vsnprintf``. The snprintf return value is awkward |
| 31 | to interpret, and misinterpreting it can lead to serious bugs. |
| 32 | |
| 33 | Size report: replacing snprintf with pw::string::Format |
| 34 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 35 | The ``Format`` functions have a small, fixed code size cost. However, relative |
| 36 | to equivalent ``std::snprintf`` calls, there is no incremental code size cost to |
| 37 | using ``Format``. |
| 38 | |
| 39 | .. include:: format_size_report.rst |
| 40 | |
| 41 | pw::StringBuilder |
| 42 | ----------------- |
| 43 | StringBuilder facilitates building formatted strings in a fixed-size buffer. |
Wyatt Hepler | ee3e02f | 2019-12-05 10:52:31 -0800 | [diff] [blame] | 44 | It is designed to give the flexibility of std::string and std::ostringstream, |
| 45 | but with a small footprint. However, applications sensitive to code size should |
Wyatt Hepler | fe85de2 | 2019-11-19 17:10:20 -0800 | [diff] [blame] | 46 | use StringBuilder with care. |
| 47 | |
| 48 | Size report: replacing snprintf with pw::StringBuilder |
| 49 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 50 | The fixed code size cost of StringBuilder is significant, though smaller than |
| 51 | std::snprintf. Using StringBuilder's << and append methods exclusively in |
| 52 | place of snprintf reduces code size, but snprintf may be difficult to avoid. |
| 53 | |
| 54 | The incremental code size cost of StringBuilder is comparable to snprintf if |
| 55 | errors are handled. Each argument to StringBuilder's << expands to a function |
| 56 | call, but one or two StringBuilder appends may have a smaller code size |
| 57 | impact than a single snprintf call. |
| 58 | |
| 59 | .. include:: string_builder_size_report.rst |
| 60 | |
| 61 | Future work |
| 62 | ^^^^^^^^^^^ |
| 63 | * StringBuilder's fixed size cost can be dramatically reduced by limiting |
| 64 | support for 64-bit integers. |
| 65 | * Consider integrating with the tokenizer module. |