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

Constructs a new, empty SymbolTable with default capacity.

This function will always allocate. To construct a symbol table without allocating, call SymbolTable::with_capacity(0).

Examples
let table = SymbolTable::new();
assert_eq!(0, table.len());
assert!(table.capacity() >= 4096);

Constructs a new, empty SymbolTable with the specified capacity.

The symbol table will be able to hold at least capacity byte strings without reallocating. If capacity is 0, the symbol table will not allocate.

Examples
let table = SymbolTable::with_capacity(10);
assert_eq!(0, table.len());
assert!(table.capacity() >= 10);

Constructs a new, empty SymbolTable with default capacity and the given hash builder.

Examples
let hash_builder = RandomState::new();
let table = SymbolTable::with_hasher(hash_builder);
assert_eq!(0, table.len());
assert!(table.capacity() >= 4096);

Constructs a new, empty SymbolTable with the specified capacity and the given hash builder.

Examples
let hash_builder = RandomState::new();
let table = SymbolTable::with_capacity_and_hasher(10, hash_builder);
assert_eq!(0, table.len());
assert!(table.capacity() >= 10);

Returns the number of byte strings the table can hold without reallocating.

Examples
let table = SymbolTable::with_capacity(10);
assert!(table.capacity() >= 10);

Returns the number of interned byte strings in the table.

Examples
let mut table = SymbolTable::new();
assert_eq!(0, table.len());

table.intern(b"abc".to_vec())?;
// only uniquely interned byte strings grow the symbol table.
table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
assert_eq!(2, table.len());

Returns true if the symbol table contains no interned byte strings.

Examples
let mut table = SymbolTable::new();
assert!(table.is_empty());

table.intern(b"abc".to_vec())?;
assert!(!table.is_empty());

Returns true if the symbol table contains the given symbol.

Examples
let mut table = SymbolTable::new();
assert!(!table.contains(Symbol::new(0)));

let sym = table.intern(b"abc".to_vec())?;
assert!(table.contains(Symbol::new(0)));
assert!(table.contains(sym));

Returns a reference to the byte string associated with the given symbol.

If the given symbol does not exist in the underlying symbol table, None is returned.

The lifetime of the returned reference is bound to the symbol table.

Examples
let mut table = SymbolTable::new();
assert!(table.get(Symbol::new(0)).is_none());

let sym = table.intern(b"abc".to_vec())?;
assert_eq!(Some(&b"abc"[..]), table.get(Symbol::new(0)));
assert_eq!(Some(&b"abc"[..]), table.get(sym));

Returns an iterator over all Symbols and byte strings in the SymbolTable.

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

let iter = table.iter();
let mut map = HashMap::new();
map.insert(Symbol::new(0), &b"abc"[..]);
map.insert(Symbol::new(1), &b"xyz"[..]);
map.insert(Symbol::new(2), &b"123"[..]);
map.insert(Symbol::new(3), &b"789"[..]);
assert_eq!(map, iter.collect::<HashMap<_, _>>());
let mut table = SymbolTable::new();
table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
table.intern(b"123".to_vec())?;
table.intern(b"789".to_vec())?;

let iter = table.iter();
assert_eq!(table.len(), iter.count());

Returns an iterator over all Symbols in the SymbolTable.

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

let mut all_symbols = table.all_symbols();
assert_eq!(Some(Symbol::new(0)), all_symbols.next());
assert_eq!(Some(Symbol::new(1)), all_symbols.nth_back(2));
assert_eq!(None, all_symbols.next());
let mut table = SymbolTable::new();
table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
table.intern(b"123".to_vec())?;
table.intern(b"789".to_vec())?;

let all_symbols = table.all_symbols();
assert_eq!(table.len(), all_symbols.count());

Returns an iterator over all byte strings in the SymbolTable.

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

let mut bytestrings = table.bytestrings();
assert_eq!(Some(&b"abc"[..]), bytestrings.next());
assert_eq!(Some(&b"xyz"[..]), bytestrings.nth_back(2));
assert_eq!(None, bytestrings.next());
let mut table = SymbolTable::new();
table.intern(b"abc".to_vec())?;
table.intern(b"xyz".to_vec())?;
table.intern(b"123".to_vec())?;
table.intern(b"789".to_vec())?;

let bytestrings = table.bytestrings();
assert_eq!(table.len(), bytestrings.count());

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

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

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

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

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

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

Trait Implementations

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Executes the destructor for this type. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.