Struct ZStr 

pub struct ZStr<'a> { /* private fields */ }

Borrowed and non-null pointer to zero-terminated text data.

Because this is a thin pointer it’s suitable for direct FFI usage.

The bytes pointed to should be utf-8 encoded, but the CharDecoder used to convert the bytes to char values is safe to use even when the bytes are not proper utf-8.

Safety

• This is repr(transparent) over a NonNull<u8>.
• The wrapped pointer points at a sequence of valid-to-read non-zero byte values followed by at least one zero byte.
• When you create a ZStr<'a> value the pointer must be valid for at least as long as the lifetime 'a.

Implementations

impl<'a> ZStr<'a>

pub const fn from_lit(s: &'static str) -> ZStr<'static>

Makes a ZStr<'static> from a &'static str

This is intended for use with string litearls, but if you leak a runtime string into a static string I guess that works too.

const FOO: ZStr<'static> = ZStr::from_lit("foo\0");

Panics

• If try_from would return an error, this will panic instead. Because this is intended for compile time constants, the panic will “just” trigger a build error.

pub fn bytes(self) -> impl Iterator<Item = u8> + 'a

An iterator over the bytes of this ZStr.

• This iterator excludes the terminating 0 byte.

pub fn chars(self) -> impl Iterator<Item = char> + 'a

An iterator over the decoded char values of this ZStr.

pub const fn as_ptr(self) -> *const u8

Gets the raw pointer to this data.

Trait Implementations

impl<'a> Clone for ZStr<'a>

fn clone(&self) -> ZStr<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ZStr<'_>

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

Debug formats with outer " around the string.

const FOO: ZStr<'static> = ZStr::from_lit("foo\0");
let s = format!("{FOO:?}");
assert_eq!(s, "\"foo\"");

impl Display for ZStr<'_>

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

Display formats the string (without outer ").

const FOO: ZStr<'static> = ZStr::from_lit("foo\0");
let s = format!("{FOO}");
assert_eq!(s, "foo");

impl From<ZStr<'_>> for ZString

Available on crate feature alloc only.

fn from(value: ZStr<'_>) -> Self

This is like a “to owned’ style operation.

const FOO: ZStr<'static> = ZStr::from_lit("foo\0");
let zstring = ZString::from(FOO);
assert_eq!(zstring, FOO);

impl Hash for ZStr<'_>

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 PartialEq<&str> for ZStr<'_>

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

A ZStr equals a &str if the bytes match.

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<const N: usize> PartialEq<ZStr<'_>> for ArrayZString<N>

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

An ArrayZString<N> equals a ZStr by bytes.

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 PartialEq<ZStr<'_>> for ZStr<'_>

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

Two ZStr are considered equal if they point at the exact same byte sequence.

This is much faster to compute when the bytes are valid UTF-8, though it is stricter if the bytes are not valid UTF-8 (the character replacement process during decoding could make two different byte sequences have the same character sequence).

const FOO1: ZStr<'static> = ZStr::from_lit("foo\0");
const FOO2: ZStr<'static> = ZStr::from_lit("foo\0");
assert_eq!(FOO1, FOO2);

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 PartialEq<ZStr<'_>> for ZString

Available on crate feature alloc only.

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

A ZString equals a ZStr by calling ZString::as_zstr

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 PartialEq<ZString> for ZStr<'_>

Available on crate feature alloc only.

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

A ZStr equals a ZString by calling ZString::as_zstr

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 PartialOrd<&str> for ZStr<'_>

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

Compares based on the byte sequence pointed to.

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<const N: usize> PartialOrd<ZStr<'_>> for ArrayZString<N>

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

An ArrayZString<N> compares to a ZStr by bytes.

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 PartialOrd<ZStr<'_>> for ZStr<'_>

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

Compares based on the byte sequence pointed to.

const ABC: ZStr<'static> = ZStr::from_lit("abc\0");
const DEF: ZStr<'static> = ZStr::from_lit("def\0");
const GHI: ZStr<'static> = ZStr::from_lit("ghi\0");
assert_eq!(ABC.partial_cmp(&DEF), Some(Ordering::Less));
assert_eq!(DEF.partial_cmp(&GHI), Some(Ordering::Less));
assert_eq!(GHI.partial_cmp(&ABC), Some(Ordering::Greater));

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 PartialOrd<ZStr<'_>> for ZString

Available on crate feature alloc only.

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

Compares based on the byte sequence pointed to.

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 PartialOrd<ZString> for ZStr<'_>

Available on crate feature alloc only.

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

Compares based on the byte sequence pointed to.

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 Pointer for ZStr<'_>

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

Formats the wrapped pointer value.

impl<'a> TryFrom<&'a str> for ZStr<'a>

fn try_from(value: &'a str) -> Result<Self, Self::Error>

Converts the value in place.

The trailing nulls of the source &str will not “be in” the output sequence of the returned ZStr.

let z1 = ZStr::try_from("abcd\0").unwrap();
assert!(z1.chars().eq("abcd".chars()));

let z2 = ZStr::try_from("abcd\0\0\0").unwrap();
assert!(z2.chars().eq("abcd".chars()));

Failure

• There must be at least one trailing null in the input &str.
• There must be no nulls followed by a non-null (“interior nulls”). This second condition is not a strict requirement of the type, more of a correctness lint. If interior nulls were allowed then "ab\0cd\0" converted to a ZStr would only be read as "ab", and the second half of the string would effectively be erased.

type Error = ZStringError

The type returned in the event of a conversion error.

impl<'a> Copy for ZStr<'a>