Auto merge of #204 - derekdreery:example_simple, r=jdm

Add a simple example of library use.

Specifically for internment without any static values.

I thought it would be useful to show a simple use of this library.

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/string-cache/204)
<!-- Reviewable:end -->

Author: bors-servo

Cargo.toml

@@ -37,6 +37,7 @@ string_cache_shared = {path = "./shared", version = "0.3"}
 
 [dev-dependencies]
 rand = "0.4"
+string_cache_codegen = { version = "0.4", path = "./string-cache-codegen" }
 
 [build-dependencies]
 string_cache_codegen = { version = "0.4", path = "./string-cache-codegen" }

examples/simple.rs

@@ -0,0 +1,26 @@
+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));
+    }
+}

src/lib.rs

@@ -7,6 +7,100 @@
 // 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.7"
+//!
+//! [dev-dependencies]
+//! string_cache_codegen = "0.4"
+//! ```
+//!
+//! In `build.rs`:
+//!
+//! ```
+//! 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));
+//! }
+//! # }
+//! ```
+//!
+
 #![crate_name = "string_cache"]
 #![crate_type = "rlib"]