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.

Note

pw_span:polyfill provides <span> and a std::span class. However, this std::span polyfill is DEPRECATED; do NOT use it for new code. Use pw::span instead, or std::span if you are building with C++20.

To use the std::span polyfill, set the GN arg pw_span_ENABLE_STD_SPAN_POLYFILL to true. This makes std::span available and makes pw::span an alias of it.

Using pw::span

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

Compatibility

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

Zephyr

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