Pigweed AI summary: The pw_string module provides efficient, easy, and safe string manipulation for embedded systems. It offers an API that closely matches that of std::string, but without dynamic memory allocation and with a much smaller binary size impact. The module includes pw::InlineString and pw::StringBuilder, which work like std::string but with better efficiency and memory benefits. The module is not suitable for projects written in C, but it works well on larger embedded platforms and host systems. The roadmap for the module includes reducing

Stable C++14 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 pw::InlineString in the same way:

// 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? pw::StringBuilder works like std::ostringstream, but with most of the efficiency and memory benefits of pw::InlineString:

// 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 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.

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 binary size impact.

Is it right for you?#

Pigweed AI summary: The article discusses the usefulness of the pw_string in handling strings in embedded C++. It is not recommended for projects written in C as there is no C API available. However, for larger platforms with enough code space and memory allocation, std::string may be a better fit. The article suggests using pw_string even on larger platforms as it provides flexibility for future moves to smaller platforms with less rework.

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.

Getting Started#

Pigweed AI summary: This section provides instructions on how to add "$dir_pw_string" to the "deps" list in the "pw_executable()" build target and includes a code block as an example. It also references the Pigweed Sample Project for further guidance. Additionally, it briefly mentions adding "CONFIG_PIGWEED_STRING=y" to the Zephyr project's configuration.

Add $dir_pw_string to the deps list in your pw_executable() build target:

pw_executable("...") {
  # ...
  deps = [
    # ...
    "$dir_pw_string",
    # ...
  ]
}

See //source/BUILD.gn in the Pigweed Sample Project for an example.

Roadmap#

Pigweed AI summary: The fixed size cost of pw::StringBuilder can be reduced by limiting support for 64-bit integers. Additionally, pw_string may be integrated with pw_tokenizer. More information can be found in the pw_string design, guide, and API sections.

  • The fixed size cost of pw::StringBuilder can be dramatically reduced by limiting support for 64-bit integers.

  • pw_string may be integrated with pw_tokenizer.