Structures for holding strings.

This module contains string::Subsystem, which manages StringIds. Since StringId is a dumb POD, two wrapper are provided: Text and Name. While both can hold strings, Name is optimized for strings with a numeric suffix. Texts implement Deref<Target=str>, which is not the case for Name, because of the optimization.

Examples

The string Subsystem can be created from a parent Logger:

use astral::string;

   # let logger = slog::Logger::root(slog::Discard, slog::o!());
let string_subsystem = string::Subsystem::new(64, &logger);

You can create a StringId with the Subsystem:

   # let logger = slog::Logger::root(slog::Discard, slog::o!());
   # let string_subsystem = astral::string::Subsystem::new(64, &logger);
use astral::string::StringId;

let id1 = StringId::new("foo", &string_subsystem);
let id2 = StringId::new("bar", &string_subsystem);
let id3 = StringId::new("foo", &string_subsystem);

assert_ne!(id1, id2);
assert_eq!(id1, id3);

Text or Name can be created from a literal string:

   # let logger = slog::Logger::root(slog::Discard, slog::o!());
   # let string_subsystem = astral::string::Subsystem::new(64, &logger);
use astral::string::Text;

let text = Text::new("foo", &string_subsystem);
assert_eq!(text, "foo");

A Text can be converted into &str:

   # let logger = slog::Logger::root(slog::Discard, slog::o!());
   # let string_subsystem = astral::string::Subsystem::new(64, &logger);
let text = Text::new("foo", &string_subsystem);
let s: &str = text.as_str();

assert_eq!("foo", s)

If you have a slice of valid UTF-8 bytes, you can make a Text or a Name out of it.

   # let logger = slog::Logger::root(slog::Discard, slog::o!());
   # let string_subsystem = astral::string::Subsystem::new(64, &logger);
let sparkle_heart = &[240, 159, 146, 150];

// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = Text::from_utf8(sparkle_heart, &string_subsystem).unwrap();

assert_eq!("💖", sparkle_heart);

let bytes = sparkle_heart.as_bytes();

assert_eq!(bytes, [240, 159, 146, 150]);