Merge pull request #276 from JuliaArrays/known

ChrisRackauckas · web-flow · commit 9f1be650371a · 2022-05-26T13:15:12.000-04:00
Move known_first, known_step, and known_last to ArrayInterfaceCore
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -14,10 +14,10 @@ jobs:
       - uses: julia-actions/setup-julia@latest
         with:
           version: '1'
-      - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-      - name: Build and deploy
+      - run: julia --project -e 'using Pkg; Pkg.develop([PackageSpec(path=joinpath(pwd(), "lib", "ArrayInterfaceCore"))])'
+      - uses: julia-actions/julia-buildpkg@latest
+      - run: julia --project=docs/ -e 'using Pkg; Pkg.develop([PackageSpec(path=joinpath(pwd(), "lib", "ArrayInterfaceCore"))]); Pkg.instantiate()'
+      - uses: julia-actions/julia-docdeploy@releases/v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
diff --git a/.github/workflows/Downstream.yml b/.github/workflows/Downstream.yml
@@ -34,29 +34,23 @@ jobs:
         with:
           version: ${{ matrix.julia-version }}
           arch: x64
-      - name: Setup ArrayInterface
-        shell: julia --color=yes {0}
-        run: |
-          using Pkg
-          function dev_subpkg(subpkg)
-              subpkg_path = joinpath("lib", subpkg)
-              Pkg.develop(Pkg.PackageSpec(path=subpkg_path))
-          end
-          dev_subpkg("ArrayInterfaceCore")
-          Pkg.build()
+      - uses: julia-actions/julia-buildpkg@latest
       - name: Clone Downstream
         uses: actions/checkout@v2
         with:
           repository: ${{ matrix.package.user }}/${{ matrix.package.repo }}
           path: downstream
       - name: Load this and run the downstream tests
-        shell: julia --color=yes --project=downstream {0}
+        shell: julia --color=yes {0}
         run: |
           using Pkg
           try
             # force it to use this PR's version of the package
             Pkg.develop(PackageSpec(path="."))  # resolver may fail with main deps
-            
+            Pkg.develop(Pkg.PackageSpec(path=joinpath(pwd(), "lib", "ArrayInterfaceCore")))
+            Pkg.develop(Pkg.PackageSpec(path=joinpath(pwd(), "lib", "ArrayInterfaceOffsetArrays")))
+            Pkg.develop(Pkg.PackageSpec(path=joinpath(pwd(), "lib", "ArrayInterfaceStaticArrays")))
+            Pkg.activate("downstream")
             Pkg.update()
             Pkg.test()  # resolver may fail with test time deps
           catch err
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,6 +9,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.group == 'Downstream' }}
     strategy:
       fail-fast: false
       matrix:
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "ArrayInterface"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "6.0.1"
+version = "6.0.2"
 
 [deps]
 ArrayInterfaceCore = "30b0a656-2188-435a-8636-2ec0e6a096e2"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,5 @@
 using ArrayInterface
+using Pkg
 
 function dev_subpkg(subpkg)
     subpkg_path = joinpath(dirname(@__DIR__), "lib", subpkg)
