Struct lasso::Rodeo

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

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));

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

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 get_or_intern<T>(&mut self, val: T) -> K where
    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) -> Option<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 and copy the given string but will instead just store it

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) -> Option<K>

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

This will not reallocate and copy the given string but will instead just store it

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 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));
}

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

impl<K, S> Rodeo<K, S> where
    K: Key + Default,
    S: BuildHasher + Clone, 

#[must_use]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),
);

#[must_use]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 for Rodeo<K, S>

fn fmt(&self, f: &mut Formatter) -> FmtResult

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: Send, S: Send> Send for Rodeo<K, S>