ParaCord is a lightweight, thread-safe, memory efficient string interner.

When calling ParaCord::get_or_intern, a [Key] is returned. This [Key] is guaranteed to be unique if the input string is unique, and is guaranteed to be the same if the input string is the same. [Key] is 32bits, and has a niche value which allows Option<Key> to also be 32bits.

The 32bit key imposes a limitation that allocating 2^32 strings will panic. There's an additional self-imposed limitation that no string can be longer than 2^32 bytes long.

If you don't want to intern the string, but check for it's existence, you can use ParaCord::get, which returns None if not present.

[Key]s can be exchanged back into strings using ParaCord::resolve. It's important to keep in mind that this might panic or return nonsense results if given a key returned by some other ParaCord instance.

This string interner is not garbage collected, so strings that are allocated in the interner are not released until the ParaCord instance is dropped.

Examples

With a self-managed ParaCord instance.

use paracord::ParaCord;

let paracord = ParaCord::default();

let foo = paracord.get_or_intern("foo");
let bar = paracord.get_or_intern("bar");

assert_ne!(foo, bar);

// returns the same key, no insert
let foo2 = paracord.get_or_intern("foo");
assert_eq!(foo, foo2);

// returns the same key, guaranteed no insert
let foo3 = paracord.get("foo").unwrap();
assert_eq!(foo, foo3);

// can be exchanged for the string
assert_eq!(paracord.resolve(foo), "foo");
assert_eq!(paracord.resolve(bar), "bar");

With a globally managed instance, with typed keys

paracord::custom_key!(pub struct NameKey);

let foo = NameKey::new("foo");
let bar = NameKey::new("bar");

assert_ne!(foo, bar);

// returns the same key, no insert
let foo2 = NameKey::new("foo");
assert_eq!(foo, foo2);

// returns the same key, guaranteed no insert
let foo3 = NameKey::try_new_existing("foo").unwrap();
assert_eq!(foo, foo3);

// can be exchanged for the string
assert_eq!(foo.as_str(), "foo");
assert_eq!(bar.as_str(), "bar");