third_party/pigweed/repo/pw_span/docs.rst

   1 .. _module-pw_span:
   2
   3 -------
   4 pw_span
   5 -------
   6 The ``pw_span`` module provides an implementation of C++20's
   7 `std::span <https://en.cppreference.com/w/cpp/container/span>`_, which is a
   8 non-owning view of an array of values. The intent is for this implementation of
   9 ``std::span`` is to exactly match the C++20 standard.
  10
  11 The only header provided by the ``pw_span`` module is ``<span>``. It is included
  12 as if it were coming from the C++ Standard Library. If the C++ library provides
  13 ``<span>``, the library's version of ``std::span`` is used in place of
  14 ``pw_span``'s.
  15
  16 ``pw_span`` requires two include paths -- ``public/`` and ``public_overrides/``.
  17 The internal implementation header is in ``public/``, and the ``<span>`` header
  18 that mimics the C++ Standard Library is in ``public_overrides/``.
  19
  20 Using std::span
  21 ===============
  22 ``std::span`` is a convenient abstraction that wraps a pointer and a size.
  23 ``std::span`` is especially useful in APIs. Spans support implicit conversions
  24 from C arrays, ``std::array``, or any STL-style container, such as
  25 ``std::string_view``.
  26
  27 Functions operating on an array of bytes typically accept pointer and size
  28 arguments:
  29
  30 .. code-block:: cpp
  31
  32   bool ProcessBuffer(char* buffer, size_t buffer_size);
  33
  34   bool DoStuff() {
  35     ProcessBuffer(c_array, sizeof(c_array));
  36     ProcessBuffer(array_object.data(), array_object.size());
  37     ProcessBuffer(data_pointer, data_size);
  38   }
  39
  40 Pointer and size arguments can be replaced with a ``std::span``:
  41
  42 .. code-block:: cpp
  43
  44   #include <span>
  45
  46   // With std::span, the buffer is passed as a single argument.
  47   bool ProcessBuffer(std::span<uint8_t> buffer);
  48
  49   bool DoStuff() {
  50     ProcessBuffer(c_array);
  51     ProcessBuffer(array_object);
  52     ProcessBuffer(std::span(data_pointer, data_size));
  53   }
  54
  55 .. tip::
  56   Use ``std::span<std::byte>`` or ``std::span<const std::byte>`` to represent
  57   spans of binary data. Use ``std::as_bytes`` or ``std::as_writeable_bytes``
  58   to convert any span to a byte span.
  59
  60   .. code-block:: cpp
  61
  62     void ProcessData(std::span<const std::byte> data);
  63
  64     void DoStuff() {
  65       std::array<AnyType, 7> data = { ... };
  66       ProcessData(std::as_bytes(std::span(data)));
  67     }
  68
  69 Compatibility
  70 =============
  71 Works with C++11, but some features require C++17.