More documentation organization + fix offset1 mess. (#190)

* Separate API traits in docs

* Fix offset1 and simplify OffsetArrays code

* Resolve deprecation of qr(A, Val(true))

* Remove dead code

* version bump

* test qr differently on v1.7

Author: Tokazama

Project.toml

@@ -1,6 +1,6 @@
 name = "ArrayInterface"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "3.1.23"
+version = "3.1.24"
 
 [deps]
 IfElse = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173"

docs/make.jl

@@ -6,6 +6,7 @@ makedocs(;
     sitename="ArrayInterface",
     pages=[
         "Home" => "index.md",
+        "API" => "api.md"
     ],
 )
 

docs/src/api.md

@@ -0,0 +1,85 @@
+# API
+
+## Traits
+
+```@docs
+ArrayInterface.can_avx
+ArrayInterface.can_change_size
+ArrayInterface.can_setindex
+ArrayInterface.contiguous_axis
+ArrayInterface.contiguous_axis_indicator
+ArrayInterface.contiguous_batch_size
+ArrayInterface.defines_strides
+ArrayInterface.device
+ArrayInterface.dimnames
+ArrayInterface.fast_matrix_colors
+ArrayInterface.fast_scalar_indexing
+ArrayInterface.has_dimnames
+ArrayInterface.has_parent
+ArrayInterface.has_sparsestruct
+ArrayInterface.is_canonical
+ArrayInterface.is_column_major
+ArrayInterface.is_lazy_conjugate
+ArrayInterface.ismutable
+ArrayInterface.issingular
+ArrayInterface.isstructured
+ArrayInterface.known_first
+ArrayInterface.known_last
+ArrayInterface.known_length
+ArrayInterface.known_offset1
+ArrayInterface.known_offsets
+ArrayInterface.known_size
+ArrayInterface.known_step
+ArrayInterface.known_strides
+```
+
+## Functions
+
+```@docs
+ArrayInterface.allowed_getindex
+ArrayInterface.allowed_setindex!
+ArrayInterface.aos_to_soa
+ArrayInterface.axes
+ArrayInterface.axes_types
+ArrayInterface.broadcast_axis
+ArrayInterface.canonicalize
+ArrayInterface.deleteat
+ArrayInterface.dense_dims
+ArrayInterface.findstructralnz
+ArrayInterface.from_parent_dims
+ArrayInterface.getindex
+ArrayInterface.indices
+ArrayInterface.insert
+ArrayInterface.lazy_axes
+ArrayInterface.lu_instance
+ArrayInterface.matrix_colors
+ArrayInterface.offset1
+ArrayInterface.offsets
+ArrayInterface.parent_type
+ArrayInterface.reduce_tup
+ArrayInterface.restructure
+ArrayInterface.safevec
+ArrayInterface.setindex!
+ArrayInterface.size
+ArrayInterface.strides
+ArrayInterface.to_axes
+ArrayInterface.to_axis
+ArrayInterface.to_dims
+ArrayInterface.to_index
+ArrayInterface.to_indices
+ArrayInterface.to_parent_dims
+ArrayInterface.unsafe_reconstruct
+ArrayInterface.zeromatrix
+```
+
+## Types
+
+```@docs
+ArrayInterface.ArrayIndex
+ArrayInterface.BroadcastAxis
+ArrayInterface.LazyAxis
+ArrayInterface.OptionallyStaticStepRange
+ArrayInterface.OptionallyStaticUnitRange
+ArrayInterface.StrideIndex
+```
+

docs/src/index.md

@@ -93,12 +93,3 @@ f(x, dim::StaticInt) = ...
 If `x`'s first dimension is named `:dim_1` then calling `f(x, :dim_1)` would result in `f(x, 1)`.
 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.
 
-## API
-
-```@index
-```
-
-```@autodocs
-Modules = [ArrayInterface]
-```
-

src/ArrayInterface.jl

@@ -915,35 +915,16 @@ function __init__()
         end
     end
     @require OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881" begin
-        size(A::OffsetArrays.OffsetArray) = size(parent(A))
-        strides(A::OffsetArrays.OffsetArray) = strides(parent(A))
-        function parent_type(
-            ::Type{O},
-        ) where {T,N,A<:AbstractArray{T,N},O<:OffsetArrays.OffsetArray{T,N,A}}
-            return A
-        end
-        device(::Type{A}) where {A<:OffsetArrays.OffsetArray} = device(parent_type(A))
-        function contiguous_axis(::Type{A}) where {A<:OffsetArrays.OffsetArray}
-            return contiguous_axis(parent_type(A))
-        end
-        function contiguous_batch_size(::Type{A}) where {A<:OffsetArrays.OffsetArray}
-            return contiguous_batch_size(parent_type(A))
-        end
-
+        parent_type(::Type{O}) where {T,N,A<:AbstractArray{T,N},O<:OffsetArrays.OffsetArray{T,N,A}} = A
         function _offset_axis_type(::Type{T}, dim::StaticInt{D}) where {T,D}
-            return OffsetArrays.IdOffsetRange{Int,ArrayInterface.axes_types(T, dim)}
+            OffsetArrays.IdOffsetRange{Int,ArrayInterface.axes_types(T, dim)}
         end
         function ArrayInterface.axes_types(::Type{T}) where {T<:OffsetArrays.OffsetArray}
-            return Static.eachop_tuple(_offset_axis_type, Static.nstatic(Val(ndims(T))), ArrayInterface.parent_type(T))
-        end
-        function stride_rank(::Type{A}) where {A<:OffsetArrays.OffsetArray}
-            return stride_rank(parent_type(A))
+            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}()))
-        @inline known_offset1(::Type{<:OffsetArrays.OffsetArray}) = 1
-        @inline known_offset1(::Type{<:OffsetArrays.OffsetVector}) = nothing
     end
 end
 

