Crate intern_all

source ·
Expand description

A type-agnostic interner

Can be used to deduplicate various structures for fast equality comparisons. The design favours flexibility over efficiency, ideally you can throw any type into [i] and it’ll just work.

use std::env;
use std::path::PathBuf;

use intern_all::{i, Tok};

// Intern a value
let a: Tok<String> = i("foo");
// Intern a path
let b: Tok<PathBuf> = i(&env::current_dir().unwrap());

Some convenience methods are also provided to make working with lists easier.

use intern_all::{i, ibv, iv, Tok};

// Intern a list as a slice of tokens
let v1: Tok<Vec<Tok<String>>> = i(&[i("bar"), i("quz"), i("quux")][..]);
// Intern a list of internable values
let v2: Tok<Vec<Tok<String>>> = iv(["bar".to_string(), "quz".to_string(), "quux".to_string()]);
// Intern a list of the borrowed form of internable values
let v3: Tok<Vec<Tok<String>>> = ibv(["bar", "quz", "quux"]);
assert!(v1 == v2 && v2 == v3)

The interner uses weak references but the unreferenced values still take up space in the token table. To avoid a memory leak, you can periodically sremove entries referring to unreferenced values from the interner with sweep or sweep_t.

use intern_all::{sweep, sweep_t};

// use this for general housekeeping
sweep();
// use this if a lot of temporary values of a particular interned type
// had been dropped recently
sweep_t::<String>();

The functions exposed by this crate have short and not very descriptive names, which may seem like a red flag. In a typical use case, these functions would appear everywhere in the codebase, so this is not a concern.

Modules§

  • The interner uses weak references and can be cleared with [sweep], but if you want to avoid using a global singleton, you can construct an instance too. Comparing tokens from different interners causes a panic.

Macros§

  • Create a thread-local token instance and copy it. This ensures that the interner will only be called the first time the expresion is executed, and subsequent calls will just copy the token. Accepts a single static expression (i.e. a literal).

Structs§

  • A shared instance. Equality comparison costs two pointer comparisons. Ordering is by pointer value.

Traits§

Functions§

  • Fully resolve a list of interned things. If the list is interned, use Tok
  • Intern something with the global interner. If Q is static, you should consider using the macro version of this function.
  • Intern a list of borrowed items in the global interner. See also iv
  • Intern a list and its elements in the global interner. See also ibv
  • Sweep the global interner. If you want to sweep a specific type, try sweep_t
  • Sweep values of a specific type from the global interner. Useful if you just constructed a large number of values of a specific type, otherwise use sweep