Struct Name

pub struct Name<'system, H = BuildHasherDefault<Murmur3>> { /* private fields */ }

A UTF-8 encoded, immutable string optimized for numeric suffixes.

Example

Name can be created from a literal string:

use astral::string::Name;

let name = Name::new("foo", &string_subsystem);
assert_eq!(name, "foo");

Representation

Name stores a StringId, a reference to a Subsystem, and an optional numeric suffix. When a new Name is created, it is first checked if the string already exists. If so, it gets the same index as the existing one. If not, a new entry is created.

The suffix is only used for reusing the same string multiple times when the string only differs at a numeric suffix. A suffix with leading zeros cannot be optimized!

Implementations

impl<'system, H> Name<'system, H>

where H: BuildHasher,

pub fn new<T>(string: T, system: &'system Subsystem<H>) -> Self

where T: AsRef<str>,

Creates a Text from the given string literal in the specified Subsystem.

Example

use astral::string::Name;

let name = Name::new("foo", &string_subsystem);
assert_eq!(name, name);

pub fn from_utf8( v: &[u8], system: &'system Subsystem<H>, ) -> Result<Self, Utf8Error>

Converts a slice of bytes to a Name.

Name requires that it is valid UTF-8. from_utf8 checks to ensure that the bytes are valid UTF-8, and then does the conversion.

If you are sure that the byte slice is valid UTF-8, and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function, from_utf8_unchecked, which has the same behavior but skips the check.

Errors

Returns Err if the slice is not UTF-8 with a description as to why the provided slice is not UTF-8.

See the docs for Utf8Error for more details on the kinds of errors that can be returned.

Examples

Basic usage:

use astral::string::Name;

// some bytes, in a vector
let sparkle_heart = &[240, 159, 146, 150];

// We know these bytes are valid, so just use `unwrap()`.
let sparkle_heart = Name::from_utf8(sparkle_heart, &string_subsystem).unwrap();

assert_eq!("💖", sparkle_heart);

Incorrect bytes:

use astral::string::Name;

// some invalid bytes, in a vector
let sparkle_heart = &[0, 159, 146, 150];

assert!(Name::from_utf8(sparkle_heart, &string_subsystem).is_err());

pub fn from_utf8_lossy(v: &[u8], system: &'system Subsystem<H>) -> Self

Converts a slice of bytes to a Name, including invalid characters.

Name requires that it is valid UTF-8. from_utf8 checks to ensure that the bytes are valid UTF-8. During this conversion, from_utf8_lossy will replace any invalid UTF-8 sequences with U+FFFD REPLACEMENT CHARACTER, which looks like this: �

If you are sure that the byte slice is valid UTF-8, and you don’t want to incur the overhead of the conversion, there is an unsafe version of this function, from_utf8_unchecked, which has the same behavior but skips the checks.

Examples

Basic usage:

use astral::string::Name;

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

let sparkle_heart = Name::from_utf8_lossy(&sparkle_heart, &string_subsystem);

assert_eq!("💖", sparkle_heart);

Incorrect bytes:

use astral::string::Name;

// some invalid bytes
let input = b"Hello \xF0\x90\x80World";
let output = Name::from_utf8_lossy(input, &string_subsystem);

assert_eq!("Hello �World", output);

pub unsafe fn from_utf8_unchecked( v: &[u8], system: &'system Subsystem<H>, ) -> Self

Converts a slice of bytes to a Name without checking that the string contains valid UTF-8.

See the safe version, from_utf8, for more details.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of the library assumes that Names are valid UTF-8.

Example

use astral::string::Name;

// some bytes, in a vector
let sparkle_heart = &[240, 159, 146, 150];

let sparkle_heart = unsafe {
    Name::from_utf8_unchecked(sparkle_heart, &string_subsystem)
};

assert_eq!("💖", sparkle_heart);

pub fn from_utf16( v: &[u16], system: &'system Subsystem<H>, ) -> Result<Self, Utf16Error>

Decode a UTF-16 encoded slice into a Name, returning Err if the slice contains any invalid data.

Example

use astral::string::Name;

// 𝄞music
let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
          0x0073, 0x0069, 0x0063];
assert_eq!(Name::new("𝄞music", &string_subsystem),
           Name::from_utf16(v, &string_subsystem).unwrap());

// 𝄞mu<invalid>ic
let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
          0xD800, 0x0069, 0x0063];
assert!(Name::from_utf16(v, &string_subsystem).is_err());

pub fn from_utf16_lossy(v: &[u16], system: &'system Subsystem<H>) -> Self

Decode a UTF-16 encoded slice into a Name, replacing invalid data with the replacement character (U+FFFD).

Example

use astral::string::Name;

// 𝄞mus<invalid>ic<invalid>
let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
          0x0073, 0xDD1E, 0x0069, 0x0063,
          0xD834];

assert_eq!(Name::new("𝄞mus\u{FFFD}ic\u{FFFD}", &string_subsystem),
           Name::from_utf16_lossy(v, &string_subsystem));

impl<'system, H> Name<'system, H>

pub unsafe fn from_raw_parts( id: StringId, number: Option<NonZeroU32>, system: &'system Subsystem<H>, ) -> Self

Creates a Name directly from a StringId, and a number in the specified Subsystem.

Safety

The Subsystem must match the one, which were used to create the StringId.

Example

use std::num::NonZeroU32;

use astral::string::{Name, StringId};

let id = StringId::new("Hello, world!", &string_subsystem);
// safe because the subsystem is the same
let hello = unsafe { Name::from_raw_parts(id, NonZeroU32::new(10), &string_subsystem) };

assert_eq!(hello, "Hello, world!10");

pub fn id(self) -> StringId

Returns the underlying StringId.

The StringId will be the same, if the strings and the subsystem are equal or only differ at the numeric suffix.

Example

use astral::string::Name;

let name1 = Name::new("foo-123", &string_subsystem);
let name2 = Name::new("foo-456", &string_subsystem);

assert_ne!(name1, name2);
assert_eq!(name1.id(), name2.id());

pub fn string_part(self) -> &'system str

Returns the string part of the Name.

Example

use astral::string::Name;

let s = Name::new("foo123", &string_subsystem);

assert_eq!("foo", s.string_part());

pub fn number(self) -> Option<NonZeroU32>

Returns the number part of the Name.

Examples

Basic usage:

use astral::string::Name;

let s = Name::new("foo123", &string_subsystem);

assert_eq!(123, s.number().unwrap().get());

pub fn as_str(self) -> Cow<'system, str>

Returns the string as Cow.

If the Name does not contain a numeric suffix, a Borrowed can be returned. Otherwise, Owned is used.

Example

use std::borrow::Cow;

use astral::string::Name;

let name = Name::new("foo", &string_subsystem);
assert_eq!(name.as_str(), Cow::Borrowed("foo"));

let name = Name::new("bar-10", &string_subsystem);
let cow: Cow<'_, str> = Cow::Owned(String::from("bar-10"));
assert_eq!(name.as_str(), cow);

Remember, than a digital suffix with leading zeros cannot be optimized:

use std::borrow::Cow;

use astral::string::Name;

let name = Name::new("hello-010", &string_subsystem);
assert_eq!(name.as_str(), Cow::Borrowed("hello-010"));

pub fn is_empty(self) -> bool

Returns true if this Name has a length of zero.

Returns false otherwise.

Examples

Basic usage:

use astral::string::Name;

let s = Name::new("foo", &string_subsystem);

assert!(!s.is_empty());
assert!(Name::new("", &string_subsystem).is_empty());

pub fn len(self) -> usize

Returns the length of this Name, in bytes.

Examples

Basic usage:

use astral::string::Name;

let s = Name::new("foo", &string_subsystem);

assert_eq!(s.len(), 3);

Trait Implementations

impl<H> Clone for Name<'_, H>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<H> Debug for Name<'_, H>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<H> Display for Name<'_, H>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'system, H> Extend<Name<'system, H>> for String

where H: 'system,

fn extend<I: IntoIterator<Item = Name<'system, H>>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<H> From<Name<'_, H>> for Box<dyn Error>

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<H> From<Name<'_, H>> for Box<dyn Error + Send + Sync>

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<H> From<Name<'_, H>> for Box<str>

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<H> From<Name<'_, H>> for OsString

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<H> From<Name<'_, H>> for PathBuf

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<H> From<Name<'_, H>> for String

fn from(string: Name<'_, H>) -> Self

Converts to this type from the input type.

impl<'system, H> From<Name<'system, H>> for Cow<'system, str>

fn from(string: Name<'system, H>) -> Cow<'system, str>

Converts to this type from the input type.

impl<'system, H> From<Text<'system, H>> for Name<'system, H>

fn from(text: Text<'system, H>) -> Self

Converts to this type from the input type.

impl<B> Hash for Name<'_, B>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<H> Ord for Name<'_, H>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<H> PartialEq<&str> for Name<'_, H>

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Cow<'_, str>> for Name<'_, H>

fn eq(&self, other: &Cow<'_, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Name<'_, H>> for &str

fn eq(&self, other: &Name<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Name<'_, H>> for Cow<'_, str>

fn eq(&self, other: &Name<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Name<'_, H>> for String

fn eq(&self, other: &Name<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Name<'_, H>> for Text<'_, H>

fn eq(&self, other: &Name<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Name<'_, H>> for str

fn eq(&self, other: &Name<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<String> for Name<'_, H>

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<Text<'_, H>> for Name<'_, H>

fn eq(&self, other: &Text<'_, H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq<str> for Name<'_, H>

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialEq for Name<'_, H>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> PartialOrd<&str> for Name<'_, H>

fn partial_cmp(&self, other: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Cow<'_, str>> for Name<'_, H>

fn partial_cmp(&self, other: &Cow<'_, str>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Name<'_, H>> for &str

fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Name<'_, H>> for Cow<'_, str>

fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Name<'_, H>> for String

fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Name<'_, H>> for Text<'_, H>

fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Name<'_, H>> for str

fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<String> for Name<'_, H>

fn partial_cmp(&self, other: &String) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<Text<'_, H>> for Name<'_, H>

fn partial_cmp(&self, other: &Text<'_, H>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd<str> for Name<'_, H>

fn partial_cmp(&self, other: &str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> PartialOrd for Name<'_, H>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<H> Copy for Name<'_, H>

impl<H> Eq for Name<'_, H>