pub struct ResRef { /* private fields */ }Expand description
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 so that every
constructed resref can 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.
Implementations§
Source§impl ResRef
impl ResRef
Sourcepub fn new(value: impl AsRef<str>) -> Result<Self, ResRefError>
pub fn new(value: impl AsRef<str>) -> Result<Self, ResRefError>
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. An empty string produces a blank ResRef.
§Errors
ResRefError::InvalidChar when a character has no
Windows-1252 mapping (Chinese, emoji). ResRefError::TooLong
when the encoded form exceeds 16 bytes, which is measured after
transcoding, so a name of 16 characters can still be too long.
Sourcepub const fn const_new(value: &str) -> Result<Self, ResRefError>
pub const fn const_new(value: &str) -> Result<Self, ResRefError>
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.
§Errors
ResRefError::TooLong above 16 bytes, and
ResRefError::InvalidChar for any non-ASCII byte. That second
case is narrower than Self::new’s: a character this rejects
may well be one the engine can store.
Sourcepub fn as_bytes(&self) -> &[u8] ⓘ
pub fn as_bytes(&self) -> &[u8] ⓘ
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).
Sourcepub fn to_padded(&self) -> [u8; 16]
pub fn to_padded(&self) -> [u8; 16]
The resref in the fixed-width field every container stores it in.
Sixteen bytes, zero-padded. Every format holding a resref holds it this way, and four writers had each open-coded the padding, so a fifth getting it subtly wrong was a matter of time.
No length check: Self::new refuses anything longer, so a resref
that would not fit cannot exist.