Struct SymbolTable

Source

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

Available on crate feature bytes only.

Expand description

Byte string interner.

This symbol table is implemented by storing byte strings with a fast path for &[u8] that are already 'static.

See module documentation for more.

§Usage

let mut table = SymbolTable::new();
let sym = table.intern(&b"abc"[..])?;
assert_eq!(sym, table.intern(b"abc".to_vec())?);
assert!(table.contains(sym));
assert!(table.is_interned(b"abc"));

Implementations§

Source §

impl<S> SymbolTable<S>
where S: BuildHasher,

Source

pub fn intern<T>(&mut self, contents: T) -> Result<Symbol, SymbolOverflowError>
where T: Into<Cow<'static, [u8]>>,

Intern a byte string for the lifetime of the symbol table.

The returned Symbol allows retrieving of the underlying bytes. Equal byte strings will be inserted into the symbol table exactly once.

This function only allocates if the underlying symbol table has no remaining capacity.

§Errors

If the symbol table would grow larger than u32::MAX interned byte strings, the Symbol counter would overflow and a SymbolOverflowError is returned.

§Examples

let mut table = SymbolTable::new();
let sym = table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
table.intern(&b"123"[..])?;
table.intern(&b"789"[..])?;

assert_eq!(4, table.len());
assert_eq!(Some(&b"abc"[..]), table.get(sym));

Source

pub fn check_interned(&self, contents: &[u8]) -> Option<Symbol>

Returns the Symbol identifier for contents if it has been interned before, None otherwise.

This method does not modify the symbol table.

§Examples

let mut table = SymbolTable::new();
assert!(!table.is_interned(b"abc"));
assert_eq!(None, table.check_interned(b"abc"));

table.intern(b"abc".to_vec())?;
assert!(table.is_interned(b"abc"));
assert_eq!(Some(Symbol::new(0)), table.check_interned(b"abc"));

Source

pub fn is_interned(&self, contents: &[u8]) -> bool

Returns true if the given byte string has been interned before.

This method does not modify the symbol table.

§Examples

let mut table = SymbolTable::new();
assert!(!table.is_interned(b"abc"));
assert_eq!(None, table.check_interned(b"abc"));

table.intern(b"abc".to_vec())?;
assert!(table.is_interned(b"abc"));
assert_eq!(Some(Symbol::new(0)), table.check_interned(b"abc"));

Source

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given SymbolTable. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

§Panics

Panics if the new capacity overflows usize.

§Examples

let mut table = SymbolTable::with_capacity(1);
table.intern(b"abc".to_vec())?;
table.reserve(10);
assert!(table.capacity() >= 11);

Source

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the symbol table as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the symbol table that there is space for a few more elements.

§Examples

let mut table = SymbolTable::with_capacity(10);
table.intern(b"abc".to_vec());
table.intern(b"xyz".to_vec());
table.intern(b"123".to_vec());
table.shrink_to_fit();
assert!(table.capacity() >= 3);

Source

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the symbol table with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

§Examples

let mut table = SymbolTable::with_capacity(10);
table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
table.intern(b"123".to_vec())?;
table.shrink_to(5);
assert!(table.capacity() >= 5);