waddling_errors_hash/

base62.rs

//! Base62 encoding for hash output
//!
//! Converts raw hash bytes to a 5-character alphanumeric string.
//! Base62 uses: 0-9, A-Z, a-z (62 characters total)
//!
//! This provides:
//! - 62^5 = 916,132,832 possible combinations
//! - Compact representation (5 characters)
//! - Safe for all logging systems (alphanumeric only)
//! - URL-safe (no special characters)

#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(feature = "std")]
use std::string::String;

#[cfg(not(feature = "std"))]
use alloc::string::String;

/// Base62 character set: 0-9, A-Z, a-z
const BASE62_CHARS: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const BASE: u64 = 62;

/// Convert bytes to a 5-character base62 string
///
/// Takes the first 5 bytes from the input and converts them to a base62 string.
/// If fewer than 5 bytes are provided, the remaining bytes are treated as 0.
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::to_base62;
///
/// let bytes = [0x12, 0x34, 0x56, 0x78, 0x9A];
/// let result = to_base62(&bytes);
/// assert_eq!(result.len(), 5);
/// assert!(result.chars().all(|c| c.is_ascii_alphanumeric()));
/// ```
pub fn to_base62(bytes: &[u8]) -> String {
    // Combine up to 5 bytes into a single u64
    // This gives us 40 bits = 5 bytes
    let mut num: u64 = 0;
    let byte_count = bytes.len().min(5);

    for &byte in bytes.iter().take(byte_count) {
        num = (num << 8) | (byte as u64);
    }

    // Pad with zeros if we have fewer than 5 bytes
    for _ in byte_count..5 {
        num <<= 8;
    }

    // Convert to base62 with exactly 5 characters
    let mut result_chars = [0u8; 5];
    let mut n = num;

    for i in (0..5).rev() {
        result_chars[i] = BASE62_CHARS[(n % BASE) as usize];
        n /= BASE;
    }

    // Safety: base62 encoding always produces valid UTF-8
    String::from_utf8(result_chars.to_vec()).expect("base62 encoding produces valid UTF-8")
}

/// Convert a u64 value to a 5-character base62 string
///
/// Uses only the first 40 bits of the u64 value.
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::u64_to_base62;
///
/// let hash = u64_to_base62(123456789);
/// assert_eq!(hash.len(), 5);
/// ```
pub fn u64_to_base62(value: u64) -> String {
    let bytes = [
        (value >> 32) as u8,
        (value >> 24) as u8,
        (value >> 16) as u8,
        (value >> 8) as u8,
        value as u8,
    ];
    to_base62(&bytes)
}

/// Seed a hash algorithm by converting a string seed to a u64
///
/// This is used for algorithms that need a numeric seed value.
/// The conversion is deterministic and consistent across platforms.
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::base62::seed_to_u64;
///
/// let seed = seed_to_u64("wdp-v1");
/// assert_eq!(seed, seed_to_u64("wdp-v1")); // Deterministic
/// assert_eq!(seed, 0x000031762D706477); // WDP v1 seed
/// ```
pub fn seed_to_u64(seed: &str) -> u64 {
    // WDP-conformant seed conversion:
    // 1. Take UTF-8 bytes of seed string
    // 2. Zero-pad to 8 bytes (on the right)
    // 3. Interpret as little-endian u64
    //
    // Per WDP Part 5, Section 4.5.1
    let seed_bytes = seed.as_bytes();
    let mut padded = [0u8; 8];
    let len = seed_bytes.len().min(8);
    padded[..len].copy_from_slice(&seed_bytes[..len]);
    u64::from_le_bytes(padded)
}

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

    #[test]
    fn test_to_base62_length() {
        let bytes = [0x12, 0x34, 0x56, 0x78, 0x9A];
        let result = to_base62(&bytes);
        assert_eq!(result.len(), 5, "Result should be exactly 5 characters");
    }

    #[test]
    fn test_to_base62_alphanumeric() {
        let bytes = [0xFF, 0xFF, 0xFF, 0xFF, 0xFF];
        let result = to_base62(&bytes);
        assert!(
            result.chars().all(|c| c.is_ascii_alphanumeric()),
            "Result should be alphanumeric only"
        );
    }

    #[test]
    fn test_to_base62_deterministic() {
        let bytes = [0x12, 0x34, 0x56, 0x78, 0x9A];
        let result1 = to_base62(&bytes);
        let result2 = to_base62(&bytes);
        assert_eq!(result1, result2, "Should be deterministic");
    }

    #[test]
    fn test_to_base62_different_inputs() {
        let bytes1 = [0x12, 0x34, 0x56, 0x78, 0x9A];
        let bytes2 = [0x12, 0x34, 0x56, 0x78, 0x9B];
        let result1 = to_base62(&bytes1);
        let result2 = to_base62(&bytes2);
        assert_ne!(
            result1, result2,
            "Different inputs should produce different outputs"
        );
    }

    #[test]
    fn test_to_base62_short_input() {
        let bytes = [0x12];
        let result = to_base62(&bytes);
        assert_eq!(result.len(), 5, "Should pad to 5 characters");
    }

    #[test]
    fn test_to_base62_empty_input() {
        let bytes = [];
        let result = to_base62(&bytes);
        assert_eq!(result.len(), 5, "Should pad to 5 characters");
    }

    #[test]
    fn test_u64_to_base62() {
        let value = 123456789u64;
        let result = u64_to_base62(value);
        assert_eq!(result.len(), 5);
        assert!(result.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    #[test]
    fn test_u64_to_base62_deterministic() {
        let value = 987654321u64;
        let result1 = u64_to_base62(value);
        let result2 = u64_to_base62(value);
        assert_eq!(result1, result2);
    }

    #[test]
    fn test_seed_to_u64_deterministic() {
        let seed = "wdp-v1";
        let result1 = seed_to_u64(seed);
        let result2 = seed_to_u64(seed);
        assert_eq!(result1, result2, "Should be deterministic");
    }

    #[test]
    fn test_seed_to_u64_wdp_conformant() {
        // Verify the WDP seed produces the correct u64 value
        // Per WDP Part 5, Section 4.5.1
        let seed = "wdp-v1";
        let result = seed_to_u64(seed);
        assert_eq!(
            result, 0x000031762D706477,
            "WDP seed should match spec value"
        );
    }

    #[test]
    fn test_seed_to_u64_different_seeds() {
        let seed1 = "wdp-v1";
        let seed2 = "Different";
        let result1 = seed_to_u64(seed1);
        let result2 = seed_to_u64(seed2);
        assert_ne!(
            result1, result2,
            "Different seeds should produce different values"
        );
    }

    #[test]
    fn test_seed_to_u64_empty() {
        // Empty seed produces 0 (all zeros)
        let seed = "";
        let result = seed_to_u64(seed);
        assert_eq!(result, 0, "Empty seed produces zero");
    }
}