Add a trait to tie together compile-time and runtime number of dimensions (#1575)

This is the next PR to address #1506. In the previous PR (#1568) we
established a trait for capturing the "dimensionality" or "rank" of an
array at the type level. This PR is focused on providing a bridge from
type-level dimensionality to runtime dimensionality, which we do through
the new `Ranked` trait.

The `Ranked` trait is pretty simple: require an associated type (`NDim`)
that carries compile-time dimensionality, and a function `fn ndim(&self)
-> usize` that tells the user runtime dimensionality. The
`src/layout/ranked.rs` file contains the definition, implementations,
and blanket implementations.

This commit also does some moves and renames of the existing
`Dimensionality` trait, renaming it to `Rank`, as well as many of
the types in that file.

Author: akern40

src/dimension/dimension_trait.rs

@@ -17,8 +17,8 @@ use super::conversion::Convert;
 use super::ops::DimAdd;
 use super::{stride_offset, stride_offset_checked};
 use crate::itertools::{enumerate, zip};
-#[cfg(feature = "unstable")]
-use crate::layout::dimensionality::*;
+use crate::layout::rank::*;
+use crate::layout::ranked::Ranked;
 use crate::IntoDimension;
 use crate::RemoveAxis;
 use crate::{ArrayView1, ArrayViewMut1};
@@ -61,6 +61,7 @@ pub trait Dimension:
     + DimAdd<Ix0, Output = Self>
     + DimAdd<Ix1, Output = <Self as Dimension>::Larger>
     + DimAdd<IxDyn, Output = IxDyn>
+    + Ranked
 {
     /// For fixed-size dimension representations (e.g. `Ix2`), this should be
     /// `Some(ndim)`, and for variable-size dimension representations (e.g.
@@ -78,13 +79,6 @@ pub trait Dimension:
     /// Next larger dimension
     type Larger: Dimension + RemoveAxis;
 
-    /// The dimensionality of the type, under the new, unstable API.
-    #[cfg(feature = "unstable")]
-    type Rank: Dimensionality;
-
-    /// Returns the number of dimensions (number of axes).
-    fn ndim(&self) -> usize;
-
     /// Convert the dimension into a pattern matching friendly value.
     fn into_pattern(self) -> Self::Pattern;
 
@@ -420,21 +414,26 @@ macro_rules! impl_insert_axis_array(
     );
 );
 
+impl<const N: usize> Ranked for Dim<[Ix; N]>
+where ConstRank<N>: Rank // Limit us to < 12, since Rank must impl Dimensionality
+{
+    type NDim = ConstRank<N>;
+
+    #[inline]
+    fn ndim(&self) -> usize
+    {
+        N
+    }
+}
+
 impl Dimension for Dim<[Ix; 0]>
 {
     const NDIM: Option<usize> = Some(0);
     type Pattern = ();
     type Smaller = Self;
     type Larger = Ix1;
-    #[cfg(feature = "unstable")]
-    type Rank = D0;
     // empty product is 1 -> size is 1
     #[inline]
-    fn ndim(&self) -> usize
-    {
-        0
-    }
-    #[inline]
     fn slice(&self) -> &[Ix]
     {
         &[]
@@ -478,13 +477,6 @@ impl Dimension for Dim<[Ix; 1]>
     type Pattern = Ix;
     type Smaller = Ix0;
     type Larger = Ix2;
-    #[cfg(feature = "unstable")]
-    type Rank = D1;
-    #[inline]
-    fn ndim(&self) -> usize
-    {
-        1
-    }
     #[inline]
     fn slice(&self) -> &[Ix]
     {
@@ -613,13 +605,6 @@ impl Dimension for Dim<[Ix; 2]>
     type Pattern = (Ix, Ix);
     type Smaller = Ix1;
     type Larger = Ix3;
-    #[cfg(feature = "unstable")]
-    type Rank = D2;
-    #[inline]
-    fn ndim(&self) -> usize
-    {
-        2
-    }
     #[inline]
     fn into_pattern(self) -> Self::Pattern
     {
@@ -790,13 +775,6 @@ impl Dimension for Dim<[Ix; 3]>
     type Pattern = (Ix, Ix, Ix);
     type Smaller = Ix2;
     type Larger = Ix4;
-    #[cfg(feature = "unstable")]
-    type Rank = D3;
-    #[inline]
-    fn ndim(&self) -> usize
-    {
-        3
-    }
     #[inline]
     fn into_pattern(self) -> Self::Pattern
     {
@@ -924,10 +902,6 @@ macro_rules! large_dim {
             type Pattern = $pattern;
             type Smaller = Dim<[Ix; $n - 1]>;
             type Larger = $larger;
-            #[cfg(feature = "unstable")]
-            type Rank = NDim<$n>;
-            #[inline]
-            fn ndim(&self) -> usize { $n }
             #[inline]
             fn into_pattern(self) -> Self::Pattern {
                 self.ix().convert()
@@ -968,6 +942,17 @@ large_dim!(6, Ix6, (Ix, Ix, Ix, Ix, Ix, Ix), IxDyn, {
     }
 });
 
+impl Ranked for IxDyn
+{
+    type NDim = DynRank;
+
+    #[inline]
+    fn ndim(&self) -> usize
+    {
+        self.ix().len()
+    }
+}
+
 /// IxDyn is a "dynamic" index, pretty hard to use when indexing,
 /// and memory wasteful, but it allows an arbitrary and dynamic number of axes.
 impl Dimension for IxDyn
@@ -976,13 +961,6 @@ impl Dimension for IxDyn
     type Pattern = Self;
     type Smaller = Self;
     type Larger = Self;
-    #[cfg(feature = "unstable")]
-    type Rank = DDyn;
-    #[inline]
-    fn ndim(&self) -> usize
-    {
-        self.ix().len()
-    }
     #[inline]
     fn slice(&self) -> &[Ix]
     {

src/dimension/dynindeximpl.rs

@@ -1,4 +1,5 @@
 use crate::imp_prelude::*;
+use crate::layout::ranked::Ranked;
 #[cfg(not(feature = "std"))]
 use alloc::boxed::Box;
 use alloc::vec;

src/dimension/ndindex.rs

@@ -2,6 +2,7 @@ use std::fmt::Debug;
 
 use super::{stride_offset, stride_offset_checked};
 use crate::itertools::zip;
+use crate::layout::ranked::Ranked;
 use crate::{Dim, Dimension, IntoDimension, Ix, Ix0, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn, IxDynImpl};
 
 /// Tuple or fixed size arrays that can be used to index an array.

src/dimension/remove_axis.rs

@@ -6,7 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use crate::{Axis, Dim, Dimension, Ix, Ix0, Ix1};
+use crate::{layout::ranked::Ranked, Axis, Dim, Dimension, Ix, Ix0, Ix1};
 
 /// Array shape with a next smaller dimension.
 ///

src/indexes.rs

@@ -7,6 +7,7 @@
 // except according to those terms.
 use super::Dimension;
 use crate::dimension::IntoDimension;
+use crate::layout::ranked::Ranked;
 use crate::split_at::SplitAt;
 use crate::zip::Offset;
 use crate::Axis;

src/layout/mod.rs

@@ -9,8 +9,8 @@
 //! flexible and expressive layout representations.
 
 mod bitset;
-#[cfg(feature = "unstable")]
-pub mod dimensionality;
+pub mod rank;
+pub mod ranked;
 
 #[allow(deprecated)]
 pub use bitset::{Layout, LayoutBitset};