Struct lasso::Rodeo

pub struct Rodeo<K = Spur, S = RandomState> { /* private fields */ }

A string interner that caches strings quickly with a minimal memory footprint, returning a unique key to re-access it with O(1) times.

By default Rodeo uses the Spur type for keys and RandomState as its hasher

Implementations

impl<K> Rodeo<K, RandomState>where
    K: Key,

pub fn new() -> Self

Create a new Rodeo

Example

use lasso::{Rodeo, Spur};

let mut rodeo: Rodeo<Spur> = Rodeo::new();
let hello = rodeo.get_or_intern("Hello, ");
let world = rodeo.get_or_intern("World!");

assert_eq!("Hello, ", rodeo.resolve(&hello));
assert_eq!("World!", rodeo.resolve(&world));

pub fn with_capacity(capacity: Capacity) -> Self

Create a new Rodeo with the specified capacity. The interner will be able to hold capacity strings without reallocating

See Capacity for more information

Example

use lasso::{Rodeo, Capacity, Spur};

let rodeo: Rodeo<Spur> = Rodeo::with_capacity(Capacity::for_strings(10));

pub fn with_memory_limits(memory_limits: MemoryLimits) -> Self

Create a new Rodeo with the specified memory limits. The interner will be able to hold max_memory_usage bytes of interned strings until it will start returning None from try_get_or_intern or panicking from get_or_intern.

Note: If the capacity of the interner is greater than the memory limit, then that will be the effective maximum for allocated memory

See MemoryLimits for more information

Example

use lasso::{Rodeo, MemoryLimits, Spur};

let rodeo: Rodeo<Spur> = Rodeo::with_memory_limits(MemoryLimits::for_memory_usage(4096));

pub fn with_capacity_and_memory_limits(
    capacity: Capacity,
    memory_limits: MemoryLimits
) -> Self

Create a new Rodeo with the specified capacity and memory limits. The interner will be able to hold max_memory_usage bytes of interned strings until it will start returning None from try_get_or_intern or panicking from get_or_intern.

Note: If the capacity of the interner is greater than the memory limit, then that will be the effective maximum for allocated memory

See Capacity MemoryLimits for more information

Example

use lasso::{Rodeo, MemoryLimits, Spur};

let rodeo: Rodeo<Spur> = Rodeo::with_memory_limits(MemoryLimits::for_memory_usage(4096));

impl<K, S> Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

pub fn with_hasher(hash_builder: S) -> Self

Creates an empty Rodeo which will use the given hasher for its internal hashmap

Example

use lasso::{Spur, Rodeo};
use std::collections::hash_map::RandomState;

let rodeo: Rodeo<Spur, RandomState> = Rodeo::with_hasher(RandomState::new());

pub fn with_capacity_and_hasher(capacity: Capacity, hash_builder: S) -> Self

Creates a new Rodeo with the specified capacity that will use the given hasher for its internal hashmap

See Capacity for more information

Example

use lasso::{Spur, Capacity, Rodeo};
use std::collections::hash_map::RandomState;

let rodeo: Rodeo<Spur, RandomState> = Rodeo::with_capacity_and_hasher(Capacity::for_strings(10), RandomState::new());

pub fn with_capacity_memory_limits_and_hasher(
    capacity: Capacity,
    memory_limits: MemoryLimits,
    hash_builder: S
) -> Self

Creates a new Rodeo with the specified capacity and memory limits that will use the given hasher for its internal hashmap

See Capacity and MemoryLimits for more information

Example

use lasso::{Spur, Capacity, MemoryLimits, Rodeo};
use std::collections::hash_map::RandomState;

let rodeo: Rodeo<Spur, RandomState> = Rodeo::with_capacity_memory_limits_and_hasher(
    Capacity::for_strings(10),
    MemoryLimits::for_memory_usage(4096),
    RandomState::new(),
);

pub fn get_or_intern<T>(&mut self, val: T) -> Kwhere
    T: AsRef<str>,

Get the key for a string, interning it if it does not yet exist

Panics

Panics if the key’s try_from_usize function fails. With the default keys, this means that you’ve interned more strings than it can handle. (For Spur this means that u32::MAX - 1 unique strings were interned)

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

// Interned the string
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_get_or_intern<T>(&mut self, val: T) -> LassoResult<K>where
    T: AsRef<str>,

Get the key for a string, interning it if it does not yet exist

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

