Crate ffizz_string

This crate provides a string abstraction that is convenient to use from both Rust and C. It provides a way to pass strings into Rust functions and to return strings to C, with clear rules for ownership.

Usage

Expose the C type fz_string_t in your C header as a struct with the same structure as that in the fz_string_t docstring. This is large enough to hold the FzString type, and ensures the C compiler will properly align the value.

You may call the type whatever you like. Type names are erased in the C ABI, so it’s fine to write a Rust declaration using fz_string_t and equivalent C declaration using your_name_here_t. You may also rename the Rust type with use ffizz_string::fz_string_t as .., if you prefer.

As an Argument

Define your extern "C" function to take a *mut fz_string_t argument:

pub unsafe extern "C" fn is_a_color_name(name: *mut fz_string_t) -> bool { .. };

Then use one of the FzString methods to handle the string value. As standard practice, address each of the items listed in the “Safety” section of each unsafe method you call. For example:

// SAFETY:
//  - name is not NULL (see docstring)
//  - no other thread will mutate name (type is documented as not threadsafe)
unsafe {
    FzString::with_ref(name, |name| {
        if let Some(name) = name.as_str() {
            return Colors::from_str(name).is_some();
        }
        false // invalid UTF-8 is _not_ a color name
    })
}

As a Return Value

To return a string, define your extern "C" function to return an fz_string_t:

pub unsafe extern "C" fn favorite_color() -> fz_string_t { .. }

Then use FzString::return_val to return the value:

// SAFETY:
//  - caller will free the returned string (see docstring)
unsafe {
    return FzString::return_val(color);
}

Example

See the kv example in this crate for a worked example of a simple library using ffizz_string.

Performance

The implementation is general-purpose, and may result in more allocations or string copies than strictly necessary. This is particularly true if the Rust implementation immediately converts FzString into std::string::String. This conversion brings great simplicity, but involves an allocation and a copy of the string.

In situations where API performance is critical, it may be preferable to create a purpose-specific string implementation, perhaps inspired by this crate.

Structs

EmbeddedNulError

EmbeddedNulError indicates that the string contains embedded NUL bytes and could not be represented as a C string.

InvalidUTF8Error

InvalidUTF8Error indicates that the string contains invalid UTF-8 and could not be represented as a Rust string.

fz_string_t

fz_string_t represents a string suitable for use with this crate, as an opaque stack-allocated value.

Enums

FzString

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

Functions

fz_string_borrow^⚠

Create a new fz_string_t containing a pointer to the given C string.

fz_string_clone^⚠

Create a new fz_string_t by cloning the content of the given C string. The resulting fz_string_t is independent of the given string.

fz_string_clone_with_len^⚠

Create a new fz_string_t containing the given string with the given length. This allows creation of strings containing embedded NUL characters. As with fz_string_clone, the resulting fz_string_t is independent of the passed buffer.

fz_string_content^⚠

Get the content of the string as a regular C string.

fz_string_content_with_len^⚠

Get the content of the string as a pointer and length.

fz_string_free^⚠

Free a fz_string_t.

fz_string_is_null^⚠

Determine whether the given fz_string_t is a Null variant.

fz_string_null^⚠

Create a new, null fz_string_t. Note that this is not the zero value of fz_string_t.