Module astral::string

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 string_subsystem = string::Subsystem::new(64, &logger);

You can create a StringId with the Subsystem:

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:

use astral::string::Text;

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

A Text can be converted into &str:

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 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]);

Structs

Name	A UTF-8 encoded, immutable string optimized for numeric suffixes.
String	A UTF-8 encoded, growable string.
StringId	An opaque struct for fast comparison between strings.
Subsystem	Manages optimized string allocation.
Text	A UTF-8 encoded, immutable string.
Utf8Error	Errors which can occur when attempting to interpret a sequence of u8 as a string.
Utf16Error	A possible error value when converting a Name or Text from an UTF-16 byte slice.

Constants

MAX_STRING_LENGTH

The maximum length of one string like Text or Name.