add new abstract type for iterators with HasShape: ShapefulIterator

Iterators with `HasShape{N}` are certainly the most well-behaved class
of iterators in Julia. Currently several separate type trees of such
iterators come with Julia. It seems like joining these trees under a
single abstract type would be nice.

Why this change is useful:
* Make expressing hardcoded `Union` types for zero-dimensional
  collections unnecessary: instead of
  `Union{Number,Ref,AbstractArray{<:Any,0}}` now it will be possible to
  write simply, and more generically, `ShapefulIterator{0}`. At
  least in some cases.
* Reduce the number of `ndims` and `IteratorSize` methods:
    * The number of `ndims` methods that come with Julia is
      decreased by six
    * The number of `IteratorSize` methods that come with Julia is
      decreased by three

Why this change doesn't prevent a better future supertype choice:
* Naively it might make sense to have `Number`, `AbstractChar` and
  `Ref` subtype a parameterless abstract type like
  `ZeroDimensionalIterator`. However:
    * This seems less useful than `ShapefulIterator{N}`
    * Adding `ShapefulIterator` doesn't preclude adding
      `ZeroDimensionalIterator <: ShapefulIterator{0}` later.
* One might ask: why not make `AbstractArray{T}` subtype a different
  abstract type, with an element type type parameter, something like
  `AbstractArray{T,N} <: TypedIterator{T}`. In this case, however,
  `TypedIterator` would be useless for the zero dimensional iterators
  mentioned above, as they are their own element types, something not
  expressible in abstract type subtyping.

Author: nsajko

NEWS.md

@@ -24,6 +24,13 @@ Build system changes
 New library functions
 ---------------------
 
+* a new abstract type for iterators with `HasShape{N}` is added: `ShapefulIterator{N}`. It supertypes existing abstract types:
+    * `AbstractArray`
+    * `AbstractChar`
+    * `Number`
+    * `Ref`
+  It's still acceptable to define a new shapeful iterator type that does not subtype `ShapefulIterator`, however choosing to subtype `ShapefulIterator{N}` means there's no need to add certain methods for one's newly-defined type.
+
 New library features
 --------------------
 

base/abstractarray.jl

@@ -3,7 +3,7 @@
 ## Basic functions ##
 
 """
-    AbstractArray{T,N}
+    AbstractArray{T,N} <: ShapefulIterator{N}
 
 Supertype for `N`-dimensional arrays (or array-like types) with elements of type `T`.
 [`Array`](@ref) and other types are subtypes of this. See the manual section on the
@@ -256,25 +256,6 @@ julia> Base.elsize(rand(Float32, 10))
 """
 elsize(A::AbstractArray) = elsize(typeof(A))
 
-"""
-    ndims(A::AbstractArray)::Integer
-
-Return the number of dimensions of `A`.
-
-See also: [`size`](@ref), [`axes`](@ref).
-
-# Examples
-```jldoctest
-julia> A = fill(1, (3,4,5));
-
-julia> ndims(A)
-3
-```
-"""
-ndims(::AbstractArray{T,N}) where {T,N} = N::Int
-ndims(::Type{<:AbstractArray{<:Any,N}}) where {N} = N::Int
-ndims(::Type{Union{}}, slurp...) = throw(ArgumentError("Union{} does not have elements"))
-
 """
     length(collection)::Integer
 

base/boot.jl

@@ -49,7 +49,8 @@
 #end
 #const nothing = Nothing()
 
-#abstract type AbstractArray{T,N} end
+#abstract type ShapefulIterator{N} end
+#abstract type AbstractArray{T,N} <: ShapefulIterator{N} end
 #abstract type DenseArray{T,N} <: AbstractArray{T,N} end
 
 #primitive type AddrSpace{Backend::Module} 8 end
@@ -208,7 +209,7 @@ export
     # key types
     Any, DataType, Vararg, NTuple,
     Tuple, Type, UnionAll, TypeVar, Union, Nothing, Cvoid,
-    AbstractArray, DenseArray, NamedTuple, Pair,
+    AbstractArray, DenseArray, NamedTuple, Pair, ShapefulIterator,
     # special objects
     Function, Method, Module, Symbol, Task, UndefInitializer, undef, WeakRef, VecElement,
     Array, Memory, MemoryRef, AtomicMemory, AtomicMemoryRef, GenericMemory, GenericMemoryRef,
@@ -245,7 +246,7 @@ export
 const getproperty = getfield # TODO: use `getglobal` for modules instead
 const setproperty! = setfield!
 
-abstract type Number end
+abstract type Number   <: ShapefulIterator{0} end
 abstract type Real     <: Number end
 abstract type AbstractFloat <: Real end
 abstract type Integer  <: Real end
@@ -259,7 +260,7 @@ primitive type Float64 <: AbstractFloat 64 end
 primitive type BFloat16 <: AbstractFloat 16 end
 
 #primitive type Bool <: Integer 8 end
-abstract type AbstractChar end
+abstract type AbstractChar <: ShapefulIterator{0} end
 primitive type Char <: AbstractChar 32 end
 
 primitive type Int8    <: Signed   8 end

base/broadcast.jl

@@ -643,7 +643,7 @@ to_index(Is::Tuple) = CartesianIndex(Is)
 
 Index into `A` with `I`, collapsing broadcasted indices to their singleton indices as appropriate.
 """
