Struct BucketBackend

pub struct BucketBackend<S = DefaultSymbol> { /* private fields */ }

An interner backend that reduces memory allocations by using string buckets.

Note

Implementation inspired by matklad’s blog post that can be found here: https://matklad.github.io/2020/03/22/fast-simple-rust-interner.html

Usage Hint

Use when deallocations or copy overhead is costly or when interning of static strings is especially common.

Usage

• Fill: Efficiency of filling an empty string interner.
• Resolve: Efficiency of interned string look-up given a symbol.
• Allocations: The number of allocations performed by the backend.
• Footprint: The total heap memory consumed by the backend.
• Contiguous: True if the returned symbols have contiguous values.
• Iteration: Efficiency of iterating over the interned strings.

Rating varies between bad, ok, good and best.

Scenario	Rating
Fill	good
Resolve	best
Allocations	good
Footprint	ok
Supports get_or_intern_static	yes
Send + Sync	yes
Contiguous	yes
Iteration	best

Trait Implementations

impl<S> Backend for BucketBackend<S>

where S: Symbol,

type Symbol = S

The symbol used by the string interner backend.

type Iter<'a> = Iter<'a, S> where Self: 'a

The iterator over the symbols and their strings.

fn with_capacity(cap: usize) -> Self

Creates a new backend for the given capacity.

fn intern(&mut self, string: &str) -> Self::Symbol

Interns the given string and returns its interned ref and symbol.

fn intern_static(&mut self, string: &'static str) -> Self::Symbol

Interns the given static string and returns its interned ref and symbol.

fn shrink_to_fit(&mut self)

Shrink backend capacity to fit interned symbols exactly.

fn resolve(&self, symbol: Self::Symbol) -> Option<&str>

Resolves the given symbol to its original string contents.

unsafe fn resolve_unchecked(&self, symbol: Self::Symbol) -> &str

Resolves the given symbol to its original string contents.

fn iter(&self) -> Self::Iter<'_>

Creates an iterator that yields all interned strings and their symbols.

impl<S> Clone for BucketBackend<S>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S: Debug> Debug for BucketBackend<S>

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

Formats the value using the given formatter.

impl<S> Default for BucketBackend<S>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, S> IntoIterator for &'a BucketBackend<S>

where S: Symbol,

type Item = (S, &'a str)

The type of the elements being iterated over.

type IntoIter = Iter<'a, S>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<S> PartialEq for BucketBackend<S>

where S: Symbol,

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

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

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

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

impl<S> Eq for BucketBackend<S>

where S: Symbol,

impl<S> Send for BucketBackend<S>

where S: Symbol,

Safety

The bucket backend requires a manual Send impl because it is self referential. When cloning a bucket backend a deep clone is performed and all references to itself are updated for the clone.

impl<S> Sync for BucketBackend<S>

where S: Symbol,

Safety

The bucket backend requires a manual Send impl because it is self referential. Those references won’t escape its own scope and also the bucket backend has no interior mutability.