qubit-codec-binary 0.6.0

Buffer-oriented binary codecs for Rust
Documentation

Qubit Binary Codec

Rust CI Coverage Crates.io Rust License 中文文档

qubit-codec-binary supplies buffer-oriented codecs for fixed-width scalars, LEB128 integers, and ZigZag values. It is for protocol and file-format code that owns its byte buffers and needs exact wire bytes without a std::io reader or writer in the codec layer.

Installation

[dependencies]
qubit-codec-binary = "0.6"
qubit-codec = "0.12"

Quick Start

Encode a fixed-width field and a compact integer into caller-owned buffers:

use qubit_codec::BigEndian;
use qubit_codec_binary::{BinaryCodec, Leb128Codec, NonStrict};

let mut fixed = [0_u8; BinaryCodec::<u32, BigEndian>::MAX_ENCODE_UNITS_PER_VALUE];
let fixed_len = unsafe {
    BinaryCodec::<u32, BigEndian>::encode(0x0102_0304, &mut fixed, 0)
};
assert_eq!(4, fixed_len);
assert_eq!([0x01, 0x02, 0x03, 0x04], fixed);

let mut compact = [0_u8; Leb128Codec::<u64, NonStrict>::MAX_ENCODE_UNITS_PER_VALUE];
let compact_len = unsafe {
    Leb128Codec::<u64, NonStrict>::encode(300, &mut compact, 0)
};
assert_eq!(&[0xac, 0x02], &compact[..compact_len]);

For ordinary one-value conversion, prefer the checked adapters from qubit-codec; they own the temporary buffer and keep the unsafe boundary inside the adapter:

use qubit_codec::{
    CodecValueDecoder,
    CodecValueEncoder,
    ValueDecoder,
    ValueEncoder,
};
use qubit_codec_binary::{Leb128Codec, NonStrict};

let mut encoder =
    CodecValueEncoder::new(Leb128Codec::<u64, NonStrict>::default());
let encoded = encoder.encode(&300).expect("u64 is always encodable");

let mut decoder =
    CodecValueDecoder::new(Leb128Codec::<u64, NonStrict>::default());
let decoded = decoder.decode(&encoded).expect("encoded value is valid");
assert_eq!(300, decoded);

The low-level encode and decode methods are unsafe: the caller must ensure the documented readable or writable capacity before calling them. Use them directly only when the surrounding protocol code already establishes those bounds or when a measured hot path justifies the unchecked boundary.

Why This Project Exists

Binary protocols often need both deterministic fixed-width fields and compact integers, but buffering and stream ownership belong to a higher layer. This crate keeps the wire-format layer small and explicit, while qubit-io-binary provides stream-oriented adapters.

What It Provides

Capability Public API Boundary
Fixed-width integers and floats BinaryCodec<T, BigEndian> / BinaryCodec<T, LittleEndian> / BinaryCodec<T, NativeEndian> Supports explicit-width integer types plus f32 and f64. Use big- or little-endian encoding for persistent and cross-platform data; native-endian encoding is only for platform-local data. It does not define a persistent width for usize or isize.
Compact integers Leb128Codec<T, P> Encoding is canonical; Strict rejects non-canonical input and NonStrict accepts compatible input.
Compact signed integers ZigZagCodec<T, P> Maps signed values to unsigned LEB128 payloads.
Decode diagnostics Leb128DecodeError Distinguishes incomplete, malformed, and non-canonical input with indices and available/required counts.

This crate does not provide std::io readers or writers, generic owned-value adapters, framing, or buffering. Import shared traits and byte-order markers from qubit-codec, and use qubit-io-binary when stream adapters are needed.

Leb128Codec<T, P> and ZigZagCodec<T, P> require an explicit decoding policy. P never affects canonical encoding; encoding-only code should use NonStrict as the conventional marker.

NonStrict accepts non-canonical representations only within the target integer's declared maximum width. Longer unterminated or over-width payloads remain malformed rather than being accepted as arbitrarily long encodings.

Learn More

Testing

# Run tests with the default feature set
cargo test

# Run tests with all declared features
cargo test --all-features

# Project CI checks
./ci-check.sh

# Check code coverage
./coverage.sh

License

Copyright (c) 2025 - 2026. Haixing Hu. All rights reserved.

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Contributing

Contributions are welcome. Please follow the Rust API guidelines, keep public API documentation and tests current, and run ./align-ci.sh to format code and ./ci-check.sh to satisfy CI requirements before submitting a pull request.

Author

Haixing Hu - Qubit Co. Ltd.

Repository: https://github.com/qubit-ltd/rs-codec-binary