Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_bytes: |
shaneajg | 9c19db4 | 2020-06-11 15:49:51 -0400 | [diff] [blame] | 2 | |
| 3 | --------- |
| 4 | pw_bytes |
| 5 | --------- |
| 6 | pw_bytes is a collection of utilities for manipulating binary data. |
| 7 | |
| 8 | Compatibility |
| 9 | ============= |
| 10 | C++17 |
| 11 | |
| 12 | Dependencies |
| 13 | ============ |
| 14 | * ``pw_preprocessor`` |
| 15 | * ``pw_status`` |
| 16 | * ``pw_span`` |
| 17 | |
| 18 | Features |
| 19 | ======== |
| 20 | |
Wyatt Hepler | 05ca54c | 2020-09-02 17:04:59 -0700 | [diff] [blame] | 21 | pw_bytes/array.h |
| 22 | ---------------- |
| 23 | Functions for working with byte arrays, primarily for building fixed-size byte |
| 24 | arrays at compile time. |
shaneajg | 9c19db4 | 2020-06-11 15:49:51 -0400 | [diff] [blame] | 25 | |
Wyatt Hepler | 05ca54c | 2020-09-02 17:04:59 -0700 | [diff] [blame] | 26 | pw_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 | |
Ewout van Bekkum | 5ea3340 | 2021-03-31 11:00:02 -0700 | [diff] [blame] | 34 | .. cpp:class:: template <size_t kMaxSize> ByteBuffer |
Wyatt Hepler | 05ca54c | 2020-09-02 17:04:59 -0700 | [diff] [blame] | 35 | |
| 36 | ``ByteBuilder`` with an internally allocated buffer. |
shaneajg | 3181d18 | 2020-06-17 20:17:23 -0400 | [diff] [blame] | 37 | |
shaneajg | f20ef8e | 2020-06-30 16:15:58 -0400 | [diff] [blame] | 38 | Size report: using ByteBuffer |
| 39 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 40 | .. include:: byte_builder_size_report |
| 41 | |
Wyatt Hepler | 05ca54c | 2020-09-02 17:04:59 -0700 | [diff] [blame] | 42 | pw_bytes/endian.h |
| 43 | ----------------- |
| 44 | Functions for converting the endianness of integral values. |
Ewout van Bekkum | 2a5f4da | 2021-08-02 13:44:10 -0700 | [diff] [blame] | 45 | |
| 46 | pw_bytes/units.h |
| 47 | ---------------- |
RJ Ascani | 04f7e41 | 2022-02-16 15:20:20 -0800 | [diff] [blame] | 48 | Constants, functions and user-defined literals for specifying a number of bytes |
| 49 | in powers of two, as defined by IEC 60027-2 A.2 and ISO/IEC 80000:13-2008. |
Ewout van Bekkum | 2a5f4da | 2021-08-02 13:44:10 -0700 | [diff] [blame] | 50 | |
| 51 | The 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 | |
| 60 | In 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; |
Yuval Peress | b8f3ad2 | 2021-10-26 22:55:27 -0600 | [diff] [blame] | 69 | |
RJ Ascani | 04f7e41 | 2022-02-16 15:20:20 -0800 | [diff] [blame] | 70 | In some cases, the use of user-defined literals is not permitted because of the |
| 71 | required using namespace directive. One example of this is in header files, |
| 72 | where it is undesirable to pollute the namespace. For this situation, there are |
| 73 | also 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 | |
Yuval Peress | b8f3ad2 | 2021-10-26 22:55:27 -0600 | [diff] [blame] | 81 | Zephyr |
| 82 | ====== |
| 83 | To enable ``pw_bytes`` for Zephyr add ``CONFIG_PIGWEED_BYTES=y`` to the |
| 84 | project's configuration. |