Struct astral::string::Name

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

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!

Methods

impl<'system, H> Name<'system, H> where
    H: BuildHasher, 

pub fn new<T>(string: T, system: &'system Subsystem<H>) -> Name<'system, H> 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<Name<'system, H>, 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>
) -> Name<'system, H>

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>
) -> Name<'system, H>

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<Name<'system, H>, 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>
) -> Name<'system, H>

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>
) -> Name<'system, H>

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> Display for Name<'_, H>

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

Formats the value using the given formatter.

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

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

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

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

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

Extends a collection with the contents of an iterator.

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

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

Formats the value using the given formatter.

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

fn from(string: Name<H>) -> Box<str>

Performs the conversion.

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

fn from(string: Name<H>) -> OsString

Performs the conversion.

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

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

Performs the conversion.

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

fn from(string: Name<H>) -> Box<dyn Error + 'static>

Performs the conversion.

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

fn from(string: Name<H>) -> String

Performs the conversion.

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

fn from(string: Name<H>) -> PathBuf

Performs the conversion.

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

fn from(string: Name<H>) -> Box<dyn Error + 'static + Send + Sync>

Performs the conversion.

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

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

Performs the conversion.

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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

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

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

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

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

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

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

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

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

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

fn clone(&self) -> Name<'_, H>

Returns a copy of the value.

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

Performs copy-assignment from source.