Crate c8str

Source
Expand description

§c8str

This crate provides the C8Str and C8String types, which combine the properties of Rust native utf-8 strings and C style null terminated strings. These types guarantee that:

  • The string is valid utf-8
  • The string ends with a null terminator
  • The string doesn’t contain any null bytes before the end

Both types provide methods to get references to both &str (with or without the null terminator) and &CStr, or a pointer to *const c_char. They dereference to &str without the null terminator.

The c8 macro creates compile time constants of type &C8Str from string literals. The c8string macro creates a C8String verified at compile time, and the c8format macro can format into C8Strings.

The WithC8Str trait provides a convenience method for accessing an object as a &C8Str.

C8Str is no_std compatible. C8String is available behind the alloc feature.

assert_eq!(c8!("hello").as_str(), "hello");
assert_eq!(c8!("hello").as_c_str(), c"hello");

§Features

  • alloc - Enable the C8String type. This requires the standard alloc or std crates.

§Recent changes

  • 0.2.1:

    • Fix c8format macro

  • 0.2.0:

    • Add c8format macro
    • Add WithC8Str trait
    • Add some methods
    • Change C8String::new to take no args and create an empty string without allocating
    • Impl Index<RangeFrom<usize>> for C8Str
    • MSRV 1.81

  • 0.1.2

    • Make C8Str::from_ptr[_unchecked] const

  • 0.1.1

    • Show documentation for all features on docs.rs

  • 0.1.0

    • First release

Macros§

c8
Makes a new C8Str constant from a string literal. This macro adds the null terminator for you and checks validity at compile time.
c8formatalloc
Format and create a new C8String. This will panic if the formatted string contains any null bytes.
c8stringalloc
Make a new C8String from a string literal. This macro adds the null terminator for you and checks validity at compile time.

Structs§

C8Str
C8Str is a string slice type combining the properties of str and CStr. Note that unlike CStr, this will always be a normal slice so that trivial conversion to both str and CStr are possible. The crate may add a thin pointer alternative to C8Str in a future version, but C8Str won’t change from being a slice.
C8StrError
Common error type for most of this crate
C8Stringalloc
C8String is a string type combining the properties of String and CString. It’s the owned version of C8Str.
NonZeroChar
A char that is guaranteed to be nonzero
NonZeroCharError
Error returned from TryFrom<char>::try_from for NonZeroChar if the char was zero

Traits§

StringTypealloc
Trait for standard utf-8 string types. Implemented for &str, String, Box<str> and Cow<'_, str>
WithC8Str
Access an object as a &C8Str