1.. _module-pw_span: 2 3======= 4pw_span 5======= 6.. pigweed-module:: 7 :name: pw_span 8 9* **Standardized**: :cpp:class:`pw::span` matches C++20's `std::span 10 <https://en.cppreference.com/w/cpp/container/span>`_ as closely as possible. 11* **Zero-cost**: If ``std::span`` is available, ``pw::span`` is simply an alias 12 of it. 13 14.. pw_span-example-start 15 16.. code-block:: cpp 17 18 #include <span> 19 20 // With pw::span, a buffer is passed as a single argument. 21 // No need to handle pointer and size arguments. 22 bool ProcessBuffer(pw::span<uint8_t> buffer); 23 24 bool DoStuff() { 25 // ... 26 ProcessBuffer(c_array); 27 ProcessBuffer(array_object); 28 ProcessBuffer(pw::span(data_pointer, data_size)); 29 } 30 31.. pw_span-example-end 32 33:cpp:class:`pw::span` is a convenient abstraction that wraps a pointer and a 34size. It's especially useful in APIs. Spans support implicit conversions from 35C arrays, ``std::array``, or any STL-style container, such as 36``std::string_view``. 37 38.. _module-pw_span-start: 39 40----------- 41Get started 42----------- 43.. repository: https://bazel.build/concepts/build-ref#repositories 44 45.. tab-set:: 46 47 .. tab-item:: Bazel 48 49 Add ``@pigweed//pw_span`` to the ``deps`` list in your Bazel target: 50 51 .. code-block:: 52 53 cc_library("...") { 54 # ... 55 deps = [ 56 # ... 57 "@pigweed//pw_span", 58 # ... 59 ] 60 } 61 62 This assumes that your Bazel ``WORKSPACE`` has a `repository 63 <https://bazel.build/concepts/build-ref#repositories>`_ named ``@pigweed`` 64 that points to the upstream Pigweed repository. 65 66 .. tab-item:: GN 67 68 Add ``$dir_pw_span`` to the ``deps`` list in your ``pw_executable()`` 69 build target: 70 71 .. code-block:: 72 73 pw_executable("...") { 74 # ... 75 deps = [ 76 # ... 77 "$dir_pw_span", 78 # ... 79 ] 80 } 81 82 .. tab-item:: CMake 83 84 Add ``pw_span`` to your ``pw_add_library`` or similar CMake target: 85 86 .. code-block:: 87 88 pw_add_library(my_library STATIC 89 HEADERS 90 ... 91 PRIVATE_DEPS 92 # ... 93 pw_span 94 # ... 95 ) 96 97 .. tab-item:: Zephyr 98 99 There are two ways to use ``pw_span`` from a Zephyr project: 100 101 #. Depend on ``pw_span`` in your CMake target (see CMake tab). This is 102 Pigweed Team's suggested approach since it enables precise CMake 103 dependency analysis. 104 105 #. Add ``CONFIG_PIGWEED_SPAN=y`` to the Zephyr project's configuration, 106 which causes ``pw_span`` to become a global dependency and have the 107 includes exposed to all targets. Pigweed team does not recommend this 108 approach, though it is the typical Zephyr solution. 109 110------ 111Guides 112------ 113 114Operating on arrays of bytes 115============================ 116When operating on an array of bytes you typically need pointer and size 117arguments: 118 119.. code-block:: cpp 120 121 bool ProcessBuffer(char* buffer, size_t buffer_size); 122 123 bool DoStuff() { 124 ProcessBuffer(c_array, sizeof(c_array)); 125 ProcessBuffer(array_object.data(), array_object.size()); 126 ProcessBuffer(data_pointer, data_size); 127 } 128 129With ``pw::span`` you can pass the buffer as a single argument instead: 130 131.. include:: docs.rst 132 :start-after: .. pw_span-example-start 133 :end-before: .. pw_span-example-end 134 135Working with spans of binary data 136================================= 137Use ``pw::span<std::byte>`` or ``pw::span<const std::byte>`` to represent 138spans of binary data. Convert spans to byte spans with ``pw::as_bytes`` or 139``pw::as_writable_bytes``. 140 141.. code-block:: cpp 142 143 void ProcessData(pw::span<const std::byte> data); 144 145 void DoStuff() { 146 std::array<AnyType, 7> data = { ... }; 147 ProcessData(pw::as_bytes(pw::span(data))); 148 } 149 150``pw_bytes/span.h`` provides ``ByteSpan`` and ``ConstByteSpan`` aliases for 151these types. 152 153---------- 154References 155---------- 156 157API reference 158============= 159See `std::span <https://en.cppreference.com/w/cpp/container/span>`_. 160The ``pw::span`` API is designed to match the ``std::span`` API. 161 162Configuration options 163===================== 164The following configurations can be adjusted via compile-time configuration of 165this module, see the 166:ref:`module documentation <module-structure-compile-time-configuration>` for 167more details. 168 169.. doxygendefine:: PW_SPAN_ENABLE_ASSERTS 170