-Base.@propagate_inbounds _broadcast_getindex(A::Union{Ref,AbstractArray{<:Any,0},Number}, I) = A[] # Scalar-likes can just ignore all indices
+Base.@propagate_inbounds _broadcast_getindex(A::ShapefulIterator{0}, I) = A[] # Scalar-likes can just ignore all indices
 Base.@propagate_inbounds _broadcast_getindex(::Ref{Type{T}}, I) where {T} = T
 # Tuples are statically known to be singleton or vector-like
 Base.@propagate_inbounds _broadcast_getindex(A::Tuple{Any}, I) = A[1]
@@ -728,7 +728,7 @@ Base.RefValue{String}("hello")
 """
 broadcastable(x::Union{Symbol,AbstractString,Function,UndefInitializer,Nothing,RoundingMode,Missing,Val,Ptr,AbstractPattern,Pair,IO,CartesianIndex}) = Ref(x)
 broadcastable(::Type{T}) where {T} = Ref{Type{T}}(T)
-broadcastable(x::Union{AbstractArray,Number,AbstractChar,Ref,Tuple,Broadcasted}) = x
+broadcastable(x::Union{ShapefulIterator,Tuple,Broadcasted}) = x
 # Default to collecting iterables — which will error for non-iterables
 broadcastable(x) = collect(x)
 broadcastable(::Union{AbstractDict, NamedTuple}) = throw(ArgumentError("broadcasting over dictionaries and `NamedTuple`s is reserved"))

base/char.jl

@@ -3,6 +3,8 @@
 import Core: AbstractChar, Char
 
 """
+    AbstractChar <: ShapefulIterator{0}
+
 The `AbstractChar` type is the supertype of all character implementations
 in Julia. A character represents a Unicode code point, and can be converted
 to an integer via the [`codepoint`](@ref) function in order to obtain the
@@ -202,10 +204,7 @@ typemin(::Type{Char}) = bitcast(Char, typemin(UInt32))
 
 size(c::AbstractChar) = ()
 size(c::AbstractChar, d::Integer) = d < 1 ? throw(BoundsError()) : 1
-ndims(c::AbstractChar) = 0
-ndims(::Type{<:AbstractChar}) = 0
 length(c::AbstractChar) = 1
-IteratorSize(::Type{Char}) = HasShape{0}()
 firstindex(c::AbstractChar) = 1
 lastindex(c::AbstractChar) = 1
 getindex(c::AbstractChar) = c

base/docs/basedocs.jl

@@ -115,10 +115,10 @@ which are their descendants. Abstract types form the conceptual hierarchy which
 Julia’s type system more than just a collection of object implementations. For example:
 
 ```julia
-abstract type Number end
+abstract type ShapefulIterator{N} end
 abstract type Real <: Number end
 ```
-[`Number`](@ref) has no supertype, whereas [`Real`](@ref) is an abstract subtype of `Number`.
+[`ShapefulIterator`](@ref) has no supertype, whereas [`Real`](@ref) is an abstract subtype of `Number`.
 """
 kw"abstract type", kw"abstract"
 
@@ -2184,7 +2184,23 @@ Stacktrace:
 DivideError
 
 """
