rakata_core/

resref.rs

use std::fmt::{Display, Formatter};
use std::str::FromStr;
use thiserror::Error;

use crate::text::{decode_text, encode_text, EncodeTextError, TextEncoding};

/// Maximum number of bytes for a KotOR resource reference.
pub const MAX_RESREF_LEN: usize = 16;

/// Error returned when constructing a [`ResRef`] fails validation.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum ResRefError {
    /// Input exceeded the maximum allowed resref length, measured in
    /// the Windows-1252 encoding the engine actually stores.
    #[error("resref length {len} exceeds maximum {max} (Windows-1252 bytes)")]
    TooLong {
        /// Actual input length in Windows-1252 bytes.
        len: usize,
        /// Maximum allowed length.
        max: usize,
    },
    /// Input contained a Unicode character with no representation in
    /// the engine's Windows-1252 encoding (e.g., Chinese, emoji).
    #[error("invalid resref character '{ch}': no Windows-1252 mapping")]
    InvalidChar {
        /// The unencodable character.
        ch: char,
    },
}

impl From<EncodeTextError> for ResRefError {
    fn from(err: EncodeTextError) -> Self {
        Self::InvalidChar { ch: err.character }
    }
}

/// Canonicalized resource reference.
///
/// KotOR resource references are case-insensitive identifiers up to
/// 16 bytes long, stored as Windows-1252-encoded bytes (the engine's
/// native encoding). This type holds the bytes in an inline fixed-size
/// buffer, making it `Copy` and zero-allocation.
///
/// ## Validation rules
///
/// Accepts any input that round-trips through Windows-1252 encoding.
/// ASCII bytes pass straight through; non-ASCII chars that have a
/// Windows-1252 representation (`é`, `ü`, `£`, etc.) get transcoded
/// to their single-byte Windows-1252 form. Characters with no
/// Windows-1252 mapping (Chinese, emoji, etc.) are rejected.
///
/// The engine itself performs no character validation at all (verbatim
/// memcpy into a 16-byte buffer). Validation here exists to ensure we
/// only construct resrefs that can actually be stored in the
/// engine-native encoding. For the full engine audit, see the
/// **ResRef Validation** section of
/// `docs/src/formats/resource_system.md`.
///
/// ## Storage and access
///
/// Use [`Self::as_bytes`] for byte-level work (writing to disk,
/// hashing, lint inspection, byte-level comparison). For a string
/// view, use the `Display` impl (e.g. `format!("{resref}")` or
/// `resref.to_string()`); it decodes Windows-1252 → UTF-8 on demand.
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(try_from = "String", into = "String"))]
pub struct ResRef {
    bytes: [u8; MAX_RESREF_LEN],
    len: u8,
}

impl ResRef {
    /// Creates and validates a new resource reference.
    ///
    /// The input is transcoded from UTF-8 to Windows-1252 (the engine's
    /// native encoding); ASCII letters are lowercased for the
    /// engine's case-insensitive lookup. Returns
    /// [`ResRefError::InvalidChar`] when a character has no
    /// Windows-1252 mapping (Chinese, emoji, etc.) and
    /// [`ResRefError::TooLong`] when the encoded form exceeds 16 bytes.
    /// An empty string produces a blank ResRef.
    pub fn new(value: impl AsRef<str>) -> Result<Self, ResRefError> {
        let encoded = encode_text(value.as_ref(), TextEncoding::Windows1252)?;
        if encoded.len() > MAX_RESREF_LEN {
            return Err(ResRefError::TooLong {
                len: encoded.len(),
                max: MAX_RESREF_LEN,
            });
        }
        let mut bytes = [0u8; MAX_RESREF_LEN];
        for (i, &b) in encoded.iter().enumerate() {
            // Lowercase ASCII letters; leave Windows-1252 0x80+ bytes
            // untouched (the engine's case folding for the extended
            // range would need a Windows-1252 case table that we have
            // not audited; vanilla content does not use these bytes).
            bytes[i] = b.to_ascii_lowercase();
        }
        let len = u8::try_from(encoded.len()).expect("len already bounded by MAX_RESREF_LEN");
        Ok(Self { bytes, len })
    }

