Struct ffi_support::FfiStr

#[repr(transparent)]
pub struct FfiStr<'a> { /* fields omitted */ }

FfiStr<'a> is a safe (#[repr(transparent)]) wrapper around a nul-terminated *const c_char (e.g. a C string). Conceptually, it is similar to std::ffi::CStr, except that it may be used in the signatures of extern "C" functions.

Functions accepting strings should use this instead of accepting a C string directly. This allows us to write those functions using safe code without allowing safe Rust to cause memory unsafety.

A single function for constructing these from Rust (FfiStr::from_raw) has been provided. Most of the time, this should not be necessary, and users should accept FfiStr in the parameter list directly.

Caveats

An effort has been made to make this struct hard to misuse, however it is still possible, if the 'static lifetime is manually specified in the struct. E.g.

// NEVER DO THIS
#[no_mangle]
extern "C" fn never_do_this(s: FfiStr<'static>) {
    // save `s` somewhere, and access it after this
    // function returns.
}

Instead, one of the following patterns should be used:

#[no_mangle]
extern "C" fn valid_use_1(s: FfiStr<'_>) {
    // Use of `s` after this function returns is impossible
}
// Alternative:
#[no_mangle]
extern "C" fn valid_use_2(s: FfiStr) {
    // Use of `s` after this function returns is impossible
}

Methods

impl<'a> FfiStr<'a>

pub unsafe fn from_raw(ptr: *const c_char) -> Self

Construct an FfiStr from a raw pointer.

This should not be needed most of the time, and users should instead accept FfiStr in function parameter lists.

Safety

Dereferences a pointer and is thus unsafe.

pub fn from_cstr(cstr: &'a CStr) -> Self

Construct a FfiStr from a std::ffi::CStr. This is provided for completeness, as a safe method of producing an FfiStr in Rust.

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

Get an &str out of the FfiStr. This will panic in any case that FfiStr::as_opt_str would return None (e.g. null pointer or invalid UTF-8).

If the string should be optional, you should use FfiStr::as_opt_str instead. If an owned string is desired, use FfiStr::into_string or FfiStr::into_opt_string.

pub fn as_opt_str(&self) -> Option<&'a str>

Get an Option<&str> out of the FfiStr. If this stores a null pointer, then None will be returned. If a string containing invalid UTF-8 was passed, then an error will be logged and None will be returned.

If the string is a required argument, use FfiStr::as_str, or FfiStr::into_string instead. If Option<String> is desired, use FfiStr::into_opt_string (which will handle invalid UTF-8 by replacing with the replacement character).

pub fn into_opt_string(self) -> Option<String>

Get an Option<String> out of the FfiStr. Returns None if this FfiStr holds a null pointer. Note that unlike FfiStr::as_opt_str, invalid UTF-8 is replaced with the replacement character instead of causing us to return None.

If the string should be mandatory, you should use FfiStr::into_string instead. If an owned string is not needed, you may want to use FfiStr::as_str or FfiStr::as_opt_str instead, (however, note the differences in how invalid UTF-8 is handled, should this be relevant to your use).

pub fn into_string(self) -> String

Get a String out of a FfiStr. This function is essential a convenience wrapper for ffi_str.into_opt_string().unwrap(), with a message that indicates that a null argument was passed to rust when it should be mandatory. As with FfiStr::into_opt_string, invalid UTF-8 is replaced with the replacement character if encountered.

If the string should not be mandatory, you should use FfiStr::into_opt_string instead. If an owned string is not needed, you may want to use FfiStr::as_str or FfiStr::as_opt_str instead, (however, note the differences in how invalid UTF-8 is handled, should this be relevant to your use).

Trait Implementations

impl<'a> Debug for FfiStr<'a>

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

Formats the value using the given formatter.

impl<'a> From<FfiStr<'a>> for String

fn from(f: FfiStr<'a>) -> Self

Performs the conversion.

impl<'a> From<FfiStr<'a>> for Option<String>

fn from(f: FfiStr<'a>) -> Self

Performs the conversion.

impl<'a> From<FfiStr<'a>> for Option<&'a str>

fn from(f: FfiStr<'a>) -> Self

Performs the conversion.

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

fn from(f: FfiStr<'a>) -> Self

Performs the conversion.

impl<'a, 'b> PartialEq<&'b str> for FfiStr<'a>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<FfiStr<'a>> for FfiStr<'a>

fn eq(&self, other: &FfiStr<'a>) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<FfiStr<'a>> for str

fn eq(&self, other: &FfiStr<'a>) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b> PartialEq<FfiStr<'a>> for &'b str

fn eq(&self, other: &FfiStr<'a>) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<str> for FfiStr<'a>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.