tui_splitflap/

char_set.rs

//! Character set definitions and forward-wrapping distance arithmetic.

use std::collections::HashMap;
use std::sync::Arc;

use thiserror::Error;

#[derive(Debug, Error)]
pub enum CharSetError {
    #[error("CharSet requires at least 2 characters, got {0}")]
    TooFew(usize),

    #[error("duplicate character '{0}' in CharSet")]
    Duplicate(char),
}

/// Ordered sequence of characters a split-flap tile can display.
///
/// Order determines which intermediate characters appear during a
/// Sequential or Combined flip animation. Distance always travels
/// forward (wraps around), never backward.
#[derive(Debug, Clone)]
pub struct CharSet {
    chars: Arc<[char]>,
    index_of: HashMap<char, usize>,
}

// Variant glyphs (Ð, Ɨ, Ᵽ, Ɍ, Ŧ, Ʉ, Ɏ, Ƶ) placed after their base letter
// create a mid-rotation illusion during sequential flip animations.
const DEFAULT_CHARS: &[char] = &[
    ' ', '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', '.', ',', '!', '?', '&', '#', '@', '-', '\'', ':', '/',
];

impl CharSet {
    pub fn new(chars: impl Into<Arc<[char]>>) -> Result<Self, CharSetError> {
        let chars: Arc<[char]> = chars.into();

        if chars.len() < 2 {
            return Err(CharSetError::TooFew(chars.len()));
        }

        let mut index_of = HashMap::with_capacity(chars.len());

        for (i, &ch) in chars.iter().enumerate() {
            if index_of.insert(ch, i).is_some() {
                return Err(CharSetError::Duplicate(ch));
            }
        }

        Ok(Self { chars, index_of })
    }

    #[must_use]
    pub fn len(&self) -> usize {
        self.chars.len()
    }

    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.chars.is_empty()
    }

    /// O(1) lookup by index.
    pub fn get(&self, index: usize) -> Option<char> {
        self.chars.get(index).copied()
    }

    /// O(1) index lookup for a character. Returns `None` if not in set.
    pub fn index_of(&self, ch: char) -> Option<usize> {
        self.index_of.get(&ch).copied()
    }

    pub fn contains(&self, ch: char) -> bool {
        self.index_of.contains_key(&ch)
    }

    /// Forward-wrapping distance. Unknown characters resolve to index 0.
    pub fn distance(&self, from: char, to: char) -> usize {
        let a = self.resolve_index(from);
        let b = self.resolve_index(to);

        if a == b {
            return 0;
        }

        let len = self.chars.len();
        (b + len - a) % len
    }

    fn resolve_index(&self, ch: char) -> usize {
        self.index_of.get(&ch).copied().unwrap_or(0)
    }

    pub(crate) fn step_forward(&self, from: char, steps: usize) -> char {
        let start = self.resolve_index(from);
        let target = (start + steps) % self.chars.len();
        self.chars[target]
    }

    pub(crate) fn sanitize(&self, ch: char) -> char {
        self.chars[self.resolve_index(ch)]
    }
}

