API

contiguous_axis(::Type{T}) -> StaticInt{N}

Returns the axis of an array of type T containing contiguous data. If no axis is contiguous, it returns a StaticInt{-1}. If unknown, it returns nothing.

contiguous_axis_indicator(::Type{T}) -> Tuple{Vararg{StaticBool}}

Returns a tuple boolean Vals indicating whether that axis is contiguous.

contiguous_batch_size(::Type{T}) -> StaticInt{N}

Returns the Base.size of contiguous batches if !isone(stride_rank(T, contiguous_axis(T))). If isone(stride_rank(T, contiguous_axis(T))), then it will return StaticInt{0}(). If contiguous_axis(T) == -1, it will return StaticInt{-1}(). If unknown, it will return nothing.

dimnames(x) -> Tuple{Vararg{Union{Symbol,StaticSymbol}}}
dimnames(x, dim::Union{Int,StaticInt}) -> Union{Symbol,StaticSymbol}

Return the names of the dimensions for x. :_ is used to indicate a dimension does not have a name.

has_dimnames(::Type{T}) -> Bool

Returns true if x has on or more named dimensions. If all dimensions correspond to :_, then false is returned.

has_parent(::Type{T}) -> StaticBool

Returns static(true) if parent_type(T) a type unique to T.

is_column_major(A) -> StaticBool

Returns True() if elements of A are stored in column major order. Otherwise returns False().

is_lazy_conjugate(::AbstractArray) -> Bool

Determine if a given array will lazyily take complex conjugates, such as with Adjoint. This will work with nested wrappers, so long as there is no type in the chain of wrappers such that parent_type(T) == T

Examples

