Struct astral_string::Name
pub struct Name<'system, H = BuildHasherDefault<Murmur3>> { /* private fields */ }
Expand description
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,
impl<'system, H> Name<'system, H>where
H: BuildHasher,
pub fn from_utf8(
v: &[u8],
system: &'system Subsystem<H>
) -> Result<Self, Utf8Error>
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
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
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 Name
s 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>
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
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>
impl<'system, H> Name<'system, H>
pub unsafe fn from_raw_parts(
id: StringId,
number: Option<NonZeroU32>,
system: &'system Subsystem<H>
) -> Self
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
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
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>
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>
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"));
Trait Implementations
impl<'system, H> Extend<Name<'system, H>> for Stringwhere
H: 'system,
impl<'system, H> Extend<Name<'system, H>> for Stringwhere
H: 'system,
fn extend<I: IntoIterator<Item = Name<'system, H>>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = Name<'system, H>>>(&mut self, iter: I)
sourcefn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)sourcefn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)impl<H> Ord for Name<'_, H>
impl<H> Ord for Name<'_, H>
1.21.0 · sourcefn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.21.0 · sourcefn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
impl<H> PartialOrd<&str> for Name<'_, H>
impl<H> PartialOrd<&str> for Name<'_, H>
impl<H> PartialOrd<Cow<'_, str>> for Name<'_, H>
impl<H> PartialOrd<Cow<'_, str>> for Name<'_, H>
fn partial_cmp(&self, other: &Cow<'_, str>) -> Option<Ordering>
fn partial_cmp(&self, other: &Cow<'_, str>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Name<'_, H>> for &str
impl<H> PartialOrd<Name<'_, H>> for &str
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Name<'_, H>> for Cow<'_, str>
impl<H> PartialOrd<Name<'_, H>> for Cow<'_, str>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Name<'_, H>> for Name<'_, H>
impl<H> PartialOrd<Name<'_, H>> for Name<'_, H>
impl<H> PartialOrd<Name<'_, H>> for String
impl<H> PartialOrd<Name<'_, H>> for String
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Name<'_, H>> for Text<'_, H>
impl<H> PartialOrd<Name<'_, H>> for Text<'_, H>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Name<'_, H>> for str
impl<H> PartialOrd<Name<'_, H>> for str
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Name<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<String> for Name<'_, H>
impl<H> PartialOrd<String> for Name<'_, H>
fn partial_cmp(&self, other: &String) -> Option<Ordering>
fn partial_cmp(&self, other: &String) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<H> PartialOrd<Text<'_, H>> for Name<'_, H>
impl<H> PartialOrd<Text<'_, H>> for Name<'_, H>
fn partial_cmp(&self, other: &Text<'_, H>) -> Option<Ordering>
fn partial_cmp(&self, other: &Text<'_, H>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more