Module translate

Source
Expand description

Translation between GLib/GLib-based FFI types and their Rust counterparts.

This module allows library bindings authors to decouple type translation logic and use unified idioms at FFI boundaries. It also implements translation of GLib core data types.

FromGlib, from_glib and IntoGlib translate simple types like bool.

    pub fn set_accept_focus(&self, accept_focus: bool) {
        unsafe { gdk::ffi::gdk_window_set_accept_focus(self.pointer, accept_focus.into_glib()) }
    }

    pub fn get_accept_focus(&self) -> bool {
        unsafe { from_glib(gdk::ffi::gdk_window_get_accept_focus(self.pointer)) }
    }

Implementing OptionIntoGlib on a Rust type T allows specifying a sentinel to indicate a None value and auto-implementing FromGlib for Option<T>, which would not be possible in dependent crates due to the orphan rule. In the example below, IntoGlib is auto-implemented for Option<SpecialU32>.

struct SpecialU32(u32);
impl IntoGlib for SpecialU32 {
    type GlibType = libc::c_uint;
    fn into_glib(self) -> libc::c_uint {
        self.0 as libc::c_uint
    }
}
impl OptionIntoGlib for SpecialU32 {
    const GLIB_NONE: Self::GlibType = 0xFFFFFF;
}

In order to auto-implement FromGlib for Option<SpecialU32>, proceed as follows:

impl TryFromGlib<libc::c_uint> for SpecialU32 {
    type Error = GlibNoneError;
    unsafe fn try_from_glib(val: libc::c_uint) -> Result<Self, GlibNoneError> {
        if val == SpecialU32::GLIB_NONE {
            return Err(GlibNoneError);
        }
        Ok(SpecialU32(val as u32))
    }
}

The TryFromGlib trait can also be implemented when the Glib type range is larger than the target Rust type’s range. In the example below, the Rust type U32 can be built from a signed [libc::c_long], which means that the negative range is not valid.

struct U32(u32);
impl TryFromGlib<libc::c_long> for U32 {
    type Error = TryFromIntError;
    unsafe fn try_from_glib(val: libc::c_long) -> Result<Self, TryFromIntError> {
        Ok(U32(u32::try_from(val)?))
    }
}

Finally, you can define TryFromGlib with both None and Invalid alternatives by setting the associated type Error = GlibNoneOrInvalidError<I> (where I is the Error type when the value is invalid), which results in auto-implementing FromGlib for Result<Option<T>, I>.

ToGlibPtr, FromGlibPtrNone, FromGlibPtrFull and FromGlibPtrBorrow work on gpointers and ensure correct ownership of values according to Glib ownership transfer rules.

FromGlibPtrNone and FromGlibPtrFull must be called on values obtained from C, according to their transfer annotations. They acquire non-gobject types, as well as turning floating references to strong ones, which are the only ones properly handled by the Rust bindings.

For more information about floating references, please refer to the “Floating references” section of the gobject reference.

    fn get_title(&self) -> Option<String> {
        unsafe {
            let title = gtk::ffi::gtk_window_get_title(self.pointer);
            from_glib_none(title)
        }
    }
    fn create_bool(value: gboolean) -> Variant {
        unsafe {
            let variant = ffi::g_variant_new_boolean(value);
            // g_variant_new_boolean has `transfer none`
            from_glib_none(variant)
        }
    }

Letting the foreign library borrow pointers from the Rust side often requires having a temporary variable of an intermediate type (e.g. CString). A Stash contains the temporary storage and a pointer into it that is valid for the lifetime of the Stash. As the lifetime of the Stash returned from to_glib_none is at least the enclosing statement, you can avoid explicitly binding the stash in most cases and just take the pointer out of it:

    pub fn set_icon_name(&self, name: &str) {
        unsafe {
            gdk::ffi::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0)
        }
    }

Re-exports§

pub use crate::collections::ptr_slice::IntoPtrSlice;
pub use crate::collections::strv::IntoStrV;

Structs§

Borrowed
Wrapper around values representing borrowed C memory.
GlibNoneError
Error type for TryFromGlib when the Glib value is None.
HashTable
List
PtrArray
SList
Stash
Helper type that stores temporary values used for translation.
StashMut

Enums§

GlibNoneOrInvalidError
Error type for TryFromGlib when the Glib value can be None or invalid.

Traits§

FromGlib
Translate a simple type.
FromGlibContainer
Translate from a container.
FromGlibContainerAsVec
FromGlibPtrArrayContainerAsVec
FromGlibPtrBorrow
Translate from a pointer type by borrowing, without affecting the refcount.
FromGlibPtrContainer
Translate from a container of pointers.
FromGlibPtrFull
Translate from a pointer type which is annotated with transfer full. This transfers the ownership of the value to the Rust side.
FromGlibPtrNone
Translate from a pointer type which is annotated with transfer none. The resulting value is referenced at least once, by the bindings.
GlibPtrDefault
Provides the default pointer type to be used in some container conversions.
IntoGStr
A trait to accept both &str or &GStr as an argument.
IntoGlib
Translate a simple type.
IntoGlibPtr
Translate to a pointer.
IntoOptionalGStr
A trait to accept both Option<&str> or Option<&GStr> as an argument.
OptionIntoGlib
A Rust type T for which Option<T> translates to the same glib type as T.
Ptr
A pointer
ToGlibContainerFromSlice
ToGlibPtr
Translate to a pointer.
ToGlibPtrMut
Translate to a pointer with a mutable borrow.
TransparentPtrType
Trait for types that have the same memory representation as a pointer to their FFI type.
TransparentType
Trait for types that have the same memory representation as their FFI type.
TryFromGlib
Translate from a Glib type which can result in an undefined and/or invalid value.
Uninitialized
A trait for creating an uninitialized value. Handy for receiving outparams.
UnsafeFrom
Unsafe variant of the From trait.

Functions§

c_ptr_array_len
const_override
Overrides pointer constness.
from_glib
Translate a simple type.
from_glib_borrow
Translate from a pointer type, borrowing the pointer.
from_glib_full
Translate from a pointer type, transfer: full (assume ownership).
from_glib_none
Translate from a pointer type, transfer: none.
mut_override
Overrides pointer mutability.
try_from_glib
Translate from a Glib type which can result in an undefined and/or invalid value.
uninitialized
Returns an uninitialized value.