intern_all/
lib.rs

1//! A type-agnostic interner
2//!
3//! Can be used to deduplicate various structures for fast equality comparisons.
4//! The design favours flexibility over efficiency, ideally you can throw
5//! any type into [i] and it'll just work.
6//!
7//! ```
8//! use std::env;
9//! use std::path::PathBuf;
10//!
11//! use intern_all::{i, Tok};
12//!
13//! // Intern a value
14//! let a: Tok<String> = i("foo");
15//! // Intern a path
16//! let b: Tok<PathBuf> = i(&env::current_dir().unwrap());
17//! ```
18//!
19//! Some convenience methods are also provided to make working with lists
20//! easier.
21//!
22//! ```
23//! use intern_all::{i, ibv, iv, Tok};
24//!
25//! // Intern a list as a slice of tokens
26//! let v1: Tok<Vec<Tok<String>>> = i(&[i("bar"), i("quz"), i("quux")][..]);
27//! // Intern a list of internable values
28//! let v2: Tok<Vec<Tok<String>>> = iv(["bar".to_string(), "quz".to_string(), "quux".to_string()]);
29//! // Intern a list of the borrowed form of internable values
30//! let v3: Tok<Vec<Tok<String>>> = ibv(["bar", "quz", "quux"]);
31//! assert!(v1 == v2 && v2 == v3)
32//! ```
33//!
34//! The interner uses weak references but the unreferenced values still take up
35//! space in the token table. To avoid a memory leak, you can periodically
36//! sremove entries referring to unreferenced values from the interner with
37//! [sweep] or [sweep_t].
38//!
39//! ```
40//! use intern_all::{sweep, sweep_t};
41//!
42//! // use this for general housekeeping
43//! sweep();
44//! // use this if a lot of temporary values of a particular interned type
45//! // had been dropped recently
46//! sweep_t::<String>();
47//! ```
48//!
49//! The functions exposed by this crate have short and not very descriptive
50//! names, which may seem like a red flag. In a typical use case, these
51//! functions would appear everywhere in the codebase, so this is not a concern.
52mod global;
53#[warn(unsafe_code)]
54mod interner;
55mod token;
56mod typed_interner;
57
58pub use global::{ev, i, ibv, iv, sweep, sweep_t};
59pub use token::{Internable, Tok};
60
61pub mod instance {
62  //! The interner uses weak references and can be cleared with [sweep], but if
63  //! you want to avoid using a global singleton, you can construct an instance
64  //! too. Comparing tokens from different interners causes a panic.
65  //!
66  //! ```
67  //! use intern_all::instance::Interner;
68  //!
69  //! // But you can also create an instance which has methods corresponding to
70  //! // all the above functions:
71  //! let int = Interner::new();
72  //! let k = int.i("foobar");
73  //! ```
74
75  pub use super::interner::Interner;
76  pub use super::typed_interner::TypedInterner;
77}
intern_all/lib.rs

intern_all/
lib.rs
