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