string_cache/
lib.rs

1// Copyright 2014 The Servo Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10//!
11//! A library for interning things that are `AsRef<str>`.
12//!
13//! Some strings may be interned at compile time using the `string-cache-codegen` crate, or the
14//! `EmptyStaticAtomSet` may be used that has no compile-time interned strings. An `Atom` is an
15//! interned string for a given set (either `EmptyStaticAtomSet` or a generated `StaticAtomSet`).
16//!
17//! Generated `Atom`s will have assocated macros to intern static strings at compile-time.
18//!
19//! # Examples
20//!
21//! Here are two examples, one with compile-time `Atom`s, and one without.
22//!
23//! ## With compile-time atoms
24//!
25//! In `Cargo.toml`:
26//! ```toml
27//! [dependencies]
28//! string_cache = "0.10"
29//!
30//! [dev-dependencies]
31//! string_cache_codegen = "0.7"
32//! ```
33//!
34//! In `build.rs`:
35//!
36//! ```ignore
37//! use std::env;
38//! use std::path::Path;
39//!
40//! fn main() {
41//!     string_cache_codegen::AtomType::new("foo::FooAtom", "foo_atom!")
42//!         .atoms(&["foo", "bar"])
43//!         .write_to_file(&Path::new(&env::var("OUT_DIR").unwrap()).join("foo_atom.rs"))
44//!         .unwrap()
45//! }
46//! ```
47//!
48//! In `lib.rs`:
49//!
50//! ```ignore
51//! mod foo {
52//!     include!(concat!(env!("OUT_DIR"), "/foo_atom.rs"));
53//! }
54//!
55//! fn use_the_atom(t: &str) {
56//!     match *t {
57//!         foo_atom!("foo") => println!("Found foo!"),
58//!         foo_atom!("bar") => println!("Found bar!"),
59//!         // foo_atom!("baz") => println!("Found baz!"), - would be a compile time error
60//!         _ => {
61//!             println!("String not interned");
62//!             // We can intern strings at runtime as well
63//!             foo::FooAtom::from(t)
64//!         }
65//!     }
66//! }
67//! ```
68//!
69//! ## No compile-time atoms
70//!
71//! ```
72//! use string_cache::DefaultAtom;
73//!
74//! # fn main() {
75//! let mut interned_stuff = Vec::new();
76//! let text = "here is a sentence of text that will be tokenised and
77//!             interned and some repeated tokens is of text and";
78//! for word in text.split_whitespace() {
79//!     let seen_before = interned_stuff.iter()
80//!         // We can use impl PartialEq<T> where T is anything string-like
81//!         // to compare to interned strings to either other interned strings,
82//!         // or actual strings  Comparing two interned strings is very fast
83//!         // (normally a single cpu operation).
84//!         .filter(|interned_word| interned_word == &word)
85//!         .count();
86//!     if seen_before > 0 {
87//!         println!(r#"Seen the word "{}" {} times"#, word, seen_before);
88//!     } else {
89//!         println!(r#"Not seen the word "{}" before"#, word);
90//!     }
91//!     // We use the impl From<(Cow<'a, str>, or &'a str, or String)> for
92//!     // Atom<Static> to intern a new string.
93//!     interned_stuff.push(DefaultAtom::from(word));
94//! }
95//! # }
96//! ```
97//!
98
99#![cfg_attr(test, deny(warnings))]
100
101mod atom;
102mod dynamic_set;
103mod static_sets;
104mod trivial_impls;
105
106pub use atom::Atom;
107#[cfg(feature = "malloc_size_of")]
108pub use dynamic_set::malloc_size_of_dynamic_set;
109pub use static_sets::{EmptyStaticAtomSet, PhfStrSet, StaticAtomSet};
110
111/// Use this if you don’t care about static atoms.
112pub type DefaultAtom = Atom<EmptyStaticAtomSet>;
113
114const _: () = assert!(std::mem::size_of::<DefaultAtom>() == 8);
115const _: () = assert!(std::mem::size_of::<Option<DefaultAtom>>() == 8);
string_cache/lib.rs

string_cache/
lib.rs
