# Qubit Codec
[](https://github.com/qubit-ltd/rs-codec/actions/workflows/ci.yml)
[](https://qubit-ltd.github.io/rs-codec/coverage/)
[](https://crates.io/crates/qubit-codec)
[](https://www.rust-lang.org)
[](LICENSE)
[](README.zh_CN.md)
Core codec traits and buffer conversion primitives for Rust.
## Overview
Qubit Codec is the domain-neutral foundation for Qubit codec crates. It contains
small traits and value types that are shared by binary, text, misc, and I/O
adapter crates without pulling in `std::io` stream helpers or concrete format
implementations.
This crate provides:
- `Codec<Value, Unit>` for low-level single-value buffer codecs.
- `Encoder` and `Decoder` traits for owned whole-value convenience APIs.
- `Transcoder`, `TranscodeProgress`, and `TranscodeStatus` for caller-managed logical-stream
conversion.
- `ByteOrder`, `ByteOrderSpec`, `BigEndian`, and `LittleEndian` for byte-order
metadata shared by binary and text codecs.
Concrete codecs live in sibling crates such as `qubit-codec-binary`,
`qubit-codec-text`, and `qubit-codec-misc`.
## Design Goals
- **Layered Boundaries**: keep domain-neutral traits separate from binary, text,
misc, and stream-specific implementations.
- **Small Public Surface**: expose only the primitives that multiple codec
crates need to share.
- **No I/O Coupling**: avoid `std::io` dependencies so buffer codecs can remain
usable in non-stream contexts.
- **Policy Neutrality**: leave charset, malformed-input, and wire-format rules to
domain crates.
- **Zero-Cost Markers**: represent byte order as copyable type/value markers
without runtime allocation.
- **Stable Progress Reporting**: use `TranscodeProgress` and `TranscodeStatus` to make
caller-managed buffer conversion explicit.
## Features
### Core Conversion Traits
- **`Codec<Value, Unit>`**: encodes and decodes one value or codec quantum
against a caller-managed unit buffer.
- **`Encoder<Input>`**: converts a borrowed value into an owned output type.
- **`Decoder<Input>`**: converts a borrowed encoded value into an owned decoded
output type.
### Buffer Transcoder Primitives
- **`Transcoder<Input, Output>`**: converts input units into output units inside
caller-provided buffers, then finalizes pending stream state at EOF.
- **`TranscodeProgress`**: reports relative input units read and output units
written.
- **`TranscodeStatus`**: distinguishes complete conversion from `NeedInput` and
`NeedOutput` stops.
### Byte Order Markers
- **`ByteOrder`**: runtime byte-order enum for public APIs.
- **`ByteOrderSpec`**: type-level byte-order trait used by hot codecs.
- **`BigEndian` / `LittleEndian`**: zero-sized marker types.
### Focused Public API
- **`prelude` module**: imports the commonly used core traits and markers.
- **No concrete formats**: binary, text, and miscellaneous codecs are published
in sibling crates.
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
qubit-codec = "0.4"
```
## Quick Start
```rust
use qubit_codec::{
TranscodeProgress,
TranscodeStatus,
Encoder,
};
struct StringEncoder;
impl Encoder<str> for StringEncoder {
type Output = String;
type Error = core::convert::Infallible;
fn encode(&self, input: &str) -> Result<Self::Output, Self::Error> {
Ok(input.to_owned())
}
}
let encoded = Encoder::<str>::encode(&StringEncoder, "codec")?;
assert_eq!("codec", encoded);
let progress = TranscodeProgress::complete(3, 4);
assert_eq!(TranscodeStatus::Complete, progress.status());
# Ok::<(), core::convert::Infallible>(())
```
## API Reference
### Core Codec Traits
| `Codec<Value, Unit>` | Encode/decode one value or quantum against caller buffers | Binary scalar, charset char, escaped byte, Base64 quantum |
| `Encoder<Input>` | Encode a borrowed input into an owned output | Convenience text, binary, or misc helper |
| `Decoder<Input>` | Decode a borrowed input into an owned output | Convenience text, binary, or misc helper |
### `Transcoder` Operations
| `max_output_len(input_len)` | Return a finite output upper bound when known |
| `max_finish_output_len()` | Return a finite finalization output upper bound when known |
| `reset()` | Reset retained stream state while keeping configuration |
| `transcode(input, input_index, output, output_index)` | Convert input units into output units |
| `finish(output, output_index)` | Finalize EOF state, flush trailers, or reject incomplete input |
### `TranscodeStatus` Values
| `Complete` | The current conversion step completed |
| `NeedInput` | More input units are required unless the caller is ready to call `finish()` at EOF |
| `NeedOutput` | More output capacity is required |
### Byte Order Types
| `ByteOrder` | Runtime byte-order selection in public APIs |
| `ByteOrderSpec` | Type-level byte-order abstraction |
| `BigEndian` | Big-endian type marker |
| `LittleEndian` | Little-endian type marker |
## Crate Boundary
`qubit-codec` does not contain concrete binary formats, character sets,
percent/Base64/hex codecs, or `std::io` reader/writer adapters. Keep those in
domain crates so downstream users can depend on only the layers they need.
## Performance Considerations
All core abstractions are trait or marker types. `BigEndian` and `LittleEndian`
are zero-sized, and `ByteOrder` is a small copyable enum. The crate performs no
heap allocation by itself; allocation behavior is controlled by concrete codec
implementations in downstream crates.
## Testing & Code Coverage
This project keeps the core trait contracts covered by integration tests under
`tests/`.
### Running Tests
```bash
# Run all tests
cargo test
# Run with coverage report
./coverage.sh
# Generate text format report
./coverage.sh text
# Align code with CI requirements
./align-ci.sh
# Run CI checks (format, clippy, test, coverage, audit)
RS_CI_SKIP_TOOLCHAIN_UPDATE=1 ./ci-check.sh
```
## Dependencies
`qubit-codec` has no runtime dependencies.
## License
Copyright (c) 2026. Haixing Hu.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
See [LICENSE](LICENSE) for the full license text.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Development Guidelines
- Keep this crate free of concrete format implementations.
- Document public traits and marker types with examples.
- Keep tests comprehensive and deterministic.
- Ensure all checks pass before submitting a PR.
## Author
**Haixing Hu**
## Related Projects
- [qubit-codec-binary](https://github.com/qubit-ltd/rs-codec-binary): binary
buffer codecs.
- [qubit-codec-text](https://github.com/qubit-ltd/rs-codec-text): charset and
Unicode buffer codecs.
- [qubit-codec-misc](https://github.com/qubit-ltd/rs-codec-misc): reusable
miscellaneous byte and text codecs.
- [qubit-io](https://github.com/qubit-ltd/rs-io): generic `std::io` helpers.
- More Rust libraries from Qubit are available under the
[qubit-ltd](https://github.com/qubit-ltd) GitHub organization.
---
Repository: [https://github.com/qubit-ltd/rs-codec](https://github.com/qubit-ltd/rs-codec)