diff options
Diffstat (limited to 'pw_string/guide.rst')
| -rw-r--r-- | pw_string/guide.rst | 125 |
1 files changed, 105 insertions, 20 deletions
diff --git a/pw_string/guide.rst b/pw_string/guide.rst index 87ceec03e..dfa83b39b 100644 --- a/pw_string/guide.rst +++ b/pw_string/guide.rst @@ -1,19 +1,103 @@ .. _module-pw_string-guide: -================ -pw_string: Guide -================ +==================== +Get Started & Guides +==================== +.. pigweed-module-subpage:: + :name: pw_string + :tagline: pw_string: Efficient, easy, and safe string manipulation -InlineString and StringBuilder? -=============================== -Use :cpp:type:`pw::InlineString` if you need: +.. _module-pw_string-get-started: + +Get Started +=========== +.. tab-set:: + + .. tab-item:: Bazel + + Add ``@pigweed//pw_string`` to the ``deps`` list in your Bazel target: + + .. code-block:: + + cc_library("...") { + # ... + deps = [ + # ... + "@pigweed//pw_string", + # ... + ] + } + + If only one part of the module is needed, depend only on it; for example + ``@pigweed//pw_string:format``. + + This assumes ``@pigweed`` is the name you pulled Pigweed into your Bazel + ``WORKSPACE`` as. + + .. tab-item:: GN + + Add ``$dir_pw_string`` to the ``deps`` list in your ``pw_executable()`` + build target: + + .. code-block:: + + pw_executable("...") { + # ... + deps = [ + # ... + "$dir_pw_string", + # ... + ] + } + + See `//source/BUILD.gn <https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/main/source/BUILD.gn>`_ + in the Pigweed Sample Project for an example. + + .. tab-item:: CMake + + Add ``pw_string`` to your ``pw_add_library`` or similar CMake target: + + .. code-block:: + + pw_add_library(my_library STATIC + HEADERS + ... + PRIVATE_DEPS + # ... + pw_string + # ... + ) + + For a narrower dependency, depend on subtargets like + ``pw_string.builder``, etc. + + .. tab-item:: Zephyr + + There are two ways to use ``pw_string`` from a Zephyr project: + + #. Depend on ``pw_string`` in your CMake target (see CMake tab). This is + Pigweed Team's suggested approach since it enables precise CMake + dependency analysis. + + #. Add ``CONFIG_PIGWEED_STRING=y`` to the Zephyr project's configuration, + which causes ``pw_string`` to become a global dependency and have the + includes exposed to all targets. Pigweed team does not recommend this + approach, though it is the typical Zephyr solution. + +Choose between pw::InlineString and pw::StringBuilder +===================================================== +`pw::InlineString` is intended to replace typical null terminated character +arrays in embedded data structures. Use :cpp:type:`pw::InlineString` if you +need: * Compatibility with ``std::string`` * Storage internal to the object * A string object to persist in other data structures * Lower code size overhead -Use :cpp:class:`pw::StringBuilder` if you need: +`pw::StringBuilder` is intended to ease constructing strings in external data; +typically created on the stack and disposed of in the same function. Use +:cpp:class:`pw::StringBuilder` if you need: * Compatibility with ``std::ostringstream``, including custom object support * Storage external to the object @@ -59,9 +143,10 @@ constructing a string for external use. return sb.status(); } +.. _module-pw_string-guide-stringbuilder: -Building strings with pw::StringBuilder -======================================= +Build a string with pw::StringBuilder +===================================== The following shows basic use of a :cpp:class:`pw::StringBuilder`. .. code-block:: cpp @@ -90,8 +175,8 @@ The following shows basic use of a :cpp:class:`pw::StringBuilder`. return sb.status(); } -Building strings with pw::InlineString -====================================== +Build a string with pw::InlineString +==================================== :cpp:type:`pw::InlineString` objects must be constructed by specifying a fixed capacity for the string. @@ -127,8 +212,8 @@ capacity for the string. FunctionThatTakesAnInlineString(std::string_view("1234", 4)); -Building strings inside InlineString with a StringBuilder -========================================================= +Build a string inside an pw::InlineString with a pw::StringBuilder +================================================================== :cpp:class:`pw::StringBuilder` can build a string in a :cpp:type:`pw::InlineString`: @@ -143,8 +228,8 @@ Building strings inside InlineString with a StringBuilder // inline_str contains "456" } -Passing InlineStrings as parameters -=================================== +Pass an pw::InlineString object as a parameter +============================================== :cpp:type:`pw::InlineString` objects can be passed to non-templated functions via type erasure. This saves code size in most cases, since it avoids template expansions triggered by string size differences. @@ -193,8 +278,8 @@ Known size strings return string; }(); -Compact initialization of InlineStrings -======================================= +Initialization of pw::InlineString objects +=========================================== :cpp:type:`pw::InlineBasicString` supports class template argument deduction (CTAD) in C++17 and newer. Since :cpp:type:`pw::InlineString` is an alias, CTAD is not supported until C++20. @@ -208,9 +293,9 @@ is not supported until C++20. // In C++20, CTAD may be used with the pw::InlineString alias. pw::InlineString my_other_string("123456789"); -Supporting custom types with StringBuilder -========================================== -As with ``std::ostream``, StringBuilder supports printing custom types by +Custom types with pw::StringBuilder +=================================== +As with ``std::ostream``, pw::StringBuilder supports printing custom types by overriding the ``<<`` operator. This is is done by defining ``operator<<`` in the same namespace as the custom type. For example: |