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