Struct Engine 

pub struct Engine<A, const PAD: bool> { /* private fields */ }

A zero-sized Base64 engine parameterized by alphabet and padding policy.

Implementations

impl<A, const PAD: bool> Engine<A, PAD>

where A: Alphabet,

pub const fn new() -> Self

Creates a new engine value.

pub const fn is_padded(&self) -> bool

Returns whether this engine uses padded Base64.

pub const fn encoded_len(&self, input_len: usize) -> Result<usize, EncodeError>

Returns the encoded length for this engine’s padding policy.

pub const fn checked_encoded_len(&self, input_len: usize) -> Option<usize>

Returns the encoded length for this engine, or None on overflow.

pub const fn wrapped_encoded_len( &self, input_len: usize, wrap: LineWrap, ) -> Result<usize, EncodeError>

Returns the encoded length after applying a line wrapping policy.

The returned length includes inserted line endings but does not include a trailing line ending after the final encoded line.

pub const fn checked_wrapped_encoded_len( &self, input_len: usize, wrap: LineWrap, ) -> Option<usize>

Returns the encoded length after line wrapping, or None on overflow or invalid line wrapping.

pub fn decoded_len(&self, input: &[u8]) -> Result<usize, DecodeError>

Returns the exact decoded length implied by input length and padding.

This validates padding placement and impossible lengths, but it does not validate alphabet membership or non-canonical trailing bits.

pub fn decoded_len_legacy(&self, input: &[u8]) -> Result<usize, DecodeError>

Returns the exact decoded length for the explicit legacy profile.

The legacy profile ignores ASCII space, tab, carriage return, and line feed bytes before applying the same alphabet, padding, and canonical-bit checks as strict decoding.

pub fn decoded_len_wrapped( &self, input: &[u8], wrap: LineWrap, ) -> Result<usize, DecodeError>

Returns the exact decoded length for a line-wrapped profile.

The wrapped profile accepts only the configured line ending. Non-final lines must contain exactly wrap.line_len encoded bytes; the final line may be shorter. A single trailing line ending after the final line is accepted.

pub fn validate_result(&self, input: &[u8]) -> Result<(), DecodeError>

Validates strict Base64 input without writing decoded bytes.

This applies the same alphabet, padding, and canonical-bit checks as Self::decode_slice. Use this method when malformed-input diagnostics matter; use Self::validate when a boolean is enough.

Examples

use base64_ng::STANDARD;

STANDARD.validate_result(b"aGVsbG8=").unwrap();
assert!(STANDARD.validate_result(b"aGVsbG8").is_err());

pub fn validate(&self, input: &[u8]) -> bool

Returns whether input is valid strict Base64 for this engine.

This is a convenience wrapper around Self::validate_result.

Examples

use base64_ng::URL_SAFE_NO_PAD;

assert!(URL_SAFE_NO_PAD.validate(b"-_8"));
assert!(!URL_SAFE_NO_PAD.validate(b"+/8"));

pub fn validate_legacy_result(&self, input: &[u8]) -> Result<(), DecodeError>

Validates input using the explicit legacy whitespace profile.

ASCII space, tab, carriage return, and line feed bytes are ignored before applying the same alphabet, padding, and canonical-bit checks as strict decoding.

Examples

use base64_ng::STANDARD;

STANDARD.validate_legacy_result(b" aG\r\nVsbG8= ").unwrap();
assert!(STANDARD.validate_legacy_result(b" aG-=").is_err());

pub fn validate_legacy(&self, input: &[u8]) -> bool

Returns whether input is valid for the explicit legacy whitespace profile.

This is a convenience wrapper around Self::validate_legacy_result.

Examples

use base64_ng::STANDARD;

assert!(STANDARD.validate_legacy(b" aG\r\nVsbG8= "));
assert!(!STANDARD.validate_legacy(b"aG-V"));

pub fn validate_wrapped_result( &self, input: &[u8], wrap: LineWrap, ) -> Result<(), DecodeError>

Validates input using a strict line-wrapped profile.

