Struct NulStr

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

A utf8 nul-terminated immutable borrowed string.

For the purpose of passing NulStrs to C, this has the same ABI as a std::ptr::NonNull<u8>, and an Option<NulStr<'_>> has the same ABI as *const u8.

Safety

NulStr has these safety requirement:

• the string must be valid to read for the 'a lifetime
• the string must be utf8 encoded
• the string must be nul terminated
• the string must not be mutated while this is alive (the same semantics as & references)

Example

Passing to extern function

You can pass NulStr to C functions expecting a nul-terminated string.

use abi_stable::sabi_types::NulStr;

extern "C" {
    // the signature in the C side is `uint64_t add_digits(const char*)`
    fn add_digits(_: NulStr<'_>) -> u64;
}

const FOO: NulStr<'_> = NulStr::from_str("1.2.3\0");
const BAR: NulStr<'_> = NulStr::from_str("12|34\0");
const QUX: NulStr<'_> = NulStr::from_str("123_abcd_45\0");

assert_eq!(unsafe { add_digits(FOO) }, 6);
assert_eq!(unsafe { add_digits(BAR) }, 10);
assert_eq!(unsafe { add_digits(QUX) }, 15);

Implementations

impl NulStr<'static>

pub const EMPTY: Self

An empty string.

impl<'a> NulStr<'a>

pub const fn from_str(str: &'a str) -> Self

Constructs an NulStr from a string slice.

Correctness

If the string contains interior nuls, the first nul will be considered the string terminator.

Panics

This panics when the string does not end with '\0'.

Example

use abi_stable::sabi_types::NulStr;

const FOO: NulStr<'_> = NulStr::from_str("foo\0");
// `NulStr`s can be compared with `str`s
assert_eq!(FOO, "foo");

const BAR: NulStr<'_> = NulStr::from_str("bar\0");
assert_eq!(BAR, "bar");

const HEWWO: NulStr<'_> = NulStr::from_str("Hello, world!\0");
assert_eq!(HEWWO, "Hello, world!");

const TRUNCATED: NulStr<'_> = NulStr::from_str("baz\0world!\0");
assert_eq!(TRUNCATED, "baz");

pub const fn try_from_str(string: &'a str) -> Result<Self, NulStrError>

Constructs an NulStr from a string slice.

Errors

This returns a NulStrError::NoNulTerminator when the string does not end with '\0'.

This returns a NulStrError::InnerNul when the string contains a '\0' before the '\0' terminator.

Example

use abi_stable::sabi_types::{NulStr, NulStrError};

// `NulStr`s can be compared with `str`s
assert_eq!(NulStr::try_from_str("hello\0").unwrap(), "hello");

assert_eq!(
    NulStr::try_from_str("hello\0world\0"),
    Err(NulStrError::InnerNul { pos: 5 }),
);

pub const unsafe fn from_ptr(ptr: *const u8) -> Self

Constructs an NulStr from a pointer.

Safety

The same as the type-level safety docs

Correctness

If the string contains interior nuls, the first nul will be considered the string terminator.

Example

use abi_stable::sabi_types::NulStr;

const FOO: NulStr<'_> = unsafe { NulStr::from_ptr("foo\0".as_ptr()) };
assert_eq!(FOO, "foo");

const BAR: NulStr<'_> = unsafe { NulStr::from_ptr("bar\0".as_ptr()) };
assert_eq!(BAR, "bar");

const HEWWO: NulStr<'_> = unsafe { NulStr::from_ptr("Hello, world!\0".as_ptr()) };
assert_eq!(HEWWO, "Hello, world!");

const TRUNCATED: NulStr<'_> = unsafe { NulStr::from_ptr("baz\0world!\0".as_ptr()) };
assert_eq!(TRUNCATED, "baz");

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

Gets a pointer to the start of this nul-terminated string.

Example

use abi_stable::sabi_types::NulStr;

let foo_str = "foo\0";
let foo = NulStr::from_str(foo_str);
assert_eq!(foo.as_ptr(), foo_str.as_ptr());

pub fn to_str_with_nul(&self) -> &'a str

Converts this NulStr<'a> to a &'a str,including the nul byte.

Performance

This conversion requires traversing through the entire string to find the nul byte.

Example

use abi_stable::sabi_types::NulStr;

const FOO: NulStr<'_> = NulStr::from_str("foo bar\0");
let foo: &str = FOO.to_str_with_nul();
assert_eq!(&foo[..3], "foo");
assert_eq!(&foo[4..], "bar\0");

pub fn to_rstr_with_nul(&self) -> RStr<'a>

Converts this NulStr<'a> to a RStr<'a>,including the nul byte.

Performance

This conversion requires traversing through the entire string to find the nul byte.

Example

use abi_stable::sabi_types::NulStr;
use abi_stable::std_types::RStr;

const BAZ: NulStr<'_> = NulStr::from_str("baz qux\0");
let baz: RStr<'_> = BAZ.to_rstr_with_nul();
assert_eq!(&baz[..3], "baz");
assert_eq!(&baz[4..], "qux\0");

pub fn to_str(self) -> &'a str

Converts this NulStr<'a> to a &'a str,not including the nul byte.

Performance

This conversion requires traversing through the entire string to find the nul byte.

Example

use abi_stable::sabi_types::NulStr;

const FOO: NulStr<'_> = NulStr::from_str("foo bar\0");
let foo: &str = FOO.to_str();
assert_eq!(&foo[..3], "foo");
assert_eq!(&foo[4..], "bar");

pub fn to_rstr(self) -> RStr<'a>

Converts this NulStr<'a> to a RStr<'a>,not including the nul byte.

Performance

This conversion requires traversing through the entire string to find the nul byte.

Example

use abi_stable::sabi_types::NulStr;
use abi_stable::std_types::RStr;

const BAZ: NulStr<'_> = NulStr::from_str("baz qux\0");
let baz: RStr<'_> = BAZ.to_rstr();
assert_eq!(&baz[..3], "baz");
assert_eq!(&baz[4..], "qux");

Trait Implementations

impl<'a> Clone for NulStr<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for NulStr<'_>

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

Formats the value using the given formatter.

impl Default for NulStr<'_>

fn default() -> Self

Returns the “default value” for a type.

impl Display for NulStr<'_>

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

Formats the value using the given formatter.

impl<'a> GetStaticEquivalent_ for NulStr<'a>

type StaticEquivalent = _static_NulStr<'static>

The 'static equivalent of Self

impl<'a> Ord for NulStr<'a>

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<'a> PartialEq<&str> for NulStr<'a>

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<'a> PartialEq<NulStr<'a>> for &str

fn eq(&self, other: &NulStr<'a>) -> 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<'a> PartialEq<NulStr<'a>> for str

fn eq(&self, other: &NulStr<'a>) -> 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<'a> PartialEq<str> for NulStr<'a>

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<'a> PartialEq for NulStr<'a>

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<'a> PartialOrd for NulStr<'a>

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<'a> StableAbi for NulStr<'a>

const LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

type IsNonZeroType = <NonNull<u8> as StableAbi>::IsNonZeroType

Whether this type has a single invalid bit-pattern.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.

impl<'a> Copy for NulStr<'a>

impl<'a> Eq for NulStr<'a>

impl Send for NulStr<'_>

impl Sync for NulStr<'_>