1.. _module-pw_bytes: 2 3========= 4pw_bytes 5========= 6pw_bytes is a collection of utilities for manipulating binary data. 7 8------------- 9Compatibility 10------------- 11C++17 12 13------------ 14Dependencies 15------------ 16* ``pw_preprocessor`` 17* ``pw_status`` 18* ``pw_span`` 19 20-------- 21Features 22-------- 23 24pw_bytes/array.h 25================ 26Functions for working with byte arrays, primarily for building fixed-size byte 27arrays at compile time. 28 29pw_bytes/byte_builder.h 30======================= 31.. cpp:class:: ByteBuilder 32 33 ``ByteBuilder`` is a class that facilitates building or reading arrays of 34 bytes in a fixed-size buffer. ByteBuilder handles reading and writing integers 35 with varying endianness. 36 37.. cpp:class:: template <size_t kMaxSize> ByteBuffer 38 39 ``ByteBuilder`` with an internally allocated buffer. 40 41Size report: using ByteBuffer 42----------------------------- 43.. include:: byte_builder_size_report 44 45pw_bytes/bit.h 46================ 47Implementation of features provided by C++20's ``<bit>`` header. Supported 48features: 49 50* ``pw::endian`` -- Implementation of the ``std::endian`` enum. If 51 ``std::endian`` is available, ``pw::endian`` is an alias of it. 52 53pw_bytes/endian.h 54================= 55Functions for converting the endianness of integral values. 56 57pw_bytes/units.h 58================ 59Constants, functions and user-defined literals for specifying a number of bytes 60in powers of two, as defined by IEC 60027-2 A.2 and ISO/IEC 80000:13-2008. 61 62The supported suffixes include: 63 64* ``_B`` for bytes (1024\ :sup:`0`) 65* ``_KiB`` for kibibytes (1024\ :sup:`1`) 66* ``_MiB`` for mebibytes (1024\ :sup:`2`) 67* ``_GiB`` for gibibytes (1024\ :sup:`3`) 68* ``_TiB`` for tebibytes (1024\ :sup:`4`) 69* ``_PiB`` for pebibytes (1024\ :sup:`5`) 70* ``_EiB`` for exbibytes (1024\ :sup:`6`) 71 72In order to use these you must use a using namespace directive, for example: 73 74.. code-block:: cpp 75 76 #include "pw_bytes/units.h" 77 78 using namespace pw::bytes::unit_literals; 79 80 constexpr size_t kRandomBufferSizeBytes = 1_MiB + 42_KiB; 81 82In some cases, the use of user-defined literals is not permitted because of the 83required using namespace directive. One example of this is in header files, 84where it is undesirable to pollute the namespace. For this situation, there are 85also similar functions: 86 87.. code-block:: cpp 88 89 #include "pw_bytes/units.h" 90 91 constexpr size_t kBufferSizeBytes = pw::bytes::MiB(1) + pw::bytes::KiB(42); 92 93------ 94Zephyr 95------ 96To enable ``pw_bytes`` for Zephyr add ``CONFIG_PIGWEED_BYTES=y`` to the 97project's configuration. 98