Crate castflip 

Crate castflip is a Rust library for encoding and decoding numeric variables, arrays and structures. It provides methods to convert between a byte representation of a fixed binary 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 with endianness handling,
• to decast a value of a type as a byte representation of the type with endianness handling, and
• to be used as bounds to determine which methods can be applied.

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 struct UdpHdr in native-endian.

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

//
// Step 1: Define struct `UdpHdr` (The UDP header) 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
}

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

//
// Step 2: Encast a byte representation of the UDP header in big-endian
// (`BE`) at the head of variable `in_bytes` as a value of struct
// `UdpHdr` in native-endian and save it to variable `out_hdr`.
//
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

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
5. How to convert between bytes and nested structs

Long Examples with Explanations:

1. How to convert between bytes and a struct (of the UDP header)
2. How to convert between bytes and nested structs
3. How to convert between bytes and an array of type [T; N]
   1. As a value of type [T; N]
   2. As N-consecutive values of type T
   3. As an element of slice [[T; N]]
4. How to convert between bytes and a struct (of 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 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 with endianness handling, 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 with endianness handling, and save the resulting byte representations at the head of the byte slice specified by parameter 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 with endianness handling, 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 parameter self as one or more values of the type with endianness handling, and return the resulting values.

Flip

Marks types whose values’ endiannesses can be flipped by using 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.