pw_span

The pw_span module provides pw::span, an implementation of C++20’s std::span. std::span is a non-owning view of an array of values. The intent is for pw::span is to match the C++20 standard as closely as possible.

If C++20’s std::span is available, pw::span is simply an alias of it.

Using pw::span

Pigweed AI summary: The article discusses the use of pw::span, which is a convenient abstraction that wraps a pointer and a size, and is useful in APIs. Spans support implicit conversions from C arrays, std::array, or any STL-style container, such as std::string_view. Functions operating on an array of bytes can be simplified by replacing pointer and size arguments with a pw::span. The article also provides tips on using pw::span to represent spans of binary data and converting any span to a byte

pw::span is a convenient abstraction that wraps a pointer and a size. pw::span is especially useful in APIs. Spans support implicit conversions from C arrays, std::array, or any STL-style container, such as std::string_view.

Functions operating on an array of bytes typically accept pointer and size arguments:

bool ProcessBuffer(char* buffer, size_t buffer_size);

bool DoStuff() {
  ProcessBuffer(c_array, sizeof(c_array));
  ProcessBuffer(array_object.data(), array_object.size());
  ProcessBuffer(data_pointer, data_size);
}

Pointer and size arguments can be replaced with a pw::span:

#include <span>

// With pw::span, the buffer is passed as a single argument.
bool ProcessBuffer(pw::span<uint8_t> buffer);

bool DoStuff() {
  ProcessBuffer(c_array);
  ProcessBuffer(array_object);
  ProcessBuffer(pw::span(data_pointer, data_size));
}

Tip

Use pw::span<std::byte> or pw::span<const std::byte> to represent spans of binary data. Use pw::as_bytes or pw::as_writable_bytes to convert any span to a byte span.

void ProcessData(pw::span<const std::byte> data);

void DoStuff() {
  std::array<AnyType, 7> data = { ... };
  ProcessData(pw::as_bytes(pw::span(data)));
}

pw_bytes/span.h provides ByteSpan and ConstByteSpan aliases for these types.

Module Configuration Options

The following configurations can be adjusted via compile-time configuration of this module, see the module documentation for more details.

PW_SPAN_ENABLE_ASSERTS

PW_SPAN_ENABLE_ASSERTS controls whether pw_span’s implementation includes asserts for detecting disallowed span operations at runtime. For C++20 and later, this replaces std::span with the custom implementation in pw_span to ensure bounds-checking asserts have been enabled.

This defaults to disabled because of the significant increase in code size caused by enabling this feature. It’s strongly recommended to enable this in debug and testing builds. This can be done by setting pw_span_ENABLE_ASSERTS to true in the GN build.

Compatibility

Pigweed AI summary: This section discusses the compatibility of the program with different versions of C++. It states that the program works with C++14, but some features require C++17. It also suggests using "std::span" instead in C++20.

Works with C++14, but some features require C++17. In C++20, use std::span instead.

Zephyr

Pigweed AI summary: To use pw_span in Zephyr, simply add CONFIG_PIGWEED_SPAN=y to the project's configuration.

To enable pw_span for Zephyr add CONFIG_PIGWEED_SPAN=y to the project’s configuration.