Skip to main content

qubit_codec_binary/
lib.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8
9//! # Qubit Binary Codec
10//!
11//! Buffer-oriented binary codecs for Rust.
12//!
13//! This crate provides fixed-width scalar, LEB128, and ZigZag codecs for
14//! caller-managed byte buffers. Stream-oriented readers and writers live in
15//! `qubit-io-binary`.
16//!
17//! # Checked single-value conversion
18//!
19//! For ordinary one-value conversion, prefer
20//! [`qubit_codec::CodecValueEncoder`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/struct.CodecValueEncoder.html)
21//! and [`qubit_codec::CodecValueDecoder`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/struct.CodecValueDecoder.html).
22//! These checked adapters own the temporary buffer and keep the unsafe
23//! boundary inside the adapter:
24//!
25//! ```
26//! use qubit_codec::{CodecValueDecoder, CodecValueEncoder, ValueEncoder};
27//! use qubit_codec_binary::{Leb128Codec, NonStrict, Strict};
28//!
29//! let mut encoder = CodecValueEncoder::new(Leb128Codec::<u64, NonStrict>::default());
30//! let encoded = encoder.encode(&300).expect("u64 is always encodable");
31//!
32//! let mut decoder = CodecValueDecoder::new(Leb128Codec::<u64, Strict>::default());
33//! let decoded = decoder.decode(&encoded).expect("the encoding is canonical");
34//! assert_eq!(300, decoded);
35//! ```
36//!
37//! Each adapter handles exactly one value. The decoder rejects empty input and
38//! trailing bytes, and does not return a consumed prefix. Encoding is always
39//! canonical; `NonStrict` is the conventional policy marker for this
40//! encode-only path, while `Strict` verifies the canonical encoded value.
41//!
42//! # API navigation
43//!
44//! For fixed-width fields, see [`BinaryCodec`] and
45//! [`qubit_codec::BigEndian`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/struct.BigEndian.html),
46//! [`qubit_codec::LittleEndian`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/struct.LittleEndian.html),
47//! and [`qubit_codec::NativeEndian`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/struct.NativeEndian.html).
48//! For variable-width fields, see
49//! [`Leb128Codec`], [`ZigZagCodec`], [`Strict`], and [`NonStrict`].
50//!
51//! Direct calls to the low-level `unsafe` methods require the surrounding code
52//! to guarantee valid input/output indices and sufficient readable/writable
53//! capacity. See [`qubit_codec::Codec`](https://docs.rs/qubit-codec/0.17.1/qubit_codec/trait.Codec.html)
54//! for the low-level contract.
55//!
56//! Read the [English user guide](https://github.com/qubit-ltd/rs-codec-binary/blob/main/doc/user_guide.md)
57//! or the [中文用户指南](https://github.com/qubit-ltd/rs-codec-binary/blob/main/doc/user_guide.zh_CN.md).
58
59mod codec;
60
61#[doc = include_str!("../README.md")]
62#[cfg(doctest)]
63mod readme_examples {}
64
65#[doc = include_str!("../README.zh_CN.md")]
66#[cfg(doctest)]
67mod readme_zh_cn_examples {}
68
69#[doc = include_str!("../doc/user_guide.md")]
70#[cfg(doctest)]
71mod user_guide_examples {}
72
73#[doc = include_str!("../doc/user_guide.zh_CN.md")]
74#[cfg(doctest)]
75mod user_guide_zh_cn_examples {}
76
77pub use codec::BinaryCodec;
78pub use codec::Leb128Codec;
79pub use codec::Leb128DecodeError;
80pub use codec::Leb128DecodeErrorKind;
81pub use codec::Leb128DecodePolicy;
82pub use codec::NonStrict;
83pub use codec::Strict;
84pub use codec::ZigZagCodec;