    /// `const`-friendly version of [`Self::new`] for declaring
    /// `pub const` resref constants at compile time.
    ///
    /// Restricted to ASCII-only input (Windows-1252 transcoding is
    /// not const-friendly). Use [`Self::new`] for runtime input
    /// that may contain extended Windows-1252 characters.
    pub const fn const_new(value: &str) -> Result<Self, ResRefError> {
        let raw = value.as_bytes();
        if raw.len() > MAX_RESREF_LEN {
            return Err(ResRefError::TooLong {
                len: raw.len(),
                max: MAX_RESREF_LEN,
            });
        }
        let mut bytes = [0u8; MAX_RESREF_LEN];
        let mut i = 0;
        while i < raw.len() {
            let b = raw[i];
            if !b.is_ascii() {
                // CLIPPY: char::from(u8) is not const-stable, and every
                // u8 is a valid Unicode scalar value (latin-1 range) so
                // the cast is sound.
                #[allow(clippy::as_conversions)]
                return Err(ResRefError::InvalidChar { ch: b as char });
            }
            bytes[i] = b.to_ascii_lowercase();
            i += 1;
        }
        // CLIPPY: u8::try_from is not const-stable as of 1.85, and the
        // length is already bounded above by MAX_RESREF_LEN = 16, so
        // truncation cannot occur.
        #[allow(clippy::as_conversions)]
        let len = raw.len() as u8;
        Ok(Self { bytes, len })
    }

    /// Returns an empty resource reference.
    pub const fn blank() -> Self {
        Self {
            bytes: [0u8; MAX_RESREF_LEN],
            len: 0,
        }
    }

    /// Returns the canonical Windows-1252 bytes that make up this
    /// resref.
    ///
    /// This is the engine-actual storage form. Use this for byte-level
    /// work (writing to disk, hashing, lint inspection of byte
    /// patterns, comparing against a byte-string literal).
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes[..usize::from(self.len)]
    }

    /// Returns `true` when the resource reference is empty.
    pub const fn is_blank(&self) -> bool {
        self.len == 0
    }

    /// Returns `true` when the resource reference is empty.
    ///
    /// Alias for [`is_blank`](Self::is_blank) matching the standard collection API.
    pub const fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Returns the length in Windows-1252 bytes.
    ///
    /// For ASCII-only resrefs (the overwhelming majority) this equals
    /// the character count. For extended-character resrefs it is the
    /// engine-storage byte count, not the UTF-8 byte count of the
    /// Display form.
    #[allow(clippy::as_conversions)]
    pub const fn len(&self) -> usize {
        // u8 to usize is a lossless widening; usize::from is not yet const-stable
        // as of 1.93, so `as` is the only option in a const context.
        self.len as usize
    }
}

impl std::fmt::Debug for ResRef {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let decoded = decode_text(self.as_bytes(), TextEncoding::Windows1252);
        write!(f, "ResRef({decoded:?})")
    }
}

impl Default for ResRef {
    fn default() -> Self {
        Self::blank()
    }
}

impl Display for ResRef {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let decoded = decode_text(self.as_bytes(), TextEncoding::Windows1252);
        f.write_str(&decoded)
    }
}