-    Number
+    ShapefulIterator{N}
+
+`N`-dimensional [iterator](@ref man-interface-iteration) type, where `N isa Int`.
+
+These functions have methods defined for all subtypes of `ShapefulIterator`, no need to add new methods - if you do add new methods they must be consistent with the following definitions:
+* [`ndims`](@ref): returns `N`
+* [`Base.IteratorSize`](@ref): returns `Base.HasShape{N}()`
+
+New subtypes must implement:
+* [`length`](@ref)
+* [`size`](@ref)
+* [`axes`](@ref), if the new subtype uses non-traditional indices
+"""
+ShapefulIterator
+
+"""
+    Number <: ShapefulIterator{0}
 
 Abstract supertype for all number types.
 """

base/exports.jl

@@ -5,7 +5,7 @@ export Core,
     # key types
     Any, DataType, Vararg, NTuple,
     Tuple, Type, UnionAll, TypeVar, Union, Nothing, Cvoid,
-    AbstractArray, DenseArray, NamedTuple, Pair,
+    AbstractArray, DenseArray, NamedTuple, Pair, ShapefulIterator,
     # special objects
     Function, Method, Module, Symbol, Task, UndefInitializer, undef, WeakRef, VecElement,
     Array, Memory, MemoryRef, AtomicMemory, AtomicMemoryRef, GenericMemory, GenericMemoryRef,

base/generator.jl

@@ -97,11 +97,30 @@ IteratorSize(::Type{Union{}}, slurp...) = throw(ArgumentError("Union{} does not
 IteratorSize(::Type{Any}) = SizeUnknown()
 
 IteratorSize(::Type{<:Tuple}) = HasLength()
-IteratorSize(::Type{<:AbstractArray{<:Any,N}})  where {N} = HasShape{N}()
+IteratorSize(::Type{<:ShapefulIterator{N}})  where {N} = HasShape{N::Int}()
 IteratorSize(::Type{Generator{I,F}}) where {I,F} = IteratorSize(I)
 
 haslength(iter) = IteratorSize(iter) isa Union{HasShape, HasLength}
 
+"""
+    ndims(A::ShapefulIterator)::Int
+
+Return the number of dimensions of `A`.
+
+See also: [`size`](@ref), [`axes`](@ref).
+
+# Examples
+```jldoctest
+julia> A = fill(1, (3,4,5));
+
+julia> ndims(A)
+3
+```
+"""
+ndims(::ShapefulIterator{N}) where {N} = N::Int
+ndims(::Type{<:ShapefulIterator{N}}) where {N} = N::Int
+ndims(::Type{Union{}}, slurp...) = throw(ArgumentError("Union{} does not have elements"))
+
 abstract type IteratorEltype end
 struct EltypeUnknown <: IteratorEltype end
 struct HasEltype <: IteratorEltype end

base/number.jl

@@ -82,14 +82,11 @@ size(x::Number, d::Integer) = d < 1 ? throw(BoundsError()) : 1
 axes(x::Number) = ()
 axes(x::Number, d::Integer) = d < 1 ? throw(BoundsError()) : OneTo(1)
 eltype(::Type{T}) where {T<:Number} = T
-ndims(x::Number) = 0
-ndims(::Type{<:Number}) = 0
 length(x::Number) = 1
 firstindex(x::Number) = 1
 firstindex(x::Number, d::Int) = d < 1 ? throw(BoundsError()) : 1
 lastindex(x::Number) = 1
 lastindex(x::Number, d::Int) = d < 1 ? throw(BoundsError()) : 1
-IteratorSize(::Type{<:Number}) = HasShape{0}()
 keys(::Number) = OneTo(1)
 
 getindex(x::Number) = x

base/refpointer.jl

@@ -3,7 +3,7 @@
 import Core: Ref
 
 """
-    Ref{T}
+    Ref{T} <: ShapefulIterator{0}
 
 An object that safely references data of type `T`. This type is guaranteed to point to
 valid, Julia-allocated memory of the correct type. The underlying data is protected from
@@ -100,11 +100,8 @@ size(x::Ref) = ()
 axes(x::Ref) = ()
 length(x::Ref) = 1
 isempty(x::Ref) = false
-ndims(x::Ref) = 0
-ndims(::Type{<:Ref}) = 0
 iterate(r::Ref) = (r[], nothing)
 iterate(r::Ref, s) = nothing
-IteratorSize(::Type{<:Ref}) = HasShape{0}()
 
 # create Ref objects for general object conversion
 unsafe_convert(::Type{Ref{T}}, x::Ref{T}) where {T} = unsafe_convert(Ptr{T}, x)