Crate endian_num

Byte-order-aware numeric types.

This crate provides the Be (big-endian) and Le (little-endian) byte-order-aware numeric types.

Unlike the popular byteorder crate, which focuses on the action of encoding and decoding numbers to and from byte streams, this crate focuses on the state of numbers. This is useful to create structs that contain fields of a specific endianness for interoperability, such as in virtio. In comparison to other crates that focus on state, this crate closely follows naming conventions from core::num, has rich functionality, and extensive documentation of each method.

The core API looks roughly like this (correspondingly for Be):

#[repr(transparent)]
pub struct<T> Le(pub T);

impl Le<T: Integer> {
    pub const fn from_ne(n: T) -> Self;
    pub const fn from_be(n: Be<T>) -> Self;

    pub const fn to_ne(self) -> T;
    pub const fn to_be(self) -> Be<T>;

    pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()];
    pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()];
    pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()];

    pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self;
    pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self;
    pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self;
}

The types also implement appropriate traits from core::cmp, core::convert, core::fmt, and core::ops and provide additional helper methods for computations.

In addition to widening and byte-reordering From implementations, the endian number types implement conversions to and from arrays of smaller number types of the same ordering. This is useful in situations, where a larger field has to be treated as multiple smaller field.

Examples

use endian_num::Le;

let a = Le::<u32>::from_ne(0x1A);
let b = Le::<u32>::from_ne(0x2B00);

assert_eq!((a + b).to_le_bytes(), [0x1A, 0x2B, 0x00, 0x00]);

Optional features

This crate has the following optional features:

• bitflags — Be and Le implement Bits, ParseHex, and WriteHex.
• bytemuck — Be and Le implement Zeroable and Pod.
• linux-types — Type aliases like in linux/types.h, such as le32.
• zerocopy — Be and Le implement KnownLayout, Immutable, FromBytes, and IntoBytes.

Related crates

Several crates provide alternative approaches to byte-order-aware numeric types:

• endian-type
• endian-type-rs — Depends on num.
• endiantype
• nora_endian
• simple_endian — Also provides f32, f64, and bool types.
• zerocopy::byteorder — These types are Unaligned, which makes them unsuitable for volatile memory operations.

Structs

Be

An integer stored in big-endian byte order.

Le

An integer stored in little-endian byte order.

Type Aliases

be16linux-types

A 16-bit unsigned integer stored in big-endian byte order.

be32linux-types

A 32-bit unsigned integer stored in big-endian byte order.

be64linux-types

A 64-bit unsigned integer stored in big-endian byte order.

be128linux-types

A 128-bit unsigned integer stored in big-endian byte order.

le16linux-types

A 16-bit unsigned integer stored in little-endian byte order.

le32linux-types

A 32-bit unsigned integer stored in little-endian byte order.

le64linux-types

A 64-bit unsigned integer stored in little-endian byte order.

le128linux-types

A 128-bit unsigned integer stored in little-endian byte order.