CartesianRange constructor and eachindex

NEWS.md

@@ -388,6 +388,11 @@ Library improvements
  This supersedes the old behavior of reinterpret on Arrays. As a result, reinterpreting
  arrays with different alignment requirements (removed in 0.6) is once again allowed ([#23750]).
 
+ * `CartesianRange` changes ([#24715]):
+ - Inherits from `AbstractArray`
+ - Constructor taking an array
+ - `eachindex` returns the linear indices into a reshaped array, as `sub2ind` alternative
+
 Compiler/Runtime improvements
 -----------------------------
 

base/abstractarray.jl

@@ -811,6 +811,17 @@ if all inputs have fast linear indexing, a [`CartesianRange`](@ref)
 otherwise).
 If the arrays have different sizes and/or dimensionalities, `eachindex` returns an
 iterable that spans the largest range along each dimension.
+
+For a CartesianRange, this returns a reshaped range of the linear indices into
+the range, e.g.:
+
+```jldoctest
+julia> eachindex(CartesianRange((1:2,1:3)))
+2×3 reshape(::Base.OneTo{Int64}, 2, 3) with eltype Int64:
+ 1 3 5
+ 2 4 6
+```
+
 """
 eachindex(A::AbstractArray) = (@_inline_meta(); eachindex(IndexStyle(A), A))
 

base/multidimensional.jl

@@ -172,6 +172,11 @@ module IteratorsMD
  Consequently these can be useful for writing algorithms that
  work in arbitrary dimensions.
 
+ CartesianRange(A::AbstractArray) -> R
+
+ As a convenience, constructing a CartesianRange from an array makes a
+ range of its indices.
+
  # Examples
  ```jldoctest
  julia> foreach(println, CartesianRange((2, 2, 2)))
@@ -183,7 +188,47 @@ module IteratorsMD
  CartesianIndex(2, 1, 2)
  CartesianIndex(1, 2, 2)
  CartesianIndex(2, 2, 2)
+
+ julia> CartesianRange(ones(2,3))
+ 2×3 CartesianRange{2,Tuple{Base.OneTo{Int64},Base.OneTo{Int64}}}:
+ CartesianIndex(1, 1) CartesianIndex(1, 2) CartesianIndex(1, 3)
+ CartesianIndex(2, 1) CartesianIndex(2, 2) CartesianIndex(2, 3)
  ```
+
+ ## Conversion between linear and cartesian indices
+ 
+ Linear index to cartesian index conversion exploits the fact that a
+ `CartesianRange` is an `AbstractArray` and can be indexed linearly:
+ 
+ ```jldoctest subarray
+ julia> cartesian = CartesianRange(1:3,1:2)
+ 3×2 CartesianRange{2,Tuple{UnitRange{Int64},UnitRange{Int64}}}:
+ CartesianIndex(1, 1) CartesianIndex(1, 2)
+ CartesianIndex(2, 1) CartesianIndex(2, 2)
+ CartesianIndex(3, 1) CartesianIndex(3, 2)
+ 
+ julia> cartesian[4]
+ CartesianIndex(1, 2)
+ ```
+ 
+ For cartesian to linear index conversion, [`eachindex`](@ref) returns a
+ reshaped version of the linear indices when called on a `CartesianRange`:
+ 
+ ```jldoctest subarray
+ julia> linear = eachindex(cartesian)
+ 3×2 reshape(::Base.OneTo{Int64}, 3, 2) with eltype Int64:
+ 1 4
+ 2 5
+ 3 6
+ 
+ julia> linear[1,2]
+ 4
+ 
+ julia> linear[cartesian[4]]
+ 4
+ ```
+ 
+
  """
  struct CartesianRange{N,R<:NTuple{N,AbstractUnitRange{Int}}} <: AbstractArray{CartesianIndex{N},N}
  indices::R
@@ -204,6 +249,8 @@ module IteratorsMD
  CartesianRange(inds::NTuple{N,Union{<:Integer,AbstractUnitRange{<:Integer}}}) where {N} =
  CartesianRange(map(i->first(i):last(i), inds))
 
+ CartesianRange(A::AbstractArray) = CartesianRange(indices(A))
+
  convert(::Type{Tuple{}}, R::CartesianRange{0}) = ()
  convert(::Type{NTuple{N,AbstractUnitRange{Int}}}, R::CartesianRange{N}) where {N} =
  R.indices
@@ -225,6 +272,7 @@ module IteratorsMD
  # AbstractArray implementation
  Base.IndexStyle(::Type{CartesianRange{N,R}}) where {N,R} = IndexCartesian()
  @inline Base.getindex(iter::CartesianRange{N,R}, I::Vararg{Int, N}) where {N,R} = CartesianIndex(first.(iter.indices) .- 1 .+ I)
+ Base.eachindex(iter::CartesianRange) = reshape(linearindices(iter), size(iter))
 
  ndims(R::CartesianRange) = ndims(typeof(R))
  ndims(::Type{CartesianRange{N}}) where {N} = N

doc/src/devdocs/subarrays.md

@@ -22,9 +22,8 @@ computation (such as interpolation), and the type under discussion here, `SubArr
 For these types, the underlying information is more naturally described in terms of
 cartesian indexes.
 
-You can manually convert from a cartesian index to a linear index with `sub2ind`, and vice versa
-using `ind2sub`. `getindex` and `setindex!` functions for `AbstractArray` types may include similar
-operations.
+The `getindex` and `setindex!` functions for `AbstractArray` types may include automatic conversion
+between indexing types. For explicit conversion, [`CartesianRange`](@ref) can be used.
 
 While converting from a cartesian index to a linear index is fast (it's just multiplication and
 addition), converting from a linear index to a cartesian index is very slow: it relies on the

test/abstractarray.jl

@@ -894,4 +894,7 @@ end
  j = (i_lin-i) ÷ length(xrng) + 1
  @test CR[i_lin] == CartesianIndex(xrng[i],yrng[j])
  end
+
+ @test CartesianRange(ones(2,3)) == CartesianRange((2,3))
+ @test eachindex(CartesianRange((2,3))) == [1 3 5; 2 4 6]
 end