endianness.py

"""
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
"""


def 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
    """
    if value < 0 or value > 0xFFFF:
        msg = f"value must be between 0 and {0xFFFF}"
        raise ValueError(msg)

    return ((value & 0xFF) << 8) | ((value & 0xFF00) >> 8)


def 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
    """
    if value < 0 or value > 0xFFFFFFFF:
        msg = f"value must be between 0 and {0xFFFFFFFF}"
        raise ValueError(msg)

    return (
        ((value & 0x000000FF) << 24)
        | ((value & 0x0000FF00) << 8)
        | ((value & 0x00FF0000) >> 8)
        | ((value & 0xFF000000) >> 24)
    )


def 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
    """
    if value < 0 or value > 0xFFFFFFFFFFFFFFFF:
        msg = f"value must be between 0 and {0xFFFFFFFFFFFFFFFF}"
        raise ValueError(msg)

    return (
        ((value & 0x00000000000000FF) << 56)
        | ((value & 0x000000000000FF00) << 40)
        | ((value & 0x0000000000FF0000) << 24)
        | ((value & 0x00000000FF000000) << 8)
        | ((value & 0x000000FF00000000) >> 8)
        | ((value & 0x0000FF0000000000) >> 24)
        | ((value & 0x00FF000000000000) >> 40)
        | ((value & 0xFF00000000000000) >> 56)
    )


def 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
    """
    if not data or len(data) > 8:
        msg = "data must be between 1 and 8 bytes"
        raise ValueError(msg)

    return int.from_bytes(data, byteorder="little")


def 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
    """
    if not data or len(data) > 8:
        msg = "data must be between 1 and 8 bytes"
        raise ValueError(msg)

    return int.from_bytes(data, byteorder="big")


def 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'
    """
    if value < 0:
        msg = "value must be non-negative"
        raise ValueError(msg)

    if num_bytes < 1 or num_bytes > 8:
        msg = "num_bytes must be between 1 and 8"
        raise ValueError(msg)

    if value >= (1 << (num_bytes * 8)):
        msg = f"value {value} too large for {num_bytes} bytes"
        raise ValueError(msg)

    return value.to_bytes(num_bytes, byteorder="little")


def 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'
    """
    if value < 0:
        msg = "value must be non-negative"
        raise ValueError(msg)

    if num_bytes < 1 or num_bytes > 8:
        msg = "num_bytes must be between 1 and 8"
        raise ValueError(msg)

    if value >= (1 << (num_bytes * 8)):
        msg = f"value {value} too large for {num_bytes} bytes"
        raise ValueError(msg)

    return value.to_bytes(num_bytes, byteorder="big")


if __name__ == "__main__":
    import doctest

    _ = doctest.testmod()

    print("Endianness Conversion Examples:")
    print(f"16-bit: 0x1234 → {hex(swap_endianness_16(0x1234))}")
    print(f"32-bit: 0x12345678 → {hex(swap_endianness_32(0x12345678))}")
    print(f"64-bit: 0x0123456789ABCDEF → {hex(swap_endianness_64(0x0123456789ABCDEF))}")
    print(f"Bytes to int (little): {bytes_to_int_little(b'\x78\x56\x34\x12'):#x}")
    print(f"Bytes to int (big): {bytes_to_int_big(b'\x12\x34\x56\x78'):#x}")