@@ -21,4 +22,3 @@ makedocs(;
 deploydocs(;
     repo="github.com/JuliaArrays/ArrayInterface.jl"
 )
-
diff --git a/lib/ArrayInterfaceCore/Project.toml b/lib/ArrayInterfaceCore/Project.toml
@@ -1,7 +1,7 @@
 name = "ArrayInterfaceCore"
 uuid = "30b0a656-2188-435a-8636-2ec0e6a096e2"
 authors = ["Zachary P. Christensen <zchristensen7@gmail.com>"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
diff --git a/lib/ArrayInterfaceCore/src/ArrayInterfaceCore.jl b/lib/ArrayInterfaceCore/src/ArrayInterfaceCore.jl
@@ -441,4 +441,95 @@ Base.@propagate_inbounds function Base.getindex(ind::TridiagonalIndex, i::Int)
     end
 end
 
+_cartesian_index(i::Tuple{Vararg{Int}}) = CartesianIndex(i)
+_cartesian_index(::Any) = nothing
+
+"""
+    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
+julia> ArrayInterface.known_first(typeof(1:4))
+nothing
+
+julia> ArrayInterface.known_first(typeof(Base.OneTo(4)))
+1
+```
+"""
+known_first(x) = known_first(typeof(x))
+function known_first(::Type{T}) where {T}
+    if parent_type(T) <: T
+        return nothing
+    else
+        return known_first(parent_type(T))
+    end
+end
+known_first(::Type{Base.OneTo{T}}) where {T} = 1
+function known_first(::Type{<:CartesianIndices{N,R}}) where {N,R}
+    _cartesian_index(ntuple(i -> known_first(R.parameters[i]), Val(N)))
+end
+
+"""
+    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
+julia> ArrayInterface.known_last(typeof(1:4))
+nothing
+
+julia> ArrayInterface.known_first(typeof(static(1):static(4)))
+4
+
+```
+"""
+known_last(x) = known_last(typeof(x))
+known_last(::Type{T}) where {T} = parent_type(T) <: T ? nothing : known_last(parent_type(T))
+function known_last(::Type{<:CartesianIndices{N,R}}) where {N,R}
+    _cartesian_index(ntuple(i -> known_last(R.parameters[i]), Val(N)))
+end
+
+"""
+    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
+julia> ArrayInterface.known_step(typeof(1:2:8))
+nothing
+
+julia> ArrayInterface.known_step(typeof(1:4))
+1
+
+```
+"""
+known_step(x) = known_step(typeof(x))
+known_step(::Type{T}) where {T} = parent_type(T) <: T ? nothing : known_step(parent_type(T))
+known_step(::Type{<:AbstractUnitRange}) = 1
+
+"""
+    is_splat_index(::Type{T}) -> Bool
+Returns `static(true)` if `T` is a type that splats across multiple dimensions. 
+"""
+is_splat_index(@nospecialize(x)) = is_splat_index(typeof(x))
+is_splat_index(T::Type) = false
+
+"""
+    ndims_index(::Type{I}) -> Int
+
+Returns the number of dimension that an instance of `I` maps to when indexing. For example,
+`CartesianIndex{3}` maps to 3 dimensions. If this method is not explicitly defined, then `1`
+is returned.
+"""
+ndims_index(@nospecialize(i)) = ndims_index(typeof(i))
+ndims_index(::Type{I}) where {I} = 1
+ndims_index(::Type{<:Base.AbstractCartesianIndex{N}}) where {N} = N
+ndims_index(::Type{<:AbstractArray{T}}) where {T} = ndims_index(T)
+ndims_index(::Type{<:AbstractArray{Bool,N}}) where {N} = N
+ndims_index(::Type{<:Base.LogicalIndex{<:Any,<:AbstractArray{Bool,N}}}) where {N} = N
+
 end # module
diff --git a/lib/ArrayInterfaceCore/test/runtests.jl b/lib/ArrayInterfaceCore/test/runtests.jl
@@ -239,4 +239,25 @@ end
     @test has_sparsestruct(STri)
     rowind,colind=findstructralnz(STri)
     @test [STri[rowind[i],colind[i]] for i in 1:length(rowind)]==[1,2,3,4,5,6,7,5,6,7]
-end
+end
+
+@testset "known values" begin
+    CI = CartesianIndices((2, 2))
+
+    @test isnothing(@inferred(ArrayInterfaceCore.known_first(typeof(1:4))))
+    @test isone(@inferred(ArrayInterfaceCore.known_first(Base.OneTo(4))))
+    @test isone(@inferred(ArrayInterfaceCore.known_first(typeof(Base.OneTo(4)))))
+    @test @inferred(ArrayInterfaceCore.known_first(typeof(CI))) == CartesianIndex(1, 1)
+    @test @inferred(ArrayInterfaceCore.known_first(typeof(CI))) == CartesianIndex(1, 1)
+
+    @test isnothing(@inferred(ArrayInterfaceCore.known_last(1:4)))
+    @test isnothing(@inferred(ArrayInterfaceCore.known_last(typeof(1:4))))
+    @test @inferred(ArrayInterfaceCore.known_last(typeof(CI))) === nothing
+
+    @test isnothing(@inferred(ArrayInterfaceCore.known_step(typeof(1:0.2:4))))
+    @test isone(@inferred(ArrayInterfaceCore.known_step(1:4)))
+    @test isone(@inferred(ArrayInterfaceCore.known_step(typeof(1:4))))
+    @test isone(@inferred(ArrayInterfaceCore.known_step(typeof(Base.Slice(1:4)))))
+    @test isone(@inferred(ArrayInterfaceCore.known_step(typeof(view(1:4, 1:2)))))
+end
+
diff --git a/src/ArrayInterface.jl b/src/ArrayInterface.jl
@@ -5,7 +5,7 @@ import ArrayInterfaceCore: allowed_getindex, allowed_setindex!, aos_to_soa, buff
     parent_type, fast_matrix_colors, findstructralnz, has_sparsestruct,
     issingular, isstructured, matrix_colors, restructure, lu_instance,
     safevec, zeromatrix, ColoringAlgorithm, merge_tuple_type,
-    fast_scalar_indexing, parameterless_type, _is_reshaped
+    fast_scalar_indexing, parameterless_type, _is_reshaped, ndims_index, is_splat_index
 
 # ArrayIndex subtypes and methods
 import ArrayInterfaceCore: ArrayIndex, MatrixIndex, VectorIndex, BidiagonalIndex, TridiagonalIndex
@@ -17,6 +17,8 @@ import ArrayInterfaceCore: MatAdjTrans, VecAdjTrans, UpTri, LoTri
 import ArrayInterfaceCore: AbstractDevice, AbstractCPU, CPUPointer, CPUTuple, CheckParent,
     CPUIndex, GPU, can_avx
 
+import ArrayInterfaceCore: known_first, known_step, known_last
+
 using Static
 using Static: Zero, One, nstatic, eq, ne, gt, ge, lt, le, eachop, eachop_tuple,
     permute, invariant_permutation, field_type, reduce_tup, find_first_eq
diff --git a/src/axes.jl b/src/axes.jl
@@ -191,11 +191,11 @@ Base.IndexStyle(::Type{T}) where {T<:LazyAxis} = IndexStyle(parent_type(T))
 
 can_change_size(::Type{LazyAxis{N,P}}) where {N,P} = can_change_size(P)
 
-known_first(::Type{LazyAxis{N,P}}) where {N,P} = known_offsets(P, static(N))
-known_first(::Type{LazyAxis{:,P}}) where {P} = 1
+ArrayInterfaceCore.known_first(::Type{LazyAxis{N,P}}) where {N,P} = known_offsets(P, static(N))
+ArrayInterfaceCore.known_first(::Type{LazyAxis{:,P}}) where {P} = 1
 Base.firstindex(x::LazyAxis) = first(x)
 @inline function Base.first(x::LazyAxis{N})::Int where {N}
-    if known_first(x) === nothing
+    if ArrayInterfaceCore.known_first(x) === nothing
         return Int(offsets(parent(x), static(N)))
     else
         return Int(known_first(x))
@@ -208,8 +208,8 @@ end
         return known_first(x)
     end
 end
-known_last(::Type{LazyAxis{N,P}}) where {N,P} = known_last(axes_types(P, static(N)))
-known_last(::Type{LazyAxis{:,P}}) where {P} = known_length(P)
+ArrayInterfaceCore.known_last(::Type{LazyAxis{N,P}}) where {N,P} = known_last(axes_types(P, static(N)))
+ArrayInterfaceCore.known_last(::Type{LazyAxis{:,P}}) where {P} = known_length(P)
 Base.lastindex(x::LazyAxis) = last(x)
 Base.last(x::LazyAxis) = _last(known_last(x), x)
 _last(::Nothing, x) = last(parent(x))
diff --git a/src/dimensions.jl b/src/dimensions.jl
@@ -36,6 +36,12 @@ function is_increasing(perm::Tuple{StaticInt{X},StaticInt{Y}}) where {X, Y}
 end
 is_increasing(::Tuple{StaticInt{X}}) where {X} = True()
 
+"""
+    from_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
+    from_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
+
+Returns the mapping from parent dimensions to child dimensions.
+"""
 from_parent_dims(x) = from_parent_dims(typeof(x))
 from_parent_dims(::Type{T}) where {T} = nstatic(Val(ndims(T)))
 from_parent_dims(::Type{T}) where {T<:VecAdjTrans} = (StaticInt(2),)
@@ -76,7 +82,6 @@ Compat.@constprop :aggressive function from_parent_dims(::Type{T}, dim::Int)::In
         throw_dim_error(T, dim)
     end
 end
-
 function from_parent_dims(::Type{T}, ::StaticInt{dim}) where {T,dim}
     if dim > ndims(T)
         return static(ndims(parent_type(T)) + dim - ndims(T))
@@ -87,6 +92,12 @@ function from_parent_dims(::Type{T}, ::StaticInt{dim}) where {T,dim}
     end
 end
 
+"""
+    to_parent_dims(::Type{T}) -> Tuple{Vararg{Union{Int,StaticInt}}}
+    to_parent_dims(::Type{T}, dim) -> Union{Int,StaticInt}
+
+Returns the mapping from child dimensions to parent dimensions.
+"""
 to_parent_dims(x) = to_parent_dims(typeof(x))
 to_parent_dims(::Type{T}) where {T} = nstatic(Val(ndims(T)))
 to_parent_dims(::Type{T}) where {T<:Union{Transpose,Adjoint}} = (StaticInt(2), One())
@@ -135,10 +146,21 @@ function to_parent_dims(::Type{T}, ::StaticInt{dim}) where {T,dim}
     end
 end
 
-@inline function has_dimnames(x)
-    static(known_dimnames(x) !== ntuple(Compat.Returns(:_), Val(ndims(x))))
-end
+"""
+    has_dimnames(::Type{T}) -> Bool
 
+Returns `true` if `x` has on or more named dimensions. If all dimensions correspond
+to `:_`, then `false` is returned.
+"""
+@inline has_dimnames(x) = static(known_dimnames(x) !== ntuple(Compat.Returns(:_), Val(ndims(x))))
+
+"""
+    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.
+"""
 @inline known_dimnames(x, dim::Integer) = _known_dimname(known_dimnames(x), canonicalize(dim))
 known_dimnames(x) = known_dimnames(typeof(x))
 known_dimnames(::Type{T}) where {T} = _known_dimnames(T, parent_type(T))
@@ -155,6 +177,13 @@ end
 end
 @inline _inbounds_known_dimname(x, dim) = @inbounds(_known_dimname(x, dim))
 
+"""
+    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.
+"""
 @inline dimnames(x, dim::Integer) = _dimname(dimnames(x), canonicalize(dim))
 @inline dimnames(x) = _dimnames(has_parent(x), x)
 @inline function _dimnames(::True, x)
@@ -169,6 +198,11 @@ _dimnames(::False, x) = ntuple(_->static(:_), Val(ndims(x)))
 end
 @inline _inbounds_dimname(x, dim) = @inbounds(_dimname(x, dim))
 
+"""
+    to_dims(x, dim) -> Union{Int,StaticInt}
+
+This returns the dimension(s) of `x` corresponding to `dim`.
+"""
 to_dims(x, dim::Colon) = dim
 to_dims(x, dim::Integer) = canonicalize(dim)
 to_dims(x, dim::Union{StaticSymbol,Symbol}) = _to_dim(dimnames(x), dim)
diff --git a/src/indexing.jl b/src/indexing.jl
@@ -1,22 +1,13 @@
-is_splat_index(@nospecialize(x)) = is_splat_index(typeof(x))
-is_splat_index(::Type{T}) where {T} = static(false)
-_is_splat(::Type{I}, i::StaticInt) where {I} = is_splat_index(field_type(I, i))
 
-"""
-    ndims_index(::Type{I}) -> StaticInt
-
-Returns the number of dimension that an instance of `I` maps to when indexing. For example,
-`CartesianIndex{3}` maps to 3 dimensions. If this method is not explicitly defined, then `1`
-is returned.
+function _is_splat(::Type{I}, i::StaticInt) where {I}
+    if dynamic(is_splat_index(field_type(I, i)))
+        True()
+    else
+        False()
+    end
+end
 
-"""
-ndims_index(@nospecialize(i)) = ndims_index(typeof(i))
-ndims_index(::Type{I}) where {I} = static(1)
-ndims_index(::Type{<:AbstractCartesianIndex{N}}) where {N} = static(N)
-ndims_index(::Type{<:AbstractArray{T}}) where {T} = ndims_index(T)
-ndims_index(::Type{<:AbstractArray{Bool,N}}) where {N} = static(N)
-ndims_index(::Type{<:LogicalIndex{<:Any,<:AbstractArray{Bool,N}}}) where {N} = static(N)
-_ndims_index(::Type{I}, i::StaticInt) where {I} = ndims_index(field_type(I, i))
+_ndims_index(::Type{I}, i::StaticInt) where {I} = StaticInt(ndims_index(field_type(I, i)))
 
 """
     to_indices(A, I::Tuple) -> Tuple
@@ -238,7 +229,7 @@ indices calling [`to_axis`](@ref).
 end
 # drop this dimension
 to_axes(A, a::Tuple, i::Tuple{<:Integer,Vararg{Any}}) = to_axes(A, tail(a), tail(i))
-to_axes(A, a::Tuple, i::Tuple{I,Vararg{Any}}) where {I} = _to_axes(ndims_index(I), A, a, i)
+to_axes(A, a::Tuple, i::Tuple{I,Vararg{Any}}) where {I} = _to_axes(StaticInt(ndims_index(I)), A, a, i)
 function _to_axes(::StaticInt{1}, A, axs::Tuple, inds::Tuple)
     return (to_axis(first(axs), first(inds)), to_axes(A, tail(axs), tail(inds))...)
 end
diff --git a/src/ranges.jl b/src/ranges.jl
diff --git a/test/ranges.jl b/test/ranges.jl

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`using ArrayInterface`
	`2`	`+using Pkg`
`2`	`3`
`3`	`4`	`function dev_subpkg(subpkg)`
`4`	`5`	`subpkg_path = joinpath(dirname(@__DIR__), "lib", subpkg)`
`@@ -21,4 +22,3 @@ makedocs(;`
`21`	`22`	`deploydocs(;`
`22`	`23`	`repo="github.com/JuliaArrays/ArrayInterface.jl"`
`23`	`24`	`)`
`24`		`-`