Struct intaglio::path::SymbolTable

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

This is supported on crate feature path only.

Path string interner.

This symbol table is implemented by storing PathBufs with a fast path for &Path that are already 'static.

See module documentation for more.

Usage

let mut table = SymbolTable::new();
let sym = table.intern(Path::new("abc"))?;
assert_eq!(sym, table.intern(PathBuf::from("abc"))?);
assert!(table.contains(sym));
assert!(table.is_interned(Path::new("abc")));

Implementations

impl SymbolTable<RandomState>

pub fn new() -> Self

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

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty SymbolTable with the specified capacity.

The symbol table will be able to hold at least capacity path 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);

impl<S> SymbolTable<S>

pub fn with_hasher(hash_builder: S) -> Self

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

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

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

pub fn capacity(&self) -> usize

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

Examples

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

pub fn len(&self) -> usize

Returns the number of interned path strings in the table.

Examples

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

table.intern(PathBuf::from("abc"))?;
// only uniquely interned path strings grow the symbol table.
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
assert_eq!(2, table.len());

pub fn is_empty(&self) -> bool

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

Examples

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

table.intern(PathBuf::from("abc"))?;
assert!(!table.is_empty());

pub fn contains(&self, id: Symbol) -> bool

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(PathBuf::from("abc"))?;
assert!(table.contains(Symbol::new(0)));
assert!(table.contains(sym));

pub fn get(&self, id: Symbol) -> Option<&Path>

Returns a reference to the path 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(PathBuf::from("abc"))?;
assert_eq!(Some(Path::new("abc")), table.get(Symbol::new(0)));
assert_eq!(Some(Path::new("abc")), table.get(sym));

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

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

Examples

let mut table = SymbolTable::new();
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

let iter = table.iter();
let mut map = HashMap::new();
map.insert(Symbol::new(0), Path::new("abc"));
map.insert(Symbol::new(1), Path::new("xyz"));
map.insert(Symbol::new(2), Path::new("123"));
map.insert(Symbol::new(3), Path::new("789"));
assert_eq!(map, iter.collect::<HashMap<_, _>>());

let mut table = SymbolTable::new();
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

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

pub fn all_symbols(&self) -> AllSymbols<'_>

Returns an iterator over all Symbols in the SymbolTable.

Examples

let mut table = SymbolTable::new();
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

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(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

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

pub fn paths(&self) -> Paths<'_>

Returns an iterator over all path strings in the SymbolTable.

Examples

let mut table = SymbolTable::new();
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

let mut paths = table.paths();
assert_eq!(Some(Path::new("abc")), paths.next());
assert_eq!(Some(Path::new("xyz")), paths.nth_back(2));
assert_eq!(None, paths.next());

let mut table = SymbolTable::new();
table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(PathBuf::from("123"))?;
table.intern(PathBuf::from("789"))?;

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

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

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

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

The returned Symbol allows retrieving of the underlying Path. Equal path 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 C strings, the Symbol counter would overflow and a SymbolOverflowError is returned.

Examples

let mut table = SymbolTable::new();
let sym = table.intern(PathBuf::from("abc"))?;
table.intern(PathBuf::from("xyz"))?;
table.intern(Path::new("123"))?;
table.intern(Path::new("789"))?;

assert_eq!(4, table.len());
assert_eq!(Some(Path::new("abc")), table.get(sym));

pub fn check_interned(&self, contents: &Path) -> 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(Path::new("abc")));
assert_eq!(None, table.check_interned(Path::new("abc")));

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

pub fn is_interned(&self, contents: &Path) -> bool

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

This method does not modify the symbol table.

Examples

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

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

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(PathBuf::from("abc"))?;
table.reserve(10);
assert!(table.capacity() >= 11);

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(PathBuf::from("abc"));
table.intern(PathBuf::from("xyz"));
table.intern(PathBuf::from("123"));
table.shrink_to_fit();
assert!(table.capacity() >= 3);

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(PathBuf::from("abc"));
table.intern(PathBuf::from("xyz"));
table.intern(PathBuf::from("123"));
table.shrink_to(5);
assert!(table.capacity() >= 5);

Trait Implementations

impl<S: Debug> Debug for SymbolTable<S>

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

Formats the value using the given formatter.

impl<S: Default> Default for SymbolTable<S>

fn default() -> SymbolTable<S>

Returns the “default value” for a type.

impl<S> Drop for SymbolTable<S>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> IntoIterator for &'a SymbolTable

type Item = (Symbol, &'a Path)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.