This is stricter than Self::validate_legacy_result: it accepts only the configured line ending and enforces the configured line length for every non-final line.

Examples

use base64_ng::{LineEnding, LineWrap, STANDARD};

let wrap = LineWrap::new(4, LineEnding::Lf);
STANDARD.validate_wrapped_result(b"aGVs\nbG8=", wrap).unwrap();
assert!(STANDARD.validate_wrapped_result(b"aG\nVsbG8=", wrap).is_err());

pub fn validate_wrapped(&self, input: &[u8], wrap: LineWrap) -> bool

Returns whether input is valid for a strict line-wrapped profile.

This is a convenience wrapper around Self::validate_wrapped_result.

Examples

use base64_ng::{LineEnding, LineWrap, STANDARD};

let wrap = LineWrap::new(4, LineEnding::Lf);
assert!(STANDARD.validate_wrapped(b"aGVs\nbG8=", wrap));
assert!(!STANDARD.validate_wrapped(b"aG\nVsbG8=", wrap));

pub const fn encode_array<const INPUT_LEN: usize, const OUTPUT_LEN: usize>( &self, input: &[u8; INPUT_LEN], ) -> [u8; OUTPUT_LEN]

Encodes a fixed-size input into a fixed-size output array in const contexts.

Stable Rust does not yet allow this API to return an array whose length is computed from INPUT_LEN directly. Instead, the caller supplies the output length through the destination type and this function panics during const evaluation if the length is wrong.

Panics

Panics if OUTPUT_LEN is not exactly the encoded length for INPUT_LEN and this engine’s padding policy, or if that length overflows usize.

Examples

use base64_ng::{STANDARD, URL_SAFE_NO_PAD};

const HELLO: [u8; 8] = STANDARD.encode_array(b"hello");
const URL_SAFE: [u8; 3] = URL_SAFE_NO_PAD.encode_array(b"\xfb\xff");

assert_eq!(&HELLO, b"aGVsbG8=");
assert_eq!(&URL_SAFE, b"-_8");

Incorrect output lengths fail during const evaluation:

use base64_ng::STANDARD;

const TOO_SHORT: [u8; 7] = STANDARD.encode_array(b"hello");

