Crate intaglio

This crate provides a library for interning strings.

The primary API is a symbol table. Its API is similar to a bimap in that symbols can resolve an underlying string and a string slice can retrieve its associated symbol.

For more specific details on the API for interning strings into a symbol table, please see the documentation for the SymbolTable type.

Examples

let mut table = SymbolTable::new();
let sym_id = table.intern("abc")?;
assert_eq!(sym_id, table.intern("abc".to_string())?);
assert!(table.contains(sym_id));
assert!(table.is_interned("abc"));

String interning

Intaglio SymbolTables store at most one copy of a string. All requests to intern a string that is already present in the table, regardless of whether the string is an owned String or borrowed &'static str, will return the same immutable Symbol.

Symbols are u32 indexes into a SymbolTable that are cheap to compare, copy, store, and send.

Allocations

SymbolTable exposes several constructors for tuning the initial allocated size of the table. It also exposes several APIs for tuning the table’s memory usage such as SymbolTable::reserve and SymbolTable::shrink_to_fit.

SymbolTable::intern does not clone or copy interned strings. It takes ownership of the string contents with no additional allocations.

Types of Interners

Intaglio includes multiple symbol tables which differ in the types of strings they allow you to intern.

• SymbolTable interns UTF-8 strings: String and &str.
• bytes::SymbolTable interns binary strings: Vec<u8> and &[u8].

Crate features

All features are enabled by default.

• bytes - Enables an additional symbol table implementation for interning byte strings (Vec<u8> and &'static [u8]).
• cstr - Enables an additional symbol table implementation for interning C strings (CString and &'static CStr).
• osstr - Enables an additional symbol table implementation for interning platform strings (OsString and &'static OsStr).
• path - Enables an additional symbol table implementation for interning path strings (PathBuf and &'static Path).

Modules

• bytesbytes
  Intern arbitrary bytes.

Structs

• AllSymbols
  An iterator over all Symbols in a SymbolTable.
• Iter
  An iterator over all symbols and interned strings in a SymbolTable.
• Strings
  An iterator over all interned strings in a SymbolTable.
• Symbol
  Identifier bound to an interned string.
• SymbolOverflowError
  Error returned when a SymbolTable or symbol identifier overflows.
• SymbolTable
  UTF-8 string interner.

Constants

• DEFAULT_SYMBOL_TABLE_CAPACITY
  Default capacity for a new SymbolTable created with SymbolTable::new.