from2to 0.2.0

Fast conversion at the terminal: hex2bin, dec2char, hex2b64, and friends
Documentation
//! The set of things we can convert between.
//!
//! A `Format` is either a real positional number base (2..=36) or one of the
//! "pseudo-bases" that are really byte encodings. Treating them uniformly is
//! what lets `hex2b64` and `hex2bin` be the same code path.

use std::fmt;

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Format {
    /// A positional base, 2..=36.
    Positional(u32),
    /// Text: Unicode scalars, or raw bytes.
    Char,
    /// Standard base64 (RFC 4648, padded).
    B64,
    /// URL-safe base64.
    B64Url,
    /// Standard base32.
    B32,
    /// base32hex (extended hex alphabet).
    B32Hex,
}

impl Format {
    pub const BIN: Format = Format::Positional(2);
    pub const OCT: Format = Format::Positional(8);
    pub const DEC: Format = Format::Positional(10);
    pub const HEX: Format = Format::Positional(16);

    /// The radix, if this is a real positional base.
    pub fn radix(self) -> Option<u32> {
        match self {
            Format::Positional(r) => Some(r),
            _ => None,
        }
    }

    pub fn is_positional(self) -> bool {
        matches!(self, Format::Positional(_))
    }

    /// Bits per digit, but only for bases that are exact powers of two.
    ///
    /// This is the hinge of the whole design: when both sides answer `Some`,
    /// conversion is pure bit regrouping (no bignum, leading zeros preserved),
    /// and a digit count translates directly into a byte width.
    pub fn bits_per_digit(self) -> Option<u32> {
        let r = self.radix()?;
        if r.is_power_of_two() {
            Some(r.trailing_zeros())
        } else {
            None
        }
    }

    /// True for formats whose natural currency is bytes rather than a number.
    pub fn is_byteish(self) -> bool {
        !self.is_positional()
    }

    /// True for the base64/base32 family (as opposed to `Char`).
    pub fn is_encoding(self) -> bool {
        matches!(
            self,
            Format::B64 | Format::B64Url | Format::B32 | Format::B32Hex
        )
    }

    /// Parse a format name: a word (`hex`), an alias (`ascii`), or a bare
    /// radix (`16`, `36`).
    pub fn parse(s: &str) -> Option<Format> {
        let lower = s.to_ascii_lowercase();
        let f = match lower.as_str() {
            "bin" | "b" | "binary" => Format::BIN,
            "oct" | "o" | "octal" => Format::OCT,
            "dec" | "d" | "decimal" | "int" => Format::DEC,
            "hex" | "h" | "hexadecimal" => Format::HEX,
            "char" | "chr" | "ascii" | "text" | "str" | "raw" | "utf8" => Format::Char,
            "b64" | "base64" => Format::B64,
            "b64url" | "base64url" | "b64u" => Format::B64Url,
            "b32" | "base32" => Format::B32,
            "b32hex" | "base32hex" => Format::B32Hex,
            _ => {
                let r: u32 = lower.parse().ok()?;
                if (2..=36).contains(&r) {
                    Format::Positional(r)
                } else {
                    return None;
                }
            }
        };
        Some(f)
    }

    /// The canonical short name, as used in command names.
    pub fn name(self) -> &'static str {
        match self {
            Format::Positional(2) => "bin",
            Format::Positional(8) => "oct",
            Format::Positional(10) => "dec",
            Format::Positional(16) => "hex",
            Format::Positional(_) => "base",
            Format::Char => "char",
            Format::B64 => "b64",
            Format::B64Url => "b64url",
            Format::B32 => "b32",
            Format::B32Hex => "b32hex",
        }
    }
}

impl fmt::Display for Format {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Format::Positional(r) if self.name() == "base" => write!(f, "base{r}"),
            other => write!(f, "{}", other.name()),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parses_words_aliases_and_radices() {
        assert_eq!(Format::parse("hex"), Some(Format::HEX));
        assert_eq!(Format::parse("HEX"), Some(Format::HEX));
        assert_eq!(Format::parse("16"), Some(Format::HEX));
        assert_eq!(Format::parse("ascii"), Some(Format::Char));
        assert_eq!(Format::parse("base64"), Some(Format::B64));
        assert_eq!(Format::parse("36"), Some(Format::Positional(36)));
    }

    #[test]
    fn rejects_out_of_range_radices() {
        assert_eq!(Format::parse("1"), None);
        assert_eq!(Format::parse("37"), None);
        assert_eq!(Format::parse("0"), None);
        assert_eq!(Format::parse("nonsense"), None);
    }

    #[test]
    fn bits_per_digit_only_for_powers_of_two() {
        assert_eq!(Format::BIN.bits_per_digit(), Some(1));
        assert_eq!(Format::OCT.bits_per_digit(), Some(3));
        assert_eq!(Format::HEX.bits_per_digit(), Some(4));
        assert_eq!(Format::Positional(32).bits_per_digit(), Some(5));
        assert_eq!(Format::DEC.bits_per_digit(), None);
        assert_eq!(Format::Positional(36).bits_per_digit(), None);
        assert_eq!(Format::Char.bits_per_digit(), None);
    }

    #[test]
    fn display_names_arbitrary_bases() {
        assert_eq!(Format::HEX.to_string(), "hex");
        assert_eq!(Format::Positional(36).to_string(), "base36");
    }
}