diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f2f0e5..dff2f4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` storage and return the initialized prefix. + ## v0.1.1 (2026-11-17) ### Improvements diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md index 01edba2..6d5215c 100644 --- a/bases/ARCHITECTURE.md +++ b/bases/ARCHITECTURE.md @@ -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` 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` and `Decoder` 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`. diff --git a/bases/README.md b/bases/README.md index 178190f..1763a0d 100644 --- a/bases/README.md +++ b/bases/README.md @@ -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` 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 diff --git a/bases/src/base16.rs b/bases/src/base16.rs index 569e7ae..41a8bec 100644 --- a/bases/src/base16.rs +++ b/bases/src/base16.rs @@ -158,6 +158,17 @@ where codec::encode_into::(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], + ) -> Result<&'output mut str, EncodeError> { + codec::encode_into_uninit::(input, output) + } + /// Decodes `input` into `output`, returning the written prefix. /// /// After any error, the contents of `output` are unspecified. @@ -175,6 +186,17 @@ where codec::decode_into::(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], + ) -> Result<&mut [u8], DecodeSliceError> { + codec::decode_into_uninit::(input.as_ref(), output) + } + /// Decodes `buf` in place, returning the written prefix. /// /// After any error, the contents of `buf` are unspecified. diff --git a/bases/src/base32.rs b/bases/src/base32.rs index 0c425c3..7bdd1cd 100644 --- a/bases/src/base32.rs +++ b/bases/src/base32.rs @@ -214,6 +214,17 @@ where codec::encode_into::(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], + ) -> Result<&'output mut str, EncodeError> { + codec::encode_into_uninit::(input, output) + } + /// Decodes `input` into `output`, returning the written prefix. /// /// After any error, the contents of `output` are unspecified. @@ -231,6 +242,17 @@ where codec::decode_into::(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], + ) -> Result<&mut [u8], DecodeSliceError> { + codec::decode_into_uninit::(input.as_ref(), output) + } + /// Decodes `buf` in place, returning the written prefix. /// /// After any error, the contents of `buf` are unspecified. diff --git a/bases/src/base64.rs b/bases/src/base64.rs index 89de3b8..a555f8e 100644 --- a/bases/src/base64.rs +++ b/bases/src/base64.rs @@ -182,6 +182,17 @@ where codec::encode_into::(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], + ) -> Result<&'output mut str, EncodeError> { + codec::encode_into_uninit::(input, output) + } + /// Decodes `input` into `output`, returning the written prefix. /// /// After any error, the contents of `output` are unspecified. @@ -199,6 +210,17 @@ where codec::decode_into::(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], + ) -> Result<&mut [u8], DecodeSliceError> { + codec::decode_into_uninit::(input.as_ref(), output) + } + /// Decodes `buf` in place, returning the written prefix. /// /// After any error, the contents of `buf` are unspecified. diff --git a/bases/src/codec.rs b/bases/src/codec.rs index 8dd4ffe..ac0e910 100644 --- a/bases/src/codec.rs +++ b/bases/src/codec.rs @@ -107,6 +107,33 @@ pub trait Codec: sealed::Sealed + Sized + 'static { encode_into::(input, output) } + /// Encodes into possibly uninitialized storage and returns the initialized ASCII prefix. + /// + /// Previously initialized slots stay initialized on success and error. Their values may change. + /// + /// # Errors + /// + /// Returns the same length and capacity errors as [`encode_into`](Self::encode_into). + /// + /// # Examples + /// + /// ``` + /// use core::mem::MaybeUninit; + /// + /// use bases::Base64; + /// + /// let mut output = [MaybeUninit::uninit(); 8]; + /// let text = Base64::encode_into_uninit(b"foo", &mut output).unwrap(); + /// assert_eq!(text, "Zm9v"); + /// ``` + #[inline] + fn encode_into_uninit<'output>( + input: &[u8], + output: &'output mut [MaybeUninit], + ) -> Result<&'output mut str, EncodeError> { + encode_into_uninit::(input, output) + } + /// Decodes `input` into `output`, returning the written prefix. /// /// Decoding is strict: non-alphabet bytes, misplaced padding, and @@ -127,6 +154,41 @@ pub trait Codec: sealed::Sealed + Sized + 'static { decode_into::(input.as_ref(), output) } + /// Decodes `input` into possibly uninitialized storage and returns the initialized prefix. + /// + /// An error may leave partial writes and gives no initialized length. Previously initialized + /// slots remain initialized, but their values may change. + /// + /// # Errors + /// + /// Returns the same decoding and capacity errors as [`decode_into`](Self::decode_into). + /// An undersized buffer can be reported before the entire input has been validated. + /// + /// # Examples + /// + /// Writing into a vector's spare capacity leaves its length unchanged. Use the returned + /// slice's length to include the decoded bytes in the vector. + /// + /// ``` + /// use bases::Base64; + /// + /// let mut bytes = Vec::with_capacity(8); + /// bytes.extend_from_slice(b"id:"); + /// let start = bytes.len(); + /// let written = Base64::decode_into_uninit("Zg==", bytes.spare_capacity_mut())?.len(); + /// // SAFETY: The successful decode initialized the next `written` bytes of spare capacity. + /// unsafe { bytes.set_len(start + written) }; + /// assert_eq!(bytes.as_slice(), b"id:f"); + /// # Ok::<(), bases::DecodeSliceError>(()) + /// ``` + #[inline] + fn decode_into_uninit( + input: impl AsRef<[u8]>, + output: &mut [MaybeUninit], + ) -> Result<&mut [u8], DecodeSliceError> { + decode_into_uninit::(input.as_ref(), output) + } + /// Decodes `buf` in place, returning the written prefix. /// /// After any error, the contents of `buf` are unspecified. @@ -293,6 +355,16 @@ pub fn as_uninit_slice(bytes: &mut [u8]) -> &mut [MaybeUninit] { unsafe { slice::from_raw_parts_mut(bytes.as_mut_ptr().cast::>(), len) } } +/// # Safety +/// +/// Every slot in `bytes` must be initialized. +#[allow(unsafe_code)] +#[inline] +pub unsafe fn assume_init_slice_mut(bytes: &mut [MaybeUninit]) -> &mut [u8] { + // SAFETY: The caller guarantees initialization; the cast preserves layout and borrow. + unsafe { slice::from_raw_parts_mut(bytes.as_mut_ptr().cast::(), bytes.len()) } +} + /// Converts an ASCII byte slice to `&mut str` without re-validating UTF-8. /// /// # Safety @@ -357,11 +429,19 @@ fn append_encoded_ascii(input: &[u8], buf: &mut String, start: usize, debug_assert!(vec[start..new_len].is_ascii()); } -#[allow(unsafe_code)] #[inline] pub fn encode_into<'output, C: Codec>( input: &[u8], output: &'output mut [u8], +) -> Result<&'output mut str, EncodeError> { + encode_into_uninit::(input, as_uninit_slice(output)) +} + +#[allow(unsafe_code)] +#[inline] +pub fn encode_into_uninit<'output, C: Codec>( + input: &[u8], + output: &'output mut [MaybeUninit], ) -> Result<&'output mut str, EncodeError> { let required = C::encoded_len(input.len())?; if output.len() < required { @@ -371,18 +451,30 @@ pub fn encode_into<'output, C: Codec>( }); } - let written = C::Profile::encode_impl(input, as_uninit_slice(output)); + let written = C::Profile::encode_impl(input, output); debug_assert_eq!(written, required); - // SAFETY: Binary-to-text backends always write `written` initialized ASCII bytes into - // `output[..written]`. - Ok(unsafe { ascii_to_str_mut(&mut output[..written]) }) + let output = &mut output[..written]; + // SAFETY: The backend initialized this prefix as ASCII. + Ok(unsafe { + let bytes = assume_init_slice_mut(output); + ascii_to_str_mut(bytes) + }) } #[inline] pub fn decode_into<'output, C: Codec>( input: &[u8], output: &'output mut [u8], +) -> Result<&'output mut [u8], DecodeSliceError> { + decode_into_uninit::(input, as_uninit_slice(output)) +} + +#[allow(unsafe_code)] +#[inline] +pub fn decode_into_uninit<'output, C: Codec>( + input: &[u8], + output: &'output mut [MaybeUninit], ) -> Result<&'output mut [u8], DecodeSliceError> { let plan = C::Profile::decode_plan_impl(input)?; if output.len() < plan.required { @@ -393,9 +485,10 @@ pub fn decode_into<'output, C: Codec>( } let out = &mut output[..plan.required]; - let written = C::Profile::decode_with_plan_impl(input, plan, as_uninit_slice(out))?; + let written = C::Profile::decode_with_plan_impl(input, plan, out)?; debug_assert_eq!(written, plan.required); - Ok(out) + // SAFETY: Successful decoding initializes exactly the `plan.required` bytes in `out`. + Ok(unsafe { assume_init_slice_mut(out) }) } #[inline] @@ -518,6 +611,10 @@ pub(crate) mod sealed { /// Quanta must satisfy `0 < INPUT_QUANTUM < ENCODED_QUANTUM` and fit the /// stream buffers; sizing and buffering rely on these bounds. + /// + /// Output methods must initialize the full reported prefix on success, using ASCII bytes + /// for encoding. Every write must preserve initialization of previously initialized slots, + /// including when decoding returns an error. pub trait Profile { const NAME: &'static str; const INPUT_QUANTUM: usize; @@ -542,3 +639,79 @@ pub(crate) mod sealed { fn decoded_padding_reduction(padding: usize) -> Option; } } + +#[cfg(test)] +mod tests { + use core::hint; + use core::mem::MaybeUninit; + + use crate::Base16Lower; + use crate::Base32; + use crate::Base64; + use crate::DecodeError; + use crate::DecodeSliceError; + + #[test] + fn initialized_storage_remains_readable_after_decode_error() { + let mut storage = [7_u8; 12]; + assert_eq!( + Base64::decode_into("Zm9v!!!!", &mut storage[2..8]), + Err(DecodeSliceError::Decode(DecodeError::InvalidByte { + index: 4, + byte: b'!', + })), + ); + assert_eq!(&storage[..2], &[7; 2]); + assert_eq!(&storage[8..], &[7; 4]); + for byte in storage { + hint::black_box(byte); + } + } + + #[test] + fn uninitialized_results_are_borrowed_prefixes() { + let mut encoded = [MaybeUninit::::uninit(); 8]; + let encoded_ptr = encoded.as_ptr().cast::(); + let text = Base64::encode_into_uninit(b"foo", &mut encoded).unwrap(); + assert_eq!(text, "Zm9v"); + assert_eq!(text.as_ptr(), encoded_ptr); + + let mut decoded = [MaybeUninit::::uninit(); 8]; + let decoded_ptr = decoded.as_ptr().cast::(); + let bytes = Base64::decode_into_uninit("/w==", &mut decoded).unwrap(); + assert_eq!(bytes, [0xff]); + assert_eq!(bytes.as_ptr(), decoded_ptr); + + let mut hex = [MaybeUninit::::uninit(); 2]; + assert_eq!( + Base16Lower::encode_into_uninit(b"\xff", &mut hex).unwrap(), + "ff" + ); + assert_eq!( + Base16Lower::decode_into_uninit("ff", &mut hex).unwrap(), + [0xff] + ); + } + + #[test] + fn base32_bulk_output_initializes_only_the_successful_prefix() { + let mut raw = [0_u8; 161]; + raw[160] = b'f'; + let mut wire = [b'A'; 264]; + wire[256..].copy_from_slice(b"MY======"); + + let mut encoded = [MaybeUninit::::uninit(); 272]; + assert_eq!( + Base32::encode_into_uninit(&raw, &mut encoded) + .unwrap() + .as_bytes(), + wire, + ); + let mut decoded = [MaybeUninit::::uninit(); Base32::max_decoded_len(264)]; + assert_eq!(Base32::decode_into_uninit(wire, &mut decoded).unwrap(), raw); + + wire[255] = b'!'; + let mut output = [MaybeUninit::::uninit(); Base32::max_decoded_len(264)]; + assert!(Base32::decode_into_uninit(wire, &mut output).is_err()); + } +} diff --git a/bases/src/lib.rs b/bases/src/lib.rs index 6b9e4cd..8fbe3e2 100644 --- a/bases/src/lib.rs +++ b/bases/src/lib.rs @@ -66,7 +66,8 @@ //! - **Sizing and caller buffers (`no_std`)**: `encoded_len`, `max_decoded_len`, `encode_into`, //! `decode_into`, `decode_in_place`, and `decode_array` operate without allocation, with `const //! fn` support on concrete profile `new`, `name`, `encoded_len`, `max_decoded_len`, `display`, -//! `encoder`, and `decoder`. +//! `encoder`, and `decoder`. [`Codec::encode_into_uninit`] and [`Codec::decode_into_uninit`] +//! accept caller-provided `MaybeUninit` storage. //! - **Owned and append helpers (`alloc`)**: `encode`, `encode_append`, `decode`, and transactional //! `decode_append` return or extend `String` and `Vec`. //! - **Incremental streaming (`no_std` / `std`)**: [`Encoder`] and [`Decoder`] process arbitrarily diff --git a/tests-integration/tests/contracts.rs b/tests-integration/tests/contracts.rs index e1f9204..c6a81d6 100644 --- a/tests-integration/tests/contracts.rs +++ b/tests-integration/tests/contracts.rs @@ -71,6 +71,10 @@ macro_rules! profile { buffers::check::(&reference($alphabet, $padded, $mixed)); } #[test] + fn uninitialized_output_buffers() { + buffers::uninitialized::(&reference($alphabet, $padded, $mixed)); + } + #[test] fn fixed_arrays() { buffers::arrays::(&reference($alphabet, $padded, $mixed)); } diff --git a/tests-integration/tests/contracts/buffers.rs b/tests-integration/tests/contracts/buffers.rs index 97d5377..9db0e5f 100644 --- a/tests-integration/tests/contracts/buffers.rs +++ b/tests-integration/tests/contracts/buffers.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +use core::mem::MaybeUninit; + use bases::Codec; use bases::DecodeError; use bases::DecodeSliceError; @@ -108,6 +110,76 @@ pub fn check(reference: &Encoding) { } } +pub fn uninitialized(reference: &Encoding) { + for len in [ + 0, 1, 2, 3, 4, 5, 12, 15, 16, 17, 24, 31, 32, 33, 63, 64, 65, 159, 160, 161, 164, 1024, + ] { + let raw = payload(len); + let wire = reference.encode(&raw); + for offset in [0, 1] { + for capacity in [wire.len(), wire.len() + 32] { + with_guarded_output(offset, capacity, |output| { + assert_eq!(C::encode_into_uninit(&raw, output).unwrap(), wire.as_str()); + }); + } + + for capacity in [len, C::max_decoded_len(wire.len()), len + 32] { + with_guarded_output(offset, capacity, |output| { + assert_eq!(C::decode_into_uninit(&wire, output).unwrap(), raw); + }); + } + } + + if len != 0 { + let mut encoded = vec![MaybeUninit::::uninit(); wire.len() - 1]; + assert_eq!( + C::encode_into_uninit(&raw, &mut encoded), + Err(EncodeError::OutputTooSmall { + required: wire.len(), + available: wire.len() - 1, + }), + ); + let mut decoded = vec![MaybeUninit::::uninit(); len - 1]; + assert_eq!( + C::decode_into_uninit(&wire, &mut decoded), + Err(DecodeSliceError::OutputTooSmall { + required: len, + available: len - 1, + }), + ); + } + } + + let wire = reference.encode(b"foo"); + let mut encoded = Vec::::with_capacity(wire.len()); + assert_eq!( + C::encode_into_uninit(b"foo", encoded.spare_capacity_mut()).unwrap(), + wire.as_str(), + ); + assert_eq!(encoded.len(), 0); + + let mut decoded = Vec::::with_capacity(C::max_decoded_len(wire.len())); + assert_eq!( + C::decode_into_uninit(&wire, decoded.spare_capacity_mut()).unwrap(), + b"foo", + ); + assert_eq!(decoded.len(), 0); +} + +#[allow(unsafe_code)] +fn with_guarded_output(offset: usize, capacity: usize, check: impl FnOnce(&mut [MaybeUninit])) { + let mut storage = vec![MaybeUninit::new(0xa5); offset + capacity + 32]; + let (before, rest) = storage.split_at_mut(offset); + let (output, after) = rest.split_at_mut(capacity); + output.fill(MaybeUninit::uninit()); + check(output); + + for guard in before.iter().chain(after.iter()) { + // SAFETY: Both guard slices contain 0xa5 at initialization and only `output` is lent out. + assert_eq!(unsafe { guard.assume_init() }, 0xa5); + } +} + pub fn short_inputs(reference: &Encoding) { // Exhaust all one- and two-byte messages, including the partial-quantum packing rules. for byte in 0..=255 { diff --git a/tests-integration/tests/contracts/malformed.rs b/tests-integration/tests/contracts/malformed.rs index 90efed2..0bb5678 100644 --- a/tests-integration/tests/contracts/malformed.rs +++ b/tests-integration/tests/contracts/malformed.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +use core::mem::MaybeUninit; + use bases::Codec; use bases::DecodeError; use bases::DecodeSliceError; @@ -116,6 +118,11 @@ fn assert_error(wire: &[u8], expected: DecodeError) { C::decode_into(wire, &mut output), err(eq(&DecodeSliceError::Decode(expected))) ); + let mut uninitialized = vec![MaybeUninit::::uninit(); output.len()]; + assert_that!( + C::decode_into_uninit(wire, &mut uninitialized), + err(eq(&DecodeSliceError::Decode(expected))) + ); assert_that!(C::decode(wire), err(eq(&expected))); assert_that!(C::decode_in_place(&mut wire.to_vec()), err(eq(&expected)));