Struct Value 

#[non_exhaustive]
pub struct Value<RType, CType>
where
    RType: Sized,
    CType: Sized + From<RType> + Into<RType>,
{ /* private fields */ }

Value is used to “pass by value’ semantics.

This is typically used for Copy types, such as integers or enums. For types that are not Copy, crate::Unboxed is a better choice.

The two type parameters must be convertible using Into<RType> for CType and From<RType> for CType. This choice of traits was made deliberately, on the assumption that CType is defined locally to your crate, while RType may be a type from another crate.

Example

Define your C and Rust types, then a type alias parameterizing Value:

#[repr(C)]
pub struct uuid_t([u8; 16]);

type UuidValue = Value<Uuid, uuid_t>;

Then call static mtehods on that type alias.

Implementations

impl<RType, CType> Value<RType, CType>

where RType: Sized, CType: Sized + From<RType> + Into<RType>,

pub fn take(cval: CType) -> RType

Take a CType and return an owned value.

The caller retains a copy of the value.

Examples found in repository

examples/uuid.rs (line 55)

pub unsafe extern "C" fn uuid_version(uuid: uuid_t) -> usize {
    // SAFETY:
    //  - tcuuid is a valid uuid_t (all byte patterns are valid)
    let uuid = unsafe { UuidValue::take(uuid) };
    uuid.get_version_num()
}

/// Write the string representation of a uuid_t into the given buffer, which must be
/// at least UUID_STRING_BYTES long.  No NUL terminator is added.
///
/// # Safety
///
/// * buf must point to at least UUID_STRING_BYTES of valid memory.
#[no_mangle]
pub unsafe extern "C" fn uuid_to_buf(tcuuid: uuid_t, buf: *mut c_char) {
    debug_assert!(!buf.is_null());
    // SAFETY:
    //  - buf is valid for len bytes (by C convention)
    //  - (no alignment requirements for a byte slice)
    //  - content of buf will not be mutated during the lifetime of this slice (lifetime
    //    does not outlive this function call)
    //  - the length of the buffer is less than isize::MAX (see docstring)
    let buf: &mut [u8] =
        unsafe { std::slice::from_raw_parts_mut(buf as *mut u8, UUID_STRING_BYTES) };
    // SAFETY:
    //  - tcuuid is a valid uuid_t (all byte patterns are valid)
    let uuid = unsafe { UuidValue::take(tcuuid) };
    uuid.as_hyphenated().encode_lower(buf);
}

pub fn return_val(rval: RType) -> CType

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

Examples found in repository

examples/uuid.rs (line 39)

pub unsafe extern "C" fn uuid_new_v4() -> uuid_t {
    // SAFETY:
    // - value is not allocated
    unsafe { UuidValue::return_val(uuid::Uuid::new_v4()) }
}

/// Create a new UUID with the nil value.
#[no_mangle]
pub unsafe extern "C" fn uuid_nil() -> uuid_t {
    // SAFETY:
    // - value is not allocated
    unsafe { UuidValue::return_val(uuid::Uuid::nil()) }
}

examples/status.rs (line 237)

pub unsafe extern "C" fn hittr_system_status(system: *const System) -> hittr_status_t {
    // SAFETY:
    // - system is not NULL and valid (see docstring)
    // - system is valid for the life of this function (documented as not threadsafe)
    // - system will not be modified during the life of this function (documented as not threadsafe)
    unsafe {
        BoxedSystem::with_ref_nonnull(system, |system| {
            // SAFETY:
            // - hittr_status_t is not allocated, so no issues
            unsafe { StatusValue::return_val(system.status) }
        })
    }
}

pub unsafe fn to_out_param(rval: RType, arg_out: *mut CType)

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

If the pointer is NULL, rval is dropped. Use Value::to_out_param_nonnull to panic in this situation.

Safety

• if arg_out is not NULL, then it must be aligned for and have enough space for CType.

Examples found in repository

examples/uuid.rs (line 102)

pub unsafe extern "C" fn uuid_from_str(s: *const c_char, uuid_out: *mut uuid_t) -> bool {
    debug_assert!(!s.is_null());
    debug_assert!(!uuid_out.is_null());
    // SAFETY:
    //  - s is valid (see docstring)
    let s = unsafe { CStr::from_ptr(s) };
    if let Ok(s) = s.to_str() {
        if let Ok(u) = uuid::Uuid::parse_str(s) {
            // SAFETY:
            //  - uuid_out is not NULL (see docstring)
            //  - alignment is not required
            unsafe { UuidValue::to_out_param(u, uuid_out) };
            return true;
        }
    }
    false
}

pub unsafe fn to_out_param_nonnull(rval: RType, arg_out: *mut CType)

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

If the pointer is NULL, this method will panic.

Safety

• arg_out must not be NULL, must be aligned for CType and have enough space for CType.