Qubit Binary Codec
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
[]
= "0.8"
= "0.16"
Quick Start
Encode a fixed-width field and a compact integer into caller-owned buffers:
use BigEndian;
use ;
let mut fixed = ;
let fixed_len = unsafe ;
assert_eq!;
assert_eq!;
let mut compact = ;
let compact_len = unsafe ;
assert_eq!;
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 ;
use ;
let mut encoder =
new;
let encoded = encoder.encode.expect;
let mut decoder =
new;
let decoded = decoder.decode.expect;
assert_eq!;
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
# Run tests with all declared features
# Project CI checks
# Check code coverage
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 ./.infra/bin/align-ci.sh to format code and
./.infra/bin/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