internment/lib.rs
1#![deny(missing_docs)]
2// Copyright 2018,2020 David Roundy
3//
4// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
5// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
6// http://opensource.org/licenses/MIT>, at your option. This file may not be
7// copied, modified, or distributed except according to those terms.
8
9//! A very easy to use library for
10//! [interning](https://en.wikipedia.org/wiki/String_interning)
11//! strings or other data in rust. Interned data is very efficient to
12//! either hash or compare for equality (just a pointer comparison).
13//! Data is also automatically de-duplicated.
14//!
15//! You have three options with the internment crate:
16//!
17//! 1. `Intern`, which will never free your data. This means that an
18//! `Intern` is `Copy`, so you can make as many copies of the pointer
19//! as you may care to at no cost.
20//!
21//! 2. `ArcIntern`, which reference-counts your data and frees it when
22//! there are no more references. `ArcIntern` will keep memory use
23//! down, but uses an atomic increment/decrement whenever a clone of
24//! your pointer is made, or a pointer is dropped.
25//!
26//! 3. `ArenaIntern`, which stores its data in an `Arena`, with the data being freed
27//! when the arena itself is freed. Requires feature `arena`.
28//!
29//! In each case, accessing your data is a single pointer dereference, and the size
30//! of any internment data structure (`Intern` or `ArcIntern` or `ArenaIntern`) is a
31//! single pointer. In each case, you have a guarantee that a single data value (as
32//! defined by `Eq` and `Hash`) will correspond to a single pointer value. This
33//! means that we can use pointer comparison (and a pointer hash) in place of value
34//! comparisons, which is very fast.
35//!
36//! # Example
37//! ```rust
38//! use internment::Intern;
39//! let x = Intern::new("hello");
40//! let y = Intern::new("world");
41//! assert_ne!(x, y);
42//! println!("The conventional greeting is '{} {}'", x, y);
43//! ```
44
45// Enable the `doc_cfg` feature when the `docsrs` configuration attribute is
46// defined
47#![cfg_attr(docsrs, feature(doc_cfg))]
48
49mod boxedset;
50
51#[cfg(feature = "_experimental-new-intern")]
52mod typearena;
53
54#[doc(hidden)]
55#[cfg(feature = "_experimental-new-intern")]
56pub use typearena::Intern as NewIntern;
57
58#[cfg(feature = "intern")]
59mod container;
60
61#[cfg(feature = "intern")]
62mod intern;
63#[cfg(feature = "intern")]
64pub use intern::Intern;
65
66#[cfg(feature = "arena")]
67mod arena;
68
69#[cfg(feature = "arena")]
70pub use arena::Arena;
71
72#[cfg(feature = "arena")]
73pub use arena::ArenaIntern;
74
75#[cfg(feature = "arc")]
76mod arc;
77#[cfg(feature = "arc")]
78mod arc_dst;
79
80#[cfg(feature = "arc")]
81pub use arc::ArcIntern;
82
83#[cfg(all(feature = "arc", feature = "deepsize"))]
84pub use arc::deep_size_of_arc_interned;
85
86#[cfg(all(feature = "intern", feature = "deepsize"))]
87pub use intern::deep_size_of_interned;