Struct jlrs::wrappers::ptr::array::Array

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

An n-dimensional Julia array. 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.scope(|_global, frame| {
    let arr = Array::new::<f64, _, _, _>(&mut *frame, (3, 3))?
        .into_jlrs_result()?;

    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. If the inline data is a bits union, the flag indicating the active variant is stored separately from the elements. You can check how the data is stored by calling Array::is_value_array, Array::is_inline_array, or Array::is_union_array.

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 in 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, this type must implement ValidLayout to ensure the layouts in Rust and Julia are compatible.

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.

Implementations

impl<'data> Array<'_, 'data>

pub fn new<'target, 'current, T, D, S, F>(
    scope: S,
    dims: D
) -> JlrsResult<S::JuliaResult> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Allocates a new n-dimensional array in Julia of dimensions dims. If dims = (4, 2) a two-dimensional array with 4 rows and 2 columns is created. This method can only be used in combination with types that implement IntoJulia. If you want to create an array for a type that doesn’t implement this trait you must use Array::new_for.

If the array size is too large, Julia will throw an error. This error is caught and returned.

pub fn new_unchecked<'target, 'current, T, D, S, F>(
    scope: S,
    dims: D
) -> JlrsResult<S::Value> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Allocates a new n-dimensional array in Julia of dimensions dims. If dims = (4, 2) a two-dimensional array with 4 rows and 2 columns is created. This method can only be used in combination with types that implement IntoJulia. If you want to create an array for a type that doesn’t implement this trait you must use Array::new_for.

If the array size is too large, the process will abort.

pub fn new_for<'target, 'current, D, S, F>(
    scope: S,
    dims: D,
    ty: Value<'_, '_>
) -> JlrsResult<S::JuliaResult> where
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Allocates a new n-dimensional array in Julia for elements of type ty, which must be a Union, UnionAll or DataType, and dimensions dims. If dims = (4, 2) a two-dimensional array with 4 rows and 2 columns is created. If an exception is thrown due to either the type or dimensions being invalid it’s caught and returned.

pub fn new_for_unchecked<'target, 'current, D, S, F>(
    scope: S,
    dims: D,
    ty: Value<'_, '_>
) -> JlrsResult<S::Value> where
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Allocates a new n-dimensional array in Julia for elements of type ty, which must be a Union, UnionAll or DataType, and dimensions dims. If dims = (4, 2) a two-dimensional array with 4 rows and 2 columns is created. If an exception is thrown due to either the type or dimensions being invalid the process aborts.

pub fn from_slice<'target, 'current, T, D, S, F>(
    scope: S,
    data: &'data mut [T],
    dims: D
) -> JlrsResult<S::Value> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, 'data, F>,
    F: Frame<'current>, 

Borrows an n-dimensional array from Rust for use in Julia with dimensions dims. If dims = (4, 2)` a two-dimensional array with 4 rows and 2 columns is created.

pub fn from_vec<'target, 'current, T, D, S, F>(
    scope: S,
    data: Vec<T>,
    dims: D
) -> JlrsResult<S::Value> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Moves an n-dimensional array from Rust for use in Julia with dimensions dims. If dims = (4, 2) a two-dimensional array with 4 rows and 2 columns is created.

pub fn from_string<'target, 'current, A: AsRef<str>, S, F>(
    scope: S,
    data: A
) -> JlrsResult<S::Value> where
    A: IntoJulia,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Convert a string to an array.

impl<'scope, 'data> Array<'scope, 'data>

pub fn dimensions(self) -> ArrayDimensions<'scope>

Returns the array’s dimensions.

pub fn element_type(self) -> Value<'scope, 'static>

Returns the type of this array’s elements.

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

Returns true if the layout of the elements is compatible with T.

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

Returns true if the layout of the elements is compatible with 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 is_union_array(self) -> bool

Returns true if the elements of the array are stored inline and the element type is a union type. In this case the contents of the array can be accessed from Rust with Array::union_data and Array::union_data_mut.

pub fn has_inlined_pointers(self) -> bool

Returns true if the elements of the array are stored inline and at least one of the fields of the inlined type is a pointer.

pub fn zero_init(self) -> bool

Returns true if elements of this array are zero-initialized.

pub fn is_value_array(self) -> bool

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

pub fn as_typed_array<T>(self) -> JlrsResult<TypedArray<'scope, 'data, T>> where
    T: Clone + ValidLayout + Debug, 

Convert this untyped array to a TypedArray.

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

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, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<InlineArrayData<'borrow, 'scope, 'data, T>> where
    T: ValidLayout,
    F: Frame<'frame>, 

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, 'frame, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<InlineArrayDataMut<'borrow, 'scope, 'data, T>> where
    'borrow: 'data,
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably borrow inline array data, you can mutably borrow a single array at a 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 unrestricted_inline_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<UnrestrictedInlineArrayDataMut<'borrow, 'scope, 'data, T>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably borrow inline array data without the restriction that only a single array can be mutably borrowed. It’s your responsibility to ensure you don’t create multiple mutable references to the same array data.

Returns JlrsError::NotInline if the data is not stored inline or JlrsError::WrongType if the type of the elements is incorrect.

pub fn value_data<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<ValueArrayData<'borrow, 'scope, 'data>> where
    F: Frame<'frame>, 

Immutably borrow the data of this array of values, 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.

pub fn wrapper_data<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<ValueArrayData<'borrow, 'scope, 'data, T>> where
    F: Frame<'frame>,
    T: Wrapper<'scope, 'data>,
    T::Ref: ValidLayout, 

Immutably borrow the data of this array of wrappers, 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.

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

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

pub fn wrapper_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<ValueArrayDataMut<'borrow, 'scope, 'data, T>> where
    F: Frame<'frame>,
    T: Wrapper<'scope, 'data>,
    T::Ref: ValidLayout, 

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

pub unsafe fn unrestricted_value_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<UnrestrictedValueArrayDataMut<'borrow, 'scope, 'data>> where
    F: Frame<'frame>, 

Mutably borrow the data of this array of values without the restriction that only a single array can be mutably borrowed. It’s your responsibility to ensure you don’t create multiple mutable references to the same array data. Returns JlrsError::Inline if the data is stored inline.

pub unsafe fn unrestricted_wrapper_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<UnrestrictedValueArrayDataMut<'borrow, 'scope, 'data, T>> where
    F: Frame<'frame>,
    T: Wrapper<'scope, 'data>, 

Mutably borrow the data of this array of wrappers without the restriction that only a single array can be mutably borrowed. It’s your responsibility to ensure you don’t create multiple mutable references to the same array data. Returns JlrsError::Inline if the data is stored inline.

impl<'scope> Array<'scope, 'static>

pub fn union_data<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<UnionArrayData<'borrow, 'scope>> where
    F: Frame<'frame>, 

Access the contents of a bits-union array.

pub fn union_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<UnionArrayDataMut<'borrow, 'scope>> where
    F: Frame<'frame>, 

Mutably borrow the data of this array of bits-unions, you can mutably borrow a single array at a time.

pub unsafe fn unrestricted_union_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<UnresistrictedUnionArrayDataMut<'borrow, 'scope>> where
    F: Frame<'frame>, 

Mutably borrow the data of this array of bits-unions without the restriction that only a single array can be mutably borrowed. It’s your responsibility to ensure you don’t create multiple mutable references to the same array data.

impl<'scope> Array<'scope, 'static>

pub fn reshape<'target, 'current, D, S, F>(
    self,
    scope: S,
    dims: D
) -> JlrsResult<S::JuliaResult> where
    D: Dims,
    S: Scope<'target, 'current, 'static, F>,
    F: Frame<'current>, 

Reshape the array, a new array is returned that has dimensions dims. This new array and self share their data. This method returns an exception if the old and new array have a different number of elements or if the array contains data that has been borrowed or moved from Rust.

pub fn grow_end<'current, F>(
    self,
    frame: &mut F,
    inc: usize
) -> JlrsResult<JuliaResult<'current, 'static, ()>> where
    F: Frame<'current>, 

Inserts inc more elements at the end of the array. The array must be 1D and contain no data borrowed or moved from Rust, otherwise an exception is returned. Depending on the type of the array elements the newly added elements will either be left uninitialized, or their contents will be set to 0s. It’s set to 0s if DataType::zero_init returns true, if the elements are stored as pointers to Julia data, or if the elements contain pointers to Julia data.

pub fn del_end<'current, F>(
    self,
    frame: &mut F,
    dec: usize
) -> JlrsResult<JuliaResult<'current, 'static, ()>> where
    F: Frame<'current>, 

Removes the final dec elements from the array. The array must be 1D and contain no data borrowed or moved from Rust, otherwise an exception is returned.

pub fn grow_begin<'current, F>(
    self,
    frame: &mut F,
    inc: usize
) -> JlrsResult<JuliaResult<'current, 'static, ()>> where
    F: Frame<'current>, 

Inserts inc more elements at the beginning of the array. The array must be 1D and contain no data borrowed or moved from Rust, otherwise an exception is returned. Depending on the type of the array elements the newly added elements will either be left uninitialized, or their contents will be set to 0s. It’s set to 0s if DataType::zero_init returns true, if the elements are stored as pointers to Julia data, or if the elements contain pointers to Julia data.

pub fn del_begin<'current, F>(
    self,
    frame: &mut F,
    dec: usize
) -> JlrsResult<JuliaResult<'current, 'static, ()>> where
    F: Frame<'current>, 

Removes the first dec elements from the array. The array must be 1D and contain no data borrowed or moved from Rust, otherwise an exception is returned.

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Array<'_, '_>

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

Formats the value using the given formatter.

impl<'frame: 'borrow, 'data: 'borrow, 'borrow, T: ValidLayout + Clone> NdArray<'borrow, T> for Array<'frame, 'data>

fn array_view<'fr: 'borrow, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<ArrayView<'borrow, T, Dim<IxDynImpl>>> where
    F: Frame<'fr>,
    T: ValidLayout + Clone, 

Borrow the data in the array as an ArrayView. Returns an error if the wrong type is provided or the data is not stored inline.

fn array_view_mut<'fr: 'borrow, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<ArrayViewMut<'borrow, T, Dim<IxDynImpl>>> where
    F: Frame<'fr>,
    T: ValidLayout + Clone, 

Mutably borrow the data in the array as an ArrayViewMut. Returns an error if the wrong type is provided or the data is not stored inline.

impl<'scope, 'data> ValidLayout for Array<'scope, 'data>

fn valid_layout(v: Value<'_, '_>) -> bool

Check if the layout of the implementor is compatible with the layout of ty. This argument is a Value to account for the fact that a field type can be a Union, UnionAll or Union{}.

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

impl<'scope, 'data> Typecheck for Array<'scope, 'data>