endian_cast/

lib.rs

//! This crate provides a convenient [`EndianCast`] type and a trait [`Endianness`] for
//! converting between little-endian and big-endian byte representations of various data types,
//! including a way to cast to the opposite endianness.
//!
//! ## [`EndianCast`]
//!
//! The [`EndianCast`] type is a wrapper around a value of type `T` allowing you to convert it
//! into little-endian, big-endian, native-endian, or opposite-endian byte arrays, even within
//! const contexts. When instantiating [`EndianCast`], you must specify the size of the type
//! `T` as a const generic. Providing an incorrect size will result in a panic at compile time.
//!
//! When the system endianness matches the requested endianness, the conversion is essentially
//! a no-op, and the bytes are returned as-is. When the system endianness does not match the
//! requested endianness, the bytes are reversed.
//!
//! The [`EndianCast`] interface is provided as a way to offer the same functionality as the
//! [`Endianness`] trait within const contexts, as the trait methods cannot be used in const
//! contexts.
//!
//! ### Example
//! ```
//! use endian_cast::EndianCast;
//!
//! let x = 0x12345678u32;
//! let le_bytes = EndianCast::<4, u32>(x).le_bytes();
//! let be_bytes = EndianCast::<4, u32>(x).be_bytes();
//! let op_bytes = EndianCast::<4, u32>(x).op_bytes();
//! let ne_bytes = *EndianCast::<4, u32>(x).ne_bytes();
//!
//! assert_ne!(le_bytes, be_bytes);
//! assert_ne!(ne_bytes, op_bytes);
//! assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12]);
//! assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78]);
//!
//! // usable in const contexts
//! const LE: [u8; 4] = EndianCast::<4, u32>(0x12345678).le_bytes();
//! ```
//!
//! ## [`Endianness`]
//!
//! The [`Endianness`] trait provides methods for converting to and from the byte
//! representation of the type implementing the trait. It is automatically implemented for all
//! primitive types and arrays of bytes and can easily be implemented on arbitrary types that
//! implement [`Sized`] and [`Copy`] by manually implementing the trait. As with
//! [`EndianCast`], you must specify the size of the type as a const generic, and providing an
//! incorrect size will result in a panic at compile time.
//!
//! When the system endianness matches the requested endianness, the conversion is essentially
//! a no-op, and the bytes are returned as-is. When the system endianness does not match the
//! requested endianness, the bytes are reversed.
//!
//! ### Example
//! ```
//! use endian_cast::Endianness;
//!
//! let x = 0x12345678u32;
//! let le_bytes = x.le_bytes();
//! let be_bytes = x.be_bytes();
//! let op_bytes = x.op_bytes();
//! let ne_bytes = *x.ne_bytes();
//! assert_ne!(le_bytes, be_bytes);
//! assert_ne!(ne_bytes, op_bytes);
//! assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12].into());
//! assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78].into());
//! ```

#![no_std]

use generic_array::{ArrayLength, GenericArray};
use typenum::{U1, U2, U4, U8, U16, Unsigned};

/// The [`EndianCast`] type is a wrapper around a value of type `T` allowing you to convert it
/// into little-endian, big-endian, native-endian, or opposite-endian byte arrays, even within
/// const contexts. When instantiating [`EndianCast`], you must specify the size of the type
/// `T` as a const generic. Providing an incorrect size will result in a panic at compile time.
///
/// When the system endianness matches the requested endianness, the conversion is essentially
/// a no-op, and the bytes are returned as-is. When the system endianness does not match the
/// requested endianness, the bytes are reversed.
///
/// The [`EndianCast`] interface is provided as a way to offer the same functionality as the
/// [`Endianness`] trait within const contexts, as the trait methods cannot be used in const
/// contexts.
///
/// ## Example
/// ```
/// use endian_cast::EndianCast;
///
/// let x = 0x12345678u32;
/// let le_bytes = EndianCast::<4, u32>(x).le_bytes();
/// let be_bytes = EndianCast::<4, u32>(x).be_bytes();
/// let op_bytes = EndianCast::<4, u32>(x).op_bytes();
/// let ne_bytes = *EndianCast::<4, u32>(x).ne_bytes();
///
/// assert_ne!(le_bytes, be_bytes);
/// assert_ne!(ne_bytes, op_bytes);
/// assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12]);
/// assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78]);
///
/// // usable in const contexts
/// const LE: [u8; 4] = EndianCast::<4, u32>(0x12345678).le_bytes();
/// ```
#[repr(transparent)]
#[derive(Copy, Clone, Debug)]
pub struct EndianCast<const N: usize, T: Sized + Copy>(pub T);