src/array_index.jl

@@ -189,16 +189,15 @@ end
 Subtype of `ArrayIndex` that transforms and index using stride layout information
 derived from `x`.
 """
-struct StrideIndex{N,R,C,S,O,O1} <: ArrayIndex{N}
+struct StrideIndex{N,R,C,S,O} <: ArrayIndex{N}
     strides::S
     offsets::O
-    offset1::O1
 
-    function StrideIndex{N,R,C}(s::S, o::O, o1::O1) where {N,R,C,S,O,O1}
-        return new{N,R::NTuple{N,Int},C::Int,S,O,O1}(s, o, o1)
+    function StrideIndex{N,R,C}(s::S, o::O) where {N,R,C,S,O}
+        return new{N,R::NTuple{N,Int},C::Int,S,O}(s, o)
     end
     function StrideIndex{N,R,C}(a::A) where {N,R,C,A}
-        return StrideIndex{N,R,C}(strides(a),offsets(a),offset1(a))
+        return StrideIndex{N,R,C}(strides(a), offsets(a))
     end
     function StrideIndex(a::A) where {A}
         return StrideIndex{ndims(A),known(stride_rank(A)), known(contiguous_axis(A))}(a)

src/indexing.jl

@@ -145,7 +145,7 @@ function to_index(::IndexLinear, x, arg::AbstractCartesianIndex{N}) where {N}
     inds = Tuple(arg)
     o = offsets(x)
     s = size(x)
-    return first(inds) + (offset1(x) - first(o)) + _subs2int(first(s), tail(s), tail(o), tail(inds))
+    return first(inds) + (static(1) - first(o)) + _subs2int(first(s), tail(s), tail(o), tail(inds))
 end
 @inline function _subs2int(stride, s::Tuple{Any,Vararg}, o::Tuple{Any,Vararg}, inds::Tuple{Any,Vararg})
     i = ((first(inds) - first(o)) * stride)
@@ -215,7 +215,7 @@ end
     @boundscheck checkbounds(x, arg)
     return LogicalIndex{Int}(arg)
 end
-to_index(::IndexCartesian, x, i::Integer) = NDIndex(_int2subs(offsets(x), size(x), i - offset1(x)))
+to_index(::IndexCartesian, x, i::Integer) = NDIndex(_int2subs(offsets(x), size(x), i - static(1)))
 @inline function _int2subs(o::Tuple{Any,Vararg{Any}}, s::Tuple{Any,Vararg{Any}}, i)
     len = first(s)
     inext = div(i, len)

src/stridelayout.jl

@@ -42,7 +42,7 @@ function known_offsets(::Type{T}) where {T}
 end
 _known_offsets(::Type{T}, dim::StaticInt) where {T} = known_first(_get_tuple(T, dim))
 
-known_offsets(::Type{<:StrideIndex{N,R,C,S,O,O1}}) where {N,R,C,S,O,O1} = known(O)
+known_offsets(::Type{<:StrideIndex{N,R,C,S,O}}) where {N,R,C,S,O} = known(O)
 
 """
     offsets(A) -> Tuple
