Struct EncodedBuffer 

pub struct EncodedBuffer<const CAP: usize> { /* private fields */ }

Stack-backed encoded Base64 output.

This type is intended for short values where heap allocation would be unnecessary but manually sizing and passing a separate output slice is noisy. Its visible bytes are produced by crate encoders, so Self::as_str can return &str without exposing a fallible UTF-8 conversion to callers. core::fmt::Display intentionally writes the full encoded text; use SecretBuffer for encoded secrets that may reach logs or error messages.

The backing array is cleared when the value is dropped. This is best-effort data-retention reduction and is not a formal zeroization guarantee.

On wasm32 targets, the wipe barrier uses only a compiler fence. The wasm runtime JIT may still optimize or retain cleared bytes in ways this crate cannot control. wasm32 builds fail closed by default; enable allow-wasm32-best-effort-wipe only when the deployment explicitly accepts this limitation and applies its own memory strategy around stack-backed buffers.

Implementations

impl<const CAP: usize> EncodedBuffer<CAP>

pub const fn new() -> Self

Creates an empty encoded buffer.

pub const fn len(&self) -> usize

Returns the number of visible encoded bytes.

pub const fn is_empty(&self) -> bool

Returns whether the buffer has no visible encoded bytes.

pub const fn is_full(&self) -> bool

Returns whether the visible encoded bytes fill the stack backing array.

pub const fn capacity(&self) -> usize

Returns the stack capacity in bytes.

pub const fn remaining_capacity(&self) -> usize

Returns the number of unused bytes in the stack backing array.

pub fn as_bytes(&self) -> &[u8]

Returns the visible encoded bytes.

pub fn as_utf8(&self) -> Result<&str, Utf8Error>

Returns the visible encoded bytes as UTF-8 text.

Encoded Base64 output is produced as ASCII by this crate, so this method should not fail unless an internal invariant has been broken. It is provided for callers that prefer a fallible accessor over Self::as_str.

pub fn as_str(&self) -> &str

Returns the visible encoded bytes as UTF-8.

Panics

Panics only if the crate’s internal invariant is broken and the buffer contains non-UTF-8 bytes.

pub fn constant_time_eq_public_len(&self, other: &[u8]) -> bool

Compares this encoded output to other without short-circuiting on the first differing byte.

Length and the final equality result remain public. Different lengths return false immediately; use this helper only when the compared lengths are public protocol facts or have been normalized by the caller. For equal-length inputs, this helper scans every byte before returning. It is constant-time-oriented best effort, not a formal cryptographic constant-time guarantee. This comparison is deliberately explicit: redacted buffer types do not implement PartialEq because == would make a best-effort helper look like a formal token/MAC comparison primitive.

Do not use this helper as the sole MAC, bearer-token, password-hash, or authentication-secret comparison primitive in high-assurance systems. Applications that can admit dependencies should use a reviewed constant-time comparison primitive, such as subtle, at the protocol boundary.

pub fn into_exposed_array(self) -> ExposedEncodedArray<CAP>

Consumes the wrapper and returns the backing array plus visible length inside a drop-wiping exposed wrapper.

This is an explicit escape hatch for no-alloc interop with APIs that require ownership of a fixed array. The returned ExposedEncodedArray remains redacted by formatting and clears its backing array on drop.

pub fn clear(&mut self)

Clears the visible bytes and the full backing array.

pub fn clear_tail(&mut self)

Clears bytes after the visible prefix.

Trait Implementations

impl<const CAP: usize> AsRef<[u8]> for EncodedBuffer<CAP>

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl<const CAP: usize> Clone for EncodedBuffer<CAP>

fn clone(&self) -> Self

Clones the visible encoded bytes into a second stack-backed buffer.

Security note: cloning duplicates the visible bytes in memory. Both the original and the clone must be dropped or explicitly cleared before the duplicated bytes are gone on the crate’s best-effort cleanup path. The compiler may also create temporary stack copies while performing the copy; those intermediates are outside this crate’s cleanup boundary. Avoid cloning encoded secret material; use SecretBuffer when redacted formatting and heap-owned secret handling are required.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const CAP: usize> Debug for EncodedBuffer<CAP>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const CAP: usize> Default for EncodedBuffer<CAP>

fn default() -> Self

Returns the “default value” for a type.

impl<const CAP: usize> Display for EncodedBuffer<CAP>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Writes the full Base64 text.

Security note: this is intentionally not redacted. Do not use EncodedBuffer for encoded secrets that may reach logs or error messages; use SecretBuffer for redacted formatting.

impl<const CAP: usize> Drop for EncodedBuffer<CAP>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<const CAP: usize> From<EncodedBuffer<CAP>> for SecretBuffer

Available on crate feature alloc only.

fn from(buffer: EncodedBuffer<CAP>) -> Self

Copies visible encoded bytes from a stack-backed buffer into an owned redacted buffer.

The consumed stack-backed buffer clears its backing array when it is dropped at the end of the conversion.

impl<const CAP: usize, const N: usize> TryFrom<&[u8; N]> for EncodedBuffer<CAP>

fn try_from(input: &[u8; N]) -> Result<Self, Self::Error>

Encodes a byte array into strict standard padded Base64 in a stack-backed buffer.

Use crate::Engine::encode_buffer or crate::Profile::encode_buffer when a different alphabet, padding mode, or line-wrapping profile is required.

type Error = EncodeError

The type returned in the event of a conversion error.

impl<const CAP: usize> TryFrom<&[u8]> for EncodedBuffer<CAP>

fn try_from(input: &[u8]) -> Result<Self, Self::Error>

Encodes bytes into strict standard padded Base64 in a stack-backed buffer.

Use crate::Engine::encode_buffer or crate::Profile::encode_buffer when a different alphabet, padding mode, or line-wrapping profile is required.

type Error = EncodeError

The type returned in the event of a conversion error.

impl<const CAP: usize> TryFrom<&str> for EncodedBuffer<CAP>

fn try_from(input: &str) -> Result<Self, Self::Error>

Encodes UTF-8 text bytes into strict standard padded Base64 in a stack-backed buffer.

This treats the string as raw input bytes. Use crate::Engine::encode_buffer or crate::Profile::encode_buffer when a different alphabet, padding mode, or line-wrapping profile is required.

type Error = EncodeError

The type returned in the event of a conversion error.