1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
.. _module-pw_string:
=========
pw_string
=========
.. pigweed-module::
:name: pw_string
:tagline: Efficient, easy, and safe string manipulation
:status: stable
:languages: C++17
:code-size-impact: 500 to 1500 bytes
- **Efficient**: No memory allocation, no pointer indirection.
- **Easy**: Use the string API you already know.
- **Safe**: Never worry about buffer overruns or undefined behavior.
*Pick three!* If you know how to use ``std::string``, just use
:cpp:type:`pw::InlineString` in the same way:
.. code-block:: cpp
// Create a string from a C-style char array; storage is pre-allocated!
pw::InlineString<16> my_string = "Literally";
// We have some space left, so let's add to the string.
my_string.append('?', 3); // "Literally???"
// Let's try something evil and extend this past its capacity 😈
my_string.append('!', 8);
// Foiled by a crash! No mysterious bugs or undefined behavior.
Need to build up a string? :cpp:type:`pw::StringBuilder` works like
``std::ostringstream``, but with most of the efficiency and memory benefits
of :cpp:type:`pw::InlineString`:
.. code-block:: cpp
// Create a pw::StringBuilder with a built-in buffer
pw::StringBuffer<32> my_string_builder = "Is it really this easy?";
// Add to it with idiomatic C++
my_string << " YES!";
// Use it like any other string
PW_LOG_DEBUG("%s", my_string_builder.c_str());
Check out :ref:`module-pw_string-guide` for more code samples.
String manipulation on embedded systems can be surprisingly challenging.
- **C strings?** They're light-weight but come with many pitfalls for those who
don't know the standard library deeply.
- **C++ strings?** STL string classes are safe and easy to use, but they consume
way too much code space and are designed to be used with dynamic memory
allocation.
- **Roll your own strings?** You don't have time! You have a product to ship!
Embedded systems need string functionality that is both *safe* and *suitable*
for resource-constrained platforms.
.. rst-class:: key-text
``pw_string`` provides safe string handling functionality with an API that
closely matches that of ``std::string``, but without dynamic memory
allocation and with a *much* smaller :ref:`binary size impact<module-pw_string-size-reports>`.
--------------------
Is it right for you?
--------------------
.. rst-class:: key-text
``pw_string`` is useful any time you need to handle strings in embedded C++.
If your project written in C, ``pw_string`` is not a good fit since we don't
currently expose a C API.
On the other hand, for larger platforms where code space isn't in short supply
and dynamic memory allocation isn't a problem, you may find that ``std::string``
meets your needs.
.. tip::
``pw_string`` works just as well on larger embedded platforms and host
systems. Using ``pw_string`` even when you could get away with ``std:string``
gives you the flexibility to move to smaller platforms later with much less
rework.
.. toctree::
:hidden:
:maxdepth: 1
guide
api
design
code_size
.. grid:: 2
.. grid-item-card:: :octicon:`rocket` Get Started & Guides
:link: module-pw_string-get-started
:link-type: ref
:class-item: sales-pitch-cta-primary
Integrate pw_string into your project and learn common use cases
.. grid-item-card:: :octicon:`code-square` API Reference
:link: module-pw_string-api
:link-type: ref
:class-item: sales-pitch-cta-secondary
Detailed description of the pw_string's classes and methods
.. grid:: 2
.. grid-item-card:: :octicon:`code-square` Design & Roadmap
:link: module-pw_string-design
:link-type: ref
:class-item: sales-pitch-cta-secondary
Learn why pw_string is designed the way it is, and upcoming plans
.. grid-item-card:: :octicon:`code-square` Code Size Analysis
:link: module-pw_string-size-reports
:link-type: ref
:class-item: sales-pitch-cta-secondary
Understand pw_string's code footprint and savings potential
|
