Module array 

N-dimensional arrays

Julia has a generic array type, Array{T, N}. These arrays are column-major, N-dimensional arrays that can hold elements of type T.

jlrs provides a flexible base type that wraps instances of this type, ArrayBase. This type has two generics: a type constructor T, and a constant isize rank N. You shouldn’t use this type directly, but use the four available type aliases instead: Array, TypedArray, RankedArray, and TypedRankedArray. If Typed is missing from the name, the element type T is set to Unknown, if Ranked is missing the the rank N is set to -1.

There are several special aliases: Vector, VectorAny and TypedVector (rank 1), and Matrix and TypedMatrix (rank 2).

Converting between array types

The methods ArrayBase::set_rank and ArrayBase::set_type can be used to set the two generic parameters, ArrayBase::forget_rank and ArrayBase::forget_type lets you set them to -1 and Unknown respectively.

Constructing new arrays

Many methods that construct new arrays exist, they can be divided into several groups:

• new: Constructs a new array whose storage is managed by Julia.

• from_slice: Constructs a new array whose storage is borrowed from Rust.

• from_vec: Constructs a new array whose storage is moved from Rust.

• from_slice_cloned: Constructs a new array whose storage is managed by Julia, the elements are initialized by cloning a slice.

• from_slice_copied: Constructs a new array whose storage is managed by Julia, the elements are initialized by copying a slice.

These methods exist as named for typed arrays, the element type is constructed from the provided type parameter. Untyped arrays have *_for methods like new_for that take the element type as an argument. All these methods have unsafe, unchecked variants like new_for_unchecked.

One limitation of arrays that are backed by Rust data is that Julia is not able to reallocate this array. Functions that can reallocate, like push!, will throw an exception if they are called with such an array.

In addition to these generic constructors there are two specialized constructors: TypedVector<u8> can be constructed with from_bytes, which behaves as from_slice_copied does. VectorAny can be constructed with new_any, which behaves as new does.

Array data

In order to access the content of an array an accessor must be created first. There are several kinds of accessors to account for the different ways the elements can be laid out in memory.

Elements are either stored inline in the backing storage or as references. They are stored inline if they are immutable, concrete types. Unions of isbits types, i.e. immutable, concrete types which contain no references to other Julia data, are also stored inline. In this last case a type tag is stored for each element after the elements themselves. In all other cases, the elements are stored as references, i.e. as Option<WeakValue>.

For several reasons, some more technical than others, it’s useful to distinguish between isbits and “non-bits” immutable types. Similarly, for elements that are stored as references it can be useful to distinguish between arbitrary Values and more specific managed types. It’s also perfectly valid to not make any assumptions about the layout and only work with Values, allocating new Julia data whenever necessary.

Putting all of this together, we end up with the following accessors: BitsAccessor, InlineAccessor, BitsUnionAccessor, ValueAccessor, ManagedAccessor, and IndeterminateAccessor. There are also mutable variants of all of these accessors.

Depending on the element type parameter T and the traits it implements, it can be possible to infer that a certain accessor must be used. If this is the case, a method to create that accessor without performing any checks will be available. An example is ArrayBase::bits_data, which is only available if T: IsBits + ConstructType. If this information can’t be inferred from T, try_* and *_unchecked variants are available.

Tracking

It’s very easy to accidentally create multiple mutable accessors to the same array. In order to prevent this, you can track an array. You can either track an array exclusively or allow multiple shared references with ArrayBase::track_exclusive and ArrayBase::track_shared respectively. This dynamically enforces borrowing rules at runtime, but is limited. While it is thread-safe and even works across multiple packages, the tracking mechanism is unaware of how the data is used inside Julia. It won’t protect you from accessing an array that is currently being mutated by some Julia task running in the background. Tracking is also relatively expensive; if you can guarantee you are the only user of an array, e.g. you’ve just allocated it, you should avoid tracking the array.

Modules

data

The data of a Julia array.

dimensions

N-dimensional indexing.

tracked

Structs

ArrayBase

Wrapper type for an array of rank N whose element type is T.

Enums

How

How an array has been allocated

Unknown

Marker type used to indicate the element type of an array is unknown.

Traits

ConstructTypedArray

Constructor methods for typed arrays.

Type Aliases

Array

An array with an unknown element type and unknown rank.

ArrayBaseData

Array or WeakArray, depending on the target type T.

ArrayBaseResult

JuliaResult<Array> or WeakJuliaResult<WeakArray>, depending on the target type T.

ArrayData

ArrayResult

ArrayRet

Matrix

An array with an unknown element type of rank 2.

MatrixData

MatrixResult

MatrixRet

RankedArray

An array with an unknown element type and known rank.

RankedArrayData

RankedArrayResult

RankedArrayRet

TypedArray

An array with a known element type and unknown rank.

TypedArrayData

TypedArrayResult

TypedArrayRet

TypedMatrix

An array with a known element type of rank 2.

TypedMatrixData

TypedMatrixResult

TypedMatrixRet

TypedRankedArray

An array with a known element type and known rank.

TypedRankedArrayData

TypedRankedArrayResult

TypedRankedArrayRet

TypedVector

An array with a known element type of rank 1.

TypedVectorData

TypedVectorResult

TypedVectorRet

Vector

An array with an unknown element type of rank 1.

VectorAny

An array with an unknown element type of rank 1.

VectorAnyData

VectorAnyResult

VectorAnyRet

VectorData

VectorResult

VectorRet

WeakArray

WeakMatrix

WeakRankedArray

WeakTypedArray

WeakTypedMatrix

WeakTypedRankedArray

WeakTypedVector

WeakVector

WeakVectorAny