@@ -70,11 +70,14 @@ end
 
 Returns the linear offset of array `x` if known at compile time.
 """
-known_offset1(x) = known_offset1(typeof(x))
-known_offset1(::Type{T}) where {T} = _known_offset1(has_parent(T), T)
-_known_offset1(::True, ::Type{T}) where {T} = known_offset1(parent_type(T))
-_known_offset1(::False, ::Type{T}) where {T} = 1
-known_offset(::Type{<:StrideIndex{N,R,C,S,O,O1}}) where {N,R,C,S,O,O1} = known(O1)
+@inline known_offset1(x) = known_offset1(typeof(x))
+@inline function known_offset1(::Type{T}) where {T}
+    if ndims(T) === 0
+        return 1
+    else
+        return known_offsets(T, 1)
+    end
+end
 
 """
     offset1(x) -> Union{Int,StaticInt}
@@ -84,12 +87,15 @@ Returns the offset of the linear indices for `x`.
 @inline function offset1(x::X) where {X}
     o1 = known_offset1(X)
     if o1 === nothing
-        return firstindex(x)
+        if ndims(X) === 0
+            return 1
+        else
+            return offsets(x, 1)
+        end
     else
         return static(o1)
     end
 end
-offset1(x::StrideIndex) = getfield(x, :offset1)
 
 """
     contiguous_axis(::Type{T}) -> StaticInt{N}
@@ -442,7 +448,7 @@ function known_strides(::Type{T}, dim::Integer) where {T}
         return known_strides(T)[dim]
     end
 end
-known_strides(::Type{<:StrideIndex{N,R,C,S,O,O1}}) where {N,R,C,S,O,O1} = known(S)
+known_strides(::Type{<:StrideIndex{N,R,C,S,O}}) where {N,R,C,S,O} = known(S)
 
 known_strides(x) = known_strides(typeof(x))
 known_strides(::Type{T}) where {T<:Vector} = (1,)

test/runtests.jl

@@ -53,7 +53,11 @@ rowind,colind=findstructralnz(Sp)
 
 
 @test !fast_scalar_indexing(qr(rand(10, 10)).Q)
-@test !fast_scalar_indexing(qr(rand(10, 10), Val(true)).Q)
+if VERSION >= v"1.7"
+    @test !fast_scalar_indexing(qr(rand(10, 10), ColumnNorm()).Q)
+else
+    @test !fast_scalar_indexing(qr(rand(10, 10), Val(true)).Q)
+end
 @test !fast_scalar_indexing(lq(rand(10, 10)).Q)
 
 using BandedMatrices
@@ -682,8 +686,6 @@ end
     @test @inferred(ArrayInterface.offsets(Op)) === (11, 4, 8)
 
     @test @inferred(ArrayInterface.offsets((1,2,3))) === (StaticInt(1),)
-    @test @inferred(ArrayInterface.offset1(O)) === StaticInt(1)
-    @test @inferred(ArrayInterface.offset1(Op)) === StaticInt(1)
     o = OffsetArray(vec(A), 8);
     @test @inferred(ArrayInterface.offset1(o)) === 9