conversions.endianness
======================

.. py:module:: conversions.endianness

.. autoapi-nested-parse::

   Endianness Conversion Algorithm

   This module implements endianness (byte order) conversion utilities for converting
   between big-endian and little-endian representations of multi-byte integers.

   Endianness refers to the order of bytes in a multi-byte data type:
   - Big-endian: Most significant byte first (e.g., 0x12345678 → [0x12, 0x34, 0x56, 0x78])
   - Little-endian: Least significant byte first
     (e.g., 0x12345678 → [0x78, 0x56, 0x34, 0x12])

   Common uses:
   - Network protocols (TCP/IP uses big-endian for multi-byte fields)
   - File format parsing (PNG, JPEG headers specify endianness)
   - Cryptographic algorithms (MD5 uses little-endian, SHA-256 uses big-endian)
   - Binary data serialization (Protocol Buffers, MessagePack)
   - Hardware interfacing (ARM is bi-endian, x86 is strictly little-endian)
   - Cross-platform data exchange

   Real-world examples:
   - IP addresses are transmitted in big-endian (network byte order)
   - Modern ARM and x86 processors typically operate in little-endian mode
   - Java class files use big-endian format
   - Bitcoin uses little-endian for block hashes
   - USB and PCI protocols use little-endian

   References:
   - https://en.wikipedia.org/wiki/Endianness
   - RFC 1700 (Network Byte Order)
   - https://tools.ietf.org/html/rfc1700



Attributes
----------

.. autoapisummary::

   conversions.endianness._


Functions
---------

.. autoapisummary::

   conversions.endianness.bytes_to_int_big
   conversions.endianness.bytes_to_int_little
   conversions.endianness.int_to_bytes_big
   conversions.endianness.int_to_bytes_little
   conversions.endianness.swap_endianness_16
   conversions.endianness.swap_endianness_32
   conversions.endianness.swap_endianness_64


Module Contents
---------------

.. py:function:: bytes_to_int_big(data: bytes) -> int

   Convert bytes to integer using big-endian byte order.

   Args:
       data: Byte sequence to convert (1-8 bytes)

   Returns:
       Integer representation in big-endian order

   Raises:
       TypeError: If data is not bytes
       ValueError: If data is empty or exceeds 8 bytes

   >>> bytes_to_int_big(b'\x12\x34\x56\x78')
   305419896

   >>> hex(bytes_to_int_big(b'\x12\x34\x56\x78'))
   '0x12345678'

   >>> bytes_to_int_big(b'\x01\x02')
   258

   >>> bytes_to_int_big(b'\xff')
   255

   >>> bytes_to_int_big(b'\x00\x00\x00\x01')
   1


.. py:function:: bytes_to_int_little(data: bytes) -> int

   Convert bytes to integer using little-endian byte order.

   Args:
       data: Byte sequence to convert (1-8 bytes)

   Returns:
       Integer representation in little-endian order

   Raises:
       TypeError: If data is not bytes
       ValueError: If data is empty or exceeds 8 bytes

   >>> bytes_to_int_little(b'\x78\x56\x34\x12')
   305419896

   >>> hex(bytes_to_int_little(b'\x78\x56\x34\x12'))
   '0x12345678'

   >>> bytes_to_int_little(b'\x01\x02')
   513

   >>> bytes_to_int_little(b'\xff')
   255

   >>> bytes_to_int_little(b'\x00\x00\x00\x01')
   16777216


.. py:function:: int_to_bytes_big(value: int, num_bytes: int) -> bytes

   Convert integer to bytes using big-endian byte order.

   Args:
       value: Integer to convert (non-negative)
       num_bytes: Number of bytes in output (1-8)

   Returns:
       Bytes representation in big-endian order

   Raises:
       ValueError: If value is negative, num_bytes invalid, or value too large

   >>> int_to_bytes_big(0x12345678, 4)
   b'\x124Vx'

   >>> int_to_bytes_big(258, 2)
   b'\x01\x02'

   >>> int_to_bytes_big(255, 1)
   b'\xff'

   >>> int_to_bytes_big(1, 4)
   b'\x00\x00\x00\x01'


.. py:function:: int_to_bytes_little(value: int, num_bytes: int) -> bytes

   Convert integer to bytes using little-endian byte order.

   Args:
       value: Integer to convert (non-negative)
       num_bytes: Number of bytes in output (1-8)

   Returns:
       Bytes representation in little-endian order

   Raises:
       ValueError: If value is negative, num_bytes invalid, or value too large

   >>> int_to_bytes_little(0x12345678, 4)
   b'xV4\x12'

   >>> int_to_bytes_little(513, 2)
   b'\x01\x02'

   >>> int_to_bytes_little(255, 1)
   b'\xff'

   >>> int_to_bytes_little(16777216, 4)
   b'\x00\x00\x00\x01'


.. py:function:: swap_endianness_16(value: int) -> int

   Swap the byte order of a 16-bit integer.

   Args:
       value: 16-bit integer (0 to 65,535)

   Returns:
       Integer with swapped byte order

   Raises:
       ValueError: If value is negative or exceeds 16-bit range

   >>> swap_endianness_16(0x1234)
   13330

   >>> hex(swap_endianness_16(0x1234))
   '0x3412'

   >>> swap_endianness_16(0xABCD)
   52651

   >>> hex(swap_endianness_16(0xABCD))
   '0xcdab'

   >>> swap_endianness_16(0)
   0

   >>> swap_endianness_16(0xFFFF)
   65535


.. py:function:: swap_endianness_32(value: int) -> int

   Swap the byte order of a 32-bit integer.

   Args:
       value: 32-bit integer (0 to 4,294,967,295)

   Returns:
       Integer with swapped byte order

   Raises:
       ValueError: If value is negative or exceeds 32-bit range

   >>> swap_endianness_32(0x12345678)
   2018915346

   >>> hex(swap_endianness_32(0x12345678))
   '0x78563412'

   >>> swap_endianness_32(0xDEADBEEF)
   4022250974

   >>> hex(swap_endianness_32(0xDEADBEEF))
   '0xefbeadde'

   >>> swap_endianness_32(0)
   0

   >>> swap_endianness_32(0xFFFFFFFF)
   4294967295

   >>> swap_endianness_32(0x01020304)
   67305985


.. py:function:: swap_endianness_64(value: int) -> int

   Swap the byte order of a 64-bit integer.

   Args:
       value: 64-bit integer (0 to 18,446,744,073,709,551,615)

   Returns:
       Integer with swapped byte order

   Raises:
       ValueError: If value is negative or exceeds 64-bit range

   >>> swap_endianness_64(0x0123456789ABCDEF)
   17279655951921914625

   >>> hex(swap_endianness_64(0x0123456789ABCDEF))
   '0xefcdab8967452301'

   >>> swap_endianness_64(0xFEDCBA9876543210)
   1167088121787636990

   >>> hex(swap_endianness_64(0xFEDCBA9876543210))
   '0x1032547698badcfe'

   >>> swap_endianness_64(0)
   0

   >>> swap_endianness_64(0xFFFFFFFFFFFFFFFF)
   18446744073709551615


.. py:data:: _