impl FromStr for ResRef {
    type Err = ResRefError;

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

impl TryFrom<&str> for ResRef {
    type Error = ResRefError;

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

impl TryFrom<String> for ResRef {
    type Error = ResRefError;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl From<ResRef> for String {
    fn from(val: ResRef) -> Self {
        val.to_string()
    }
}

// Convenience byte-comparison impls for assertions and lookups against
// literals like `resref == "module"` or `resref == b"module"`. These
// compare the canonical Windows-1252 bytes directly. For ASCII inputs
// (the overwhelming majority of resrefs) this matches both the engine
// semantics and what the caller intuitively expects. For an extended
// Windows-1252 byte (`é` = 0xE9), comparing against a UTF-8 string
// literal (`"é"` = 0xC3 0xA9) returns false, which is the correct
// outcome since the byte sequences genuinely differ.
impl PartialEq<str> for ResRef {
    fn eq(&self, other: &str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

impl PartialEq<&str> for ResRef {
    fn eq(&self, other: &&str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

impl PartialEq<ResRef> for str {
    fn eq(&self, other: &ResRef) -> bool {
        other == self
    }
}

impl PartialEq<ResRef> for &str {
    fn eq(&self, other: &ResRef) -> bool {
        other == self
    }
}

impl PartialEq<[u8]> for ResRef {
    fn eq(&self, other: &[u8]) -> bool {
        self.as_bytes() == other
    }
}

impl PartialEq<&[u8]> for ResRef {
    fn eq(&self, other: &&[u8]) -> bool {
        self.as_bytes() == *other
    }
}

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

    #[test]
    fn accepts_valid_resref() {
        let parsed = ResRef::new("P_Bastila").expect("valid resref");
        assert_eq!(parsed.as_bytes(), b"p_bastila");
    }

    #[test]
    fn rejects_too_long_resref() {
        let err = ResRef::new("this_name_is_longer_than_sixteen").expect_err("must fail");
        assert!(matches!(err, ResRefError::TooLong { .. }));
    }

    #[test]
    fn accepts_arbitrary_ascii_characters() {
        // The engine has no character whitelist (Ghidra-audited;
        // see docs/src/formats/resource_system.md). Vanilla content
        // uses bytes our prior whitelist rejected: `+` in chitin.key
        // upgrade-modifier resrefs, `!` in RIM key tables, and so
        // on. All single ASCII bytes round-trip.
        for name in [
            "g_w_lghtsbr+1",
            "bad!name",
            "with space",
            "punct.dot",
            "amp&char",
            "t3-m4",
        ] {
            let parsed = ResRef::new(name).unwrap_or_else(|e| {
                panic!("`{name}` should be valid (any ASCII byte allowed): {e:?}")
            });
            assert_eq!(parsed.as_bytes(), name.as_bytes());
        }
    }

    #[test]
    fn accepts_extended_windows_1252_input() {
        // `é` has a single-byte Windows-1252 representation (0xE9), so
        // it is acceptable even though the UTF-8 form is multi-byte.
        let parsed = ResRef::new("café").expect("é round-trips through Windows-1252");
        assert_eq!(parsed.as_bytes(), &[b'c', b'a', b'f', 0xE9]);
    }

    #[test]
    fn rejects_unencodable_input() {
        // Characters with no Windows-1252 mapping (CJK, emoji, etc.)
        // cannot be stored in the engine's byte buffer, so we reject
        // at the API boundary.
        let err = ResRef::new("名前").expect_err("CJK has no Windows-1252 mapping");
        assert!(matches!(err, ResRefError::InvalidChar { .. }));
    }

    #[test]
    fn const_new_rejects_non_ascii_input() {
        // const_new is ASCII-only by design (no const Windows-1252
        // transcoding), so even a Windows-1252-encodable char like
        // `é` is rejected at compile time.
        let err = ResRef::const_new("café").expect_err("non-ASCII rejected at compile time");
        assert!(matches!(err, ResRefError::InvalidChar { .. }));
    }

    #[test]
    fn blank_is_empty() {
        let r = ResRef::blank();
        assert!(r.is_blank());
        assert_eq!(r.as_bytes(), b"");
        assert_eq!(r.len(), 0);
    }

    #[test]
    fn max_length_accepted() {
        let parsed = ResRef::new("a23456789_123456").expect("16 chars is valid");
        assert_eq!(parsed.as_bytes(), b"a23456789_123456");
        assert_eq!(parsed.len(), 16);
    }

    #[test]
    fn is_copy() {
        fn takes_copy<T: Copy>(_: T) {}
        takes_copy(ResRef::blank());
    }

    #[test]
    fn roundtrip_through_string() {
        let original = ResRef::new("test_resref").expect("valid");
        let s: String = original.into();
        assert_eq!(s, "test_resref");
        let back: ResRef = s.try_into().expect("valid");
        assert_eq!(back, original);
    }

    #[test]
    fn const_new_accepts_valid_resref() {
        let parsed = ResRef::const_new("itempropdef").expect("valid");
        assert_eq!(parsed.as_bytes(), b"itempropdef");
    }

    #[test]
    fn const_new_lowercases_uppercase_input() {
        let parsed = ResRef::const_new("ItemPropDef").expect("valid");
        assert_eq!(parsed.as_bytes(), b"itempropdef");
    }

    #[test]
    fn const_new_rejects_too_long() {
        let err = ResRef::const_new("this_name_is_longer_than_sixteen").expect_err("must fail");
        assert!(matches!(err, ResRefError::TooLong { .. }));
    }

    #[test]
    fn const_new_matches_runtime_new_for_valid_inputs() {
        for name in ["appearance", "Hk-47", "iprp_damagecost", "T3-M4"] {
            let runtime = ResRef::new(name).expect("valid");
            let compile_time = ResRef::const_new(name).expect("valid");
            assert_eq!(runtime, compile_time, "mismatch for `{name}`");
        }
    }

    #[test]
    fn const_new_can_be_called_in_const_context() {
        // The point of `const_new`: this declaration would fail to
        // compile if the function weren't usable in a `const`.
        const APPEARANCE: Result<ResRef, ResRefError> = ResRef::const_new("appearance");
        let parsed = APPEARANCE.expect("compile-time-valid");
        assert_eq!(parsed.as_bytes(), b"appearance");
    }
}