Struct ZString 

pub struct ZString { /* private fields */ }

Available on crate feature alloc only.

Owning and non-null pointer to zero-terminated textual 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.
• The ZString owns the data, and will free it on drop.

Implementations

impl ZString

pub unsafe fn new_unchecked(b: Box<str>) -> Self

Converts a Box<str> into a ZString without any additional checking.

Safety

• The data must have exactly one null byte at the end.
• The data must not contain interior null bytes.

Breaking either of the above rules will cause the wrong amount to be freed when the ZString drops.

pub const fn as_zstr(&self) -> ZStr<'_>

Borrows this ZString as a ZStr.

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

Gets the raw pointer to this data.

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

An iterator over the bytes of this ZStr.

• This iterator excludes the terminating 0 byte.

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

An iterator over the decoded char values of this ZStr.

Trait Implementations

impl Clone for ZString

fn clone(&self) -> Self

Clones the value

//
let zstring1 = ZString::try_from("abc").unwrap();
let zstring2 = zstring1.clone();
assert!(zstring1.chars().eq(zstring2.chars()));

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

Performs copy-assignment from source.

impl Debug for ZString

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

Debug formats with outer " around the string.

let zstring = ZString::try_from("foo").unwrap();
let s = format!("{zstring:?}");
assert_eq!("\"foo\"", s);

impl Display for ZString

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

Display formats the string (without outer ").

let zstring = ZString::try_from("foo").unwrap();
let s = format!("{zstring}");
assert_eq!("foo", s);

impl Drop for ZString

fn drop(&mut self)

Executes the destructor for this type.

impl From<ZStr<'_>> for ZString

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 FromIterator<char> for ZString

fn from_iter<T: IntoIterator<Item = char>>(iter: T) -> Self

Creates a value from an iterator.

impl Hash for ZString

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 ZString

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

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<const N: usize> PartialEq<ZString> for ArrayZString<N>

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

An ArrayZString<N> equals a ZString when they contain the same 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<ZString> for ZStr<'_>

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 PartialEq for ZString

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

Two ZString 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).

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 ZString

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

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<const N: usize> PartialOrd<ZString> for ArrayZString<N>

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

An ArrayZString<N> compares to a ZString 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<ZString> for ZStr<'_>

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 PartialOrd for ZString

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 ZString

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

Formats the wrapped pointer value.

impl TryFrom<&str> for ZString

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

Trims any trailing nulls and then makes a ZString from what’s left.

let zstring1 = ZString::try_from("abc").unwrap();
assert!("abc".chars().eq(zstring1.chars()));

let zstring2 = ZString::try_from("foo\0\0\0\0").unwrap();
assert!("foo".chars().eq(zstring2.chars()));

Failure

• If there are any interior nulls.

assert!(ZString::try_from("ab\0c").is_err());

type Error = ZStringError

The type returned in the event of a conversion error.