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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

All significant changes to this project will be documented in this file.

## Unreleased

### Features

* 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)

### Improvements
Expand Down
2 changes: 1 addition & 1 deletion bases/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Bases separates observable encoding semantics from execution strategy.

- 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`).
- 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.
- Slice, in-place, and fixed-array primitives (`encode_into`, `decode_into`, `decode_in_place`, `decode_array`) operate without allocation; `alloc` adds `encode`, `encode_append`, `decode`, and transactional `decode_append`; `serde` adds `serialize`, `deserialize_array`, and (`alloc`) `deserialize`.
- 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}`.
- Formatting adapters (`EncodedDisplay` and explicit-case `HexDisplay`) stream encoded output through `core::fmt`.

Expand Down
17 changes: 17 additions & 0 deletions bases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,23 @@ Every profile exposes inherent methods without requiring trait imports, and impl
| `std` | Enables `alloc`, I/O adapters, and runtime x86/x86_64 CPU feature detection. |
| `serde` | Adds `serde_core` serialization and fixed-array deserialization, including without an allocator. |

## Uninitialized output buffers

Use `encode_into_uninit` or `decode_into_uninit` when the destination is an uninitialized stack buffer or a vector's spare capacity. Use the returned slice to access the result. For padded Base64, it can be shorter than the decoding size estimate.

```rust
use core::mem::MaybeUninit;

use bases::Base64;

const WIRE: &[u8] = b"Zg==";
let mut output = [MaybeUninit::uninit(); Base64::max_decoded_len(WIRE.len())];
let decoded = Base64::decode_into_uninit(WIRE, &mut output).unwrap();
assert_eq!(decoded, b"f");
```

When passing `Vec::spare_capacity_mut()`, the returned slice borrows the new bytes and the vector keeps its original length. To append decoded bytes to a `Vec<u8>` with automatic length management, use `decode_append` with the `alloc` feature. A decoding error may leave partial writes and reports no initialized prefix.

## Streaming and errors

```rust
Expand Down
22 changes: 22 additions & 0 deletions bases/src/base16.rs
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,17 @@ where
codec::encode_into::<Self>(input, output)
}

/// Encodes into possibly uninitialized storage and returns the initialized ASCII prefix.
///
/// See [`Codec::encode_into_uninit`](crate::Codec::encode_into_uninit) for details.
#[inline]
pub fn encode_into_uninit<'output>(
input: &[u8],
output: &'output mut [MaybeUninit<u8>],
) -> Result<&'output mut str, EncodeError> {
codec::encode_into_uninit::<Self>(input, output)
}

/// Decodes `input` into `output`, returning the written prefix.
///
/// After any error, the contents of `output` are unspecified.
Expand All @@ -175,6 +186,17 @@ where
codec::decode_into::<Self>(input.as_ref(), output)
}

/// Decodes into possibly uninitialized storage and returns the initialized prefix.
///
/// See [`Codec::decode_into_uninit`](crate::Codec::decode_into_uninit) for details.
#[inline]
pub fn decode_into_uninit(
input: impl AsRef<[u8]>,
output: &mut [MaybeUninit<u8>],
) -> Result<&mut [u8], DecodeSliceError> {
codec::decode_into_uninit::<Self>(input.as_ref(), output)
}

/// Decodes `buf` in place, returning the written prefix.
///
/// After any error, the contents of `buf` are unspecified.
Expand Down
22 changes: 22 additions & 0 deletions bases/src/base32.rs
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,17 @@ where
codec::encode_into::<Self>(input, output)
}

/// Encodes into possibly uninitialized storage and returns the initialized ASCII prefix.
///
/// See [`Codec::encode_into_uninit`](crate::Codec::encode_into_uninit) for details.
#[inline]
pub fn encode_into_uninit<'output>(
input: &[u8],
output: &'output mut [MaybeUninit<u8>],
) -> Result<&'output mut str, EncodeError> {
codec::encode_into_uninit::<Self>(input, output)
}

/// Decodes `input` into `output`, returning the written prefix.
///
/// After any error, the contents of `output` are unspecified.
Expand All @@ -231,6 +242,17 @@ where
codec::decode_into::<Self>(input.as_ref(), output)
}

/// Decodes into possibly uninitialized storage and returns the initialized prefix.
///
/// See [`Codec::decode_into_uninit`](crate::Codec::decode_into_uninit) for details.
#[inline]
pub fn decode_into_uninit(
input: impl AsRef<[u8]>,
output: &mut [MaybeUninit<u8>],
) -> Result<&mut [u8], DecodeSliceError> {
codec::decode_into_uninit::<Self>(input.as_ref(), output)
}

/// Decodes `buf` in place, returning the written prefix.
///
/// After any error, the contents of `buf` are unspecified.
Expand Down
22 changes: 22 additions & 0 deletions bases/src/base64.rs
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,17 @@ where
codec::encode_into::<Self>(input, output)
}

/// Encodes into possibly uninitialized storage and returns the initialized ASCII prefix.
///
/// See [`Codec::encode_into_uninit`](crate::Codec::encode_into_uninit) for details.
#[inline]
pub fn encode_into_uninit<'output>(
input: &[u8],
output: &'output mut [MaybeUninit<u8>],
) -> Result<&'output mut str, EncodeError> {
codec::encode_into_uninit::<Self>(input, output)
}

/// Decodes `input` into `output`, returning the written prefix.
///
/// After any error, the contents of `output` are unspecified.
Expand All @@ -199,6 +210,17 @@ where
codec::decode_into::<Self>(input.as_ref(), output)
}

/// Decodes into possibly uninitialized storage and returns the initialized prefix.
///
/// See [`Codec::decode_into_uninit`](crate::Codec::decode_into_uninit) for details.
#[inline]
pub fn decode_into_uninit(
input: impl AsRef<[u8]>,
output: &mut [MaybeUninit<u8>],
) -> Result<&mut [u8], DecodeSliceError> {
codec::decode_into_uninit::<Self>(input.as_ref(), output)
}

/// Decodes `buf` in place, returning the written prefix.
///
/// After any error, the contents of `buf` are unspecified.
Expand Down
Loading
Loading