Struct Interner

pub struct Interner<S = RandomState> { /* private fields */ }

An interner will keep track of strings and ensure there is only one allocation for any given string contents.

For example:

let interner = Interner::new();
let foo0 = interner.intern(String::from("foo"));
let foo1 = interner.intern(String::from("foo"));
assert!(InternedStr::ptr_eq(&foo0, &foo1));

Because foo0 and foo1 have the same contents, they become a single allocation.

Interned strings are immutable, which means that you must construct the finished string before interning it.

This is useful if you have many instances of the same strings (e.g., if 200 different structs contain the string "foo", an interner allows there to be 200 pointers to one allocation, rather than 200 different allocations).

This Interner is thread-safe, meaning that it implements both Send and Sync (when S implements Send, which the default does).

Implementations

impl Interner

pub fn new() -> Self

Constructs a new Interner.

impl<S> Interner<S>

pub fn with_hasher(hasher: S) -> Self

Constructs a new Interner with the given hasher. See BuildHasher for more information.

pub fn from_set(strings: HashSet<InternedStr, S>) -> Self

Construct a new Interner with the given set’s contents already interned. The new Interner will also use the given set’s hasher.

pub fn into_set(self) -> HashSet<InternedStr, S>

Consume this Interner and return a set containing all of strings that were interned. The returned set also uses the same hasher.

Panics

This method panics if this Interner has been poisoned.

pub fn clear(&self)

Locks this Interner and removes all of the interned strings, or blocks until it is able to do so.

interner.clear() is equivalent to intenerer.lock().clear(). (See LockedInterner::clear.)

Panics

This method panics if this Interner has been poisoned, and it may panic if this Interner is already locked on this thread.

pub fn lock(&self) -> LockedInterner<'_, S>

Locks this Interner on the current thread until the returned LockedInterner is dropped, or blocks until it is able to do so.

While it is locked, the current thread has exclusive access to this Interner’s methods (accessible from the LockedInterner; any methods used directly on self may panic). This enables some additional functionality, most notably LockedInterner::iter.

If a panic occurs on the current thread while this Interner is locked, it will become poisoned.

Panics

This method panics if this Interner has been poisoned, and it may panic if this Interner is already locked on this thread.

impl<S: BuildHasher> Interner<S>

pub fn intern(&self, string: impl AsRef<str>) -> InternedStr

where S: BuildHasher,

Locks this Interner, saves the given string if it is not already saved, and returns a reference to the saved allocation, or blocks until it is able to do so.

interner.intern(string) is equivalent to interner.lock().intern(string). (See LockedInterner::intern.)

Panics

This method panics if this Interner has been poisoned, and it may panic if this Interner is already locked on this thread.

pub fn contains(&self, string: impl AsRef<str>) -> bool

Returns whether the given string has already been saved, or blocks until it is able to do so.

pub fn get(&self, string: impl AsRef<str>) -> Option<InternedStr>

If the given string has already been saved, returns a reference to the saved allocation, or None otherwise, or blocks until it is able to do so.

Trait Implementations

impl<S: Clone> Clone for Interner<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Debug for Interner<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Default> Default for Interner<S>

fn default() -> Self

Returns the “default value” for a type.

impl<A, S> FromIterator<A> for Interner<S>

where HashSet<InternedStr, S>: FromIterator<A>,

fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self

Creates a value from an iterator.

impl<S> IntoIterator for Interner<S>

type Item = Arc<str>

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter

Creates an iterator from a value.

impl<S: BuildHasher> PartialEq for Interner<S>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Self) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: BuildHasher> Eq for Interner<S>