julia> a = transpose([1 + im, 1-im]')
2×1 transpose(adjoint(::Vector{Complex{Int64}})) with eltype Complex{Int64}:
 1 - 1im
 1 + 1im

julia> is_lazy_conjugate(a)
True()

julia> b = a'
1×2 adjoint(transpose(adjoint(::Vector{Complex{Int64}}))) with eltype Complex{Int64}:
 1+1im  1-1im

julia> is_lazy_conjugate(b)
False()

is_splat_index(::Type{T}) -> Bool

Returns static(true) if T is a type that splats across multiple dimensions.

known_dimnames(::Type{T}) -> Tuple{Vararg{Union{Symbol,Nothing}}}
known_dimnames(::Type{T}, dim::Union{Int,StaticInt}) -> Union{Symbol,Nothing}

Return the names of the dimensions for x. :_ is used to indicate a dimension does not have a name.

known_first(::Type{T}) -> Union{Int,Nothing}

If first of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> known_first(typeof(1:4))
nothing

julia> known_first(typeof(Base.OneTo(4)))
1

known_last(::Type{T}) -> Union{Int,Nothing}

If last of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> known_last(typeof(1:4))
nothing

julia> known_first(typeof(static(1):static(4)))
4

known_length(::Type{T}) -> Union{Int,Nothing}

If length of an instance of type T is known at compile time, return it. Otherwise, return nothing.

known_offset1(::Type{T}) -> Union{Int,Nothing}

Returns the linear offset of array x if known at compile time.

known_offsets(::Type{T}) -> Tuple
known_offsets(::Type{T}, dim) -> Union{Int,Nothing}

Returns a tuple of offset values known at compile time. If the offset of a given axis is not known at compile time nothing is returned its position.

known_size(::Type{T}) -> Tuple
known_size(::Type{T}, dim) -> Union{Int,Nothing}

Returns the size of each dimension of A or along dimension dim of A that is known at compile time. If a dimension does not have a known size along a dimension then nothing is returned in its position.

known_step(::Type{T}) -> Union{Int,Nothing}

If step of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> known_step(typeof(1:2:8))
nothing

julia> known_step(typeof(1:4))
1

known_strides(::Type{T}) -> Tuple
known_strides(::Type{T}, dim) -> Union{Int,Nothing}

Returns the strides of array A known at compile time. Any strides that are not known at compile time are represented by nothing.

static_axes(A) -> Tuple{Vararg{AbstractUnitRange{Int}}}
static_axes(A, dim) -> AbstractUnitRange{Int}

Returns the axis associated with each dimension of A or dimension dim. static_axes(::AbstractArray) behaves nearly identical to Base.axes with the exception of a handful of types replace Base.OneTo{Int} with SOneTo. For example, the axis along the first dimension of Transpose{T,<:AbstractVector{T}} and Adjoint{T,<:AbstractVector{T}} can be represented by SOneTo(1). Similarly, Base.ReinterpretArray's first axis may be statically sized.

axes_types(::Type{T}) -> Type{Tuple{Vararg{AbstractUnitRange{Int}}}}
axes_types(::Type{T}, dim) -> Type{AbstractUnitRange{Int}}

Returns the type of each axis for the T, or the type of of the axis along dimension dim.

broadcast_axis(x, y)

Broadcast axis x and y into a common space. The resulting axis should be equal in length to both x and y unless one has a length of 1, in which case the longest axis will be equal to the output.

julia> broadcast_axis(1:10, 1:10)

julia> broadcast_axis(1:10, 1)
1:10

deleteat(collection, index)

Returns a new instance of collection with the item at the given index removed.

dense_dims(::Type{<:AbstractArray{N}}) -> Tuple{Vararg{StaticBool,N}}

Returns a tuple of indicators for whether each axis is dense. An axis i of array A is dense if stride(A, i) * Base.size(A, i) == stride(A, j) where stride_rank(A)[i] + 1 == stride_rank(A)[j].

from_parent_dims(::Type{T}) -> Tuple{Vararg{Union{StaticInt,Tuple{Vararg{StaticInt}}}}}

Returns the mapping from parent dimensions to child dimensions.

!!! Warning This method is still experimental and may change without notice.

indices(x, dim) -> AbstractUnitRange{Int}

Given an array x, this returns the indices along dimension dim.

indices(x) -> AbstractUnitRange{Int}

Returns valid indices for the entire length of x.

indices(x::Tuple) -> AbstractUnitRange{Int}

Returns valid indices for the entire length of each array in x.

indices(x::Tuple, dim)  -> AbstractUnitRange{Int}

Returns valid indices for each array in x along dimension dim

indices(x::Tuple, dim::Tuple) -> AbstractUnitRange{Int}

Returns valid indices given a tuple of arrays x and tuple of dimesions for each respective array (dim).

indices(x, dim::Tuple) -> Tuple{Vararg{AbstractUnitRange{Int}}}

Returns valid indices for array x along each dimension specified in dim.

insert(collection, index, item)

Returns a new instance of collection with item inserted into at the given index.

static_length(A) -> Union{Int,StaticInt}

Returns the length of A. If the length is known at compile time, it is returned as Static number. Otherwise, static_length(A) is identical to Base.length(A).

julia> using StaticArrays, ArrayInterface

julia> A = @SMatrix rand(3,4);

julia> static_length(A)
static(12)

lazy_axes(x)

Produces a tuple of axes where each axis is constructed lazily. If an axis of x is already constructed or it is simply retrieved.

offset1(x) -> Union{Int,StaticInt}

Returns the offset of the linear indices for x.

offsets(A) -> Tuple
offsets(A, dim) -> Union{Int,StaticInt}

Returns offsets of indices with respect to 0. If values are known at compile time, it should return them as Static numbers. For example, if A isa Base.Matrix, offsets(A) === (StaticInt(1), StaticInt(1)).

setindex!(A, args...)

Store the given values at the given key or index within a collection.

static_size(A) -> Tuple
static_size(A, dim) -> Union{Int,StaticInt}

Returns the size of each dimension of A or along dimension dim of A. If the size of any axes are known at compile time, these should be returned as Static numbers. Otherwise, static_size(A) is identical to Base.size(A)

julia> using StaticArrays, ArrayInterface

julia> A = @SMatrix rand(3,4);

julia> static_size(A)
(static(3), static(4))

static_strides(A) -> Tuple{Vararg{Union{Int,StaticInt}}}
static_strides(A, dim) -> Union{Int,StaticInt}

Returns the strides of array A. If any strides are known at compile time, these should be returned as Static numbers. For example:

julia> A = rand(3,4);

julia> static_strides(A)
(static(1), 3)

Additionally, the behavior differs from Base.strides for adjoint vectors:

julia> x = rand(5);

julia> static_strides(x')
(static(1), static(1))

This is to support the pattern of using just the first stride for linear indexing, x[i], while still producing correct behavior when using valid cartesian indices, such as x[1,i]. ```

to_axes(A, inds) -> Tuple

Construct new axes given the corresponding inds constructed after to_indices(A, args) -> inds. This method iterates through each pair of axes and indices calling to_axis.

to_axis(old_axis, index) -> new_axis

Construct an new_axis for a newly constructed array that corresponds to the previously executed to_index(old_axis, arg) -> index. to_axis assumes that index has already been confirmed to be in bounds. The underlying indices of new_axis begins at one and extends the length of index (i.e., one-based indexing).

to_dims(x, dim) -> Union{Int,StaticInt}

This returns the dimension(s) of x corresponding to dim.

to_index([::IndexStyle, ]axis, arg) -> index

Convert the argument arg that was originally passed to static_getindex for the dimension corresponding to axis into a form for native indexing (Int, Vector{Int}, etc.).

to_index supports passing a function as an index. This function-index is transformed into a proper index.

julia> using ArrayInterface, Static

julia> to_index(static(1):static(10), 5)
5

julia> to_index(static(1):static(10), <(5))
static(1):4

julia> to_index(static(1):static(10), <=(5))
static(1):5

julia> to_index(static(1):static(10), >(5))
6:static(10)

julia> to_index(static(1):static(10), >=(5))
5:static(10)

Use of a function-index helps ensure that indices are inbounds

julia> to_index(static(1):static(10), <(12))
static(1):10

julia> to_index(static(1):static(10), >(-1))
1:static(10)

New axis types with unique behavior should use an IndexStyle trait:

to_index(axis::MyAxisType, arg) = to_index(IndexStyle(axis), axis, arg)
to_index(::MyIndexStyle, axis, arg) = ...

static_to_indices(A, I::Tuple) -> Tuple

Converts the tuple of indexing arguments, I, into an appropriate form for indexing into A. Typically, each index should be an Int, StaticInt, a collection with values of Int, or a collection with values of CartesianIndex This is accomplished in three steps after the initial call to static_to_indices:

Extended help

This implementation differs from that of Base.to_indices in the following ways:

• static_to_indices(A, I) never results in recursive processing of I through static_to_indices(A, static_axes(A), I). This is avoided through the use of an internal @generated method that aligns calls of static_to_indices and to_index based on the return values of ndims_index. This is beneficial because the compiler currently does not optimize away the increased time spent recursing through each additional argument that needs converting. For example: ```julia julia> x = rand(4,4,4,4,4,4,4,4,4,4);

  julia> inds1 = (1, 2, 1, 2, 1, 2, 1, 2, 1, 2);

  julia> inds2 = (1, CartesianIndex(1, 2), 1, CartesianIndex(1, 2), 1, CartesianIndex(1, 2), 1);

  julia> inds3 = (fill(true, 4, 4), 2, fill(true, 4, 4), 2, 1, fill(true, 4, 4), 1);

  julia> @btime Base.to_indices(x, inds2) 1.105 μs (12 allocations: 672 bytes) (1, 1, 2, 1, 1, 2, 1, 1, 2, 1)

  julia> @btime statictoindices(x, inds2) 0.041 ns (0 allocations: 0 bytes) (1, 1, 2, 1, 1, 2, 1, 1, 2, 1)

  julia> @btime Base.to_indices(x, inds3); 340.629 ns (14 allocations: 768 bytes)

  julia> @btime statictoindices(x, inds3); 11.614 ns (0 allocations: 0 bytes)

  ```

• Recursing through static_to_indices(A, axes, I::Tuple{I1,Vararg{Any}}) is intended to provide context for processing I1. However, this doesn't tell use how many dimensions are consumed by what is in Vararg{Any}. Using ndims_index to directly align the axes of A with each value in I ensures that a CartesiaIndex{3} at the tail of I isn't incorrectly assumed to only consume one dimension.

• Base.to_indices may fail to infer the returned type. This is the case for inds2 and inds3 in the first bullet on Julia 1.6.4.

• Specializing by dispatch through method definitions like this: static_to_indices(::ArrayType, ::Tuple{AxisType,Vararg{Any}}, ::Tuple{::IndexType,Vararg{Any}}) require an excessive number of hand written methods to avoid ambiguities. Furthermore, if AxisType is wrapping another axis that should have unique behavior, then unique parametric types need to also be explicitly defined.

• to_index(static_axes(A, dim), index) is called, as opposed to Base.to_index(A, index). The IndexStyle of the resulting axis is used to allow indirect dispatch on nested axis types within to_index.

to_parent_dims(::Type{T}) -> Tuple{Vararg{Union{StaticInt,Tuple{Vararg{StaticInt}}}}}

Returns the mapping from child dimensions to parent dimensions.

!!! Warning This method is still experimental and may change without notice.

unsafe_reconstruct(A, data; kwargs...)

Reconstruct A given the values in data. New methods using unsafe_reconstruct should only dispatch on A.

BroadcastAxis

An abstract trait that is used to determine how axes are combined when calling broadcast_axis.

LazyAxis{N}(parent::AbstractArray)

A lazy representation of axes(parent, N).

StrideIndex(x)

Subtype of ArrayIndex that transforms and index using stride layout information derived from x.