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

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

An n-dimensional Julia array.

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 examples 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<JuliaResult<'target, 'static, Array<'target, 'static>>> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, F>,
    F: Frame<'current>, 

Allocate a new n-dimensional Julia array of dimensions dims for data of type T.

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 unsafe fn new_unchecked<'target, 'current, T, D, S, F>(
    scope: S,
    dims: D
) -> JlrsResult<Array<'target, 'static>> where
    T: IntoJulia,
    D: Dims,
    S: Scope<'target, 'current, F>,
    F: Frame<'current>, 

Allocate a new n-dimensional Julia array of dimensions dims for data of type T.

This method is equivalent to Array::new except that Julia exceptions are not caught.

Safety: If the array size is too large, Julia will throw an error. This error is not caught, which is UB from a ccalled function.

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

Allocate a new n-dimensional Julia array of dimensions dims for data of type ty.

The elementy type, ty must be a Union, UnionAllorDataType`.

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

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

Allocate a new n-dimensional Julia array of dimensions dims for data of type T.

This method is equivalent to Array::new_for except that Julia exceptions are not caught.

Safety: If the array size is too large or if the type is invalid, Julia will throw an error. This error is not caught, which is UB from a ccalled function.

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

Create a new n-dimensional Julia array of dimensions dims that borrows data from Rust.

This method can only be used in combination with types that implement IntoJulia. Because the data is borrowed from Rust, operations that can change the size of the array (e.g. push!) will fail.

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

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

Create a new n-dimensional Julia array of dimensions dims that borrows data from Rust.

This method can only be used in combination with types that implement IntoJulia. Because the data is borrowed from Rust, operations that can change the size of the array (e.g. push!) will fail.

Safety: If the array size is too large, Julia will throw an error. This error is not caught, which is UB from a ccalled function.

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

Create a new n-dimensional Julia array of dimensions dims that takes ownership of Rust data.

This method can only be used in combination with types that implement IntoJulia. Because the data is allocated by Rust, operations that can change the size of the array (e.g. push!) will fail.

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

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

Create a new n-dimensional Julia array of dimensions dims that takes ownership of Rust data.

This method can only be used in combination with types that implement IntoJulia. Because the data is allocated by Rust, operations that can change the size of the array (e.g. push!) will fail.

Safety: If the array size is too large, Julia will throw an error. This error is not caught, which is UB from a ccalled function.

pub fn from_string<'target, A, S>(
    scope: S,
    data: A
) -> JlrsResult<Array<'target, 'static>> where
    A: AsRef<str>,
    S: PartialScope<'target>, 

Convert a string to a Julia array.

pub fn root<'target>(self, output: Output<'target>) -> Array<'target, 'data>

Use the Output to extend the lifetime of this data.

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 element_size(self) -> usize

Returns the size 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.

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 try_as_typed<T>(self) -> JlrsResult<TypedArray<'scope, 'data, T>> where
    T: Clone + ValidLayout + Debug, 

Convert this untyped array to a TypedArray.

pub unsafe fn as_typed_unchecked<T>(self) -> TypedArray<'scope, 'data, T> where
    T: Clone + ValidLayout, 

Convert this untyped array to a TypedArray without checking if this conversion is valid.

Safety: T must be a valid representation of the data stored in the array.

pub fn copy_inline_data<'frame, T, F>(self, _: &F) -> JlrsResult<CopiedArray<T>> where
    T: 'static + ValidLayout,
    F: Frame<'frame>, 

Copy the data of an inline array to Rust.

Returns ArrayLayoutError::NotInline if the data is not stored inline or AccessError::InvalidLayout if the type of the elements is incorrect.

pub fn bits_data<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<BitsArrayAccessor<'borrow, 'scope, 'data, T, Immutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Immutably the contents of this array. The elements must have an isbits type.

You can borrow data from multiple arrays at the same time.

Returns ArrayLayoutError::NotInline if the data is not stored inline, ArrayLayoutError::NotBits if the type is not an isbits type, or AccessError::InvalidLayout if T is not a valid layout for the array elements.

pub unsafe fn bits_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<BitsArrayAccessor<'borrow, 'scope, 'data, T, Mutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably access the contents of this array. The elements must have an isbits type.

This method can be used to gain mutable access to the contents of a single array.

Returns ArrayLayoutError::NotInline if the data is not stored inline, ArrayLayoutError::NotBits if the type is not an isbits type, or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

pub unsafe fn unrestricted_bits_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<BitsArrayAccessor<'borrow, 'scope, 'data, T, Mutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably access the contents of this array. The elements must have an isbits type.

Unlike Array::bits_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Returns ArrayLayoutError::NotInline if the data is not stored inline, ArrayLayoutError::NotBits if the type is not an isbits type, or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

pub fn inline_data<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<InlinePtrArrayAccessor<'borrow, 'scope, 'data, T, Immutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Immutably the contents of this array. The elements must be stored inline.

You can borrow data from multiple arrays at the same time.

Returns ArrayLayoutError::NotInline if the data is not stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

pub unsafe fn inline_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<InlinePtrArrayAccessor<'borrow, 'scope, 'data, T, Mutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably access the contents of this array. The elements must be stored inline.

This method can be used to gain mutable access to the contents of a single array.

Returns ArrayLayoutError::NotInline if the data is not stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

pub unsafe fn unrestricted_inline_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<InlinePtrArrayAccessor<'borrow, 'scope, 'data, T, Mutable<'borrow, T>>> where
    T: ValidLayout,
    F: Frame<'frame>, 

Mutably access the contents of this array. The elements must be stored inline.

Unlike Array::inline_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Returns ArrayLayoutError::NotInline if the data is not stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

pub fn wrapper_data<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow F
) -> JlrsResult<PtrArrayAccessor<'borrow, 'scope, 'data, T, Immutable<'borrow, T>>> where
    T: WrapperRef<'scope, 'data>,
    F: Frame<'frame>, 

Immutably the contents of this array. The elements must not be stored inline.

You can borrow data from multiple arrays at the same time.

Returns ArrayLayoutError::NotPointer if the data is stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

pub unsafe fn wrapper_data_mut<'borrow, 'frame, T, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<PtrArrayAccessor<'borrow, 'scope, 'data, T, Mutable<'borrow, T>>> where
    T: WrapperRef<'frame, 'data>,
    F: Frame<'frame>, 

Mutably access the contents of this array. The elements must not be stored inline.

This method can be used to gain mutable access to the contents of a single array.

Returns ArrayLayoutError::NotPointer if the data is stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

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

Mutably access the contents of this array. The elements must not be stored inline.

Unlike Array::wrapper_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Returns ArrayLayoutError::NotPointer if the data is stored inline or AccessError::InvalidLayout if T is not a valid layout for the array elements.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

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

Immutably the contents of this array. The elements must not be stored inline.

You can borrow data from multiple arrays at the same time.

Returns ArrayLayoutError::NotPointer if the data is stored inline.

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

Mutably access the contents of this array. The elements must not be stored inline.

This method can be used to gain mutable access to the contents of a single array.

Returns ArrayLayoutError::NotPointer if the data is stored inline.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

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

Mutably access the contents of this array. The elements must not be stored inline.

Unlike Array::value_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Returns ArrayLayoutError::NotPointer if the data is stored inline.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

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

Immutably access the contents of this array. The element type must be a bits union type.

You can borrow data from multiple arrays at the same time.

Returns ArrayLayoutError::NotUnion if the data is not stored as a bits union.

pub unsafe fn union_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow mut F
) -> JlrsResult<UnionArrayAccessor<'borrow, 'scope, 'data, Mutable<'borrow, u8>>> where
    F: Frame<'frame>, 

Mutably access the contents of this array. The element type must be a bits union.

This method can be used to gain mutable access to the contents of a single array.

Returns ArrayLayoutError::NotUnion if the data is not stored as a bits union.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

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

Mutably access the contents of this array. The element type must be a bits union.

Unlike Array::union_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Returns ArrayLayoutError::NotUnion if the data is not stored as a bits union.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

pub fn indeterminate_data<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> IndeterminateArrayAccessor<'borrow, 'scope, 'data, Immutable<'borrow, u8>> where
    F: Frame<'frame>, 

Immutably access the contents of this array.

You can borrow data from multiple arrays at the same time.

pub unsafe fn indeterminate_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow mut F
) -> IndeterminateArrayAccessor<'borrow, 'scope, 'data, Mutable<'borrow, u8>> where
    F: Frame<'frame>, 

Mutably access the contents of this array.

This method can be used to gain mutable access to the contents of a single array.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed.

pub unsafe fn unrestricted_indeterminate_data_mut<'borrow, 'frame, F>(
    self,
    frame: &'borrow F
) -> IndeterminateArrayAccessor<'borrow, 'scope, 'data, Mutable<'borrow, u8>> where
    F: Frame<'frame>, 

Mutably access the contents of this array.

Unlike Array::indeterminate_data_mut, this method can be used to gain mutable access to the contents of multiple arrays simultaneously.

Safety: Mutating Julia data is generally unsafe because it can’t be guaranteed mutating this value is allowed. This method can create multiple mutable references to the same data.

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

Reshape the array, a new array is returned that has dimensions dims. The new array and self share their data.

This method returns an exception if the old and new array have a different number of elements.

pub unsafe fn reshape_unchecked<'target, 'current, D, S, F>(
    self,
    scope: S,
    dims: D
) -> JlrsResult<Array<'target, 'data>> where
    D: Dims,
    S: Scope<'target, 'current, F>,
    F: Frame<'current>, 

Reshape the array, a new array is returned that has dimensions dims. The new array and self share their data.

Safety: If the dimensions are incompatible with the array size, Julia will throw an error. This error is not caught, which is UB from a ccalled function.

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

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

Insert inc elements at the end of the array.

The array must be 1D and not contain data borrowed or moved from Rust, otherwise an exception is returned.

pub unsafe fn grow_end_unchecked<'current, F>(self, _: &mut F, inc: usize) where
    F: Frame<'current>, 

Insert inc elements at the end of the array.

Safety: the array must be 1D and not contain data borrowed or moved from Rust, otherwise Julia throws an exception. This error is not exception, which is UB from a ccalled function.

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

Remove dec elements from the end of the array.

The array must be 1D, not contain data borrowed or moved from Rust, otherwise an exception is returned.

pub unsafe fn del_end_unchecked<'current, F>(self, _: &mut F, dec: usize) where
    F: Frame<'current>, 

Remove dec elements from the end of the array.

Safety: the array must be 1D and not contain data borrowed or moved from Rust, otherwise Julia throws an exception. This error is not exception, which is UB from a ccalled function.

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

Insert inc elements at the beginning of the array.

The array must be 1D, not contain data borrowed or moved from Rust, otherwise an exception is returned.

pub unsafe fn grow_begin_unchecked<'current, F>(self, _: &mut F, inc: usize) where
    F: Frame<'current>, 

Insert inc elements at the beginning of the array.

Safety: the array must be 1D and not contain data borrowed or moved from Rust, otherwise Julia throws an exception. This error is not exception, which is UB from a ccalled function.

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

Remove dec elements from the beginning of the array.

The array must be 1D, not contain data borrowed or moved from Rust, otherwise an exception is returned.

pub unsafe fn del_begin_unchecked<'current, F>(self, _: &mut F, dec: usize) where
    F: Frame<'current>, 

Remove dec elements from the beginning of the array.

Safety: the array must be 1D and not contain data borrowed or moved from Rust, otherwise Julia throws an exception. This error is not exception, which is UB from a ccalled function.

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<'scope, 'data> Copy for Array<'scope, 'data>

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