blob: dbfc0536481e8e3e9dff3b509fdc6c839d931167 [file] [log] [blame]
.. _chapter-pw-span:
.. default-domain:: cpp
.. highlight:: sh
The pw_span module provides an implementation of C++20's
`std::span <>`_, which is a
non-owning view of an array of values. The intent is for ``pw::span``'s
interface to exactly match ``std::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
Functions operating on an array of bytes typically accept pointer and size
.. code-block:: cpp
bool ProcessBuffer(char* buffer, size_t buffer_size);
bool DoStuff() {
ProcessBuffer(c_array, sizeof(c_array));
ProcessBuffer(, array_object.size());
ProcessBuffer(data_pointer, data_size);
Pointer and size arguments can be replaced with a ``pw::span``:
.. code-block:: cpp
// With pw::span, the buffer is passed as a single argument.
bool ProcessBuffer(const pw::span<uint8_t>& buffer);
bool DoStuff() {
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.
.. code-block:: cpp
void ProcessData(pw::span<const std::byte> data);
void DoStuff() {
std::array<AnyType, 7> data = { ... };