base64url_nopad 0.2.0

//! [![git]](https://git.philomathiclife.com/base64url_nopad/log.html) [![crates-io]](https://crates.io/crates/base64url_nopad) [![docs-rs]](crate)
//!
//! [git]: https://git.philomathiclife.com/git_badge.svg
//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
//!
//! `base64url_nopad` is a library for fast, efficient, correct, and `const` encoding and decoding of base64url
//! without padding data. All functions that can be `const` are `const`. Great care is made to ensure _all_
//! arithmetic is free from "side effects" (e.g., overflow). `panic`s are avoided at all costs unless explicitly
//! documented _including_ `panic`s related to memory allocations.
//!
//! ## `base64url_nopad` in action
//!
//! ```
//! # use base64url_nopad::DecodeErr;
//! /// Length of our input to encode.
//! const INPUT_LEN: usize = 259;
//! /// The base64url encoded value without padding of our input.
//! const ENCODED_VAL: &str = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn-AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq-wsbKztLW2t7i5uru8vb6_wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t_g4eLj5OXm5-jp6uvs7e7v8PHy8_T19vf4-fr7_P3-_1MH0Q";
//! let mut input = [0; INPUT_LEN];
//! for i in 0..=255 {
//!     input[usize::from(i)] = i;
//! }
//! input[256] = 83;
//! input[257] = 7;
//! input[258] = 209;
//! let mut output = [0; base64url_nopad::encode_len(INPUT_LEN)];
//! assert_eq!(base64url_nopad::encode_buffer(&input, &mut output), ENCODED_VAL);
//! assert_eq!(base64url_nopad::decode_len(output.len()), Some(INPUT_LEN));
//! base64url_nopad::decode_buffer(ENCODED_VAL.as_bytes(), &mut output[..INPUT_LEN])?;
//! assert_eq!(input, output[..INPUT_LEN]);
//! # Ok::<_, DecodeErr>(())
//! ```
//!
//! ## Cargo "features"
//!
//! ### `alloc`
//!
//! Enables support for memory allocations via [`alloc`].
//!
//! ## Correctness of code
//!
//! This library is written in a way that is free from any overflow, underflow, or other kinds of
//! "arithmetic side effects". All functions that can `panic` are explicitly documented as such; and all
//! possible `panic`s are isolated to convenience functions that `panic` instead of error. Strict encoding and
//! decoding is performed; thus if an input contains _any_ invalid data, it is guaranteed to fail when decoding
//! it (e.g., trailing non-zero bits).
#![expect(
    clippy::doc_paragraphs_missing_punctuation,
    reason = "false positive for crate documentation having image links"
)]
#![cfg_attr(
    all(
        test,
        target_os = "macos",
        any(
            target_pointer_width = "16",
            target_pointer_width = "32",
            target_pointer_width = "64"
        )
    ),
    allow(linker_info, reason = "getrandom causes linker-info to fire on macos")
)]
#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#[cfg(any(doc, feature = "alloc"))]
extern crate alloc;
/// Unit tests.
#[cfg(test)]
mod tests;
#[cfg(any(doc, feature = "alloc"))]
use alloc::{collections::TryReserveError, string::String, vec::Vec};
use core::{
    error::Error,
    fmt::{self, Display, Formatter, Write},
    hint::cold_path,
    mem,
};
/// The base64url alphabet.
#[expect(
    non_camel_case_types,
    reason = "want to use a variant as close to what the value is"
)]
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq, PartialOrd, Ord)]
#[repr(u8)]
pub enum Alphabet {
    /// A.
    #[default]
    A,
    /// B.
    B,
    /// C.
    C,
    /// D.
    D,
    /// E.
    E,
    /// F.
    F,
    /// G.
    G,
    /// H.
    H,
    /// I.
    I,
    /// J.
    J,
    /// K.
    K,
    /// L.
    L,
    /// M.
    M,
    /// N.
    N,
    /// O.
    O,
    /// P.
    P,
    /// Q.
    Q,
    /// R.
    R,
    /// S.
    S,
    /// T.
    T,
    /// U.
    U,
    /// V.
    V,
    /// W.
    W,
    /// X.
    X,
    /// Y.
    Y,
    /// Z.
    Z,
    /// a.
    a,
    /// b.
    b,
    /// c.
    c,
    /// d.
    d,
    /// e.
    e,
    /// f.
    f,
    /// g.
    g,
    /// h.
    h,
    /// i.
    i,
    /// j.
    j,
    /// k.
    k,
    /// l.
    l,
    /// m.
    m,
    /// n.
    n,
    /// o.
    o,
    /// p.
    p,
    /// q.
    q,
    /// r.
    r,
    /// s.
    s,
    /// t.
    t,
    /// u.
    u,
    /// v.
    v,
    /// w.
    w,
    /// x.
    x,
    /// y.
    y,
    /// z.
    z,
    /// 0.
    Zero,
    /// 1.
    One,
    /// 2.
    Two,
    /// 3.
    Three,
    /// 4.
    Four,
    /// 5.
    Five,
    /// 6.
    Six,
    /// 7.
    Seven,
    /// 8.
    Eight,
    /// 9.
    Nine,
    /// -.
    Hyphen,
    /// _.
    Underscore,
}
/// Sorted ASCII `u8`s for [`Alphabet`].
const ASCII: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
/// Sorted `char`s for [`Alphabet`].
const CHARS: &[char; 64] = &[
    'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S',
    'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',
    'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4',
    '5', '6', '7', '8', '9', '-', '_',
];
/// [`Alphabet`] variants indexed based on the their ASCII representation.
const FROM_ASCII: &[Option<Alphabet>; 256] = &[
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    Some(Alphabet::Hyphen),
    None,
    None,
    Some(Alphabet::Zero),
    Some(Alphabet::One),
    Some(Alphabet::Two),
    Some(Alphabet::Three),
    Some(Alphabet::Four),
    Some(Alphabet::Five),
    Some(Alphabet::Six),
    Some(Alphabet::Seven),
    Some(Alphabet::Eight),
    Some(Alphabet::Nine),
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    Some(Alphabet::A),
    Some(Alphabet::B),
    Some(Alphabet::C),
    Some(Alphabet::D),
    Some(Alphabet::E),
    Some(Alphabet::F),
    Some(Alphabet::G),
    Some(Alphabet::H),
    Some(Alphabet::I),
    Some(Alphabet::J),
    Some(Alphabet::K),
    Some(Alphabet::L),
    Some(Alphabet::M),
    Some(Alphabet::N),
    Some(Alphabet::O),
    Some(Alphabet::P),
    Some(Alphabet::Q),
    Some(Alphabet::R),
    Some(Alphabet::S),
    Some(Alphabet::T),
    Some(Alphabet::U),
    Some(Alphabet::V),
    Some(Alphabet::W),
    Some(Alphabet::X),
    Some(Alphabet::Y),
    Some(Alphabet::Z),
    None,
    None,
    None,
    None,
    Some(Alphabet::Underscore),
    None,
    Some(Alphabet::a),
    Some(Alphabet::b),
    Some(Alphabet::c),
    Some(Alphabet::d),
    Some(Alphabet::e),
    Some(Alphabet::f),
    Some(Alphabet::g),
    Some(Alphabet::h),
    Some(Alphabet::i),
    Some(Alphabet::j),
    Some(Alphabet::k),
    Some(Alphabet::l),
    Some(Alphabet::m),
    Some(Alphabet::n),
    Some(Alphabet::o),
    Some(Alphabet::p),
    Some(Alphabet::q),
    Some(Alphabet::r),
    Some(Alphabet::s),
    Some(Alphabet::t),
    Some(Alphabet::u),
    Some(Alphabet::v),
    Some(Alphabet::w),
    Some(Alphabet::x),
    Some(Alphabet::y),
    Some(Alphabet::z),
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    None,
];
impl Alphabet {
    /// Returns `Self` that corresponds to `b`.
    ///
    /// `Some` is returned iff `b` is in `0..=63`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// assert_eq!(Alphabet::from_u8(25), Some(Alphabet::Z));
    /// for i in 0..=63 {
    ///     assert!(Alphabet::from_u8(i).is_some());
    /// }
    /// for i in 64..=255 {
    ///     assert!(Alphabet::from_u8(i).is_none());
    /// }
    /// ```
    #[expect(unsafe_code, reason = "comment justifies correctness")]
    #[expect(clippy::as_conversions, reason = "comment justifies correctness")]
    #[inline]
    #[must_use]
    pub const fn from_u8(b: u8) -> Option<Self> {
        // `Self` is `repr(u8)` and all `u8`s are valid from 0 until the maximum value
        // represented by `Self::Underscore`.
        if b <= Self::Underscore as u8 {
            // SAFETY:
            // Our safety precondition is that `b` is in-range.
            Some(unsafe { mem::transmute::<u8, Self>(b) })
        } else {
            None
        }
    }
    /// Returns the `u8` `self` represents.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// assert_eq!(Alphabet::Hyphen.to_u8(), 62);
    /// assert_eq!(Alphabet::Eight.to_u8(), Alphabet::Eight as u8);
    /// ```
    #[expect(clippy::as_conversions, reason = "comment justifies correctness")]
    #[inline]
    #[must_use]
    pub const fn to_u8(self) -> u8 {
        // `Self` is `repr(u8)`; thus this is correct.
        self as u8
    }
    /// Returns the ASCII representation of `self`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// assert_eq!(Alphabet::c.to_ascii(), b'c');
    /// ```
    #[expect(
        clippy::as_conversions,
        clippy::indexing_slicing,
        reason = "comments justify correctness"
    )]
    #[inline]
    #[must_use]
    pub const fn to_ascii(self) -> u8 {
        // `u8 as usize` is always OK; and we want this to be `const` so can't rely on `usize::from`.
        // `self.to_u8() < 64` and `ASCII.len() == 64`, so indexing can't `panic`.
        ASCII[self.to_u8() as usize]
    }
    /// Returns `Some` iff `ascii` is the ASCII representation of `Self`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// for i in 0u8..=255 {
    ///     if i.is_ascii_alphanumeric() || i == b'-' || i == b'_' {
    ///         assert!(Alphabet::from_ascii(i).is_some());
    ///     } else {
    ///         assert!(Alphabet::from_ascii(i).is_none());
    ///     }
    /// }
    /// ```
    #[expect(
        clippy::as_conversions,
        clippy::indexing_slicing,
        reason = "comments justify correctness"
    )]
    #[inline]
    #[must_use]
    pub const fn from_ascii(ascii: u8) -> Option<Self> {
        // `u8 as usize` is always OK; and we want this to be `const` so can't rely on `usize::from`.
        // `FROM_ASCII` has length 256, so indexing can't `panic`.
        FROM_ASCII[ascii as usize]
    }
    /// Same as [`Self::to_ascii`] except a `char` is returned.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// assert_eq!(Alphabet::J.to_char(), 'J');
    /// ```
    #[expect(
        clippy::as_conversions,
        clippy::indexing_slicing,
        reason = "comments justify correctness"
    )]
    #[inline]
    #[must_use]
    pub const fn to_char(self) -> char {
        // `u8 as usize` is always OK; and we want this to be `const` so can't rely on `usize::from`.
        // `self.to_u8() < 64` and `CHARS.len() == 64`, so indexing can't `panic`.
        CHARS[self.to_u8() as usize]
    }
    /// Same as [`Self::from_ascii`] except the input is a `char`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use base64url_nopad::Alphabet;
    /// for i in char::MIN..=char::MAX {
    ///     if i.is_ascii_alphanumeric() || i == '-' || i == '_' {
    ///         assert!(Alphabet::from_char(i).is_some());
    ///     } else {
    ///         assert!(Alphabet::from_char(i).is_none());
    ///     }
    /// }
    /// ```
    #[expect(
        clippy::as_conversions,
        clippy::cast_possible_truncation,
        reason = "comments justify correctness"
    )]
    #[inline]
    #[must_use]
    pub const fn from_char(c: char) -> Option<Self> {
        // `char as u32` is always OK.
        let code_point = c as u32;
        if code_point < 256 {
            // We just verified `code_point` does not exceed `u8::MAX`, so `code_point as u8` is lossless.
            Self::from_ascii(code_point as u8)
        } else {
            None
        }
    }
}
impl Display for Alphabet {
    #[inline]
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        f.write_char(self.to_char())
    }
}
impl From<Alphabet> for u8 {
    #[inline]
    fn from(value: Alphabet) -> Self {
        value.to_u8()
    }
}
impl From<Alphabet> for u16 {
    #[inline]
    fn from(value: Alphabet) -> Self {
        Self::from(value.to_u8())
    }
}
impl From<Alphabet> for u32 {
    #[inline]
    fn from(value: Alphabet) -> Self {
        Self::from(value.to_u8())
    }
}
impl From<Alphabet> for u64 {
    #[inline]
    fn from(value: Alphabet) -> Self {
        Self::from(value.to_u8())
    }
}
impl From<Alphabet> for u128 {
    #[inline]
    fn from(value: Alphabet) -> Self {
        Self::from(value.to_u8())
    }
}
impl From<Alphabet> for char {
    #[inline]
    fn from(value: Alphabet) -> Self {
        value.to_char()
    }
}
/// The maximum value [`encode_len_checked`] will accept before returning `None`.
// This won't `panic` since `usize::MAX` ≢ 1 (mod 4).
pub const MAX_ENCODE_INPUT_LEN: usize = decode_len(usize::MAX).unwrap();
/// Returns the exact number of bytes needed to encode an input of length `input_length`.
///
/// `Some` is returned iff the length needed does not exceed [`usize::MAX`].
///
/// Note since Rust guarantees all memory allocations don't exceed [`isize::MAX`] bytes, then one can
/// instead call [`encode_len`] when the argument passed corresponds to the length of an allocation since
/// `isize::MAX <` [`MAX_ENCODE_INPUT_LEN`].
///
/// # Examples
///
/// ```
/// # use base64url_nopad::MAX_ENCODE_INPUT_LEN;
/// assert!(base64url_nopad::encode_len_checked(usize::MAX).is_none());
/// assert!(base64url_nopad::encode_len_checked(MAX_ENCODE_INPUT_LEN + 1).is_none());
/// assert_eq!(base64url_nopad::encode_len_checked(MAX_ENCODE_INPUT_LEN), Some(usize::MAX));
/// assert_eq!(base64url_nopad::encode_len_checked(3), Some(4));
/// assert_eq!(base64url_nopad::encode_len_checked(2), Some(3));
/// assert_eq!(base64url_nopad::encode_len_checked(1), Some(2));
/// assert_eq!(base64url_nopad::encode_len_checked(0), Some(0));
/// ```
#[expect(
    clippy::arithmetic_side_effects,
    clippy::integer_division,
    clippy::integer_division_remainder_used,
    reason = "proof and comment justifies their correctness"
)]
#[inline]
#[must_use]
pub const fn encode_len_checked(input_length: usize) -> Option<usize> {
    // 256^n is the number of distinct values of the input. Let the base64 encoding in a URL safe
    // way without padding of the input be O. There are 64 possible values each byte in O can be; thus we must find
    // the minimum nonnegative integer m such that:
    // 64^m = (2^6)^m = 2^(6m) >= 256^n = (2^8)^n = 2^(8n)
    // <==>
    // lg(2^(6m)) = 6m >= lg(2^(8n)) = 8n   lg is defined on all positive reals which 2^(6m) and 2^(8n) are
    // <==>
    // m >= 8n/6 = 4n/3
    // Clearly that corresponds to m = ⌈4n/3⌉.
    // We claim ⌈4n/3⌉ = 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉.
    // Proof:
    // There are three partitions for n:
    // (1) 3i = n ≡ 0 (mod 3) for some integer i
    //   <==>
    //   ⌈4n/3⌉ = ⌈4(3i)/3⌉ = ⌈4i⌉ = 4i = 4⌊i⌋ = 4⌊3i/3⌋ = 4⌊n/3⌋ + 0 = 4⌊n/3⌋ + ⌈4(0)/3⌉ = 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉
    // (2) 3i + 1 = n ≡ 1 (mod 3) for some integer i
    //   <==>
    //   ⌈4n/3⌉ = ⌈4(3i + 1)/3⌉ = ⌈4i + 4/3⌉ = 4i + ⌈4/3⌉ = 4i + 2 = 4⌊i + 1/3⌋ + ⌈4(1)/3⌉
    //                                                             = 4⌊(3i + 1)/3⌋ + ⌈4((3i + 1) mod 3)/3⌉
    //                                                             = 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉
    // (3) 3i + 2 = n ≡ 2 (mod 3) for some integer i
    //   <==>
    //   ⌈4n/3⌉ = ⌈4(3i + 2)/3⌉ = ⌈4i + 8/3⌉ = 4i + ⌈8/3⌉ = 4i + 3 = 4⌊i + 2/3⌋ + ⌈4(2)/3⌉
    //                                                             = 4⌊(3i + 2)/3⌋ + ⌈4((3i + 2) mod 3)/3⌉
    //                                                             = 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉
    // QED
    // Proof of no overflow:
    // `MAX_ENCODE_INPUT_LEN` = decode_len(usize::MAX).unwrap(); thus all values less than or equal to
    // `MAX_ENCODE_INPUT_LEN` won't overflow ignoring intermediate calcuations since ⌈4n/3⌉ is a
    // monotonically increasing function.
    // QED
    // Naively implementing ⌈4n/3⌉ as (4 * n).div_ceil(3) can cause overflow due to `4 * n`; thus
    // we implement the equivalent equation 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉ instead:
    // `(4 * (n / 3)) + (4 * (n % 3)).div_ceil(3)` since none of the intermediate calculations suffer
    // from overflow.
    if input_length <= MAX_ENCODE_INPUT_LEN {
        // (n / 3) << 2 <= m <= usize::MAX; thus the left operand of + is fine.
        // n % 3 <= 2
        // <==>
        // 4(n % 3) <= 8 < usize::MAX; thus (n % 3) << 2 is fine.
        // <==>
        // ⌈4(n % 3)/3⌉ <= 4(n % 3), so the right operand of + is fine.
        // The sum is fine since
        // m = ⌈4n/3⌉ = 4⌊n/3⌋ + ⌈4(n mod 3)/3⌉ = ((n / 3) << 2) + ((n % 3) << 2).div_ceil(3), and m <= usize::MAX.
        Some(((input_length / 3) << 2) + ((input_length % 3) << 2).div_ceil(3))
    } else {
        cold_path();
        None
    }
}
/// Same as [`encode_len_checked`] except a `panic` occurs instead of `None` being returned.
///
/// One should prefer this function over `encode_len_checked` when passing the length of a memory allocation
/// since such a length is guaranteed to succeed.
///
/// # Panics
///
/// `panic`s iff [`encode_len_checked`] returns `None`.
///
/// # Examples
///
/// ```
/// # use base64url_nopad::MAX_ENCODE_INPUT_LEN;
/// // Uncommenting below will cause a `panic`.
/// // base64url_nopad::encode_len(usize::MAX - 4);
/// // Uncommenting below will cause a `panic`.
/// // base64url_nopad::encode_len(MAX_ENCODE_INPUT_LEN + 1);
/// assert_eq!(base64url_nopad::encode_len(MAX_ENCODE_INPUT_LEN), usize::MAX);
/// assert!(base64url_nopad::encode_len(isize::MAX as usize) > isize::MAX as usize);
/// assert_eq!(base64url_nopad::encode_len(3), 4);
/// assert_eq!(base64url_nopad::encode_len(2), 3);
/// assert_eq!(base64url_nopad::encode_len(1), 2);
/// assert_eq!(base64url_nopad::encode_len(0), 0);
/// ```
#[expect(clippy::unwrap_used, reason = "comment justifies correctness")]
#[inline]
#[must_use]
pub const fn encode_len(input_length: usize) -> usize {
    // A precondition for calling this function is to ensure `encode_len_checked` can't return `None`.
    encode_len_checked(input_length).unwrap()
}
/// `const`-version of `unreachable`.
macro_rules! impossible {
    ( $( $x:literal)? ) => {
        {
            cold_path();
            $(
                panic!($x);
            )?
        }
    };
}
/// Encodes `input` into `output` re-interpreting the encoded subset of `output` as a `str` before returning it.
///
/// `Some` is returned iff `output.len()` is large enough to write the encoded data into.
///
/// Note since Rust guarantees all memory allocations don't exceed [`isize::MAX`] bytes, one can
/// instead call [`encode_buffer`] using a buffer whose length is at least as large as the value returned from
/// [`encode_len`] without fear of a `panic` and the benefit of getting a `str` instead of an `Option`.
///
/// # Examples
///
/// ```
/// assert_eq!(
///     base64url_nopad::encode_buffer_checked([0; 0].as_slice(), [0; 0].as_mut_slice()).as_deref(), Some("")
/// );
/// assert_eq!(
///     base64url_nopad::encode_buffer_checked([0; 1].as_slice(), [0; 2].as_mut_slice()).as_deref(), Some("AA")
/// );
/// // A larger output buffer than necessary is OK.
/// assert_eq!(
///     base64url_nopad::encode_buffer_checked([1; 1].as_slice(), [0; 128].as_mut_slice()).as_deref(), Some("AQ")
/// );
/// assert_eq!(
///     base64url_nopad::encode_buffer_checked(
///         [0xc9; 14].as_slice(),
///         [0; base64url_nopad::encode_len(14)].as_mut_slice()
///     ).as_deref(),
///     Some("ycnJycnJycnJycnJyck")
/// );
/// assert!(base64url_nopad::encode_buffer_checked([0; 1].as_slice(), [0; 1].as_mut_slice()).is_none());
/// ```
#[expect(unsafe_code, reason = "comments justify correctness")]
#[expect(
    clippy::missing_asserts_for_indexing,
    reason = "trust the compiler to already optimize since we match on the length"
)]
#[expect(
    clippy::arithmetic_side_effects,
    clippy::as_conversions,
    clippy::indexing_slicing,
    reason = "comments justify correctness"
)]
#[inline]
pub const fn encode_buffer_checked<'a>(input: &[u8], output: &'a mut [u8]) -> Option<&'a mut str> {
    // This won't `panic` since Rust guarantees that all memory allocations won't exceed `isize::MAX`.
    let final_len = encode_len(input.len());
    if output.len() >= final_len {
        let (mut chunks, rem) = input.as_chunks::<3>();
        let (mut fst, mut snd, mut third);
        let mut output_idx = 0;
        // There is a _substantial_ boost in performance if we chunk encode.
        while let [first, ref rest @ ..] = *chunks {
            (fst, snd, third) = (first[0], first[1], first[2]);
            // We trim the last two bits and interpret `fst` as a 6-bit integer.
            // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
            // `ASCII.len() == 64 > fst >> 2`, so indexing won't `panic`.
            output[output_idx] = ASCII[(fst >> 2) as usize];
            // The two bits we trimmed are the first two bits of the next 6-bit integer.
            output_idx += 1;
            // We trim the last four bits and interpret `snd` as a 6-bit integer.
            // The first two bits are the trailing 2 bits from the previous value.
            // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
            // `ASCII.len() == 64 > ((fst & 3) << 4) | (snd >> 4)`, so indexing won't `panic`.
            output[output_idx] = ASCII[(((fst & 3) << 4) | (snd >> 4)) as usize];
            output_idx += 1;
            // We trim the last six bits and interpret `third` as a 6-bit integer.
            // The first four bits are the trailing 4 bits from the previous value.
            // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
            // `ASCII.len() == 64 > ((snd & 15) << 2) | (third >> 6)`, so indexing won't `panic`.
            output[output_idx] = ASCII[(((snd & 15) << 2) | (third >> 6)) as usize];
            // Every third `u8` corresponds to a fourth base64url `u8`.
            output_idx += 1;
            // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
            // `ASCII.len() == 64 > (third & 63)`, so indexing won't `panic`.
            output[output_idx] = ASCII[(third & 63) as usize];
            output_idx += 1;
            chunks = rest;
        }
        match rem.len() {
            0 => {}
            1 => {
                // `rem.len() == 1`, so indexing won't `panic`.
                fst = rem[0];
                // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
                // `ASCII.len() == 64 > fst >> 2`, so indexing won't `panic`.
                output[output_idx] = ASCII[(fst >> 2) as usize];
                // `ASCII.len() == 64 > (fst & 3) << 4`, so indexing won't `panic`.
                output[output_idx + 1] = ASCII[((fst & 3) << 4) as usize];
            }
            2 => {
                // `rem.len() == 2`, so indexing won't `panic`.
                (fst, snd) = (rem[0], rem[1]);
                // `input.len()` is not a multiple of 3; thus we have to append a final `u8` containing the
                // last bits.
                // `u8 as usize` is always OK; and we want this to be `const` so `usize::from` won't work.
                // `ASCII.len() == 64 > fst >> 2`, so indexing won't `panic`.
                output[output_idx] = ASCII[(fst >> 2) as usize];
                // `ASCII.len() == 64 > ((fst & 3) << 4) | (snd >> 4)`, so indexing won't `panic`.
                output[output_idx + 1] = ASCII[(((fst & 3) << 4) | (snd >> 4)) as usize];
                // `ASCII.len() == 64 > (snd & 15) << 2`, so indexing won't `panic`.
                output[output_idx + 2] = ASCII[((snd & 15) << 2) as usize];
            }
            _ => impossible!("there is a bug in core::slice::as_chunks"),
        }
        // SAFETY:
        // We verified `output.len() >= final_len`.
        let val = unsafe { output.split_at_mut_unchecked(final_len) }.0;
        // SAFETY:
        // `val` has the exact length needed to encode `input`, and all of the `u8`s in it
        // are from `Alphabet::to_ascii` which is a subset of UTF-8; thus this is safe.
        // Note the above is vacuously true when `val` is empty.
        Some(unsafe { str::from_utf8_unchecked_mut(val) })
    } else {
        cold_path();
        None
    }
}
/// Same as [`encode_buffer_checked`] except a `panic` occurs instead of `None` being returned.
///
/// # Panics
///
/// `panic`s iff [`encode_buffer_checked`] returns `None` (i.e., the length of the output buffer is too small).
///
/// # Examples
///
/// ```
/// assert_eq!(
///     base64url_nopad::encode_buffer([0; 0].as_slice(), [0; 0].as_mut_slice()),
///     ""
/// );
/// assert_eq!(
///     base64url_nopad::encode_buffer([0; 1].as_slice(), [0; 2].as_mut_slice()),
///     "AA"
/// );
/// // A larger output buffer than necessary is OK.
/// assert_eq!(
///     base64url_nopad::encode_buffer([255; 1].as_slice(), [0; 256].as_mut_slice()),
///     "_w"
/// );
/// assert_eq!(
///     base64url_nopad::encode_buffer(
///         [0xc9; 14].as_slice(),
///         [0; base64url_nopad::encode_len(14)].as_mut_slice()
///     ),
///     "ycnJycnJycnJycnJyck"
/// );
/// // The below will `panic` when uncommented since the supplied output buffer is too small.
/// // _ = base64url_nopad::encode_buffer([0; 1].as_slice(), [0; 1].as_mut_slice());
/// ```
#[expect(clippy::unwrap_used, reason = "comment justifies correctness")]
#[inline]
pub const fn encode_buffer<'a>(input: &[u8], output: &'a mut [u8]) -> &'a mut str {
    // A precondition for calling this function is to ensure `encode_buffer_checked` can't return `None`.
    encode_buffer_checked(input, output).unwrap()
}
/// Similar to [`encode_buffer`] except a `String` is returned instead using its buffer to write to.
///
/// # Errors
///
/// Errors iff an error occurs from allocating the capacity needed to contain the encoded data.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::collections::TryReserveError;
/// assert_eq!(
///     base64url_nopad::try_encode([0; 0].as_slice())?,
///     ""
/// );
/// assert_eq!(
///     base64url_nopad::try_encode([0; 1].as_slice())?,
///     "AA"
/// );
/// assert_eq!(
///     base64url_nopad::try_encode([128, 40, 3].as_slice())?,
///     "gCgD"
/// );
/// assert_eq!(
///     base64url_nopad::try_encode([0x7b; 22].as_slice())?,
///     "e3t7e3t7e3t7e3t7e3t7e3t7e3t7ew"
/// );
/// # Ok::<_, TryReserveError>(())
/// ```
#[cfg(feature = "alloc")]
#[expect(unsafe_code, reason = "comment justifies correctness")]
#[inline]
pub fn try_encode(input: &[u8]) -> Result<String, TryReserveError> {
    let mut output = Vec::new();
    // `encode_len` won't `panic` since Rust guarantees `input.len()` will not return a value greater
    // than `isize::MAX`.
    let len = encode_len(input.len());
    output.try_reserve_exact(len).map(|()| {
        output.resize(len, 0);
        _ = encode_buffer(input, output.as_mut_slice());
        // SAFETY:
        // `output` has the exact length needed to encode `input`, and all of the `u8`s in it
        // are from `Alphabet` which is a subset of UTF-8; thus this is safe.
        // Note the above is vacuously true when `output` is empty.
        unsafe { String::from_utf8_unchecked(output) }
    })
}
/// Same as [`try_encode`] except a `panic` occurs on allocation failure.
///
/// # Panics
///
/// `panic`s iff [`try_encode`] errors.
///
/// # Examples
///
/// ```
/// assert_eq!(
///     base64url_nopad::encode([0; 0].as_slice()),
///     ""
/// );
/// assert_eq!(
///     base64url_nopad::encode([0; 1].as_slice()),
///     "AA"
/// );
/// assert_eq!(
///     base64url_nopad::encode([128, 40, 3].as_slice()),
///     "gCgD"
/// );
/// assert_eq!(
///     base64url_nopad::encode([0x7b; 22].as_slice()),
///     "e3t7e3t7e3t7e3t7e3t7e3t7e3t7ew"
/// );
/// ```
#[cfg(feature = "alloc")]
#[expect(
    clippy::unwrap_used,
    reason = "purpose of function is to panic on allocation failure"
)]
#[inline]
#[must_use]
pub fn encode(input: &[u8]) -> String {
    try_encode(input).unwrap()
}
/// Writes the base64url encoding of `input` using `writer`.
///
/// Internally a buffer of at most 1024 bytes is used to write the encoded data.
///
/// # Errors
///
/// Errors iff [`Write::write_str`] does.
///
/// # Panics
///
/// `panic`s iff [`Write::write_str`] does.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::string::String;
/// # use core::fmt::Error;
/// let mut buffer = String::new();
/// base64url_nopad::encode_write([0; 0].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "");
/// buffer.clear();
/// base64url_nopad::encode_write([0; 1].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "AA");
/// buffer.clear();
/// base64url_nopad::encode_write(
///     [0xc9; 14].as_slice(),
///     &mut buffer,
/// )?;
/// assert_eq!(buffer, "ycnJycnJycnJycnJyck");
/// # Ok::<_, Error>(())
/// ```
#[expect(unsafe_code, reason = "comment justifies correctness")]
#[expect(
    clippy::arithmetic_side_effects,
    clippy::as_conversions,
    clippy::indexing_slicing,
    reason = "comments justify correctness"
)]
#[inline]
pub fn encode_write<W: Write>(mut input: &[u8], mut writer: W) -> fmt::Result {
    /// The max buffer size.
    ///
    /// This must be at least 4, no more than `i16::MAX`, and must be a power of 2.
    const MAX_BUFFER_LEN: usize = 1024;
    /// Want to ensure at compilation time that `MAX_BUFFER_LEN` upholds its invariants. Namely
    /// that it's at least as large as 4, doesn't exceed [`i16::MAX`], and is always a power of 2.
    const _: () = {
        // `i16::MAX <= usize::MAX`, so this is fine.
        /// `i16::MAX`.
        const MAX_LEN: usize = i16::MAX as usize;
        assert!(
            4 <= MAX_BUFFER_LEN && MAX_BUFFER_LEN < MAX_LEN && MAX_BUFFER_LEN.is_power_of_two(),
            "encode_write::MAX_BUFFER_LEN must be a power of two less than i16::MAX but at least as large as 4"
        );
    };
    /// The input size that corresponds to an encoded value of length `MAX_BUFFER_LEN`.
    // This will never `panic` since `MAX_BUFFER_LEN` is a power of two at least as large as 4
    // (i.e., `MAX_BUFFER_LEN` ≢ 1 (mod 4)).
    const INPUT_LEN: usize = decode_len(MAX_BUFFER_LEN).unwrap();
    let mut buffer = [0; MAX_BUFFER_LEN];
    // This won't `panic` since `input.len()` is guaranteed to be no more than `isize::MAX`.
    let len = encode_len(input.len());
    if len <= MAX_BUFFER_LEN {
        // `buffer.len() == MAX_BUFFER_LEN >= len`, so indexing is fine.
        // `encode_buffer` won't `panic` since `len` is the exact number of bytes needed to encode
        // the data.
        writer.write_str(encode_buffer(input, &mut buffer[..len]))
    } else {
        let mut counter = 0;
        // `len / MAX_BUFFER_LEN` is equal to ⌊len / MAX_BUFFER_LEN⌋ since `MAX_BUFFER_LEN` is a power of two.
        // We can safely encode `term` chunks of `INPUT_LEN` length into `buffer`.
        let term = len >> MAX_BUFFER_LEN.trailing_zeros();
        let mut input_buffer;
        while counter < term {
            // SAFETY:
            // `input.len() >= INPUT_LEN`.
            input_buffer = unsafe { input.split_at_unchecked(INPUT_LEN) };
            // `encode_buffer` won't `panic` since `buffer` has length `MAX_BUFFER_LEN` which
            // is the exact length needed for `INPUT_LEN` length inputs which `input_buffer.0` is.
            writer.write_str(encode_buffer(input_buffer.0, buffer.as_mut_slice()))?;
            input = input_buffer.1;
            // `counter < term`, so overflow cannot happen.
            counter += 1;
        }
        // `encode_len` won't `panic` since `input.len() < MAX_ENCODE_INPUT_LEN`.
        // `input.len() < INPUT_LEN`; thus `encode_len(input.len()) < MAX_BUFFER_LEN = buffer.len()` so
        // indexing is fine.
        // `encode_buffer` won't `panic` since the buffer is the exact length needed to encode `input`.
        writer.write_str(encode_buffer(input, &mut buffer[..encode_len(input.len())]))
    }
}
/// Appends the base64url encoding of `input` to `s` returning the `str` that was appended.
///
/// # Errors
///
/// Errors iff an error occurs from allocating the capacity needed to append the encoded data.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::{collections::TryReserveError, string::String};
/// let mut buffer = String::new();
/// assert_eq!(
///     base64url_nopad::try_encode_append([0; 0].as_slice(), &mut buffer)?,
///     ""
/// );
/// assert_eq!(
///     base64url_nopad::try_encode_append([0; 1].as_slice(), &mut buffer)?,
///     "AA"
/// );
/// assert_eq!(
///     base64url_nopad::try_encode_append([128, 40, 3].as_slice(), &mut buffer)?,
///     "gCgD"
/// );
/// assert_eq!(buffer, "AAgCgD");
/// assert_eq!(
///     base64url_nopad::try_encode_append([0x7b; 22].as_slice(), &mut buffer)?,
///     "e3t7e3t7e3t7e3t7e3t7e3t7e3t7ew"
/// );
/// assert_eq!(buffer, "AAgCgDe3t7e3t7e3t7e3t7e3t7e3t7e3t7ew");
/// # Ok::<_, TryReserveError>(())
/// ```
#[cfg(feature = "alloc")]
#[expect(unsafe_code, reason = "comment justifies correctness")]
#[expect(
    clippy::arithmetic_side_effects,
    clippy::indexing_slicing,
    reason = "comments justify correctness"
)]
#[inline]
pub fn try_encode_append<'a>(
    input: &[u8],
    s: &'a mut String,
) -> Result<&'a mut str, TryReserveError> {
    // `encode_len` won't `panic` since Rust guarantees `input.len()` will return a value no larger
    // than `isize::MAX`.
    let additional_len = encode_len(input.len());
    s.try_reserve_exact(additional_len).map(|()| {
        // SAFETY:
        // We only append base64url ASCII which is a subset of UTF-8, so this will remain valid UTF-8.
        let utf8 = unsafe { s.as_mut_vec() };
        let original_len = utf8.len();
        // Overflow can't happen; otherwise `s.try_reserve_exact` would have erred.
        utf8.resize(original_len + additional_len, 0);
        // `utf8.len() >= original_len`, so indexing is fine.
        // `encode_buffer` won't `panic` since `utf8[original_len..]` has length `additional_len`
        // which is the exact number of bytes needed to encode `input`.
        encode_buffer(input, &mut utf8[original_len..])
    })
}
/// Same as [`try_encode_append`] except the encoded `str` is not returned.
///
/// # Errors
///
/// Errors iff [`try_encode_append`] does.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::{collections::TryReserveError, string::String};
/// let mut buffer = String::new();
/// base64url_nopad::try_encode_append_only([0; 0].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "");
/// base64url_nopad::try_encode_append_only([0; 1].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "AA");
/// base64url_nopad::try_encode_append_only([128, 40, 3].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "AAgCgD");
/// base64url_nopad::try_encode_append_only([0x7b; 22].as_slice(), &mut buffer)?;
/// assert_eq!(buffer, "AAgCgDe3t7e3t7e3t7e3t7e3t7e3t7e3t7ew");
/// # Ok::<_, TryReserveError>(())
/// ```
#[cfg(feature = "alloc")]
#[inline]
pub fn try_encode_append_only(input: &[u8], s: &mut String) -> Result<(), TryReserveError> {
    try_encode_append(input, s).map(|_| ())
}
/// Same as [`try_encode_append`] except a `panic` occurs on allocation failure.
///
/// # Panics
///
/// `panic`s iff [`try_encode_append`] errors.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::{collections::TryReserveError, string::String};
/// let mut buffer = String::new();
/// assert_eq!(
///     base64url_nopad::encode_append([0; 0].as_slice(), &mut buffer),
///     ""
/// );
/// assert_eq!(
///     base64url_nopad::encode_append([0; 1].as_slice(), &mut buffer),
///     "AA"
/// );
/// assert_eq!(
///     base64url_nopad::encode_append([128, 40, 3].as_slice(), &mut buffer),
///     "gCgD"
/// );
/// assert_eq!(buffer, "AAgCgD");
/// assert_eq!(
///     base64url_nopad::encode_append([0x7b; 22].as_slice(), &mut buffer),
///     "e3t7e3t7e3t7e3t7e3t7e3t7e3t7ew"
/// );
/// assert_eq!(buffer, "AAgCgDe3t7e3t7e3t7e3t7e3t7e3t7e3t7ew");
/// ```
#[cfg(feature = "alloc")]
#[expect(
    clippy::unwrap_used,
    reason = "purpose of this function is to panic on allocation failure"
)]
#[inline]
pub fn encode_append<'a>(input: &[u8], s: &'a mut String) -> &'a mut str {
    try_encode_append(input, s).unwrap()
}
/// Same as [`encode_append`] except the encoded `str` is not returned.
///
/// # Panics
///
/// `panic`s iff [`encode_append`] does.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// # use alloc::{collections::TryReserveError, string::String};
/// let mut buffer = String::new();
/// base64url_nopad::encode_append_only([0; 0].as_slice(), &mut buffer);
/// assert_eq!(buffer, "");
/// base64url_nopad::encode_append_only([0; 1].as_slice(), &mut buffer);
/// assert_eq!(buffer, "AA");
/// base64url_nopad::encode_append_only([128, 40, 3].as_slice(), &mut buffer);
/// assert_eq!(buffer, "AAgCgD");
/// base64url_nopad::encode_append_only([0x7b; 22].as_slice(), &mut buffer);
/// assert_eq!(buffer, "AAgCgDe3t7e3t7e3t7e3t7e3t7e3t7e3t7ew");
/// # Ok::<_, TryReserveError>(())
/// ```
#[cfg(feature = "alloc")]
#[inline]
pub fn encode_append_only(input: &[u8], s: &mut String) {
    _ = encode_append(input, s);
}
/// Returns the exact number of bytes needed to decode a base64url without padding input of length `input_length`.
///
/// `Some` is returned iff `input_length` represents a possible length of a base64url without padding input.
///
/// # Examples
///
/// ```
/// # use base64url_nopad::MAX_ENCODE_INPUT_LEN;
/// assert!(base64url_nopad::decode_len(1).is_none());
/// assert_eq!(base64url_nopad::decode_len(usize::MAX), Some(MAX_ENCODE_INPUT_LEN));
/// assert_eq!(base64url_nopad::decode_len(4), Some(3));
/// assert_eq!(base64url_nopad::decode_len(3), Some(2));
/// assert_eq!(base64url_nopad::decode_len(2), Some(1));
/// assert_eq!(base64url_nopad::decode_len(0), Some(0));
/// ```
#[expect(
    clippy::arithmetic_side_effects,
    reason = "proof and comment justifies their correctness"
)]
#[inline]
#[must_use]
pub const fn decode_len(input_length: usize) -> Option<usize> {
    // 64^n is the number of distinct values of the input. Let the decoded output be O.
    // There are 256 possible values each byte in O can be; thus we must find
    // the maximum nonnegative integer m such that:
    // 256^m = (2^8)^m = 2^(8m) <= 64^n = (2^6)^n = 2^(6n)
    // <==>
    // lg(2^(8m)) = 8m <= lg(2^(6n)) = 6n   lg is defined on all positive reals which 2^(8m) and 2^(6n) are
    // <==>
    // m <= 6n/8 = 3n/4
    // Clearly that corresponds to m = ⌊3n/4⌋.
    // From the proof in `encode_len_checked`, we know that n is a valid length
    // iff n ≢ 1 (mod 4).
    // We claim ⌊3n/4⌋ = 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋.
    // Proof:
    // There are three partitions for n:
    // (1) 4i = n ≡ 0 (mod 4) for some integer i
    //   <==>
    //   ⌊3n/4⌋ = ⌊3(4i)/4⌋ = ⌊3i⌋ = 3i = 3⌊i⌋ = 3⌊4i/4⌋ = 3⌊n/4⌋ + 0 = 3⌊n/4⌋ + ⌊3(0)/4⌋ = 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋
    // (2) 4i + 2 = n ≡ 2 (mod 4) for some integer i
    //   <==>
    //   ⌊3n/4⌋ = ⌊3(4i + 2)/4⌋ = ⌊3i + 6/4⌋ = 3i + ⌊6/4⌋ = 3i + 1 = 3⌊i⌋ + ⌊3(2)/4⌋
    //                                                             = 3⌊(4i + 2)/4⌋ + ⌊3((4i + 2) mod 4)/4⌋
    //                                                             = 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋
    // (3) 4i + 3 = n ≡ 3 (mod 4) for some integer i
    //   <==>
    //   ⌊3n/4⌋ = ⌊3(4i + 3)/4⌋ = ⌊3i + 9/4⌋ = 3i + ⌊9/4⌋ = 3i + 2 = 3⌊i⌋ + ⌊3(3)/4⌋
    //                                                             = 3⌊(4i + 3)/4⌋ + ⌊3((4i + 3) mod 4)/4⌋
    //                                                             = 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋
    // QED
    // Naively implementing ⌊3n/4⌋ as (3 * n) / 4 can cause overflow due to `3 * n`; thus
    // we implement the equivalent equation 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋ instead:
    // `(3 * (n / 4)) + ((3 * (n % 4)) / 4)` since none of the intermediate calculations suffer
    // from overflow.
    // `input_length % 4`.
    let rem = input_length & 3;
    if rem == 1 {
        None
    } else {
        // 3 * (n >> 2) <= m < usize::MAX; thus the left operand of + is fine.
        // rem <= 3
        // <==>
        // 3rem <= 9 < usize::MAX; thus 3 * rem is fine.
        // <==>
        // ⌊3rem/4⌋ <= 3rem, so the right operand of + is fine.
        // The sum is fine since
        // m = ⌊3n/4⌋ = 3⌊n/4⌋ + ⌊3(n mod 4)/4⌋ = (3 * (n >> 2)) + ((3 * rem) >> 2), and m < usize::MAX.
        Some((3 * (input_length >> 2)) + ((3 * rem) >> 2))
    }
}
/// Error returned from [`decode_buffer`] and [`decode`].
///
/// Note when [`alloc`](./index.html#alloc) is not enabled, [`Copy`] is also implemented.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum DecodeErr {
    /// The encoded input had an invalid length.
    EncodedLen,
    /// The buffer supplied had a length that was too small to contain the decoded data.
    BufferLen,
    /// The encoded data contained trailing bits that were not zero.
    TrailingBits,
    /// The encoded data contained an invalid `u8`.
    InvalidByte,
    /// [`decode`] could not allocate enough memory to contain the decoded data.
    #[cfg(feature = "alloc")]
    TryReserve(TryReserveError),
}
#[cfg(not(feature = "alloc"))]
impl Copy for DecodeErr {}
impl Display for DecodeErr {
    #[inline]
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        match *self {
            Self::EncodedLen => f.write_str("length of encoded data was invalid"),
            Self::BufferLen => {
                f.write_str("length of the output buffer is too small to contain the decoded data")
            }
            Self::TrailingBits => {
                f.write_str("encoded data contained trailing bits that were not zero")
            }
            Self::InvalidByte => f.write_str("encoded data contained an invalid byte"),
            #[cfg(feature = "alloc")]
            Self::TryReserve(ref err) => err.fmt(f),
        }
    }
}
impl Error for DecodeErr {}
/// Decodes `input` into `output` returning the subset of `output` containing the decoded data.
///
/// # Errors
///
/// Errors iff [`decode_len`] of `input.len()` does not return `Some` containing a
/// `usize` that does not exceed `ouput.len()` or `input` is an invalid base64url-encoded value without padding.
/// Note [`DecodeErr::TryReserve`] will never be returned.
///
/// # Examples
///
/// ```
/// # use base64url_nopad::DecodeErr;
/// assert_eq!(base64url_nopad::decode_buffer(b"", [0; 0].as_mut_slice())?, b"");
/// assert_eq!(
///     base64url_nopad::decode_buffer(b"A", [0; 0].as_mut_slice()).unwrap_err(),
///     DecodeErr::EncodedLen
/// );
/// assert_eq!(
///     base64url_nopad::decode_buffer(b"A+".as_slice(), [0; 3].as_mut_slice()).unwrap_err(),
///     DecodeErr::InvalidByte
/// );
/// assert_eq!(
///     base64url_nopad::decode_buffer(b"AA".as_slice(), [0; 0].as_mut_slice()).unwrap_err(),
///     DecodeErr::BufferLen
/// );
/// assert_eq!(
///     base64url_nopad::decode_buffer(b"-8", [0; 3].as_mut_slice()).unwrap_err(),
///     DecodeErr::TrailingBits
/// );
/// // A larger output buffer than necessary is OK.
/// assert_eq!(base64url_nopad::decode_buffer(b"C8Aa_A--91VZbx0", &mut [0; 128])?, [0x0b, 0xc0, 0x1a, 0xfc, 0x0f, 0xbe, 0xf7, b'U', b'Y', b'o', 0x1d]);
/// # Ok::<_, DecodeErr>(())
/// ```
#[expect(unsafe_code, reason = "comment justifies correctness")]
#[expect(
    clippy::missing_asserts_for_indexing,
    reason = "trust the compiler to already optimize since we match on the length"
)]
#[expect(
    clippy::arithmetic_side_effects,
    clippy::indexing_slicing,
    reason = "comments justify correctness"
)]
#[expect(clippy::redundant_else, reason = "prefer the elses")]
#[inline]
pub const fn decode_buffer<'a>(
    input: &[u8],
    output: &'a mut [u8],
) -> Result<&'a mut [u8], DecodeErr> {
    let len = input.len();
    if let Some(output_len) = decode_len(len) {
        if output.len() >= output_len {
            let mut output_idx = 0;
            let (mut chunks, rem) = input.as_chunks::<4>();
            let (mut snd, mut third);
            // There is a _substantial_ boost in performance if we chunk decode.
            while let [first, ref rest @ ..] = *chunks {
                if let Some(base64_fst) = Alphabet::from_ascii(first[0])
                    && let Some(base64_snd) = Alphabet::from_ascii(first[1])
                    && let Some(base64_third) = Alphabet::from_ascii(first[2])
                    && let Some(base64_fourth) = Alphabet::from_ascii(first[3])
                {
                    (snd, third) = (base64_snd.to_u8(), base64_third.to_u8());
                    output[output_idx] = (base64_fst.to_u8() << 2) | (snd >> 4);
                    output_idx += 1;
                    output[output_idx] = (snd << 4) | (third >> 2);
                    output_idx += 1;
                    output[output_idx] = (third << 6) | base64_fourth.to_u8();
                    output_idx += 1;
                    chunks = rest;
                } else {
                    return Err(DecodeErr::InvalidByte);
                }
            }
            match rem.len() {
                0 => {}
                1 => impossible!("there is a bug in base64url_nopad::decode_len"),
                2 => {
                    if let Some(base64_fst) = Alphabet::from_ascii(rem[0])
                        && let Some(base64_snd) = Alphabet::from_ascii(rem[1])
                    {
                        snd = base64_snd.to_u8();
                        if snd.trailing_zeros() < 4 {
                            cold_path();
                            return Err(DecodeErr::TrailingBits);
                        } else {
                            output[output_idx] = (base64_fst.to_u8() << 2) | (snd >> 4);
                        }
                    } else {
                        cold_path();
                        return Err(DecodeErr::InvalidByte);
                    }
                }
                3 => {
                    if let Some(base64_fst) = Alphabet::from_ascii(rem[0])
                        && let Some(base64_snd) = Alphabet::from_ascii(rem[1])
                        && let Some(base64_third) = Alphabet::from_ascii(rem[2])
                    {
                        (snd, third) = (base64_snd.to_u8(), base64_third.to_u8());
                        if third.trailing_zeros() < 2 {
                            cold_path();
                            return Err(DecodeErr::TrailingBits);
                        } else {
                            output[output_idx] = (base64_fst.to_u8() << 2) | (snd >> 4);
                            output[output_idx + 1] = (snd << 4) | (third >> 2);
                        }
                    } else {
                        cold_path();
                        return Err(DecodeErr::InvalidByte);
                    }
                }
                _ => impossible!("there is a bug in core::slice::as_chunks"),
            }
            // SAFETY:
            // `output.len() >= output_len`.
            Ok(unsafe { output.split_at_mut_unchecked(output_len) }.0)
        } else {
            cold_path();
            Err(DecodeErr::BufferLen)
        }
    } else {
        Err(DecodeErr::EncodedLen)
    }
}
/// Similar to [`decode_buffer`] except a `Vec` is returned instead using its buffer to write to.
///
/// # Errors
///
/// Errors iff [`decode_buffer`] errors or an error occurs from allocating the capacity needed to contain
/// the decoded data. Note [`DecodeErr::BufferLen`] is not possible to be returned.
///
/// # Examples
///
/// ```
/// # use base64url_nopad::DecodeErr;
/// assert_eq!(base64url_nopad::decode([0; 0].as_slice())?, b"");
/// assert_eq!(
///     base64url_nopad::decode(b"A").unwrap_err(),
///     DecodeErr::EncodedLen
/// );
/// assert_eq!(
///     base64url_nopad::decode(b"AA==").unwrap_err(),
///     DecodeErr::InvalidByte
/// );
/// assert_eq!(
///     base64url_nopad::decode(b"-8").unwrap_err(),
///     DecodeErr::TrailingBits
/// );
/// assert_eq!(base64url_nopad::decode(b"C8Aa_A--91VZbx0")?, [0x0b, 0xc0, 0x1a, 0xfc, 0x0f, 0xbe, 0xf7, b'U', b'Y', b'o', 0x1d]);
/// # Ok::<_, DecodeErr>(())
/// ```
#[cfg(feature = "alloc")]
#[inline]
pub fn decode(input: &[u8]) -> Result<Vec<u8>, DecodeErr> {
    decode_len(input.len())
        .ok_or(DecodeErr::EncodedLen)
        .and_then(|capacity| {
            let mut buffer = Vec::new();
            buffer
                .try_reserve_exact(capacity)
                .map_err(DecodeErr::TryReserve)
                .and_then(|()| {
                    buffer.resize(capacity, 0);
                    if let Err(e) = decode_buffer(input, buffer.as_mut_slice()) {
                        Err(e)
                    } else {
                        Ok(buffer)
                    }
                })
        })
}
/// Similar to [`decode_buffer`] except the data is not decoded.
///
/// In some situations, one does not want to actually decode data but merely validate that the encoded data
/// is valid base64url without padding. Since data is not actually decoded, one avoids the need to allocate
/// a large-enough buffer first.
///
/// # Errors
///
/// Errors iff `input` is an invalid base64url without padding.
///
/// Note since no buffer is used to decode the data into, neither [`DecodeErr::BufferLen`] nor
/// [`DecodeErr::TryReserve`] will ever be returned.
///
/// # Examples
///
/// ```
/// # use base64url_nopad::DecodeErr;
/// base64url_nopad::validate_encoded_data(b"")?;
/// assert_eq!(
///     base64url_nopad::validate_encoded_data(b"A").unwrap_err(),
///     DecodeErr::EncodedLen
/// );
/// assert_eq!(
///     base64url_nopad::validate_encoded_data(b"A/").unwrap_err(),
///     DecodeErr::InvalidByte
/// );
/// assert_eq!(
///     base64url_nopad::validate_encoded_data(b"-8").unwrap_err(),
///     DecodeErr::TrailingBits
/// );
/// base64url_nopad::validate_encoded_data(b"C8Aa_A--91VZbx0")?;
/// # Ok::<_, DecodeErr>(())
/// ```
#[expect(
    clippy::missing_asserts_for_indexing,
    reason = "trust the compiler to already optimize since we match on the length"
)]
#[expect(clippy::indexing_slicing, reason = "comments justify correctness")]
#[inline]
pub const fn validate_encoded_data(input: &[u8]) -> Result<(), DecodeErr> {
    let (mut chunks, rem) = input.as_chunks::<4>();
    // There is a _substantial_ boost in performance if we chunk decode.
    while let [first, ref rest @ ..] = *chunks {
        if Alphabet::from_ascii(first[0]).is_some()
            && Alphabet::from_ascii(first[1]).is_some()
            && Alphabet::from_ascii(first[2]).is_some()
            && Alphabet::from_ascii(first[3]).is_some()
        {
            chunks = rest;
        } else {
            return Err(DecodeErr::InvalidByte);
        }
    }
    match rem.len() {
        0 => Ok(()),
        1 => {
            cold_path();
            Err(DecodeErr::EncodedLen)
        }
        2 => {
            if Alphabet::from_ascii(rem[0]).is_some()
                && let Some(base64_snd) = Alphabet::from_ascii(rem[1])
            {
                if base64_snd.to_u8().trailing_zeros() < 4 {
                    cold_path();
                    Err(DecodeErr::TrailingBits)
                } else {
                    Ok(())
                }
            } else {
                cold_path();
                Err(DecodeErr::InvalidByte)
            }
        }
        3 => {
            if Alphabet::from_ascii(rem[0]).is_some()
                && Alphabet::from_ascii(rem[1]).is_some()
                && let Some(base64_third) = Alphabet::from_ascii(rem[2])
            {
                if base64_third.to_u8().trailing_zeros() < 2 {
                    cold_path();
                    Err(DecodeErr::TrailingBits)
                } else {
                    Ok(())
                }
            } else {
                cold_path();
                Err(DecodeErr::InvalidByte)
            }
        }
        _ => impossible!("there is a bug in core::slice::as_chunks"),
    }
}
/// Same as [`encode_buffer`] except `output` must have the _exact_ length needed to encode `input`, and the
/// encoded `str` is not returned.
///
/// # Panics
///
/// `panic`s iff `output` does not have the _exact_ length needed to encode `input`.
///
/// # Examples
///
/// ```
/// let mut buffer = [0; 256];
/// base64url_nopad::encode_buffer_exact([0; 0].as_slice(), &mut buffer[..0]);
/// base64url_nopad::encode_buffer_exact([0; 1].as_slice(), &mut buffer[..2]);
/// assert_eq!(*b"AA", buffer[..2]);
/// // Uncommenting below will cause a `panic` since the output buffer must be exact.
/// // base64url_nopad::encode_buffer_exact([255; 1].as_slice(), &mut buffer);
/// ```
#[inline]
pub const fn encode_buffer_exact(input: &[u8], output: &mut [u8]) {
    assert!(
        // `encode_len` won't `panic` since Rust guarantees `input.len()` is at most `isize::MAX`.
        output.len() == encode_len(input.len()),
        "encode_buffer_exact must be passed an output buffer whose length is exactly the length needed to encode the data"
    );
    _ = encode_buffer(input, output);
}
/// Same as [`decode_buffer`] except `output` must have the _exact_ length needed, and the decoded `slice`
/// is not returned.
///
/// # Errors
///
/// Errors iff [`decode_buffer`] errors. Note that since a `panic` occurs when `output.len()` is not the
/// exact length needed, [`DecodeErr::BufferLen`] is not possible in addition to [`DecodeErr::TryReserve`].
///
/// # Panics
///
/// `panic`s iff `output` does not have the _exact_ length needed to contain the decoded data and `input`
/// has a valid length (i.e., [`DecodeErr::EncodedLen`] is returned _not_ a `panic` when `input` has invalid
/// length).
///
/// # Examples
///
/// ```
/// # use base64url_nopad::DecodeErr;
/// assert_eq!(
///     base64url_nopad::decode_buffer_exact(b"A", [0; 0].as_mut_slice()).unwrap_err(),
///     DecodeErr::EncodedLen
/// );
/// assert_eq!(
///     base64url_nopad::decode_buffer_exact(b"+A", [0; 1].as_mut_slice()).unwrap_err(),
///     DecodeErr::InvalidByte
/// );
/// assert_eq!(
///     base64url_nopad::decode_buffer_exact(b"-8", [0; 1].as_mut_slice()).unwrap_err(),
///     DecodeErr::TrailingBits
/// );
/// let mut buffer = [0; base64url_nopad::decode_len(b"C8Aa_A--91VZbx0".len()).unwrap()];
/// base64url_nopad::decode_buffer_exact(b"C8Aa_A--91VZbx0", &mut buffer)?;
/// assert_eq!(buffer, [0x0b, 0xc0, 0x1a, 0xfc, 0x0f, 0xbe, 0xf7, b'U', b'Y', b'o', 0x1d]);
/// // Uncommenting below will cause a `panic` since a larger output buffer than necessary is _not_ OK.
/// // base64url_nopad::decode_buffer_exact(b"C8Aa_A--91VZbx0", &mut [0; 128])?;
/// # Ok::<_, DecodeErr>(())
/// ```
#[expect(
    clippy::panic,
    clippy::panic_in_result_fn,
    reason = "purpose of this function is to panic when output does not have the exact length needed"
)]
#[inline]
pub const fn decode_buffer_exact(input: &[u8], output: &mut [u8]) -> Result<(), DecodeErr> {
    let output_len = output.len();
    match decode_buffer(input, output) {
        Ok(v) => {
            assert!(
                v.len() == output_len,
                "decode_buffer_exact must be passed an output buffer whose length is exactly the length needed to decode the data"
            );
            Ok(())
        }
        Err(e) => {
            if matches!(e, DecodeErr::BufferLen) {
                cold_path();
                panic!(
                    "decode_buffer_exact must be passed an output buffer whose length is exactly the length needed to decode the data"
                );
            } else {
                Err(e)
            }
        }
    }
}