// Interned the string
let key = rodeo.try_get_or_intern("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.try_get_or_intern("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn get_or_intern_static(&mut self, string: &'static str) -> K

Get the key for a static string, interning it if it does not yet exist

This will not reallocate or copy the given string

Panics

Panics if the key’s try_from_usize function fails. With the default keys, this means that you’ve interned more strings than it can handle. (For Spur this means that u32::MAX - 1 unique strings were interned)

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

// Interned the string
let key = rodeo.get_or_intern_static("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.get_or_intern_static("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_get_or_intern_static(
    &mut self,
    string: &'static str
) -> LassoResult<K>

Get the key for a static string, interning it if it does not yet exist

This will not reallocate or copy the given string

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

// Interned the string
let key = rodeo.try_get_or_intern_static("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.try_get_or_intern_static("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn get<T>(&self, val: T) -> Option<K>where
    T: AsRef<str>,

Get the key value of a string, returning None if it doesn’t exist

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!(Some(key), rodeo.get("Strings of things with wings and dings"));

assert_eq!(None, rodeo.get("This string isn't interned"));

pub fn contains<T>(&self, val: T) -> boolwhere
    T: AsRef<str>,

Returns true if the given string has been interned

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert!(rodeo.contains("Strings of things with wings and dings"));

assert!(!rodeo.contains("This string isn't interned"));

impl<K, S> Rodeo<K, S>where
    K: Key,

pub fn contains_key(&self, key: &K) -> bool

Returns true if the given key exists in the current interner

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert!(rodeo.contains_key(&key));

assert!(!rodeo.contains_key(&key_that_doesnt_exist));

pub fn resolve<'a>(&'a self, key: &K) -> &'a str

Resolves a string by its key. Only keys made by the current Rodeo may be used

Panics

Panics if the key is out of bounds

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_resolve<'a>(&'a self, key: &K) -> Option<&'a str>

Resolves a string by its key, returning None if it’s out of bounds. Only keys made by the current Rodeo may be used

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!(Some("Strings of things with wings and dings"), rodeo.try_resolve(&key));

pub unsafe fn resolve_unchecked<'a>(&'a self, key: &K) -> &'a str

Resolves a string by its key, without bounds checks

Safety

The key must be valid for the current interner

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
unsafe {
    assert_eq!("Strings of things with wings and dings", rodeo.resolve_unchecked(&key));
}

impl<K, S> Rodeo<K, S>

pub fn len(&self) -> usize

Gets the number of interned strings

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();
rodeo.get_or_intern("Documentation often has little hidden bits in it");

assert_eq!(rodeo.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if there are no currently interned strings

Example

use lasso::Rodeo;

let rodeo = Rodeo::default();
assert!(rodeo.is_empty());

pub fn capacity(&self) -> usize

Returns the number of strings that can be interned without a reallocation

Example

use lasso::{Spur, Capacity, Rodeo};

let rodeo: Rodeo<Spur> = Rodeo::with_capacity(Capacity::for_strings(10));
assert_eq!(rodeo.capacity(), 10);

pub fn iter(&self) -> Iter<'_, K>

Returns an iterator over the interned strings and their key values

pub fn strings(&self) -> Strings<'_, K>

Returns an iterator over the interned strings

pub fn set_memory_limits(&mut self, memory_limits: MemoryLimits)

Set the Rodeo’s maximum memory usage while in-flight

Note that setting the maximum memory usage to below the currently allocated memory will do nothing

pub fn current_memory_usage(&self) -> usize

Get the Rodeo’s currently allocated memory

pub fn max_memory_usage(&self) -> usize

Get the Rodeo’s current maximum of allocated memory

impl<K, S> Rodeo<K, S>

pub fn into_reader(self) -> RodeoReader<K, S>

Consumes the current Rodeo, returning a RodeoReader to allow contention-free access of the interner from multiple threads

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();
let key = rodeo.get_or_intern("Appear weak when you are strong, and strong when you are weak.");

let read_only_rodeo = rodeo.into_reader();
assert_eq!(
    "Appear weak when you are strong, and strong when you are weak.",
    read_only_rodeo.resolve(&key),
);

pub fn into_resolver(self) -> RodeoResolver<K>

Consumes the current Rodeo, returning a RodeoResolver to allow contention-free access of the interner from multiple threads with the lowest possible memory consumption

Example

use lasso::Rodeo;

let mut rodeo = Rodeo::default();
let key = rodeo.get_or_intern("Appear weak when you are strong, and strong when you are weak.");

let resolver_rodeo = rodeo.into_resolver();
assert_eq!(
    "Appear weak when you are strong, and strong when you are weak.",
    resolver_rodeo.resolve(&key),
);

Trait Implementations

impl<K: Debug, S: Debug> Debug for Rodeo<K, S>

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

Formats the value using the given formatter.

impl Default for Rodeo<Spur, RandomState>

Creates a Rodeo using Spur as its key and RandomState as its hasher

fn default() -> Self

Returns the “default value” for a type.

impl<K, S, T> Extend<T> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,
    T: AsRef<str>,

fn extend<I>(&mut self, iter: I)where
    I: IntoIterator<Item = T>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Str, K, S> FromIterator<Str> for Rodeo<K, S>where
    Str: AsRef<str>,
    K: Key,
    S: BuildHasher + Default,

fn from_iter<T>(iter: T) -> Selfwhere
    T: IntoIterator<Item = Str>,

Creates a value from an iterator.

impl<K, S> Index<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

type Output = str

The returned type after indexing.

fn index(&self, idx: K) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<K, S> Interner<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

fn get_or_intern(&mut self, val: &str) -> K

Get the key for a string, interning it if it does not yet exist

fn try_get_or_intern(&mut self, val: &str) -> LassoResult<K>

Get the key for a string, interning it if it does not yet exist

fn get_or_intern_static(&mut self, val: &'static str) -> K

Get the key for a static string, interning it if it does not yet exist

fn try_get_or_intern_static(&mut self, val: &'static str) -> LassoResult<K>

Get the key for a static string, interning it if it does not yet exist

impl<'a, K: Key, S> IntoIterator for &'a Rodeo<K, S>

type Item = (K, &'a str)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, S> IntoReader<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

type Reader = RodeoReader<K, S>

The type of Reader the interner will be converted into

fn into_reader(self) -> Self::Readerwhere
    Self: 'static,

Consumes the current Interner and converts it into a Reader to allow contention-free access of the interner from multiple threads

impl<K, S> IntoResolver<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

type Resolver = RodeoResolver<K>

The type of Resolver the reader will be converted into

fn into_resolver(self) -> Self::Resolverwhere
    Self: 'static,

Consumes the current Reader and makes it into a Resolver, allowing contention-free access from multiple threads with the lowest possible memory consumption

impl<K, S> PartialEq<Rodeo<K, S>> for Rodeo<K, S>

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> PartialEq<Rodeo<K, S>> for RodeoReader<K, S>

fn eq(&self, other: &Rodeo<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> PartialEq<Rodeo<K, S>> for RodeoResolver<K>

fn eq(&self, other: &Rodeo<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> PartialEq<Rodeo<K, S>> for ThreadedRodeo<K, S>where
    K: Eq + Hash + Key,
    S: Clone + BuildHasher,

fn eq(&self, other: &Rodeo<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> PartialEq<RodeoReader<K, S>> for Rodeo<K, S>

fn eq(&self, other: &RodeoReader<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> PartialEq<RodeoResolver<K>> for Rodeo<K, S>

fn eq(&self, other: &RodeoResolver<K>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, S> Reader<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

fn get(&self, val: &str) -> Option<K>

Get a key for the given string value if it exists

fn contains(&self, val: &str) -> bool

Returns true if the current interner contains the given string

impl<K, S> Resolver<K> for Rodeo<K, S>where
    K: Key,

fn resolve<'a>(&'a self, key: &K) -> &'a str

Resolves the given key into a string

fn try_resolve<'a>(&'a self, key: &K) -> Option<&'a str>

Attempts to resolve the given key into a string, returning None if it cannot be found

unsafe fn resolve_unchecked<'a>(&'a self, key: &K) -> &'a str

Resolves a string by its key without preforming bounds checks

fn contains_key(&self, key: &K) -> bool

Returns true if the current interner contains the given key

fn len(&self) -> usize

Gets the number of currently interned strings

fn is_empty(&self) -> bool

Returns true if there are no currently interned strings

impl<K, S> Eq for Rodeo<K, S>

impl<K, S> IntoReaderAndResolver<K> for Rodeo<K, S>where
    K: Key,
    S: BuildHasher,

impl<K: Send, S: Send> Send for Rodeo<K, S>