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