62 lines
2.2 KiB
ReStructuredText
62 lines
2.2 KiB
ReStructuredText
|
|
.. _packing:
|
|
|
|
==========================
|
|
Packing / Unpacking Values
|
|
==========================
|
|
|
|
A few of Spicy's atomic types support low-level conversion from, or
|
|
into, a binary representation through two operators:
|
|
|
|
- ``pack(VALUE, ARGS)`` turns a ``VALUE`` into a sequence of raw bytes
|
|
representing the value in binary form. ``ARGS`` specify what
|
|
encoding to use for the representation; they are type-specific (see
|
|
below for a list). The ``pack`` operator returns a ``bytes``
|
|
instance containing the encoded data.
|
|
|
|
As an example, ``pack(uint16(513), spicy::ByteOrder::Network)``
|
|
returns ``\x02\x01``, which is 513 in network byte order.
|
|
|
|
- ``unpack<TYPE>(DATA, ARGS)`` parses a value of type ``TYPE`` from a
|
|
binary representation ``DATA``. ``ARGS`` specify what encoding to
|
|
expect for ``DATA``. The ``unpack`` operator returns a 2-tuple
|
|
``(VALUE, REMAINDER)`` where ``VALUE`` is the parsed value, and
|
|
``REMAINDER`` is any bytes left over from ``DATA`` that weren't used
|
|
for parsing the value. If parsing fails, ``unpack`` throws an
|
|
``InvalidValue`` exception.
|
|
|
|
As an example, ``unpack<uint16>(b"\x02\x01XYZ",
|
|
spicy::ByteOrder::Network)`` returns the tuple ``(513, b"XYZ")``.
|
|
|
|
The following table summarizes the types that currently support
|
|
packing/unpacking, along with the encoding arguments that the
|
|
operators expect for each:
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:align: left
|
|
|
|
* - Type
|
|
- ``pack``
|
|
- ``unpack``
|
|
- Links
|
|
|
|
* - :ref:`type_address`
|
|
- ``pack(VALUE, spicy::ByteOrder)``
|
|
- ``unpack<addr>(DATA, spicy::ByteOrder)``
|
|
- :ref:`Address Family <spicy_addressfamily>`, :ref:`Byte Order <spicy_byteorder>`
|
|
|
|
* - :ref:`type_integer`
|
|
- ``pack(VALUE, spicy::ByteOrder)``
|
|
- ``unpack<uintX|intX>(DATA, spicy::ByteOrder)``
|
|
- :ref:`Address Family <spicy_addressfamily>`, :ref:`Byte Order <spicy_byteorder>`
|
|
|
|
* - :ref:`type_real`
|
|
- ``pack(VALUE, spicy::RealType, spicy::ByteOrder)``
|
|
- ``unpack<real>(DATA, spicy::RealType, spicy::ByteOrder)``
|
|
- :ref:`Real Type <spicy_realtype>` [1], :ref:`Byte Order <spicy_byteorder>`
|
|
|
|
.. note::
|
|
|
|
[1] Packing a ``real`` value as ``IEEE754_Single`` may loose information.
|