impl Default for CharSet {
    fn default() -> Self {
        Self::new(DEFAULT_CHARS).expect("default CharSet is valid")
    }
}

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

    #[test]
    fn default_charset_starts_with_space() {
        let cs = CharSet::default();
        assert_eq!(cs.get(0), Some(' '));
    }

    #[test]
    fn default_charset_contains_all_expected_characters() {
        let cs = CharSet::default();

        assert!(cs.contains(' '));

        for ch in 'A'..='Z' {
            assert!(cs.contains(ch), "missing letter {ch}");
        }

        for ch in '0'..='9' {
            assert!(cs.contains(ch), "missing digit {ch}");
        }

        for ch in ['.', ',', '!', '?', '&', '#', '@', '-', '\'', ':', '/'] {
            assert!(cs.contains(ch), "missing punctuation {ch}");
        }
    }

    #[test]
    fn default_charset_order() {
        let cs = CharSet::default();
        assert_eq!(cs.index_of('A'), Some(1));
        assert_eq!(cs.index_of('Z'), Some(33));
        assert_eq!(cs.index_of('0'), Some(35));
        assert_eq!(cs.index_of('9'), Some(44));
    }

    #[test]
    fn default_charset_length() {
        let cs = CharSet::default();
        assert_eq!(cs.len(), 56);
    }

    #[test]
    fn default_charset_contains_variant_glyphs() {
        let cs = CharSet::default();

        for (base, variant) in [
            ('D', 'Ð'),
            ('I', 'Ɨ'),
            ('P', 'Ᵽ'),
            ('R', 'Ɍ'),
            ('T', 'Ŧ'),
            ('U', 'Ʉ'),
            ('Y', 'Ɏ'),
            ('Z', 'Ƶ'),
        ] {
            let base_idx = cs
                .index_of(base)
                .expect("base char should be in default charset");
            let variant_idx = cs
                .index_of(variant)
                .expect("variant char should be in default charset");
            assert_eq!(variant_idx, base_idx + 1, "{variant} should follow {base}");
        }
    }

    #[test]
    fn distance_forward_same_region() {
        let cs = CharSet::default();
        // A(1) → F(7): passes through B, C, D, Ð, E, F = distance 6
        assert_eq!(cs.distance('A', 'F'), 6);
    }

    #[test]
    fn distance_wraps_forward() {
        let cs = CharSet::default();
        let d = cs.distance('Z', 'A');

        // Z(33) → A(1): forward wrap = (1 + 56 - 33) % 56 = 24
        assert_eq!(d, 24);
        assert!(d > 0, "must wrap forward, not backward");
    }

    #[test]
    fn distance_identical_is_zero() {
        let cs = CharSet::default();
        assert_eq!(cs.distance('A', 'A'), 0);
    }

    #[test]
    fn distance_unknown_char_treated_as_space() {
        let cs = CharSet::default();

        // '~' is not in the set → resolves to index 0 (space)
        // distance from space to 'A' = 1
        assert_eq!(cs.distance('~', 'A'), 1);
    }

    #[test]
    fn step_forward_basic() {
        let cs = CharSet::default();
        // A(1) + 6 = 7 → F (passes B, C, D, Ð, E)
        assert_eq!(cs.step_forward('A', 6), 'F');
    }

    #[test]
    fn step_forward_wraps() {
        let cs = CharSet::default();
        let result = cs.step_forward('/', 1);
        assert_eq!(result, ' ', "wrapping past last char returns to space");
    }

    #[test]
    fn sanitize_known_char_unchanged() {
        let cs = CharSet::default();
        assert_eq!(cs.sanitize('A'), 'A');
    }

    #[test]
    fn sanitize_unknown_char_becomes_space() {
        let cs = CharSet::default();
        assert_eq!(cs.sanitize('~'), ' ');
    }

    #[test]
    fn custom_charset_accepted() {
        static CUSTOM: &[char] = &['X', 'Y', 'Z'];
        let cs = CharSet::new(CUSTOM).expect("CUSTOM should be a valid charset");
        assert_eq!(cs.len(), 3);
        assert_eq!(cs.distance('X', 'Z'), 2);
    }

    #[test]
    fn custom_charset_too_few_rejected() {
        static ONE: &[char] = &['A'];
        let err = CharSet::new(ONE).expect_err("single-char charset should be rejected");
        assert!(matches!(err, CharSetError::TooFew(1)));
    }

    #[test]
    fn custom_charset_empty_rejected() {
        static EMPTY: &[char] = &[];
        let err = CharSet::new(EMPTY).expect_err("empty charset should be rejected");
        assert!(matches!(err, CharSetError::TooFew(0)));
    }

    #[test]
    fn custom_charset_duplicates_rejected() {
        static DUPE: &[char] = &['A', 'B', 'A'];
        let err = CharSet::new(DUPE).expect_err("charset with duplicates should be rejected");
        assert!(matches!(err, CharSetError::Duplicate('A')));
    }

    #[test]
    fn index_lookup_is_consistent() {
        let cs = CharSet::default();

        for i in 0..cs.len() {
            let ch = cs.get(i).expect("index should be within charset bounds");
            assert_eq!(cs.index_of(ch), Some(i));
        }
    }
}