Enum ffizz_string::FzString

pub enum FzString<'a> {
    Null,
    String(String),
    CString(CString),
    CStr(&'a CStr),
    Bytes(Vec<u8>),
}

A FzString carries a single string between Rust and C code, represented from the C side as an opaque struct.

The two environments carry some different requirements: C generally requires that strings be NUL-terminated, while Rust requires that strings be valid UTF-8. Rust also permits NUL characters in the middle of a string.

This type accepts whatever kind of data it receives without error, and converts – potentially with an error – when output of a different kind is required.

FzStrings also have a special “Null” state, similar to the None variant of Option. Rust code should use .unwrap() where the Null variant is not allowed. For user convenience, a NULL pointer is treated as a pointer to the Null variant wherever a pointer is accepted. Note that the Null variant is not necessarily represented with an all-zero byte pattern.

A FzString points to allocated memory, and must be freed to avoid memory leaks.

Variants

Null

An un-set FzString.

String(String)

An owned Rust string (not NUL-terminated, valid UTF-8).

CString(CString)

An owned C String (NUL-terminated, may contain invalid UTF-8).

CStr(&'a CStr)

A borrowed C string.

Bytes(Vec<u8>)

An owned bunch of bytes (not NUL-terminated, may contain invalid UTF-8).

Implementations

impl<'a> FzString<'a>

pub fn is_null(&self) -> bool

Check if this is a Null FzString.

pub fn as_str(&mut self) -> Result<Option<&str>, InvalidUTF8Error>

Convert this value to &str.

If required, the FzString is converted in-place to a String variant. If this conversion fails because the content is not valid UTF-8, an error is returned.

The Null FzString is represented as None.

pub fn as_cstr(&mut self) -> Result<Option<&CStr>, EmbeddedNulError>

Convert this value to a CStr: a slice of bytes containing a valid, NUL-terminated C string.

If required, the FzString is converted in-place to a CString variant. If this conversion fails because the content contains embedded NUL characters, an error is returned.

The Null FzString is represented as None.

pub fn into_string(self) -> Result<Option<String>, InvalidUTF8Error>

Consume this FzString and return an equivalent String.

As with as_str, the FzString is converted in-place, and this conversion can fail. In the failure case, the original data is lost.

The Null varaiant is represented as None.

pub fn as_bytes(&self) -> Option<&[u8]>

Get the slice of bytes representing the content of this value, not including any NUL terminator.

Any variant can be represented as a byte slice, so this method does not mutate the FzString and cannot fail.

The Null variant is represented as None.

Trait Implementations

impl<'a> Debug for FzString<'a>

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

Formats the value using the given formatter.

impl Default for FzString<'_>

fn default() -> Self

Returns the “default value” for a type.

impl From<&[u8]> for FzString<'static>

fn from(bytes: &[u8]) -> FzString<'static>

Converts to this type from the input type.

impl From<&str> for FzString<'static>

fn from(string: &str) -> FzString<'static>

Converts to this type from the input type.

impl From<Option<&[u8]>> for FzString<'static>

fn from(bytes: Option<&[u8]>) -> FzString<'static>

Converts to this type from the input type.

impl From<Option<&str>> for FzString<'static>

fn from(string: Option<&str>) -> FzString<'static>

Converts to this type from the input type.

impl From<Option<String>> for FzString<'static>

fn from(string: Option<String>) -> FzString<'static>

Converts to this type from the input type.

impl From<Option<Vec<u8, Global>>> for FzString<'static>

fn from(bytes: Option<Vec<u8>>) -> FzString<'static>

Converts to this type from the input type.

impl From<String> for FzString<'static>

fn from(string: String) -> FzString<'static>

Converts to this type from the input type.

impl From<Vec<u8, Global>> for FzString<'static>

fn from(bytes: Vec<u8>) -> FzString<'static>

Converts to this type from the input type.

impl OpaqueStruct for FzString<'_>

type CType = fz_string_t

The C representation of this type. This must have the same alignment as Self and its size must not be less than that of Self.

fn null_value() -> Self

Get the value of this type used to represent a NULL pointer.

unsafe fn with_ref<T, F>(cptr: *const Self::CType, f: F) -> Twhere
    F: Fn(&Self) -> T,

Call the contained function with a shared reference to the data type.

unsafe fn with_ref_mut<T, F>(cptr: *mut Self::CType, f: F) -> Twhere
    F: Fn(&mut Self) -> T,

Call the contained function with an exclusive reference to the data type.

unsafe fn initialize(cptr: *mut Self::CType, rval: Self)

Initialize the value pointed to cptr with rval, “moving” rval into the pointer.

unsafe fn return_val(self) -> Self::CType

Return a CType containing self, moving self in the process.

unsafe fn take(cptr: *mut Self::CType) -> Self

Take a CType and return an owned value.

impl<'a> PartialEq<FzString<'a>> for FzString<'a>

fn eq(&self, other: &FzString<'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> Eq for FzString<'a>

impl<'a> StructuralEq for FzString<'a>

impl<'a> StructuralPartialEq for FzString<'a>