bitfield-serialize 0.1.0

# Rust Bitfield Serializer

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

[中文版本](README_zh.md)

## 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`:

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

## Usage Examples

### Using Macros (Recommended)

```rust
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

```rust
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

```rust
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

```rust
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](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](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