pub fn encode_slice( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, EncodeError>

Encodes input into output, returning the number of bytes written.

pub fn encode_slice_wrapped( &self, input: &[u8], output: &mut [u8], wrap: LineWrap, ) -> Result<usize, EncodeError>

Encodes input into output with line wrapping.

The wrapping policy inserts line endings between encoded lines and does not append a trailing line ending after the final line.

Examples

use base64_ng::{LineEnding, LineWrap, STANDARD};

let wrap = LineWrap::new(4, LineEnding::Lf);
let mut output = [0u8; 9];
let written = STANDARD
    .encode_slice_wrapped(b"hello", &mut output, wrap)
    .unwrap();

assert_eq!(&output[..written], b"aGVs\nbG8=");

pub fn encode_slice_wrapped_clear_tail( &self, input: &[u8], output: &mut [u8], wrap: LineWrap, ) -> Result<usize, EncodeError>

Encodes input with line wrapping and clears all bytes after the encoded prefix.

If encoding fails, the entire output buffer is cleared before the error is returned.

pub fn encode_wrapped_buffer<const CAP: usize>( &self, input: &[u8], wrap: LineWrap, ) -> Result<EncodedBuffer<CAP>, EncodeError>

Encodes input with line wrapping into a stack-backed buffer.

This is useful for MIME/PEM-style protocols where heap allocation is unnecessary. If encoding fails, the internal backing array is cleared before the error is returned.

pub fn encode_wrapped_vec( &self, input: &[u8], wrap: LineWrap, ) -> Result<Vec<u8>, EncodeError>

Encodes input with line wrapping into a newly allocated byte vector.

pub fn encode_wrapped_string( &self, input: &[u8], wrap: LineWrap, ) -> Result<String, EncodeError>

Encodes input with line wrapping into a newly allocated UTF-8 string.

pub fn encode_wrapped_secret( &self, input: &[u8], wrap: LineWrap, ) -> Result<SecretBuffer, EncodeError>

Encodes input with line wrapping into a redacted owned secret buffer.

This is useful when the wrapped encoded representation itself is sensitive and should not be accidentally logged through formatting.

pub fn encode_slice_clear_tail( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, EncodeError>

Encodes input into output and clears all bytes after the encoded prefix.

If encoding fails, the entire output buffer is cleared before the error is returned.

Examples

use base64_ng::STANDARD;

let mut output = [0xff; 12];
let written = STANDARD
    .encode_slice_clear_tail(b"hello", &mut output)
    .unwrap();

assert_eq!(&output[..written], b"aGVsbG8=");
assert!(output[written..].iter().all(|byte| *byte == 0));

pub fn encode_buffer<const CAP: usize>( &self, input: &[u8], ) -> Result<EncodedBuffer<CAP>, EncodeError>

Encodes input into a stack-backed buffer.

This helper is useful for short values where callers want the convenience of an owned result without enabling alloc.

Examples

use base64_ng::STANDARD;

let encoded = STANDARD.encode_buffer::<8>(b"hello").unwrap();

assert_eq!(encoded.as_str(), "aGVsbG8=");

pub fn encode_vec(&self, input: &[u8]) -> Result<Vec<u8>, EncodeError>

Encodes input into a newly allocated byte vector.

pub fn encode_secret(&self, input: &[u8]) -> Result<SecretBuffer, EncodeError>

Encodes input into a redacted owned secret buffer.

This is useful when the encoded representation itself is sensitive and should not be accidentally logged through formatting.

pub fn encode_string(&self, input: &[u8]) -> Result<String, EncodeError>

Encodes input into a newly allocated UTF-8 string.

Base64 output is ASCII by construction. This helper is available with the alloc feature and has the same encoding semantics as Self::encode_slice.

Examples

use base64_ng::{STANDARD, URL_SAFE_NO_PAD};

assert_eq!(STANDARD.encode_string(b"hello").unwrap(), "aGVsbG8=");
assert_eq!(URL_SAFE_NO_PAD.encode_string(b"\xfb\xff").unwrap(), "-_8");

pub fn encode_in_place<'a>( &self, buffer: &'a mut [u8], input_len: usize, ) -> Result<&'a mut [u8], EncodeError>

Encodes the first input_len bytes of buffer in place.

The buffer must have enough spare capacity for the encoded output. The implementation writes from right to left, so unread input bytes are not overwritten before they are encoded.

Examples

use base64_ng::STANDARD;

let mut buffer = [0u8; 8];
buffer[..5].copy_from_slice(b"hello");
let encoded = STANDARD.encode_in_place(&mut buffer, 5).unwrap();
assert_eq!(encoded, b"aGVsbG8=");

pub fn encode_in_place_clear_tail<'a>( &self, buffer: &'a mut [u8], input_len: usize, ) -> Result<&'a mut [u8], EncodeError>

Encodes the first input_len bytes of buffer in place and clears all bytes after the encoded prefix.

If encoding fails because input_len is too large, the output buffer is too small, or the encoded length overflows usize, the entire buffer is cleared before the error is returned.

Examples

use base64_ng::STANDARD;

let mut buffer = [0xff; 12];
buffer[..5].copy_from_slice(b"hello");
let encoded = STANDARD.encode_in_place_clear_tail(&mut buffer, 5).unwrap();
assert_eq!(encoded, b"aGVsbG8=");