impl<const N: usize, T: Sized + Copy> EndianCast<N, T> {
    const CHECK_SIZE: bool = {
        if core::mem::size_of::<T>() != N {
            panic!("N must be the true byte size of T");
        }
        true
    };

    /// Converts the value to a little-endian byte array.
    #[inline(always)]
    pub const fn le_bytes(&self) -> [u8; N] {
        #[cfg(target_endian = "little")]
        {
            *self.ne_bytes()
        }
        #[cfg(target_endian = "big")]
        {
            reverse_const(*self.ne_bytes())
        }
    }

    /// Converts the value to a big-endian byte array.
    ///
    /// This function is a no-op on big-endian systems and reverses the bytes on little-endian
    /// systems.
    #[inline(always)]
    pub const fn be_bytes(&self) -> [u8; N] {
        #[cfg(target_endian = "little")]
        {
            reverse_const(*self.ne_bytes())
        }
        #[cfg(target_endian = "big")]
        {
            *self.ne_bytes()
        }
    }

    /// Converts the value to a byte array in the opposite endianness of the system endianness.
    ///
    /// This function is never a no-op and always reverses the bytes.
    #[inline(always)]
    pub const fn op_bytes(&self) -> [u8; N] {
        #[cfg(target_endian = "little")]
        {
            self.be_bytes()
        }
        #[cfg(target_endian = "big")]
        {
            self.le_bytes()
        }
    }

    /// Returns a reference to the underlying native endian bytes of `self`.
    #[inline(always)]
    pub const fn ne_bytes(&self) -> &[u8; N] {
        let _check = Self::CHECK_SIZE;
        unsafe { &*(self as *const Self as *const [u8; N]) }
    }
}

#[inline(always)]
pub const fn reverse_const<const N: usize>(mut bytes: [u8; N]) -> [u8; N] {
    let mut i = 0;
    let mut j = N - 1;

    while i < j {
        let tmp = bytes[i];
        bytes[i] = bytes[j];
        bytes[j] = tmp;

        i += 1;
        j -= 1;
    }

    bytes
}

#[inline(always)]
pub fn reverse<N: ArrayLength>(mut bytes: GenericArray<u8, N>) -> GenericArray<u8, N> {
    let mut i = 0;
    let mut j = N::USIZE - 1;

    while i < j {
        let tmp = bytes[i];
        bytes[i] = bytes[j];
        bytes[j] = tmp;

        i += 1;
        j -= 1;
    }

    bytes
}

/// The [`Endianness`] trait provides methods for converting to and from the byte
/// representation of the type implementing the trait. It is automatically implemented for all
/// primitive types and arrays of bytes and can easily be implemented on arbitrary types that
/// implement [`Sized`] and [`Copy`] by manually implementing the trait. As with
/// [`EndianCast`], you must specify the size of the type as a const generic, and providing an
/// incorrect size will result in a panic at compile time.
///
/// When the system endianness matches the requested endianness, the conversion is essentially
/// a no-op, and the bytes are returned as-is. When the system endianness does not match the
/// requested endianness, the bytes are reversed.
///
/// ### Example
/// ```
/// use endian_cast::Endianness;
///
/// let x = 0x12345678u32;
/// let le_bytes = x.le_bytes();
/// let be_bytes = x.be_bytes();
/// let op_bytes = x.op_bytes();
/// let ne_bytes = *x.ne_bytes();
/// assert_ne!(le_bytes, be_bytes);
/// assert_ne!(ne_bytes, op_bytes);
/// assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12].into());
/// assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78].into());
/// ```
pub trait Endianness: Sized + Copy {
    /// The size of this type in bytes.
    type N: ArrayLength;
    const CHECK_SIZE: bool = {
        if core::mem::size_of::<Self>() != Self::N::USIZE {
            panic!("N must be the true byte size of T");
        }
        true
    };

