Enum CFixedString

pub enum CFixedString {
    Local {
        s: [c_char; 512],
        len: usize,
    },
    Heap {
        s: CString,
        len: usize,
    },
}

This is a C String abstractions that presents a CStr like interface for interop purposes but tries to be little nicer by avoiding heap allocations if the string is within the generous bounds (512 bytes) of the statically sized buffer. Strings over this limit will be heap allocated, but the interface outside of this abstraction remains the same.

Variants

Local

Fields

s: [c_char; 512]

len: usize

Heap

Fields

s: CString

len: usize

Implementations

impl CFixedString

pub fn new() -> Self

Creates an empty CFixedString, this is intended to be used with write! or the fmt::Write trait

pub fn from_str<S: AsRef<str>>(s: S) -> Self

Create from str

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

Returns the pointer to be passed down to the C code

pub fn is_allocated(&self) -> bool

Returns true if the string has been heap allocated

pub fn to_string(&self) -> Cow<'_, str>

Converts a CFixedString into a Cow<str>.

This function will calculate the length of this string (which normally requires a linear amount of work to be done) and then return the resulting slice as a Cow<str>, replacing any invalid UTF-8 sequences with U+FFFD REPLACEMENT CHARACTER. If there are no invalid UTF-8 sequences, this will merely return a borrowed slice.

pub unsafe fn as_str(&self) -> &str

Convert back to str. Unsafe as it uses from_utf8_unchecked

Methods from Deref<Target = CStr>

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

Returns the inner pointer to this C string.

The returned pointer will be valid for as long as self is, and points to a contiguous region of memory terminated with a 0 byte to represent the end of the string.

The type of the returned pointer is *const c_char, and whether it’s an alias for *const i8 or *const u8 is platform-specific.

WARNING

The returned pointer is read-only; writing to it (including passing it to C code that writes to it) causes undefined behavior.

It is your responsibility to make sure that the underlying memory is not freed too early. For example, the following code will cause undefined behavior when ptr is used inside the unsafe block:

use std::ffi::{CStr, CString};

// 💀 The meaning of this entire program is undefined,
// 💀 and nothing about its behavior is guaranteed,
// 💀 not even that its behavior resembles the code as written,
// 💀 just because it contains a single instance of undefined behavior!

// 🚨 creates a dangling pointer to a temporary `CString`
// 🚨 that is deallocated at the end of the statement
let ptr = CString::new("Hi!".to_uppercase()).unwrap().as_ptr();

// without undefined behavior, you would expect that `ptr` equals:
dbg!(CStr::from_bytes_with_nul(b"HI!\0").unwrap());

// 🙏 Possibly the program behaved as expected so far,
// 🙏 and this just shows `ptr` is now garbage..., but
// 💀 this violates `CStr::from_ptr`'s safety contract
// 💀 leading to a dereference of a dangling pointer,
// 💀 which is immediate undefined behavior.
// 💀 *BOOM*, you're dead, you're entire program has no meaning.
dbg!(unsafe { CStr::from_ptr(ptr) });

This happens because, the pointer returned by as_ptr does not carry any lifetime information, and the CString is deallocated immediately after the expression that it is part of has been evaluated. To fix the problem, bind the CString to a local variable:

use std::ffi::{CStr, CString};

let c_str = CString::new("Hi!".to_uppercase()).unwrap();
let ptr = c_str.as_ptr();

assert_eq!(unsafe { CStr::from_ptr(ptr) }, c"HI!");

pub fn count_bytes(&self) -> usize

Returns the length of self. Like C’s strlen, this does not include the nul terminator.

Note: This method is currently implemented as a constant-time cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

Examples

assert_eq!(c"foo".count_bytes(), 3);
assert_eq!(c"".count_bytes(), 0);

pub fn is_empty(&self) -> bool

Returns true if self.to_bytes() has a length of 0.

Examples

assert!(!c"foo".is_empty());
assert!(c"".is_empty());

pub fn to_bytes(&self) -> &[u8]

Converts this C string to a byte slice.

The returned slice will not contain the trailing nul terminator that this C string has.

Note: This method is currently implemented as a constant-time cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

Examples

assert_eq!(c"foo".to_bytes(), b"foo");

pub fn to_bytes_with_nul(&self) -> &[u8]

Converts this C string to a byte slice containing the trailing 0 byte.

This function is the equivalent of CStr::to_bytes except that it will retain the trailing nul terminator instead of chopping it off.

Note: This method is currently implemented as a 0-cost cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

Examples

assert_eq!(c"foo".to_bytes_with_nul(), b"foo\0");

pub fn bytes(&self) -> Bytes<'_>

🔬This is a nightly-only experimental API. (cstr_bytes)

Iterates over the bytes in this C string.

The returned iterator will not contain the trailing nul terminator that this C string has.

Examples

#![feature(cstr_bytes)]

assert!(c"foo".bytes().eq(*b"foo"));

pub fn to_str(&self) -> Result<&str, Utf8Error>

Yields a &str slice if the CStr contains valid UTF-8.

If the contents of the CStr are valid UTF-8 data, this function will return the corresponding &str slice. Otherwise, it will return an error with details of where UTF-8 validation failed.

Examples

assert_eq!(c"foo".to_str(), Ok("foo"));

pub fn display(&self) -> impl Display

🔬This is a nightly-only experimental API. (cstr_display)

Returns an object that implements Display for safely printing a CStr that may contain non-Unicode data.

Behaves as if self were first lossily converted to a str, with invalid UTF-8 presented as the Unicode replacement character: �.

Examples

#![feature(cstr_display)]

let cstr = c"Hello, world!";
println!("{}", cstr.display());

pub fn to_string_lossy(&self) -> Cow<'_, str>

Converts a CStr into a Cow<str>.

If the contents of the CStr are valid UTF-8 data, this function will return a Cow::Borrowed(&str) with the corresponding &str slice. Otherwise, it will replace any invalid UTF-8 sequences with U+FFFD REPLACEMENT CHARACTER and return a Cow::Owned(String) with the result.

Examples

Calling to_string_lossy on a CStr containing valid UTF-8. The leading c on the string literal denotes a CStr.

use std::borrow::Cow;

assert_eq!(c"Hello World".to_string_lossy(), Cow::Borrowed("Hello World"));

Calling to_string_lossy on a CStr containing invalid UTF-8:

use std::borrow::Cow;

assert_eq!(
    c"Hello \xF0\x90\x80World".to_string_lossy(),
    Cow::Owned(String::from("Hello �World")) as Cow<'_, str>
);

Trait Implementations

impl AsRef<CStr> for CFixedString

fn as_ref(&self) -> &CStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<str> for CFixedString

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<CStr> for CFixedString

fn borrow(&self) -> &CStr

Immutably borrows from an owned value.

impl Borrow<str> for CFixedString

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl Deref for CFixedString

type Target = CStr

The resulting type after dereferencing.

fn deref(&self) -> &CStr

Dereferences the value.

impl<'a> From<&'a str> for CFixedString

fn from(s: &'a str) -> Self

Converts to this type from the input type.

impl From<CFixedString> for String

fn from(s: CFixedString) -> Self

Converts to this type from the input type.

impl Write for CFixedString

fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.