Crate codeq

Expand description

A fully customized encode/decode library.

Differences from serde: This crate focuses on a single, application defined binary format, built-in checksum support, simple encoding/decoding without intermediate formats, and application defined compatibility.

Choose this crate when you need customized and simple binary serialization with checksums, or when data format evolves over time. Use serde when you need: multiple format support (JSON, YAML, etc.), or derive macros for automatic implementation.

§Core Traits

Codec, Encode, Decode: Main trait for types that can be encoded/decoded
FixedSize: For types with known encoded size
Span: For types representing a region in a file/buffer

§Utilities

ChecksumReader/ChecksumWriter: I/O wrappers that calculate checksums
WithChecksum<T>: Wraps data with checksum for integrity
Offset: Type-safe byte position in a file/buffer
Size: Type-safe byte length
OffsetReader/OffsetWriter: I/O wrappers that track current position
Segment<T>: Represents a typed region with offset and size

§Examples

Basic encoding and decoding:

use codeq::{Codec, Decode, Encode, WithChecksum};

use codeq::config::Crc32fast;

#[derive(Debug, Clone, PartialEq)]
struct Record {
    id: u32,
    data: Vec<u8>,
}

impl Encode for Record {
    fn encode<W: io::Write>(&self, mut writer: W) -> io::Result<usize> {
        let mut n = 0;
        n += self.id.encode(&mut writer)?;
        n += self.data.encode(&mut writer)?;
        Ok(n)
    }
}
impl Decode for Record {
    fn decode<R: io::Read>(mut reader: R) -> io::Result<Self> {
        Ok(Self {
            id: u32::decode(&mut reader)?,
            data: Vec::decode(&mut reader)?,
        })
    }
}

// Add checksum protection
let record = Record { id: 1, data: vec![1, 2, 3] };
let protected = WithChecksum::<Crc32fast,_>::new(&record);

let mut buf = Vec::new();
protected.encode(&mut buf).unwrap();
assert_eq!(buf, vec![ //
    0, 0, 0, 1, // id
    0, 0, 0, 3, 1, 2, 3, // data
    0, 0, 0, 0, 31, 101, 71, 147 // checksum
]);

let decoded = Record::decode(&mut buf.as_slice()).unwrap();
assert_eq!(record, decoded);

Modules§

config: Configuration for checksum calculation and verification.
error_context_ext: Add context to error messages.
testing: Test utilities for codec implementations.

Structs§

ChecksumReader: A reader wrapper that calculates CRC32 checksum while reading data.
ChecksumWriter: A writer that calculates CRC32 checksum while writing data.
Offset: Represents a byte position/offset in a file or buffer.
OffsetReader: A reader that tracks the number of bytes read.
OffsetWriter: A writer that tracks the number of bytes written.
Segment: Represents a contiguous region in a file or buffer with an offset and size.
Size: Represents a size in bytes.
WithChecksum: A wrapper that appends a checksum to the encoded data.

Traits§

Codec: A trait that is Encode and Decode.
Decode: A trait that can be decoded from an io::Read stream.
Encode: A trait that can be encoded into an io::Write stream.
FixedSize: Trait for types that have a fixed, known size when encoded.
OffsetSize: A trait for types that span a range with an offset and size
Span: A trait for types that span a range with an offset and size