intern_lang/
error.rs

1//! The [`InternError`] type returned by fallible interning.
2
3use core::fmt;
4
5/// An error returned when a string cannot be interned.
6///
7/// Interning a *new* string consumes one symbol from a finite space. When that
8/// space is exhausted there is no symbol left to assign, and
9/// [`try_intern`](crate::Interner::try_intern) reports it with this error rather
10/// than panicking or aliasing the string onto an existing symbol.
11///
12/// This enum is `#[non_exhaustive]`: future releases may add variants for new
13/// failure modes without it being a breaking change, so a `match` on it must
14/// include a wildcard arm.
15///
16/// # Examples
17///
18/// ```
19/// use intern_lang::{InternError, Interner};
20///
21/// let mut interner = Interner::new();
22/// // Far below the symbol-space bound, interning always succeeds.
23/// assert!(interner.try_intern("name").is_ok());
24///
25/// fn describe(err: InternError) -> &'static str {
26///     match err {
27///         InternError::SymbolSpaceExhausted => "out of symbols",
28///         _ => "unknown interning error",
29///     }
30/// }
31/// assert_eq!(describe(InternError::SymbolSpaceExhausted), "out of symbols");
32/// ```
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
34#[non_exhaustive]
35pub enum InternError {
36    /// The symbol space is exhausted: the interner has already issued all
37    /// `u32::MAX` symbols, so no new string can be assigned one.
38    ///
39    /// Reaching this requires interning over four billion *distinct* strings,
40    /// which exhausts memory on any normal machine long before the symbol space.
41    /// A caller that must handle the boundary explicitly — rather than relying on
42    /// it being unreachable — should use
43    /// [`try_intern`](crate::Interner::try_intern) and treat this variant as a
44    /// hard stop: the interner cannot accept further distinct strings.
45    SymbolSpaceExhausted,
46}
47
48impl fmt::Display for InternError {
49    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
50        match self {
51            Self::SymbolSpaceExhausted => {
52                f.write_str("symbol space exhausted: the interner has issued all u32::MAX symbols")
53            }
54        }
55    }
56}
57
58impl core::error::Error for InternError {}
intern_lang/error.rs

intern_lang/
error.rs
