Rust Bitfield Serializer

A Rust library for defining and serializing bitfield structures with macro support.

中文版本

Features

• 🚀 Macro-based bitfield definition - Define bitfields with simple macros
• 📦 Flexible serialization - Serialize bitfields to binary format
• 🔧 Type safety - Compile-time type checking for bitfield operations
• 📊 Multiple data types - Support for u8, u16, u32, and custom types
• 🎯 Zero-copy operations - Efficient memory usage
• 📚 Comprehensive API - Easy-to-use traits and utilities
• 🔄 Bidirectional - Both serialization and deserialization
• 🛡️ Error handling - Robust error handling for invalid data

Quick Start

Add this to your Cargo.toml:

[dependencies]
rust-bitfield-serializer = "0.1.0"

Usage Examples

Using Macros (Recommended)

use rust_bitfield_serializer::{bitfield, BitfieldSerialize, BitfieldSize};

// Define a simple bitfield using macro
bitfield! {
    struct SimpleBitfield {
        flag: u8, 1,
        value: u8, 7,
    }
}

fn main() {
    // Create and configure bitfield
    let mut bitfield = SimpleBitfield::new();
    bitfield.set_flag(1);
    bitfield.set_value(100);

    // Access fields
    println!("Flag: {}", bitfield.get_flag());
    println!("Value: {}", bitfield.get_value());

    // Serialize to bytes
    let bytes = bitfield.serialize();
    println!("Serialized: {:?}", bytes);

    // Deserialize from bytes
    let restored = SimpleBitfield::deserialize(&bytes).unwrap();
    println!("Restored flag: {}", restored.get_flag());
}

Manual Definition

use rust_bitfield_serializer::{
    BitField, BitfieldSerializer, BitfieldStruct,
    FieldType, FieldValue, BitfieldSerialize
};

fn main() {
    // Create bitfield manually
    let mut bitfield = BitfieldStruct::new();

    // Add fields
    bitfield.add_field("status", FieldType::U8, 2);
    bitfield.add_field("counter", FieldType::U16, 14);

    // Set values
    bitfield.set_field("status", FieldValue::U8(3));
    bitfield.set_field("counter", FieldValue::U16(1024));

    // Serialize
    let serializer = BitfieldSerializer::new();
    let bytes = serializer.serialize(&bitfield).unwrap();

    println!("Serialized: {:?}", bytes);
}

API Documentation

Core Traits

• BitfieldSerialize - Provides serialization and deserialization methods
• BitfieldSize - Provides size calculation methods

Utilities

• BitReader - Efficient bit-level reading operations
• BitWriter - Efficient bit-level writing operations
• BitfieldSerializer - Main serialization engine

Types

• BitField - Individual field definition
• BitfieldStruct - Container for multiple fields
• FieldType - Enumeration of supported field types
• FieldValue - Enumeration of field values

Advanced Features

Complex Bitfields

bitfield! {
    struct NetworkPacket {
        version: u8, 4,
        header_length: u8, 4,
        type_of_service: u8, 8,
        total_length: u16, 16,
        identification: u16, 16,
        flags: u8, 3,
        fragment_offset: u16, 13,
    }
}

Error Handling

match bitfield.serialize() {
    Ok(bytes) => println!("Success: {:?}", bytes),
    Err(e) => eprintln!("Error: {}", e),
}

Performance

This library is designed for high performance with:

• Zero-copy operations where possible
• Efficient bit manipulation
• Minimal memory allocations
• Compile-time optimizations

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

v0.1.0

• Initial release
• Basic bitfield definition and serialization
• Macro support
• Core traits and utilities