Crate castflip 

This crate provides several traits

• to encast a byte representation of a type as a value of the type,
• to decast a value of a type as a byte representation of the type, and
• to flip the endianness of a value of a type as required.

The supported types include

1. primitive numeric types, and
2. array types, struct types and union types consisting of the supported types.

This document describes the API of the castflip crate version 0.1.

Documents

Examples:

1. Basic Example: A struct type is encasted and decasted with its endianness flipped as required.
2. Nested Example: A nested struct type is encasted and decasted with its endianness flipped as required.
3. Arrayed Example: An array of a struct type is encasted and decasted with its endianness flipped as required.
4. I/O Example: A struct type is encasted and decasted with its endianness flipped as required using trait std::io::Read and trait std::io::Write.

A summary of types, traits and crate features:

1. Enum Type: Endian
2. Traits as Bounds: Cast, Flip and NopFlip
3. Traits to Cast and Flip: DecastMem and EncastMem/ DecastIO and EncastIO
4. Crate Features: alloc and std
5. Planned Releases: Version 0.2 and 0.3

A Simple Example

In this example, a byte representation of the UDP¹ header in big-endian is encasted as a value of a struct type in native-endian.

use castflip::{BE, Cast, EncastMem, Flip};

//
// Step 1: Define struct `UdpHdr` and test data.
//
#[repr(C)]            // to make it possible to apply #[derive(Cast)]
#[derive(Cast, Flip)] // to implement trait Cast and trait Flip
struct UdpHdr {  // UDP: See https://www.rfc-editor.org/rfc/rfc768.txt
    sport: u16,  // UDP Source Port
    dport: u16,  // UDP Destination Port
    len:   u16,  // UDP Length in Bytes (header plus data)
    sum:   u16,  // UDP Checksum
}

// Test data: A sample byte representation of the UDP header (8 bytes)
const BYTES1: [u8; 8] = [0xc3, 0xc9, 0x00, 0x35, 0x00, 0x32, 0x82, 0x3f];

fn my_main() -> Option<()> {
    //
    // Step 2: Encast a byte representation of the UDP header in
    // big-endian stored in const `BYTES1` as a value of struct
    // `UdpHdr` in native-endian and save it to variable `udp_hdr2`.
    //
    let udp_hdr2: UdpHdr = BYTES1.encastf(BE)?;

    // Check if all fields in variable `udp_hdr2` are as expected.
    assert_eq!(udp_hdr2.sport, 0xc3c9); // = 50121 (Ephemeral Port)
    assert_eq!(udp_hdr2.dport, 0x0035); // = 53 (DNS Port)
    assert_eq!(udp_hdr2.len,   0x0032); // = 50 (Length in Bytes)
    assert_eq!(udp_hdr2.sum,   0x823f); // = 0x823f (Checksum)

    Some(())
}

fn main() { my_main(); }

To use this crate, add the following lines to your Cargo.toml:

[dependencies]
castflip = "0.1"

---

1. The User Datagram Protocol (UDP) is one of the fundamental protocols of the Internet protocol suite. It is defined in RFC768. It is exhcanged in big-endian on the Internet. ↩

Modules

documents

Is a document folder.

experimental

Defines experimental traits and historical traits.

Enums

Endian

Defines two types of endiannesses: Relative Endiannesses (Native and Swapped) and Absolute Endiannesses (Little and Big).

Constants

BE

Is an alias of Endian::Big. BE stands for the Big Endianness.

LE

Is an alias of Endian::Little. LE stands for the Little Endianness.

NE

Is an alias of Endian::Native. NE stands for the Native Endianness.

SE

Is an alias of Endian::Swapped. SE stands for the Swapped Endianness.

Traits

Cast

Types whose values can be encasted and decasted by using the methods of this crate.

DecastIO

Provides methods that decast one or more values of a type specified by a parameter as one or more byte representations of the type and write the resulting byte representations to writer self using trait std::io::Write.

DecastMem

Provides methods that decast one or more values of a type specified by a parameter as one or more byte representations of the type and save the resulting byte representations to the memory at the head of self.

EncastIO

Provides methods that encast one or more byte representations of a type read from reader self using trait std::io::Read as one or more values of the type and return the resulting values.

EncastMem

Provides methods that encast one or more byte representations of a type in the memory at the head of self as one or more values of the type and return the resulting values.

Flip

Those types that the endiannesses of their values can be flipped by using the methods of this crate.

NopFlip

Types that implement trait Flip whose methods do nothing.

Derive Macros

Cast

Declares that the succeeding struct or union type is encastable / decastable.

Flip

Declares that the succeeding struct type is endian-flippable.

NopFlip

Declares that the succeeding struct or union type is is marked as endian-flippable but the implemented operation is Nop (No operation).