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.

A number of From<T> implementations are provided to convert from common Rust types. The fz_string_.. utility functions provide conversions from various string formats.

FzStrings also have a special “Null” state, similar to the None variant of Option. For user convenience, a NULL pointer is treated as a pointer to the Null variant wherever a pointer is accepted. Rust code should use the _nonnull methods where the Null variant is not allowed. 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_str_nonnull(&mut self) -> Result<&str, InvalidUTF8Error>

Convert this FzString, assuming it is not Null, into &str.

This is a simple wrapper that will panic on the Null variant. This is useful when the C API prohibits NULL.

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 as_cstr_nonnull(&mut self) -> Result<&CStr, EmbeddedNulError>

Convert this FzString, assuming it is not Null, into a CStr.

This is a simple wrapper that will panic on the Null variant. This is useful when the C API prohibits NULL.

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 into_string_nonnull(self) -> Result<String, InvalidUTF8Error>

Consume this FzString, assuming it is not Null, and return an equivalent String.

This is a simple wrapper that will panic on the Null variant. This is useful when the C API prohibits NULL.

pub fn into_path_buf(self) -> Result<Option<PathBuf>, Utf8Error>

Consume this FzString and return an equivalent PathBuf.

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 into_path_buf_nonnull(self) -> Result<PathBuf, Utf8Error>

Consume this FzString, assuming it is not Null, and return an equivalent PathBuf.

This is a simple wrapper that will panic on the Null variant. This is useful when the C API prohibits NULL.

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.

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

Get the slice of bytes representing the content of this value, not including any NUL terminator, panicing if this is the Null Variant.

This is a simple wrapper that will panic on the Null variant. This is useful when the C API prohibits NULL.

pub unsafe fn with_ref<T, F: Fn(&FzString<'_>) -> T>(
    fzstr: *const fz_string_t,
    f: F
) -> T

Call the contained function with a shared reference to the FzString.

This is a wrapper around ffizz_passby::OpaqueStruct::with_ref.

Safety

• fzstr must be NULL or point to a valid fz_string_t value
• no other thread may mutate the value pointed to by fzstr until with_ref returns.

pub unsafe fn with_ref_mut<T, F: Fn(&mut FzString<'_>) -> T>(
    fzstr: *mut fz_string_t,
    f: F
) -> T

Call the contained function with an exclusive reference to the FzString.

This is a wrapper around ffizz_passby::OpaqueStruct::with_ref_mut.

Safety

• fzstr must be NULL or point to a valid fz_string_t value
• no other thread may access the value pointed to by fzstr until with_ref_mut returns.

pub unsafe fn to_out_param(self, fzstr: *mut fz_string_t)

Initialize the value pointed to fzstr with, “moving” it into the pointer.

This is a wrapper around ffizz_passby::OpaqueStruct::to_out_param.

If the pointer is NULL, the value is dropped.

Safety

• if fzstr is not NULl, then it must be aligned for fz_string_t, and must have enough space for fz_string_t.
• ownership of the string is transfered to *fzstr or dropped.

pub unsafe fn to_out_param_nonnull(self, fzstr: *mut fz_string_t)

Initialize the value pointed to fzstr with, “moving” it into the pointer.

This is a wrapper around ffizz_passby::OpaqueStruct::to_out_param_nonnull.

If the pointer is NULL, this method will panic. Use this when the C API requires that the pointer be non-NULL.

Safety

• fzstr must not be NULL, must be aligned for fz_string_t, and must have enough space for fz_string_t.
• ownership of the string is transfered to *fzstr.

pub unsafe fn return_val(self) -> fz_string_t

Return a fz_string_t transferring ownership out of the function.

This is a wrapper around ffizz_passby::OpaqueStruct::return_val.

Safety

• to avoid a leak, ownership of the value must eventually be returned to Rust.

pub unsafe fn take(fzstr: fz_string_t) -> Self

Take a fz_string_t by value and return an owned FzString.

This is a wrapper around ffizz_passby::OpaqueStruct::take.

This method is intended for C API functions that take a string by value and are documented as taking ownership of the value. However, this means that C retains an expired “copy” of the value and could lead to use-after-free errors.

Where compatible with the API design, prefer to use pointers in the C API and use FzString::take_ptr to ensure the old value is invalidated.

Safety

• fzstr must be a valid fz_string_t value

pub unsafe fn take_ptr(fzstr: *mut fz_string_t) -> Self

Take a pointer to a CType and return an owned value.

This is a wrapper around ffizz_passby::OpaqueStruct::take_ptr.

This is intended for C API functions that take a value by reference (pointer), but still “take ownership” of the value. It leaves behind an invalid value, where any non-padding bytes of the Rust type are zeroed. This makes use-after-free errors in the C code more likely to crash instead of silently working. Which is about as good as it gets in C.

Do not pass a pointer to a Rust value to this function:

let rust_value = RustType::take_ptr(&mut c_value); // BAD!

This creates undefined behavior as Rust will assume c_value is still initialized. Use take in this situation.

Safety

• fzstr must be NULL or point to a valid fz_string_t value.
• the memory pointed to by fzstr is uninitialized when this function returns.

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 to_out_param(self, cptr: *mut Self::CType)

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

unsafe fn to_out_param_nonnull(self, cptr: *mut Self::CType)

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(cval: Self::CType) -> Self

Take a CType and return an owned value.

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

Take a pointer to 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>