[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");