string_interner/backend/
mod.rs

1//! Backends for the [`StringInterner`](`crate::StringInterner`).
2//!
3//! The backend is the method or strategy that handles the actual interning.
4//! There are trade-offs for the different kinds of backends. A user should
5//! find the backend that suits their use case best.
6
7mod bucket;
8mod buffer;
9mod string;
10
11#[cfg(feature = "backends")]
12pub use self::{bucket::BucketBackend, buffer::BufferBackend, string::StringBackend};
13use crate::Symbol;
14
15/// The default backend recommended for general use.
16#[cfg(feature = "backends")]
17pub type DefaultBackend = StringBackend<crate::DefaultSymbol>;
18
19/// Types implementing this trait may act as backends for the string interner.
20///
21/// The job of a backend is to actually store, manage and organize the interned
22/// strings. Different backends have different trade-offs. Users should pick
23/// their backend with hinsight of their personal use-case.
24pub trait Backend: Default {
25    /// The symbol used by the string interner backend.
26    type Symbol: Symbol;
27
28    /// The iterator over the symbols and their strings.
29    type Iter<'a>: Iterator<Item = (Self::Symbol, &'a str)>
30    where
31        Self: 'a;
32
33    /// Creates a new backend for the given capacity.
34    ///
35    /// The capacity denotes how many strings are expected to be interned.
36    fn with_capacity(cap: usize) -> Self;
37
38    /// Interns the given string and returns its interned ref and symbol.
39    ///
40    /// # Note
41    ///
42    /// The backend must make sure that the returned symbol maps back to the
43    /// original string in its [`resolve`](`Backend::resolve`) method.
44    fn intern(&mut self, string: &str) -> Self::Symbol;
45
46    /// Interns the given static string and returns its interned ref and symbol.
47    ///
48    /// # Note
49    ///
50    /// The backend must make sure that the returned symbol maps back to the
51    /// original string in its [`resolve`](`Backend::resolve`) method.
52    #[inline]
53    fn intern_static(&mut self, string: &'static str) -> Self::Symbol {
54        // The default implementation simply forwards to the normal [`intern`]
55        // implementation. Backends that can optimize for this use case should
56        // implement this method.
57        self.intern(string)
58    }
59
60    /// Shrink backend capacity to fit interned symbols exactly.
61    fn shrink_to_fit(&mut self);
62
63    /// Resolves the given symbol to its original string contents.
64    fn resolve(&self, symbol: Self::Symbol) -> Option<&str>;
65
66    /// Resolves the given symbol to its original string contents.
67    ///
68    /// # Safety
69    ///
70    /// Does not perform validity checks on the given symbol and relies
71    /// on the caller to be provided with a symbol that has been generated
72    /// by the [`intern`](`Backend::intern`) or
73    /// [`intern_static`](`Backend::intern_static`) methods of the same
74    /// interner backend.
75    unsafe fn resolve_unchecked(&self, symbol: Self::Symbol) -> &str;
76
77    /// Creates an iterator that yields all interned strings and their symbols.
78    fn iter(&self) -> Self::Iter<'_>;
79}
string_interner/backend/mod.rs

string_interner/backend/
mod.rs
