ArrayInterface.axes docs, clean up, and ReinterpretArray support. (#222)

* +axis support methods from base and +tests
* Get rid of some no good very bad spaghetti code.
* Document examples of how to use axes here.
* Incorporate ReinterpretArray changes from ArrayInterface.axes for ReshapedReinterpretArray #210. Don't assume we can go to parent arrays anymore because there are too many assumptions (offsets, sizing, views, etc) that can change it.
* Document `SoneTo`

Author: Tokazama

Project.toml

@@ -1,6 +1,6 @@
 name = "ArrayInterface"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "3.1.36"
+version = "3.1.37"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"

docs/src/api.md

@@ -81,6 +81,7 @@ ArrayInterface.BroadcastAxis
 ArrayInterface.LazyAxis
 ArrayInterface.OptionallyStaticStepRange
 ArrayInterface.OptionallyStaticUnitRange
+ArrayInteraface.SOneTo
 ArrayInterface.StrideIndex
 ```
 

docs/src/index.md

@@ -8,7 +8,7 @@ Designs for new Base array interface primitives, used widely through scientific
 
 ## Inheriting Array Traits
 
-Creating an array type with unique behavior in Julia is often accomplished by creating a lazy wrapper around previously defined array types.
+Creating an array type with unique behavior in Julia is often accomplished by creating a lazy wrapper around previously defined array types (e.g. [composition by inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance)).
 This allows the new array type to inherit functionality by redirecting methods to the parent array (e.g., `Base.size(x::Wrapper) = size(parent(x))`).
 Generic design limits the need to define an excessive number of methods like this.
 However, methods used to describe a type's traits often need to be explicitly defined for each trait method.
@@ -32,7 +32,7 @@ Most traits in `ArrayInterface` are a variant on this pattern.
 
 ## Static Traits
 
-The size along one or more dimensions of an array may be known at compile time. 
+The size along one or more dimensions of an array may be known at compile time.
 `ArrayInterface.known_size` is useful for extracting this information from array types and `ArrayInterface.size` is useful for extracting this information from an instance of an array.
 For example:
 
@@ -94,6 +94,7 @@ If `x`'s first dimension is named `:dim_1` then calling `f(x, :dim_1)` would res
 If users knew they always wanted to call `f(x, 2)` then they could define `h(x) = f(x, static(2))`, ensuring `f` passes along that information while compiling.
 
 New types defining dimension names can do something similar to:
+
 ```julia
 using Static
 using ArrayInterface
@@ -107,4 +108,69 @@ Dimension names should be appropriately propagated between nested arrays using `
 This allows types such as `SubArray` and `PermutedDimsArray` to work with named dimensions.
 Similarly, other methods that return information corresponding to dimensions (e.g., `ArrayInterfce.size`, `ArrayInterface.axes`) use `to_parent_dims` to appropriately propagate parent information.
 
+## Axes
+
+Where Julia's currently documented [array interface]( https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-array) requires defining `Base.size`, ArrayInterface instead requires defining [`ArrayInterface.axes`](@ref) and [`ArrayInterface.axes_types`](@ref).
+`ArrayInterface.axes_types(::Type{T})` facilitates propagation of a number of traits known at compile time (e.g., `known_size`, `known_offsets`) and `ArrayInterface.axes(::AbstractArray)` replaces `Base.OneTo` with `ArrayInterface.OptionallyStaticUnitRange` in situations where static information would otherwise be lost.
+`ArrayInterface.axes(::AbstractArray, dim)` utilizes `to_dims`, [as described elsewhere](#dimensions).
+
+### Simple Wrappers
+
+Let's say we have a new array type doesn't affect axes then this is as simple as:
+```julia
+Base.axes(x::SimpleWrapper) = ArrayInterface.axes(parent(x))
+Base.axes(x::SimpleWrapper, dim) = ArrayInterface.axes(parent(x), dim)
+ArrayInterface.axes_types(::Type{T}) where {T<:SimpleWrapper} = axes_types(parent_type(T))
+```
+
+To reiterate, `ArrayInterface.axes` improves on `Base.axes` for few Base array types but is otherwise identical.
+Therefore, the first method simply ensures you don't have to define multiple parametric methods for your new type to preserve statically sized nested axes (e.g., `SimpleWrapper{T,N,<:Transpose{T,<:AbstractVector}}`).
+This is otherwise identical to standard inheritance by composition.
+
+### When to Discard Axis Information
+
+Occasionally the parent array's axis information can't be preserved.
+For example, we can't map axis information from the parent array of `Base.ReshapedArray`.
+In this case we can simply build axes from the new size information.
+
+```julia
+ArrayInterface.axes_types(T::Type{<:ReshapedArray}) = NTuple{ndims(T),OneTo{Int}}
+ArrayInterface.axes(A::ReshapedArray) = map(OneTo, size(A))
+```
+
+### New Axis Types
+
+`OffsetArray` changes the first index for each axis.
+It produces axes of type `IdOffsetRange`, which contains the value of the relative offset and the parent axis.
+
+```julia
+using ArrayInterface: axes_types, parent_type, to_dims
+# Note that generating a `Tuple` type piecewise like may be type unstable and should be
+# tested using `Test.@inferred`. It's often necessary to use generated function
+# (`@generated`) or methods defined in Static.jl.
+@generated function ArrayInterface.axes_types(::Type{A}) where {A<:OffsetArray}
+    out = Expr(:curly, :Tuple)
+    P = parent_type(A)
+    for dim in 1:ndims(A)
+        # offset relative to parent array
+        O = relative_known_offsets(A, dim)
+        if O === nothing  # offset is not known at compile time and is an `Int`
+            push!(out.args, :(IdOffsetRange{Int, axes_types($P, $(static(dim)))}))
+        else # offset is known, therefore it is a `StaticInt`
+            push!(out.args, :(IdOffsetRange{StaticInt{$O}, axes_types($P, $(static(dim))}))
+        end
+    end
+end
+function Base.axes(A::OffsetArray)
+    map(IdOffsetRange, ArrayInterface.axes(parent(A)), relative_offsets(A))
+end
+function Base.axes(A::OffsetArray, dim)
+    d = to_dims(A, dim)
+    IdOffsetRange(ArrayInterface.axes(parent(A), d), relative_offsets(A, d))
+end
+```
 
+Defining these two methods ensures that other array types that wrap `OffsetArray` and appropriately define these methods propagate offsets independent of any dependency on `OffsetArray`.
+It is entirely optional to define `ArrayInterface.size` for `OffsetArray` because the size can be derived from the axes.
+However, in this particularly case we should also define
+ `ArrayInterface.size(A::OffsetArray)  = ArrayInterface.size(parent(A))` because the relative offsets attached to `OffsetArray` do not change the size but may hide static sizes if using a relative offset that is defined with an `Int`.

src/ArrayInterface.jl

@@ -15,13 +15,14 @@ using Base: @propagate_inbounds, tail, OneTo, LogicalIndex, Slice, ReinterpretAr
 
 const CanonicalInt = Union{Int,StaticInt}
 
-@static if VERSION ≥ v"1.6.0-DEV.1581"
-    _is_reshaped(::Type{ReinterpretArray{T,N,S,A,true}}) where {T,N,S,A} = true
-    _is_reshaped(::Type{ReinterpretArray{T,N,S,A,false}}) where {T,N,S,A} = false
-else
-    _is_reshaped(::Type{ReinterpretArray{T,N,S,A}}) where {T,N,S,A} = false
+@static if isdefined(Base, :ReshapedReinterpretArray)
+    _is_reshaped(::Type{<:Base.ReshapedReinterpretArray}) = true
 end
+_is_reshaped(::Type{<:ReinterpretArray}) = false
 
+@generated function merge_tuple_type(::Type{X}, ::Type{Y}) where {X<:Tuple,Y<:Tuple}
+    Tuple{X.parameters..., Y.parameters...}
+end
 Base.@pure __parameterless_type(T) = Base.typename(T).wrapper
 parameterless_type(x) = parameterless_type(typeof(x))
 parameterless_type(x::Type) = __parameterless_type(x)
@@ -582,12 +583,15 @@ abstract type AbstractArray2{T,N} <: AbstractArray{T,N} end
 Base.size(A::AbstractArray2) = map(Int, ArrayInterface.size(A))
 Base.size(A::AbstractArray2, dim) = Int(ArrayInterface.size(A, dim))
 
-Base.axes(A::AbstractArray2) = ArrayInterface.axes(A)
+function Base.axes(A::AbstractArray2)
+    !(parent_type(A) <: typeof(A)) && return ArrayInterface.axes(parent(A))
+    throw(ArgumentError("Subtypes of `AbstractArray2` must define an axes method"))
+end
 Base.axes(A::AbstractArray2, dim) = ArrayInterface.axes(A, dim)
 
 function Base.strides(A::AbstractArray2)
-    defines_strides(A) || throw(MethodError(Base.strides, (A,)))
-    return map(Int, ArrayInterface.strides(A))
+    defines_strides(A) && return map(Int, ArrayInterface.strides(A))
+    throw(MethodError(Base.strides, (A,)))
 end
 Base.strides(A::AbstractArray2, dim) = Int(ArrayInterface.strides(A, dim))
 
@@ -602,7 +606,7 @@ end
 function Base.length(A::AbstractArray2)
     len = known_length(A)
     if len === nothing
-        return prod(size(A))
+        return Int(prod(size(A)))
     else
         return Int(len)
     end
@@ -672,8 +676,6 @@ include("indexing.jl")
 include("stridelayout.jl")
 include("broadcast.jl")
 
-
-
 function __init__()
 
     @require SuiteSparse = "4607b0f0-06f3-5cda-b6b1-a6196a1729e9" begin
@@ -914,16 +916,46 @@ function __init__()
         end
     end
     @require OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881" begin
-        parent_type(::Type{O}) where {T,N,A<:AbstractArray{T,N},O<:OffsetArrays.OffsetArray{T,N,A}} = A
+        relative_offsets(r::OffsetArrays.IdOffsetRange) = (getfield(r, :offset),)
+        relative_offsets(A::OffsetArrays.OffsetArray) = getfield(A, :offsets)
+        function relative_offsets(A::OffsetArrays.OffsetArray, ::StaticInt{dim}) where {dim}
+            if dim > ndims(A)
+                return static(0)
+            else
+                return getfield(relative_offsets(A), dim)
+            end
+        end
+        function relative_offsets(A::OffsetArrays.OffsetArray, dim::Int)
+            if dim > ndims(A)
+                return 0
+            else
+                return getfield(relative_offsets(A), dim)
+            end
+        end
+        ArrayInterface.parent_type(::Type{<:OffsetArrays.OffsetArray{T,N,A}}) where {T,N,A} = A
         function _offset_axis_type(::Type{T}, dim::StaticInt{D}) where {T,D}
             OffsetArrays.IdOffsetRange{Int,ArrayInterface.axes_types(T, dim)}
         end
         function ArrayInterface.axes_types(::Type{T}) where {T<:OffsetArrays.OffsetArray}
             Static.eachop_tuple(_offset_axis_type, Static.nstatic(Val(ndims(T))), ArrayInterface.parent_type(T))
         end
-        @inline axes(A::OffsetArrays.OffsetArray) = Base.axes(A)
-        @inline _axes(A::OffsetArrays.OffsetArray, dim::Integer) = Base.axes(A, dim)
-        @inline axes(A::OffsetArrays.OffsetArray{T,N}, ::StaticInt{M}) where {T,M,N} = _axes(A, StaticInt{M}(), gt(StaticInt{M}(),StaticInt{N}()))
+        function ArrayInterface.known_offsets(::Type{A}) where {A<:OffsetArrays.OffsetArray}
+            ntuple(identity -> nothing, Val(ndims(A)))
+        end
+        function ArrayInterface.offsets(A::OffsetArrays.OffsetArray)
+            map(+, ArrayInterface.offsets(parent(A)), relative_offsets(A))
+        end
+       @inline function ArrayInterface.offsets(A::OffsetArrays.OffsetArray, dim)
+            d = ArrayInterface.to_dims(A, dim)
+            ArrayInterface.offsets(parent(A), d) + relative_offsets(A, d)
+        end
+        @inline function ArrayInterface.axes(A::OffsetArrays.OffsetArray)
+            map(OffsetArrays.IdOffsetRange, ArrayInterface.axes(parent(A)), relative_offsets(A))
+        end
+        @inline function ArrayInterface.axes(A::OffsetArrays.OffsetArray, dim)
+            d = to_dims(A, dim)
+            OffsetArrays.IdOffsetRange(ArrayInterface.axes(parent(A), d), relative_offsets(A, d))
+        end
     end
 end