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.. TODO: b/388905812 - Re-enable the size report. 66.. .. include:: byte_builder_size_report 67.. include:: ../size_report_notice 68 69pw_bytes/bit.h 70================ 71Implementation of features provided by C++20's ``<bit>`` header. Supported 72features: 73 74* ``pw::endian`` -- Implementation of the ``std::endian`` enum. If 75 ``std::endian`` is available, ``pw::endian`` is an alias of it. 76 77* Additional functions for bit-level operations. 78 79 .. doxygenfunction:: pw::bytes::SignExtend 80 .. doxygenfunction:: pw::bytes::ExtractBits 81 82pw_bytes/endian.h 83================= 84Functions for converting the endianness of integral values. 85 86pw_bytes/suffix.h 87================= 88This module exports a single ``_b`` literal, making it easier to create 89``std::byte`` values for tests. 90 91.. cpp:function:: constexpr std::byte operator""_b(unsigned long long value) 92 93.. note:: 94 This should not be used in header files, as it requires a ``using`` 95 declaration that will be publicly exported at whatever level it is 96 used. 97 98Example: 99 100.. code-block:: cpp 101 102 #include "pw_bytes/units.h" 103 104 using ::pw::operator""_b; 105 106 constexpr std::byte kValue = 5_b; 107 108pw_bytes/units.h 109================ 110Constants, functions and user-defined literals for specifying a number of bytes 111in powers of two, as defined by IEC 60027-2 A.2 and ISO/IEC 80000:13-2008. 112 113The supported suffixes include: 114 115* ``_B`` for bytes (1024\ :sup:`0`) 116* ``_KiB`` for kibibytes (1024\ :sup:`1`) 117* ``_MiB`` for mebibytes (1024\ :sup:`2`) 118* ``_GiB`` for gibibytes (1024\ :sup:`3`) 119* ``_TiB`` for tebibytes (1024\ :sup:`4`) 120* ``_PiB`` for pebibytes (1024\ :sup:`5`) 121* ``_EiB`` for exbibytes (1024\ :sup:`6`) 122 123In order to use these you must use a using namespace directive, for example: 124 125.. code-block:: cpp 126 127 #include "pw_bytes/units.h" 128 129 using namespace pw::bytes::unit_literals; 130 131 constexpr size_t kRandomBufferSizeBytes = 1_MiB + 42_KiB; 132 133In some cases, the use of user-defined literals is not permitted because of the 134required using namespace directive. One example of this is in header files, 135where it is undesirable to pollute the namespace. For this situation, there are 136also similar functions: 137 138.. code-block:: cpp 139 140 #include "pw_bytes/units.h" 141 142 constexpr size_t kBufferSizeBytes = pw::bytes::MiB(1) + pw::bytes::KiB(42); 143 144------ 145Zephyr 146------ 147To enable ``pw_bytes`` for Zephyr add ``CONFIG_PIGWEED_BYTES=y`` to the 148project's configuration. 149 150-------- 151Rust API 152-------- 153``pw_bytes``'s Rust API is documented in our 154`rustdoc API docs </rustdoc/pw_bytes/>`_. 155