Struct lasso::Rodeo

pub struct Rodeo<K: Key = Spur, S: BuildHasher + Clone = 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) internment and resolution.

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

Implementations

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

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: usize) -> Self

Create a new Rodeo with the specified capacity. The interner will be able to hold capacity strings without reallocating. If capacity is 0, the interner will not allocate.

Example

use lasso::{Rodeo, Spur};

let rodeo: Rodeo<Spur> = Rodeo::with_capacity(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: usize, hash_builder: S) -> Self

Creates a new Rodeo with the specified capacity that 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_capacity_and_hasher(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

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.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 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, Rodeo};

let rodeo: Rodeo<Spur> = Rodeo::with_capacity(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 + Key, S: Debug + BuildHasher + Clone> 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> Drop for Rodeo<K, S> where
    K: Key,
    S: BuildHasher + Clone, 

Deallocate the leaked strings interned by Rodeo

fn drop(&mut self)

Executes the destructor for this type.