Endian Trait

This crate provides a trait, Endian, which requires four methods for converting primitives with multi-byte representations between big- and little- endian orders. In addition to declaring the trait, this library implements it on Rust's primitives (bool, char, {i,u}{8,16,32,64}, f32, and f64), and on all slices &mut [Endian].

This crate also provides a custom derive macro available with #[macro_use].

The primary purpose of this library is to aid in the direct binary serialization of Rust types across machine boundaries. This is not a robust means of moving data across a network or filesystem, but it can be used as a basis for building stronger binary serialization procedures. Note that common transmission methods will also require implementing a conversion to/from byte arrays, which is currently beyond the scope of this library.

Usage

MINIMUM RUST VERSION: 1.31

Require this crate (endian_trait) in your Cargo.toml, and tag it with #[macro_use] for access to the custom derive macro.

[dependencies]
endian_trait = "1"

Import them in your crate root:

extern crate endian_trait;

and then use the Endian trait to flip bytes.

use endian_trait::Endian;

#[derive(Endian)]
struct Foo {
    bar: i32,
    baz: f64,
}

#[derive(Endian)]
struct Quux {
    f: Foo,
    g: bool,
}

let q = Quux {
    f: Foo {
        bar: 42,
        baz: 6.283185,
    },
    g: true,
}.to_be();

let q2: Quux = q.from_be();

Useful … Usage

Endian conversions destroy the utility, and in some cases (floats, chars, enums) the validity, of the data on which they are performed. Once data is transformed away from local endian, it can no longer be used as anything but a bare sequence of bytes with no further meaning. Similarly, the transformations from an order to local endian are only useful to perform on a sequence of bytes that are known to be in the right shape.

In my projects that use this, I have the following workflow for binary ser/des:

#[derive(Endian)]
struct Foo {
    //  fields
}
impl From<[u8; N]> for Foo {
    fn from(src: [u8; N]) -> Self {
        //  move fields into a byte array
    }
}
impl Into<[u8; N]> for Foo {
    fn into(self) -> [u8; N] {
        //  pull segments of the array into fields
    }
}

let f: Foo = make_a_foo();
let fbytes: [u8; N] = f.to_be().into();

let raw_foo: [u8; N] = read_from_network();
let build_foo: Foo = Foo::from(raw_foo).from_be();

Do keep in mind that once data is converted to a transport endian order, it can no longer be considered as anything but a collection of bytes. Converting a char or float will almost always result in a bit pattern that is invalid to be read as its stated type, and will remain so until converted back to native order on the other side. Converting an enum will result in undefined behavior if the enum is used as its own type rather than an untyped sequence of bytes. The From and Into impls used for binary ser/des should just be transmutes and byte shunts, as they will be likely working with data that is the correct width but of logically invalid form.

You could also move the endian conversions into the From/Into methods, but I personally prefer keeping those uncoupled.

There's really no other reason to use this trait, as far as I'm aware.

Extra Features

You can compile with --features arrays to have Endian implemented on arrays [T: Endian; N] where N is in the range 0 ≤ N ≤ 32. When const-generics are stabilized, this crate will update to use them.

In your Cargo.toml, replace the original dependency on endian_trait with:

[dependencies.endian_trait]
version = 1
features = [
    "arrays",
]