Struct jlrs::value::array::Array

#[repr(transparent)]pub struct Array<'frame, 'data>(_, _, _);

An n-dimensional Julia array. This struct implements JuliaTypecheck and Cast. It can be used in combination with DataType::is and Value::is; if the check returns true the Value can be cast to Array:

julia.frame(1, |_global, frame| {
    let arr = Value::new_array::<f64, _, _>(frame, (3, 3))?;
    assert!(arr.is::<Array>());
    assert!(arr.cast::<Array>().is_ok());
    Ok(())
}).unwrap();

Each element in the backing storage is either stored as a Value or inline. You can check how the data is stored by calling Array::is_value_array or Array::is_inline_array. Note that this is not necessarily consistent across different versions of Julia; the array might be value array in Julia 1.0, but an inline array in Julia 1.4. If you want to ensure the data is not stored inline, you should use a mutable struct as the element type.

Arrays that contain integers or floats are an example of inline arrays. Their data is stored as an array that contains numbers of the appropriate type, for example an array of Float32s in Julia is backed by an an array of f32s. The data of these arrays can be accessed with Array::inline_data and Array::inline_data_mut, and copied from Julia to Rust with Array::copy_inline_data. In order to call these methods the type of the elements must be provided, arrays that contain numbers can be accessed by providing the appropriate Rust type (eg f32 for Float32 and u64 for UInt64).

More complex inlined data is supported through two custom derives: JuliaTuple and JuliaStruct. Accessing inline array data is not supported if the data contains inlined unions, Values or other pointers.

If the data isn't inlined each element is stored as a Value. This data can be accessed using Array::value_data and Array::value_data_mut but this is unsafe.

Implementations

impl<'frame, 'data> Array<'frame, 'data>

pub fn dimensions(self) -> Dimensions

Returns the array's dimensions.

pub fn contains<T: JuliaType>(self) -> bool

Returns true if the type of the elements of this array is T.

pub fn contains_inline<T: JuliaType>(self) -> bool

Returns true if the type of the elements of this array is T and these elements are stored inline.

pub fn is_inline_array(self) -> bool

Returns true if the elements of the array are stored inline.

pub fn has_inlined_pointers(self) -> bool

Returns true if the elements of the array are stored inline and at least one of the field of the inlined type is a pointer. If this returns true the data cannot be accessed from Rust.

pub fn is_value_array(self) -> bool

Returns true if the elements of the array are stored as Values.

pub fn copy_inline_data<T>(self) -> JlrsResult<CopiedArray<T>> where
    T: JuliaType, 

Copy the data of an inline array to Rust. Returns JlrsError::NotInline if the data is not stored inline or JlrsError::WrongType if the type of the elements is incorrect.

pub fn inline_data<'borrow, 'fr, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<ArrayData<'borrow, 'fr, T, F>> where
    T: JuliaType,
    F: Frame<'fr>, 

Immutably borrow inline array data, you can borrow data from multiple arrays at the same time. Returns JlrsError::NotInline if the data is not stored inline or JlrsError::WrongType if the type of the elements is incorrect.

pub fn inline_data_mut<'borrow, 'fr, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<InlineArrayDataMut<'borrow, 'fr, T, F>> where
    T: JuliaType,
    F: Frame<'fr>, 

Mutably borrow inline array data, you can mutably borrow a single array at the same time. Returns JlrsError::NotInline if the data is not stored inline or JlrsError::WrongType if the type of the elements is incorrect.

pub unsafe fn value_data<'borrow, 'fr, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<ArrayData<'borrow, 'fr, Value<'frame, 'data>, F>> where
    F: Frame<'fr>, 

Immutably borrow the data of this value array, you can borrow data from multiple arrays at the same time. The values themselves can be mutable, but you can't replace an element with another value. Returns JlrsError::Inline if the data is stored inline.

Safety: no slot on the GC stack is required to access and use the values in this array, the GC is aware of the array's data. If the element is changed either from Rust or Julia, the original value is no longer protected from garbage collection. If you need to keep using this value you must protect it by calling Value::extend.

pub unsafe fn value_data_mut<'borrow, 'fr, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<ValueArrayDataMut<'borrow, 'frame, 'data, 'fr, F>> where
    F: Frame<'fr>, 

Mutably borrow the data of this value array, you can mutably borrow a single array at the same time. Returns JlrsError::Inline if the data is stored inline.

Safety: no slot on the GC stack is required to access and use the values in this array, the GC is aware of the array's data. If the element is changed either from Rust or Julia, the original value is no longer protected from garbage collection. If you need to keep using this value you must protect it by calling Value::extend.

Trait Implementations

impl<'frame, 'data> Cast<'frame, 'data> for Array<'frame, 'data>

type Output = Self

fn cast(value: Value<'frame, 'data>) -> JlrsResult<Self::Output>

unsafe fn cast_unchecked<'fr, 'da>(value: Value<'frame, 'data>) -> Self::Output

impl<'frame, 'data> Clone for Array<'frame, 'data>

fn clone(&self) -> Array<'frame, 'data>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'frame, 'data> Copy for Array<'frame, 'data>

impl<'frame, 'data> Debug for Array<'frame, 'data>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'frame, 'data> JuliaTypecheck for Array<'frame, 'data>

unsafe fn julia_typecheck(t: DataType) -> bool