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