    /// Converts the value to a little-endian byte array.
    ///
    /// This function is a no-op on little-endian systems and reverses the bytes on big-endian
    /// systems.
    #[inline(always)]
    fn le_bytes(&self) -> GenericArray<u8, Self::N> {
        #[cfg(target_endian = "little")]
        {
            self.ne_bytes().clone()
        }
        #[cfg(target_endian = "big")]
        {
            reverse(self.ne_bytes().clone())
        }
    }

    /// Converts the value to a big-endian byte array.
    ///
    /// This function is a no-op on big-endian systems and reverses the bytes on little-endian
    /// systems.
    #[inline(always)]
    fn be_bytes(&self) -> GenericArray<u8, Self::N> {
        #[cfg(target_endian = "little")]
        {
            reverse(self.ne_bytes().clone())
        }
        #[cfg(target_endian = "big")]
        {
            self.ne_bytes().clone()
        }
    }

    /// Converts the value to a byte array in the opposite endianness of the system endianness.
    ///
    /// This function is never a no-op and always reverses the bytes.
    #[inline(always)]
    fn op_bytes(&self) -> GenericArray<u8, Self::N> {
        #[cfg(target_endian = "little")]
        {
            self.be_bytes()
        }
        #[cfg(target_endian = "big")]
        {
            self.le_bytes()
        }
    }

    /// Returns a reference to the underlying native endian bytes of `self`.
    #[inline(always)]
    fn ne_bytes(&self) -> &GenericArray<u8, Self::N> {
        let _check = Self::CHECK_SIZE;
        unsafe { &*(self as *const Self as *const GenericArray<u8, Self::N>) }
    }
}

impl Endianness for u8 {
    type N = U1;
}
impl Endianness for i8 {
    type N = U1;
}
impl Endianness for u16 {
    type N = U2;
}
impl Endianness for i16 {
    type N = U2;
}
impl Endianness for u32 {
    type N = U4;
}
impl Endianness for i32 {
    type N = U4;
}
impl Endianness for u64 {
    type N = U8;
}
impl Endianness for i64 {
    type N = U8;
}
impl Endianness for u128 {
    type N = U16;
}
impl Endianness for i128 {
    type N = U16;
}
impl Endianness for f32 {
    type N = U4;
}
impl Endianness for f64 {
    type N = U8;
}
impl Endianness for bool {
    type N = U1;
}
impl Endianness for char {
    type N = U1;
}
#[cfg(target_pointer_width = "32")]
impl Endianness for usize {
    type N = U4;
}
#[cfg(target_pointer_width = "64")]
impl Endianness for usize {
    type N = U8;
}
#[cfg(target_pointer_width = "32")]
impl Endianness for isize {
    type N = U4;
}
#[cfg(target_pointer_width = "64")]
impl Endianness for isize {
    type N = U8;
}

impl<N: ArrayLength> Endianness for GenericArray<u8, N>
where
    <N as ArrayLength>::ArrayType<u8>: core::marker::Copy,
{
    type N = N;
}

#[test]
fn test_endianness() {
    let x = 0x12345678u32;
    let le_bytes = x.le_bytes();
    let be_bytes = x.be_bytes();
    assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12].into());
    assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78].into());
    assert_eq!(x.le_bytes(), le_bytes);
    assert_eq!(x.be_bytes(), be_bytes);
    #[cfg(target_endian = "little")]
    {
        assert_eq!(x.ne_bytes(), &le_bytes);
        assert_eq!(x.op_bytes(), be_bytes);
    }
    #[cfg(target_endian = "big")]
    {
        assert_eq!(x.ne_bytes(), &be_bytes);
        assert_eq!(x.op_bytes(), le_bytes);
    }
}

#[test]
fn test_endian_cast() {
    let x = 0x12345678u32;
    let cast = EndianCast::<4, u32>(x);
    let le_bytes = cast.le_bytes();
    let be_bytes = cast.be_bytes();
    assert_eq!(le_bytes, [0x78, 0x56, 0x34, 0x12]);
    assert_eq!(be_bytes, [0x12, 0x34, 0x56, 0x78]);
    #[cfg(target_endian = "little")]
    {
        assert_eq!(*cast.ne_bytes(), le_bytes);
        assert_eq!(cast.op_bytes(), be_bytes);
    }
    #[cfg(target_endian = "big")]
    {
        assert_eq!(*cast.ne_bytes(), be_bytes);
        assert_eq!(cast.op_bytes(), le_bytes);
    }
}