sashite-sin 1.0.0

//! The central SIN identifier type.

use crate::encode::EncodedSin;
use crate::error::ParseError;
use crate::letter::Letter;
use crate::side::Side;

/// A parsed SIN token: a player's identity at the level of notation.
///
/// An `Identifier` bundles the two attributes a token encodes — a [`Letter`]
/// abbreviation and a [`Side`] — into a single 2-byte `Copy` value.
/// Construction from typed components via [`Identifier::new`] is total: every
/// combination is a valid token, so it cannot fail.
///
/// The derived total ordering compares attributes in the order letter → side.
///
/// # Examples
///
/// ```
/// # fn main() -> Result<(), sashite_sin::ParseError> {
/// use sashite_sin::{Identifier, Side};
///
/// let chinese: Identifier = "c".parse()?;
/// assert_eq!(chinese.letter().as_char(), 'C');
/// assert_eq!(chinese.side(), Side::Second);
/// assert_eq!(chinese.to_char(), 'c');
///
/// // Transformations are cheap and infallible; the value is `Copy`.
/// assert_eq!(chinese.flipped().to_char(), 'C');
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Identifier {
    letter: Letter,
    side: Side,
}

impl Identifier {
    /// Builds an identifier from its two typed components.
    ///
    /// This is infallible: because each component type is valid by
    /// construction, every combination denotes a valid SIN token.
    ///
    /// # Examples
    ///
    /// ```
    /// use sashite_sin::{Identifier, Letter, Side};
    ///
    /// let p = Identifier::new(Letter::try_from_char('C').unwrap(), Side::Second);
    /// assert_eq!(p.encode().as_str(), "c");
    /// ```
    #[must_use]
    pub const fn new(letter: Letter, side: Side) -> Self {
        Self { letter, side }
    }

    /// Parses a string slice into an identifier.
    ///
    /// # Errors
    ///
    /// Returns a [`ParseError`] if `input` is not a valid SIN token (empty,
    /// too long, or not a single ASCII letter).
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), sashite_sin::ParseError> {
    /// use sashite_sin::Identifier;
    ///
    /// let western = Identifier::parse("W")?;
    /// assert!(western.is_first());
    /// assert_eq!(western.letter().as_char(), 'W');
    /// # Ok(())
    /// # }
    /// ```
    pub const fn parse(input: &str) -> Result<Self, ParseError> {
        crate::parse::parse(input)
    }

    /// Reports whether `input` is a valid SIN token, without allocating or
    /// constructing an identifier on the caller's side.
    #[must_use]
    pub const fn is_valid(input: &str) -> bool {
        Self::parse(input).is_ok()
    }

    /// Returns the canonical, allocation-free string encoding of this token.
    #[must_use]
    pub fn encode(self) -> EncodedSin {
        EncodedSin::from_identifier(self)
    }

    /// Returns the token as its single cased character: uppercase for
    /// [`Side::First`], lowercase for [`Side::Second`].
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), sashite_sin::ParseError> {
    /// use sashite_sin::Identifier;
    ///
    /// assert_eq!(Identifier::parse("J")?.to_char(), 'J');
    /// assert_eq!(Identifier::parse("j")?.to_char(), 'j');
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn to_char(self) -> char {
        self.letter.to_ascii(self.side) as char
    }

    // --- Accessors ---

    /// Returns the player-style abbreviation (always uppercase).
    #[must_use]
    pub const fn letter(self) -> Letter {
        self.letter
    }

    /// Returns the side the player belongs to.
    #[must_use]
    pub const fn side(self) -> Side {
        self.side
    }

    // --- Side queries ---

    /// Reports whether the side is [`Side::First`].
    #[must_use]
    pub const fn is_first(self) -> bool {
        matches!(self.side, Side::First)
    }

    /// Reports whether the side is [`Side::Second`].
    #[must_use]
    pub const fn is_second(self) -> bool {
        matches!(self.side, Side::Second)
    }

    // --- Transformations (return a new value; the type is `Copy`) ---

    /// Returns a copy with the abbreviation replaced.
    #[must_use]
    pub const fn with_letter(self, letter: Letter) -> Self {
        Self::new(letter, self.side)
    }

    /// Returns a copy with the side replaced.
    #[must_use]
    pub const fn with_side(self, side: Side) -> Self {
        Self::new(self.letter, side)
    }

    /// Returns a copy belonging to the opposite [`Side`].
    #[must_use]
    pub const fn flipped(self) -> Self {
        self.with_side(self.side.flip())
    }
}

impl core::fmt::Display for Identifier {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str(self.encode().as_str())
    }
}

impl core::str::FromStr for Identifier {
    type Err = ParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse(s)
    }
}

impl TryFrom<&str> for Identifier {
    type Error = ParseError;

    fn try_from(s: &str) -> Result<Self, Self::Error> {
        Self::parse(s)
    }
}

impl TryFrom<&[u8]> for Identifier {
    type Error = ParseError;

    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
        crate::parse::parse_bytes(bytes)
    }
}