Crate castflip 

Crate castflip is a Rust library for encoding and decoding numeric variables, arrays and structures in little-endian and big-endian. It provides methods to convert between a byte representation of a format and a value of a Rust type with endianness handling.

Introduction

Crate castflip 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.

A Simple Example

The example below encasts a byte representation of the UDP¹ header in big-endian as a value of a struct type in native-endian.

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

//
// Step 1: Define struct `UdpHdr`.
//
#[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
}

//
// Step 2: Encast a byte representation of the UDP header in big-endian
// (`BE`) stored in variable `in_bytes` as a value of struct `UdpHdr` in
// native-endian and save it to variable `out_hdr`.
//

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

// Encast a byte representation in big-endian (`BE`) as a value.
let out_hdr: UdpHdr = in_bytes.encastf(BE).unwrap();

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

Dependencies

To use crate castflip version 0.1, add the following lines to your Cargo.toml:

[dependencies]
castflip = "0.1"

Documents

The documents below describes the API of the castflip crate version 0.1.

Short Examples as a Quick Start Guide:

1. How to convert between bytes and a number
2. How to convert between bytes and an array of numbers
3. How to convert between bytes and a struct
4. How to convert between bytes and an array of structs

Long Examples with Explanations:

1. How to convert between bytes and a struct (The UDP header)
2. How to convert between bytes and a nested struct
3. How to convert between bytes and an array of structs
   1. As a value of type [T; N]
   2. As consecutive values of type T
   3. As an element of slice [[T; N]]
4. How to convert between bytes and a struct (The UDP header) using std::io
   1. Through a byte stream provided by struct std::io::Cursor
   2. Through a byte stream provided by a mutable byte slice &mut [u8]

Summaries of Types, Traits, Crate Features, etc.:

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

---

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

The documents directory

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

Marks types whose values can be encasted and decasted by 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 at the head of byte slice specified by 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 at the head of a byte slice specified by self as one or more values of the type and return the resulting values.

Flip

Marks types whose values’ endiannesses can be flipped by the methods of this crate.

NopFlip

Marks types that implement trait Flip whose methods do nothing.

Derive Macros

Cast

Derive macro generating an impl of trait Cast for a struct type or a union type.

Flip

Derive macro generating an impl of trait Flip for a struct type.

NopFlip

Derive macro generating an impl of both trait Flip whose methods do nothing and trait NopFlip for a struct type or a union type.