Crate internship [−] [src]

Interned string and more for rust.

What is interning?

Interning is a method to store exactly one copy of immutable data.

Imagine your program holds lots of string values, mostly same value in it, and does not mutate them at all. If you use String to store them, lots of memories are wasted just for storing identical texts.

Interning efficiently eliminate this problem by managing global pool of cache, in the case above the type of the pool can be HashSet<Rc<str>>. When you need a new owned string, first you should lookup global pool for it. If desired string is found then use it. If not, just create a new one and put them also to the pool.

What does this library provide?

The core of the API is Intern<T> where T is str-like types in std. You can think of it as Rc<T>, but guaranteed uniqueness over value within thread.

Example

  use internship::{Intern, intern};

  let foo = intern("foo"); // type is Intern<str>
  let foo2 = intern("foo"); // reuse foo's buffer

  let mut map = HashMap::new();
  map.insert(intern("key"), 42);
  assert_eq!(map.get(&intern("key")), Some(&42));

How is Intern<T> better then Rc<T>?

Intern<T> has some advantages over Rc<T>

  1. Space efficient

    As only single allocation is happen per unique value, you can even span intern() without worrying about memory bloat.

  2. Cheap equality check

    As only one copy of unique value can be exist, comparing two Intern<T> can be done with just single pointer comparison instead comparing every bytes of strings.

  3. Cheap hash calculation

    Again, as only one copy of unique value can be exist, its allocated memory address can represent underlying value so calculating hash over its pointer makes perfect sense to hash Intern<T>. Now you can perform blazingly-fast hashmap lookup with arbitrary string key!

What types can be interned?

Currently these types are supported.

  • str
  • [u8]
  • CStr
  • OsStr
  • Path

You can find interned type of them as re-export, like InternStr.

For now, only str and [u8] are supported by default. This limitation should be removed after docs.rs update their rustc from v1.22.0 I think it's more important to show proper docs on docs.rs than make this feature works out of the box. If you want to use others at now, turn on cargo feature "shared_from_slice2".

Structs

Intern

Interned data

Traits

AllowIntern

Functions

intern

Create new Intern<T> from given value if matching cache not found.

Type Definitions

InternBytes
InternStr