85 lines
2.1 KiB
ReStructuredText
85 lines
2.1 KiB
ReStructuredText
.. _module-pw_bytes:
|
|
|
|
---------
|
|
pw_bytes
|
|
---------
|
|
pw_bytes is a collection of utilities for manipulating binary data.
|
|
|
|
Compatibility
|
|
=============
|
|
C++17
|
|
|
|
Dependencies
|
|
============
|
|
* ``pw_preprocessor``
|
|
* ``pw_status``
|
|
* ``pw_span``
|
|
|
|
Features
|
|
========
|
|
|
|
pw_bytes/array.h
|
|
----------------
|
|
Functions for working with byte arrays, primarily for building fixed-size byte
|
|
arrays at compile time.
|
|
|
|
pw_bytes/byte_builder.h
|
|
-----------------------
|
|
.. cpp:class:: ByteBuilder
|
|
|
|
``ByteBuilder`` is a class that facilitates building or reading arrays of
|
|
bytes in a fixed-size buffer. ByteBuilder handles reading and writing integers
|
|
with varying endianness.
|
|
|
|
.. cpp:class:: template <size_t kMaxSize> ByteBuffer
|
|
|
|
``ByteBuilder`` with an internally allocated buffer.
|
|
|
|
Size report: using ByteBuffer
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
.. include:: byte_builder_size_report
|
|
|
|
pw_bytes/endian.h
|
|
-----------------
|
|
Functions for converting the endianness of integral values.
|
|
|
|
pw_bytes/units.h
|
|
----------------
|
|
Constants, functions and user-defined literals for specifying a number of bytes
|
|
in powers of two, as defined by IEC 60027-2 A.2 and ISO/IEC 80000:13-2008.
|
|
|
|
The supported suffixes include:
|
|
* ``_B`` for bytes (1024^0)
|
|
* ``_KiB`` for kibibytes (1024^1)
|
|
* ``_MiB`` for mibibytes (1024^2)
|
|
* ``_GiB`` for gibibytes (1024^3)
|
|
* ``_TiB`` for tebibytes (1024^4)
|
|
* ``_PiB`` for pebibytes (1024^5)
|
|
* ``_EiB`` for exbibytes (1024^6)
|
|
|
|
In order to use these you must use a using namespace directive, for example:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include "pw_bytes/units.h"
|
|
|
|
using namespace pw::bytes::unit_literals;
|
|
|
|
constexpr size_t kRandomBufferSizeBytes = 1_MiB + 42_KiB;
|
|
|
|
In some cases, the use of user-defined literals is not permitted because of the
|
|
required using namespace directive. One example of this is in header files,
|
|
where it is undesirable to pollute the namespace. For this situation, there are
|
|
also similar functions:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include "pw_bytes/units.h"
|
|
|
|
constexpr size_t kBufferSizeBytes = pw::bytes::MiB(1) + pw::bytes::KiB(42);
|
|
|
|
Zephyr
|
|
======
|
|
To enable ``pw_bytes`` for Zephyr add ``CONFIG_PIGWEED_BYTES=y`` to the
|
|
project's configuration.
|