More dimension names documentation (#201)

This provides a specific example of supporting `dimnames`.
Also removed the need to specify a method per dimension access to
dimnames so `dimnames(::Type{T})` is all that's necessary.

Author: Tokazama

docs/src/index.md

@@ -82,7 +82,7 @@ For example, all `Integers` passed to `to_dims` are converted to `Int` (unless `
 This is also useful for arrays that uniquely label dimensions, in which case `to_dims` serves as a safe point of hooking into existing methods with dimension arguments.
 `ArrayInterface` also defines native `Symbol` to `Int` and `StaticSymbol` to `StaticInt` mapping  for arrays defining [`ArrayInterface.dimnames`](@ref).
 
-Methods accepting dimension specific arguments should use some variation of the following pattern.
+Methods requiring dimension specific arguments should use some variation of the following pattern.
 
 ```julia
 f(x, dim) = f(x, ArrayInterface.to_dims(x, dim))
@@ -93,3 +93,18 @@ 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.
 
+New types defining dimension names can do something similar to:
+```julia
+using Static
+using ArrayInterface
+
+struct NewType{dnames} end  # where dnames::Tuple{Vararg{Symbol}}
+
+ArrayInterface.dimnames(::Type{NewType{dnames}}) = static(dnames)
+```
+
+Dimension names should be appropriately propagated between nested arrays using `ArrayInterface.to_parent_dims`. 
+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.
+
+

src/dimensions.jl

@@ -150,7 +150,8 @@ end
 """
     has_dimnames(::Type{T}) -> Bool
 
-Returns `static(true)` if `x` has on or more named dimensions.
+Returns `static(true)` if `x` has on or more named dimensions. If all dimensions correspond
+to `static(:_)`, then `static(false)` is returned.
 """
 has_dimnames(x) = has_dimnames(typeof(x))
 @inline has_dimnames(::Type{T}) where {T} = _has_dimnames(dimnames(T))
@@ -164,32 +165,25 @@ const SUnderscore = StaticSymbol(:_)
     dimnames(::Type{T}) -> Tuple{Vararg{StaticSymbol}}
     dimnames(::Type{T}, dim) -> StaticSymbol
 
-Return the names of the dimensions for `x`.
+Return the names of the dimensions for `x`. `static(:_)` is used to indicate a dimension
+does not have a name.
 """
 @inline dimnames(x) = dimnames(typeof(x))
-@inline dimnames(x, dim) = dimnames(typeof(x), dim)
-@inline function dimnames(::Type{T}, dim) where {T}
-    if parent_type(T) <: T
-        return SUnderscore
-    else
-        return dimnames(parent_type(T), to_parent_dims(T, dim))
-    end
+@inline dimnames(::Type{T}) where {T} = _dimnames(has_parent(T), T)
+_dimnames(::False, ::Type{T}) where {T} = ntuple(_->static(:_), Val(ndims(T)))
+@inline function _dimnames(::True, ::Type{T}) where {T}
+    eachop(_perm_dimnames, to_parent_dims(T), dimnames(parent_type(T)))
 end
-@inline function dimnames(::Type{T}) where {T}
-    if parent_type(T) <: T
-        return ntuple(_ -> SUnderscore, Val(ndims(T)))
+
+@inline dimnames(x, dim) = dimnames(typeof(x), dim)
+@inline dimnames(::Type{T}, dim::Integer) where {T} = _perm_dimnames(dimnames(T), dim)
+function _perm_dimnames(dnames::Tuple{Vararg{StaticSymbol,N}}, dim) where {N}
+    if dim > N
+        return static(:_)
     else
-        perm = to_parent_dims(T)
-        if invariant_permutation(perm, perm) isa True
-            return dimnames(parent_type(T))
-        else
-            return eachop(dimnames, perm, parent_type(T))
-        end
+        return @inbounds(dnames[dim])
     end
 end
-function dimnames(::Type{T}) where {T<:SubArray}
-    return eachop(dimnames, to_parent_dims(T), parent_type(T))
-end
 
 """
     to_dims(::Type{T}, dim) -> Union{Int,StaticInt}

test/dimensions.jl

@@ -10,14 +10,7 @@ struct NamedDimsWrapper{L,T,N,P<:AbstractArray{T,N}} <: ArrayInterface.AbstractA
     NamedDimsWrapper{L}(p) where {L} = new{L,eltype(p),ndims(p),typeof(p)}(p)
 end
 ArrayInterface.parent_type(::Type{T}) where {P,T<:NamedDimsWrapper{<:Any,<:Any,<:Any,P}} = P
-ArrayInterface.dimnames(::Type{T}) where {L,T<:NamedDimsWrapper{L}} = static(Val(L))
-function ArrayInterface.dimnames(::Type{T}, dim) where {L,T<:NamedDimsWrapper{L}}
-    if ndims(T) < dim
-        return static(:_)
-    else
-        return static(L[dim])
-    end
-end
+ArrayInterface.dimnames(::Type{T}) where {L,T<:NamedDimsWrapper{L}} = static(L)
 Base.parent(x::NamedDimsWrapper) = x.parent
 
 @testset "dimension permutations" begin