1.. _module-pw_bytes: 2 3======== 4pw_bytes 5======== 6.. pigweed-module:: 7 :name: pw_bytes 8 9pw_bytes is a collection of utilities for manipulating binary data. 10 11------------ 12Dependencies 13------------ 14* ``pw_preprocessor`` 15* ``pw_status`` 16* ``pw_span`` 17 18-------- 19Features 20-------- 21 22pw_bytes/alignment.h 23==================== 24Functions for aligning sizes and addresses to memory alignment boundaries. 25 26 .. doxygenfunction:: pw::AlignDown(size_t value, size_t alignment) 27 28 .. doxygenfunction:: pw::AlignDown(T* value, size_t alignment) 29 30 .. doxygenfunction:: pw::AlignUp(size_t value, size_t alignment) 31 32 .. doxygenfunction:: pw::AlignUp(T* value, size_t alignment) 33 34 .. doxygenfunction:: pw::Padding 35 36 .. doxygenfunction:: pw::GetAlignedSubspan 37 38pw_bytes/array.h 39================ 40Functions for working with byte arrays, primarily for building fixed-size byte 41arrays at compile time. 42 43pw_bytes/byte_builder.h 44======================= 45.. doxygenclass:: pw::ByteBuilder 46 :members: 47 48.. doxygenclass:: pw::ByteBuffer 49 :members: 50 51Size report: using ByteBuffer 52----------------------------- 53.. include:: byte_builder_size_report 54 55pw_bytes/bit.h 56================ 57Implementation of features provided by C++20's ``<bit>`` header. Supported 58features: 59 60* ``pw::endian`` -- Implementation of the ``std::endian`` enum. If 61 ``std::endian`` is available, ``pw::endian`` is an alias of it. 62 63* Additional functions for bit-level operations. 64 65 .. doxygenfunction:: pw::bytes::SignExtend 66 .. doxygenfunction:: pw::bytes::ExtractBits 67 68pw_bytes/endian.h 69================= 70Functions for converting the endianness of integral values. 71 72pw_bytes/suffix.h 73================= 74This module exports a single ``_b`` literal, making it easier to create 75``std::byte`` values for tests. 76 77.. cpp:function:: constexpr std::byte operator"" _b(unsigned long long value) 78 79.. note:: 80 This should not be used in header files, as it requires a ``using`` 81 declaration that will be publicly exported at whatever level it is 82 used. 83 84Example: 85 86.. code-block:: cpp 87 88 #include "pw_bytes/units.h" 89 90 using ::pw::operator""_b; 91 92 constexpr std::byte kValue = 5_b; 93 94pw_bytes/units.h 95================ 96Constants, functions and user-defined literals for specifying a number of bytes 97in powers of two, as defined by IEC 60027-2 A.2 and ISO/IEC 80000:13-2008. 98 99The supported suffixes include: 100 101* ``_B`` for bytes (1024\ :sup:`0`) 102* ``_KiB`` for kibibytes (1024\ :sup:`1`) 103* ``_MiB`` for mebibytes (1024\ :sup:`2`) 104* ``_GiB`` for gibibytes (1024\ :sup:`3`) 105* ``_TiB`` for tebibytes (1024\ :sup:`4`) 106* ``_PiB`` for pebibytes (1024\ :sup:`5`) 107* ``_EiB`` for exbibytes (1024\ :sup:`6`) 108 109In order to use these you must use a using namespace directive, for example: 110 111.. code-block:: cpp 112 113 #include "pw_bytes/units.h" 114 115 using namespace pw::bytes::unit_literals; 116 117 constexpr size_t kRandomBufferSizeBytes = 1_MiB + 42_KiB; 118 119In some cases, the use of user-defined literals is not permitted because of the 120required using namespace directive. One example of this is in header files, 121where it is undesirable to pollute the namespace. For this situation, there are 122also similar functions: 123 124.. code-block:: cpp 125 126 #include "pw_bytes/units.h" 127 128 constexpr size_t kBufferSizeBytes = pw::bytes::MiB(1) + pw::bytes::KiB(42); 129 130------ 131Zephyr 132------ 133To enable ``pw_bytes`` for Zephyr add ``CONFIG_PIGWEED_BYTES=y`` to the 134project's configuration. 135 136-------- 137Rust API 138-------- 139``pw_bytes``'s Rust API is documented in our 140`rustdoc API docs </rustdoc/pw_bytes>`_. 141