Module jlrs::convert::unbox

Extract the contents of a Julia value.

A Value contains a pointer to some data owned by Julia. The layout of this data depends on the DataType of the value. It’s often possible to provide a type defined in Rust that matches the layout of the data in Julia. For example, if the DataType is Int8, the pointer points to an i8. In order to extract the contents of a Value it must be unboxed. The Unbox trait defined in this module usually dereferences the pointer.

There are a few exceptions to this rule. In particular, unboxing a char or a bool results in a Char or a Bool respectively. The reason is that while using invalid Chars and Bools is an error in Julia, it’s undefined behavior to create them in Rust. Similarly, strings in Julia should be UTF-8 encoded, but to account for the possibility that the contents are invalid the implementation of Unbox returns a String if the contents are valid and a Vec<u8> if they’re not.

Unlike IntoJulia, the Unbox trait is not limited to bits-types. The only requirement is that the layout of the types in both languages match. Types that can be unboxed include those with pointer fields, type parameters, and bits unions. When wrappers are generated with JlrsReflect.jl Unbox is always derived. You should not implement this trait manually.

Traits

Unbox

Trait implemented by types that can be extracted from a Julia value in combination with Value::unbox and Value::unbox_unchecked. This trait can be derived, it’s recommended to use JlrsReflect.jl to ensure it’s implemented correctly. All wrappers generated by JlrsReflect.jl will implement this trait and ValidLayout, which checks if the conversion is valid at runtime.