pub fn decode_slice( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input into output, returning the number of bytes written.

This is strict decoding. Whitespace, mixed alphabets, malformed padding, and trailing non-padding data are rejected.

pub fn decode_slice_clear_tail( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input into output and clears all bytes after the decoded prefix.

If decoding fails, the entire output buffer is cleared before the error is returned.

Examples

use base64_ng::STANDARD;

let mut output = [0xff; 8];
let written = STANDARD
    .decode_slice_clear_tail(b"aGk=", &mut output)
    .unwrap();

assert_eq!(&output[..written], b"hi");
assert!(output[written..].iter().all(|byte| *byte == 0));

pub fn decode_buffer<const CAP: usize>( &self, input: &[u8], ) -> Result<DecodedBuffer<CAP>, DecodeError>

Decodes input into a stack-backed buffer.

This helper is useful for short decoded values where callers want the convenience of an owned result without enabling alloc.

Examples

use base64_ng::STANDARD;

let decoded = STANDARD.decode_buffer::<5>(b"aGVsbG8=").unwrap();

assert_eq!(decoded.as_bytes(), b"hello");

pub fn decode_slice_legacy( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input using the explicit legacy whitespace profile.

ASCII space, tab, carriage return, and line feed bytes are ignored. Alphabet selection, padding placement, trailing data after padding, and non-canonical trailing bits remain strict.

pub fn decode_slice_legacy_clear_tail( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input using the explicit legacy whitespace profile and clears all bytes after the decoded prefix.

If validation or decoding fails, the entire output buffer is cleared before the error is returned.

Examples

use base64_ng::STANDARD;

let mut output = [0xff; 8];
let written = STANDARD
    .decode_slice_legacy_clear_tail(b" aG\r\nk= ", &mut output)
    .unwrap();

assert_eq!(&output[..written], b"hi");
assert!(output[written..].iter().all(|byte| *byte == 0));

pub fn decode_buffer_legacy<const CAP: usize>( &self, input: &[u8], ) -> Result<DecodedBuffer<CAP>, DecodeError>

Decodes input into a stack-backed buffer using the explicit legacy whitespace profile.

ASCII space, tab, carriage return, and line feed bytes are ignored. Alphabet selection, padding placement, trailing data after padding, and non-canonical trailing bits remain strict. If decoding fails, the internal backing array is cleared before the error is returned.

pub fn decode_slice_wrapped( &self, input: &[u8], output: &mut [u8], wrap: LineWrap, ) -> Result<usize, DecodeError>

Decodes input using a strict line-wrapped profile.

The wrapped profile accepts only the configured line ending. Non-final lines must contain exactly wrap.line_len encoded bytes; the final line may be shorter. A single trailing line ending after the final line is accepted.

pub fn decode_slice_wrapped_clear_tail( &self, input: &[u8], output: &mut [u8], wrap: LineWrap, ) -> Result<usize, DecodeError>

Decodes input using a strict line-wrapped profile and clears all bytes after the decoded prefix.

If validation or decoding fails, the entire output buffer is cleared before the error is returned.

pub fn decode_wrapped_buffer<const CAP: usize>( &self, input: &[u8], wrap: LineWrap, ) -> Result<DecodedBuffer<CAP>, DecodeError>

Decodes input using a strict line-wrapped profile into a stack-backed buffer.

The wrapped profile accepts only the configured line ending. Non-final lines must contain exactly wrap.line_len encoded bytes; the final line may be shorter. A single trailing line ending after the final line is accepted. If decoding fails, the internal backing array is cleared before the error is returned.

pub fn decode_vec(&self, input: &[u8]) -> Result<Vec<u8>, DecodeError>

Decodes input into a newly allocated byte vector.

This is strict decoding with the same semantics as Self::decode_slice.

pub fn decode_secret(&self, input: &[u8]) -> Result<SecretBuffer, DecodeError>

Decodes input into a redacted owned secret buffer.

On malformed input, the intermediate output buffer is cleared before the error is returned by Self::decode_vec.

pub fn decode_vec_legacy(&self, input: &[u8]) -> Result<Vec<u8>, DecodeError>

Decodes input into a newly allocated byte vector using the explicit legacy whitespace profile.

pub fn decode_secret_legacy( &self, input: &[u8], ) -> Result<SecretBuffer, DecodeError>

Decodes input into a redacted owned secret buffer using the explicit legacy whitespace profile.

ASCII space, tab, carriage return, and line feed bytes are ignored. Alphabet selection, padding placement, trailing data after padding, and non-canonical trailing bits remain strict.

pub fn decode_wrapped_vec( &self, input: &[u8], wrap: LineWrap, ) -> Result<Vec<u8>, DecodeError>

Decodes line-wrapped input into a newly allocated byte vector.

pub fn decode_wrapped_secret( &self, input: &[u8], wrap: LineWrap, ) -> Result<SecretBuffer, DecodeError>

Decodes line-wrapped input into a redacted owned secret buffer.

The wrapped profile accepts only the configured line ending. Non-final lines must contain exactly wrap.line_len encoded bytes; the final line may be shorter. A single trailing line ending after the final line is accepted.

pub fn decode_in_place_wrapped<'a>( &self, buffer: &'a mut [u8], wrap: LineWrap, ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place using a strict line-wrapped profile.

The wrapped profile accepts only the configured line ending. Non-final lines must contain exactly wrap.line_len encoded bytes; the final line may be shorter. A single trailing line ending after the final line is accepted. If validation fails, the buffer contents are unspecified.

Examples

use base64_ng::{LineEnding, LineWrap, STANDARD};

let mut buffer = *b"aGVs\nbG8=";
let decoded = STANDARD
    .decode_in_place_wrapped(&mut buffer, LineWrap::new(4, LineEnding::Lf))
    .unwrap();

assert_eq!(decoded, b"hello");

pub fn decode_in_place_wrapped_clear_tail<'a>( &self, buffer: &'a mut [u8], wrap: LineWrap, ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place using a strict line-wrapped profile and clears all bytes after the decoded prefix.

If validation or decoding fails, the entire buffer is cleared before the error is returned.

Examples

use base64_ng::{LineEnding, LineWrap, STANDARD};

let mut buffer = *b"aGVs\nbG8=";
let len = STANDARD
    .decode_in_place_wrapped_clear_tail(&mut buffer, LineWrap::new(4, LineEnding::Lf))
    .unwrap()
    .len();

assert_eq!(&buffer[..len], b"hello");
assert!(buffer[len..].iter().all(|byte| *byte == 0));

pub fn decode_in_place<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes the buffer in place and returns the decoded prefix.

Examples

use base64_ng::STANDARD_NO_PAD;

let mut buffer = *b"Zm9vYmFy";
let decoded = STANDARD_NO_PAD.decode_in_place(&mut buffer).unwrap();
assert_eq!(decoded, b"foobar");

pub fn decode_in_place_clear_tail<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes the buffer in place and clears all bytes after the decoded prefix.

If decoding fails, the entire buffer is cleared before the error is returned. Use this variant when the encoded or partially decoded data is sensitive and the caller wants best-effort cleanup without adding a dependency.

Examples

use base64_ng::STANDARD;

let mut buffer = *b"aGk=";
let decoded = STANDARD.decode_in_place_clear_tail(&mut buffer).unwrap();
assert_eq!(decoded, b"hi");

pub fn decode_in_place_legacy<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place using the explicit legacy whitespace profile.

Ignored whitespace is compacted out before decoding. If validation fails, the buffer contents are unspecified.

pub fn decode_in_place_legacy_clear_tail<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place using the explicit legacy whitespace profile and clears all bytes after the decoded prefix.

If validation or decoding fails, the entire buffer is cleared before the error is returned.

Trait Implementations

impl<A, const PAD: bool> Clone for Engine<A, PAD>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A, const PAD: bool> Debug for Engine<A, PAD>

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

Formats the value using the given formatter.

impl<A, const PAD: bool> Default for Engine<A, PAD>

fn default() -> Self

Returns the “default value” for a type.

impl<A, const PAD: bool> From<Engine<A, PAD>> for Profile<A, PAD>

where A: Alphabet,

fn from(engine: Engine<A, PAD>) -> Self

Converts to this type from the input type.

impl<A, const PAD: bool> PartialEq for Engine<A, PAD>

fn eq(&self, _other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A, const PAD: bool> Copy for Engine<A, PAD>

impl<A, const PAD: bool> Eq for Engine<A, PAD>