qubit_codec_misc/

base64_quantum_codec.rs

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Base64 quantum codec.

use core::num::NonZeroUsize;

use base64::DecodeError;
use qubit_codec::Codec;
use qubit_codec::DecodeFailure;
use qubit_utils::nonzero;

use crate::MiscCodecError;
use crate::MiscCodecResult;
use crate::misc_error::map_misc_decode_failure_with_consumed;

/// Encodes and decodes one complete Base64 quantum.
///
/// A quantum maps exactly three raw bytes to four Base64 units. It does not
/// handle final short input groups or `=` padding; callers that process streams
/// must finalize those cases in a transcoder or facade layer.
///
/// # Examples
///
/// ```
/// use qubit_codec::Codec;
/// use qubit_codec_misc::Base64QuantumCodec;
///
/// let mut codec = Base64QuantumCodec::standard();
/// let mut encoded = [0; 4];
/// // SAFETY: `encoded` has room for the four units written by one quantum.
/// let written = unsafe { codec.encode(b"Man", &mut encoded, 0) }
///     .expect("three bytes can be encoded");
/// assert_eq!(written, 4);
/// assert_eq!(&encoded, b"TWFu");
/// ```
#[must_use]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Base64QuantumCodec {
    /// Selects the URL-safe alphabet when set; otherwise the standard alphabet
    /// is used.
    url_safe: bool,
}

impl Base64QuantumCodec {
    /// Creates a standard-alphabet Base64 quantum codec.
    ///
    /// # Returns
    /// Standard Base64 quantum codec.
    #[inline]
    pub fn standard() -> Self {
        Self { url_safe: false }
    }

    /// Creates a URL-safe-alphabet Base64 quantum codec.
    ///
    /// # Returns
    /// URL-safe Base64 quantum codec.
    #[inline]
    pub fn url_safe() -> Self {
        Self { url_safe: true }
    }

    /// Selects the alphabet for this quantum codec.
    ///
    /// # Returns
    /// The 64-byte alphabet used for encoding.
    #[must_use]
    #[inline]
    fn alphabet(&self) -> &'static [u8; 64] {
        if self.url_safe {
            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
        } else {
            b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
        }
    }

    /// Converts one Base64 unit to a sextet.
    ///
    /// # Parameters
    /// - `unit`: Encoded Base64 unit.
    /// - `index`: Unit index in the original input.
    ///
    /// # Returns
    /// Sextet value.
    ///
    /// # Errors
    /// Returns [`MiscCodecError::InvalidBase64`] with an
    /// [`base64::DecodeError::InvalidByte`] source when `unit` is not valid for
    /// this quantum codec's alphabet. The index is relative to the original
    /// input slice.
    fn decode_unit(&self, unit: u8, index: usize) -> MiscCodecResult<u8> {
        match unit {
            b'A'..=b'Z' => Ok(unit - b'A'),
            b'a'..=b'z' => Ok(unit - b'a' + 26),
            b'0'..=b'9' => Ok(unit - b'0' + 52),
            b'+' if !self.url_safe => Ok(62),
            b'/' if !self.url_safe => Ok(63),
            b'-' if self.url_safe => Ok(62),
            b'_' if self.url_safe => Ok(63),
            _ => Err(MiscCodecError::from(DecodeError::InvalidByte(index, unit))),
        }
    }
}

impl Default for Base64QuantumCodec {
    /// Creates a standard-alphabet Base64 quantum codec.
    ///
    /// # Returns
    /// A codec configured to use the standard Base64 alphabet.
    #[inline]
    fn default() -> Self {
        Self::standard()
    }
}

impl Codec for Base64QuantumCodec {
    /// Raw value represented by one complete Base64 quantum.
    type Value = [u8; 3];
    /// Encoded unit used by the Base64 alphabet.
    type Unit = u8;
    /// Error reported when an encoded unit is outside the selected alphabet.
    type DecodeError = MiscCodecError;
    /// Error type exposed by the codec's encoding operation.
    type EncodeError = MiscCodecError;

    const MIN_UNITS_PER_VALUE: usize = 4;
    const MAX_ENCODE_UNITS_PER_VALUE: usize = 4;

    const MAX_DECODE_UNITS_PER_VALUE: usize = 4;

    /// Decodes one complete four-unit Base64 quantum.
    ///
    /// # Parameters
    /// - `input`: Encoded Base64 units containing the quantum.
    /// - `input_index`: Index of the first unit in the quantum.
    ///
    /// # Returns
    /// The decoded three-byte value and the number of consumed input units.
    ///
    /// # Errors
    /// Returns a decode failure with [`MiscCodecError::InvalidBase64`] when any
    /// unit is not valid for the selected alphabet. Its input index is relative
    /// to `input`, and the failure reports that the complete four-unit quantum
    /// was consumed.
    ///
    /// # Safety
    /// The caller must ensure that four units starting at `input_index` are
    /// readable in `input`.
    unsafe fn decode(
        &mut self,
        input: &[u8],
        input_index: usize,
    ) -> Result<([u8; 3], NonZeroUsize), DecodeFailure<Self::DecodeError>> {
        debug_assert!(input_index + 4 <= input.len());

        let first = self
            .decode_unit(input[input_index], input_index)
            .map_err(|error| map_misc_decode_failure_with_consumed(error, nonzero(4)))?;
        let second = self
            .decode_unit(input[input_index + 1], input_index + 1)
            .map_err(|error| map_misc_decode_failure_with_consumed(error, nonzero(4)))?;
        let third = self
            .decode_unit(input[input_index + 2], input_index + 2)
            .map_err(|error| map_misc_decode_failure_with_consumed(error, nonzero(4)))?;
        let fourth = self
            .decode_unit(input[input_index + 3], input_index + 3)
            .map_err(|error| map_misc_decode_failure_with_consumed(error, nonzero(4)))?;
        Ok((
            [
                (first << 2) | (second >> 4),
                (second << 4) | (third >> 2),
                (third << 6) | fourth,
            ],
            nonzero(4),
        ))
    }

    /// Encodes one complete three-byte Base64 quantum.
    ///
    /// # Parameters
    /// - `value`: Three raw bytes to encode.
    /// - `output`: Destination buffer for four encoded units.
    /// - `output_index`: Index of the first destination unit to write.
    ///
    /// # Returns
    /// The number of output units written, which is always four.
    ///
    /// # Errors
    /// This implementation does not return an error.
    ///
    /// # Safety
    /// The caller must ensure that four units starting at `output_index` are
    /// writable in `output`.
    unsafe fn encode(
        &mut self,
        value: &[u8; 3],
        output: &mut [u8],
        output_index: usize,
    ) -> Result<usize, Self::EncodeError> {
        debug_assert!(output_index + 4 <= output.len());

        let alphabet = self.alphabet();
        output[output_index] = alphabet[(value[0] >> 2) as usize];
        output[output_index + 1] = alphabet[(((value[0] & 0x03) << 4) | (value[1] >> 4)) as usize];
        output[output_index + 2] = alphabet[(((value[1] & 0x0f) << 2) | (value[2] >> 6)) as usize];
        output[output_index + 3] = alphabet[(value[2] & 0x3f) as usize];
        Ok(4)
    }
}