Struct abi_stable::sabi_types::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 const fn const_to_str_with_nul(&self) -> &'a str

Available on crate feature rust_1_64 only.

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

Performance

To make this function const-callable, this uses a potentially less efficient approach than to_str_with_nul.

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");
const FOO_S: &str = FOO.const_to_str_with_nul();
assert_eq!(&FOO_S[..3], "foo");
assert_eq!(&FOO_S[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 const fn const_to_str(self) -> &'a str

Available on crate feature rust_1_64 only.

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

Performance

To make this function const-callable, this uses a potentially less efficient approach than to_str.

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");
const FOO_S: &str = FOO.const_to_str();
assert_eq!(&FOO_S[..3], "foo");
assert_eq!(&FOO_S[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 copy 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 + PartialOrd,

Restrict a value to a certain interval.

impl<'a> PartialEq<&str> for NulStr<'a>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Whether this type has a single invalid bit-pattern.

const LAYOUT: &'static TypeLayout = _

The layout of the type provided by implementors.

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<'_>