Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ All significant changes to this project will be documented in this file.

### Features

* Add `policy::PaddedOptional` and `policy::UnpaddedOptional` for Base32 and Base64. Both accept complete padding or none when decoding and emit padded and unpadded output, respectively.
* Add `encode_into_uninit` and `decode_into_uninit` to all profiles and the `Codec` trait. They write into caller-provided `MaybeUninit<u8>` storage and return the initialized prefix.

## v0.1.1 (2026-11-17)
Expand Down
2 changes: 1 addition & 1 deletion bases/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Bases separates observable encoding semantics from execution strategy.

## Public layers

- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`).
- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `PaddedOptional`, `UnpaddedOptional`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`).
- Concrete family types provide direct inherent methods, including `const fn` sizing and constructors (`new`, `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, `decoder`), while the sealed `Codec` trait provides the shared contract for generic `C: Codec` callers.
- Caller-buffer operations accept initialized slices (`encode_into`, `decode_into`) or `MaybeUninit<u8>` slices (`encode_into_uninit`, `decode_into_uninit`). Both `decode_in_place` and `decode_array` also operate without allocation. The `alloc` feature adds `encode`, `encode_append`, `decode`, and transactional `decode_append`. The `serde` feature adds `serialize`, `deserialize_array`, and, with `alloc`, `deserialize`.
- `Encoder<C>` and `Decoder<C>` preserve one partial quantum for incremental operation without allocation; `std` adds `bases::io::{EncoderWriter, DecoderReader}` over `std::io::{Write, Read}`.
Expand Down
11 changes: 11 additions & 0 deletions bases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,17 @@ Ten crate-root aliases cover standard encoding profiles:

Every profile exposes inherent methods without requiring trait imports, and implements the sealed `Codec` trait for generic callers. Configurable zero-sized family types (`base16::Base16`, `base32::Base32`, and `base64::Base64`) accept `policy` markers for other combinations, such as strict single-case Base16 or RFC 5155 Base32Hex with lowercase output and case-insensitive decoding. See the [API reference](https://docs.rs/bases) for types, methods, and their contracts.

For Base32 and Base64, the second type parameter selects the padding policy. The table shows how each policy handles the same byte with the standard Base64 alphabet.

| Padding policy | Encodes `b"f"` as | Accepts for `b"f"` |
| -------------------------- | ----------------- | ------------------ |
| `policy::Padded` | `Zg==` | `Zg==` |
| `policy::Unpadded` | `Zg` | `Zg` |
| `policy::PaddedOptional` | `Zg==` | `Zg==`, `Zg` |
| `policy::UnpaddedOptional` | `Zg` | `Zg==`, `Zg` |

For example, use `base64::Base64<base64::Standard, policy::UnpaddedOptional>` for gRPC binary metadata. Both optional policies reject partial padding such as `Zg=`, excess padding, and non-zero unused trailing bits.

## API layers and features

- **Caller buffers (`no_std`):** `encoded_len`, `max_decoded_len`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` operate without allocation. Concrete profiles provide `const fn` constructors and sizing methods.
Expand Down
3 changes: 2 additions & 1 deletion bases/src/base16.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ use crate::io::DecoderReader;
use crate::io::EncoderWriter;
use crate::policy;
use crate::policy::sealed::DecodeCasePolicy;
use crate::policy::sealed::DecodePadding;
use crate::policy::sealed::LetterCase;
#[cfg(feature = "serde")]
use crate::serde;
Expand Down Expand Up @@ -355,7 +356,7 @@ where
const NAME: &'static str = Self::name();
const INPUT_QUANTUM: usize = 1;
const ENCODED_QUANTUM: usize = 2;
const PADDED: bool = false;
const DECODE_PADDING: DecodePadding = DecodePadding::Forbidden;

#[inline]
fn encoded_len_impl(input_len: usize) -> Option<usize> {
Expand Down
52 changes: 23 additions & 29 deletions bases/src/base32.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,10 @@ use crate::io::DecoderReader;
use crate::io::EncoderWriter;
use crate::policy;
use crate::policy::sealed::DecodeCasePolicy;
use crate::policy::sealed::DecodePadding;
use crate::policy::sealed::LetterCase;
use crate::policy::sealed::PaddingPolicy;
use crate::policy::sealed::profile_name;
#[cfg(feature = "serde")]
use crate::serde;

Expand Down Expand Up @@ -80,7 +82,8 @@ pub(crate) mod sealed {
/// [`Standard`]), padding policy (`Padding`, defaulting to
/// [`policy::Padded`]), encoded letter case (`Case`, defaulting to
/// [`policy::Upper`]), and decoding case policy (`DecodeCase`, defaulting to
/// [`policy::Strict`]).
/// [`policy::Strict`]). Use [`policy::PaddedOptional`] or [`policy::UnpaddedOptional`] to accept
/// both input forms while emitting padded or unpadded output, respectively.
pub struct Base32<
Alphabet = Standard,
Padding = policy::Padded,
Expand Down Expand Up @@ -144,28 +147,15 @@ where
#[must_use]
#[inline]
pub const fn name() -> &'static str {
match (
Alphabet::EXTENDED_HEX,
Padding::PADDED,
Case::UPPERCASE,
DecodeCase::STRICT,
) {
(false, true, true, true) => "base32",
(false, false, true, true) => "base32-unpadded",
(false, true, false, true) => "base32-lower",
(false, false, false, true) => "base32-lower-unpadded",
(false, true, true, false) => "base32-mixed",
(false, false, true, false) => "base32-mixed-unpadded",
(false, true, false, false) => "base32-lower-mixed",
(false, false, false, false) => "base32-lower-mixed-unpadded",
(true, true, true, true) => "base32hex",
(true, false, true, true) => "base32hex-unpadded",
(true, true, false, true) => "base32hex-lower",
(true, false, false, true) => "base32hex-lower-unpadded",
(true, true, true, false) => "base32hex-mixed",
(true, false, true, false) => "base32hex-mixed-unpadded",
(true, true, false, false) => "base32hex-lower-mixed",
(true, false, false, false) => "base32hex-lower-mixed-unpadded",
match (Alphabet::EXTENDED_HEX, Case::UPPERCASE, DecodeCase::STRICT) {
(false, true, true) => profile_name!("base32", Padding),
(false, false, true) => profile_name!("base32-lower", Padding),
(false, true, false) => profile_name!("base32-mixed", Padding),
(false, false, false) => profile_name!("base32-lower-mixed", Padding),
(true, true, true) => profile_name!("base32hex", Padding),
(true, false, true) => profile_name!("base32hex-lower", Padding),
(true, true, false) => profile_name!("base32hex-mixed", Padding),
(true, false, false) => profile_name!("base32hex-lower-mixed", Padding),
}
}

Expand All @@ -178,7 +168,7 @@ where
/// that a buffer of that size can be allocated.
#[inline]
pub const fn encoded_len(input_len: usize) -> Result<usize, EncodeError> {
let len = if Padding::PADDED {
let len = if Padding::ENCODE_PADDED {
backend::base32::encoded_len::<true>(input_len)
} else {
backend::base32::encoded_len::<false>(input_len)
Expand Down Expand Up @@ -413,11 +403,11 @@ where
const NAME: &'static str = Self::name();
const INPUT_QUANTUM: usize = 5;
const ENCODED_QUANTUM: usize = 8;
const PADDED: bool = Padding::PADDED;
const DECODE_PADDING: DecodePadding = Padding::DECODE_PADDING;

#[inline]
fn encoded_len_impl(input_len: usize) -> Option<usize> {
if Padding::PADDED {
if Padding::ENCODE_PADDED {
backend::base32::encoded_len::<true>(input_len)
} else {
backend::base32::encoded_len::<false>(input_len)
Expand All @@ -431,7 +421,7 @@ where

#[inline]
fn decode_plan_impl(input: &[u8]) -> Result<DecodePlan, DecodeError> {
if Padding::PADDED {
if Padding::DECODE_PADDING.uses_padded_decoder(input) {
backend::base32::decode_plan::<true>(input)
} else {
backend::base32::decode_plan::<false>(input)
Expand All @@ -440,7 +430,11 @@ where

#[inline]
fn encode_impl(input: &[u8], output: &mut [MaybeUninit<u8>]) -> usize {
match (Alphabet::EXTENDED_HEX, Padding::PADDED, Case::UPPERCASE) {
match (
Alphabet::EXTENDED_HEX,
Padding::ENCODE_PADDED,
Case::UPPERCASE,
) {
(false, false, false) => backend::base32::encode::<false, false, false>(input, output),
(false, false, true) => backend::base32::encode::<false, false, true>(input, output),
(false, true, false) => backend::base32::encode::<false, true, false>(input, output),
Expand Down Expand Up @@ -533,7 +527,7 @@ where
fn decode_in_place_impl(buf: &mut [u8]) -> Result<usize, DecodeError> {
match (
Alphabet::EXTENDED_HEX,
Padding::PADDED,
Padding::DECODE_PADDING.uses_padded_decoder(buf),
Case::UPPERCASE,
DecodeCase::STRICT,
) {
Expand Down
29 changes: 17 additions & 12 deletions bases/src/base64.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,9 @@ use crate::io::DecoderReader;
#[cfg(feature = "std")]
use crate::io::EncoderWriter;
use crate::policy;
use crate::policy::sealed::DecodePadding;
use crate::policy::sealed::PaddingPolicy;
use crate::policy::sealed::profile_name;
#[cfg(feature = "serde")]
use crate::serde;

Expand Down Expand Up @@ -76,7 +78,8 @@ pub(crate) mod sealed {
///
/// The type parameters select the alphabet (`Alphabet`, defaulting to
/// [`Standard`]) and padding policy (`Padding`, defaulting to
/// [`policy::Padded`]).
/// [`policy::Padded`]). Use [`policy::PaddedOptional`] or [`policy::UnpaddedOptional`] to accept
/// both input forms while emitting padded or unpadded output, respectively.
pub struct Base64<Alphabet = Standard, Padding = policy::Padded>(PhantomData<(Alphabet, Padding)>);

impl<Alphabet, Padding> Clone for Base64<Alphabet, Padding> {
Expand Down Expand Up @@ -129,11 +132,10 @@ where
#[must_use]
#[inline]
pub const fn name() -> &'static str {
match (Alphabet::URL_SAFE, Padding::PADDED) {
(false, true) => "base64",
(false, false) => "base64-unpadded",
(true, true) => "base64url",
(true, false) => "base64url-unpadded",
if Alphabet::URL_SAFE {
profile_name!("base64url", Padding)
} else {
profile_name!("base64", Padding)
}
}

Expand All @@ -146,7 +148,7 @@ where
/// that a buffer of that size can be allocated.
#[inline]
pub const fn encoded_len(input_len: usize) -> Result<usize, EncodeError> {
let len = if Padding::PADDED {
let len = if Padding::ENCODE_PADDED {
backend::base64::encoded_len::<true>(input_len)
} else {
backend::base64::encoded_len::<false>(input_len)
Expand Down Expand Up @@ -379,11 +381,11 @@ where
const NAME: &'static str = Self::name();
const INPUT_QUANTUM: usize = 3;
const ENCODED_QUANTUM: usize = 4;
const PADDED: bool = Padding::PADDED;
const DECODE_PADDING: DecodePadding = Padding::DECODE_PADDING;

#[inline]
fn encoded_len_impl(input_len: usize) -> Option<usize> {
if Padding::PADDED {
if Padding::ENCODE_PADDED {
backend::base64::encoded_len::<true>(input_len)
} else {
backend::base64::encoded_len::<false>(input_len)
Expand All @@ -397,7 +399,7 @@ where

#[inline]
fn decode_plan_impl(input: &[u8]) -> Result<DecodePlan, DecodeError> {
if Padding::PADDED {
if Padding::DECODE_PADDING.uses_padded_decoder(input) {
backend::base64::decode_plan::<true>(input)
} else {
backend::base64::decode_plan::<false>(input)
Expand All @@ -406,7 +408,7 @@ where

#[inline]
fn encode_impl(input: &[u8], output: &mut [MaybeUninit<u8>]) -> usize {
match (Alphabet::URL_SAFE, Padding::PADDED) {
match (Alphabet::URL_SAFE, Padding::ENCODE_PADDED) {
(false, false) => backend::base64::encode::<false, false>(input, output),
(false, true) => backend::base64::encode::<false, true>(input, output),
(true, false) => backend::base64::encode::<true, false>(input, output),
Expand Down Expand Up @@ -450,7 +452,10 @@ where

#[inline]
fn decode_in_place_impl(buf: &mut [u8]) -> Result<usize, DecodeError> {
match (Alphabet::URL_SAFE, Padding::PADDED) {
match (
Alphabet::URL_SAFE,
Padding::DECODE_PADDING.uses_padded_decoder(buf),
) {
(false, false) => backend::base64::decode_in_place::<false, false>(buf),
(false, true) => backend::base64::decode_in_place::<false, true>(buf),
(true, false) => backend::base64::decode_in_place::<true, false>(buf),
Expand Down
3 changes: 2 additions & 1 deletion bases/src/codec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -591,6 +591,7 @@ pub(crate) mod sealed {

use crate::DecodeError;
use crate::backend::DecodePlan;
use crate::policy::sealed::DecodePadding;

/// A direct `Codec: Profile` bound would let downstream generic code skip
/// padding and output-capacity checks:
Expand Down Expand Up @@ -619,7 +620,7 @@ pub(crate) mod sealed {
const NAME: &'static str;
const INPUT_QUANTUM: usize;
const ENCODED_QUANTUM: usize;
const PADDED: bool;
const DECODE_PADDING: DecodePadding;

fn encoded_len_impl(input_len: usize) -> Option<usize>;
fn max_decoded_len_impl(input_len: usize) -> usize;
Expand Down
4 changes: 4 additions & 0 deletions bases/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@
//! profile exposes inherent methods directly without requiring trait imports, and implements the
//! sealed [`Codec`] trait for generic callers.
//!
//! To decode both fully padded and unpadded Base32 or Base64 input, choose
//! [`policy::PaddedOptional`] for padded output or [`policy::UnpaddedOptional`] for unpadded
//! output.
//!
//! # API layers
//!
//! - **Sizing and caller buffers (`no_std`)**: `encoded_len`, `max_decoded_len`, `encode_into`,
Expand Down
Loading
Loading