Merge pull request #565 from rust-ndarray/box-art-illustrations

Use box drawing art for illustrating an example for ArrayView::split_at

Author: bluss

src/impl_methods.rs

@@ -1117,6 +1117,28 @@ where
     /// **Panics** if any dimension of `window_size` is zero.<br>
     /// (**Panics** if `D` is `IxDyn` and `window_size` does not match the
     /// number of array axes.)
+    ///
+    /// This is an illustration of the 2×2 windows in a 3×4 array:
+    ///
+    /// ```text
+    ///          ──▶ Axis(1)
+    ///
+    ///      │   ┏━━━━━┳━━━━━┱─────┬─────┐   ┌─────┲━━━━━┳━━━━━┱─────┐   ┌─────┬─────┲━━━━━┳━━━━━┓
+    ///      ▼   ┃ a₀₀ ┃ a₀₁ ┃     │     │   │     ┃ a₀₁ ┃ a₀₂ ┃     │   │     │     ┃ a₀₂ ┃ a₀₃ ┃
+    /// Axis(0)  ┣━━━━━╋━━━━━╉─────┼─────┤   ├─────╊━━━━━╋━━━━━╉─────┤   ├─────┼─────╊━━━━━╋━━━━━┫
+    ///          ┃ a₁₀ ┃ a₁₁ ┃     │     │   │     ┃ a₁₁ ┃ a₁₂ ┃     │   │     │     ┃ a₁₂ ┃ a₁₃ ┃
+    ///          ┡━━━━━╇━━━━━╃─────┼─────┤   ├─────╄━━━━━╇━━━━━╃─────┤   ├─────┼─────╄━━━━━╇━━━━━┩
+    ///          │     │     │     │     │   │     │     │     │     │   │     │     │     │     │
+    ///          └─────┴─────┴─────┴─────┘   └─────┴─────┴─────┴─────┘   └─────┴─────┴─────┴─────┘
+    ///
+    ///          ┌─────┬─────┬─────┬─────┐   ┌─────┬─────┬─────┬─────┐   ┌─────┬─────┬─────┬─────┐
+    ///          │     │     │     │     │   │     │     │     │     │   │     │     │     │     │
+    ///          ┢━━━━━╈━━━━━╅─────┼─────┤   ├─────╆━━━━━╈━━━━━╅─────┤   ├─────┼─────╆━━━━━╈━━━━━┪
+    ///          ┃ a₁₀ ┃ a₁₁ ┃     │     │   │     ┃ a₁₁ ┃ a₁₂ ┃     │   │     │     ┃ a₁₂ ┃ a₁₃ ┃
+    ///          ┣━━━━━╋━━━━━╉─────┼─────┤   ├─────╊━━━━━╋━━━━━╉─────┤   ├─────┼─────╊━━━━━╋━━━━━┫
+    ///          ┃ a₂₀ ┃ a₂₁ ┃     │     │   │     ┃ a₂₁ ┃ a₂₂ ┃     │   │     │     ┃ a₂₂ ┃ a₂₃ ┃
+    ///          ┗━━━━━┻━━━━━┹─────┴─────┘   └─────┺━━━━━┻━━━━━┹─────┘   └─────┴─────┺━━━━━┻━━━━━┛
+    /// ```
     pub fn windows<E>(&self, window_size: E) -> Windows<'_, A, D>
     where
         E: IntoDimension<Dim = D>,

src/impl_views.rs

@@ -124,10 +124,74 @@ where
     ///
     /// **Panics** if `axis` or `index` is out of bounds.
     ///
-    /// Below, an illustration of `.split_at(Axis(2), 2)` on
-    /// an array with shape 3 × 5 × 5.
+    /// **Examples:**
+    /// ```rust
+    /// # use ndarray::prelude::*;
+    /// let a = aview2(&[[0, 1, 2, 3],
+    ///                  [4, 5, 6, 7],
+    ///                  [8, 9, 0, 1]]);
     ///
-    /// <img src="https://rust-ndarray.github.io/ndarray/images/split_at.svg" width="300px" height="271px">
+    /// ```
+    /// The array view `a` has two axes and shape 3 × 4:
+    /// ```text
+    ///          ──▶ Axis(1)
+    ///         ┌─────┬─────┬─────┬─────┐ 0
+    ///       │ │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │
+    ///       ▼ ├─────┼─────┼─────┼─────┤ 1
+    ///  Axis(0)│ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
+    ///         ├─────┼─────┼─────┼─────┤ 2
+    ///         │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │
+    ///         └─────┴─────┴─────┴─────┘ 3 ↑
+    ///         0     1     2     3     4 ← possible split_at indices.
+    /// ```
+    ///
+    /// Row indices increase along `Axis(0)`, and column indices increase along
+    /// `Axis(1)`. Note that we split “before” an element index, and that
+    /// both 0 and the endpoint are valid split indices.
+    ///
+    /// **Example 1**: Split `a` along the first axis, in this case the rows, at
+    /// index 1.<br>
+    /// This produces views v1 and v2 of shapes 1 × 4 and 2 × 4:
+    ///
+    /// ```rust
+    /// # use ndarray::prelude::*;
+    /// # let a = aview2(&[[0; 4]; 3]);
+    /// let (v1, v2) = a.split_at(Axis(0), 1);
+    /// ```
+    /// ```text
+    ///         ┌─────┬─────┬─────┬─────┐       0  ↓ indices
+    ///         │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │            along Axis(0)
+    ///         ├─────┼─────┼─────┼─────┤ v1    1
+    ///         │ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
+    ///         └─────┴─────┴─────┴─────┘
+    ///         ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄       2
+    ///         ┌─────┬─────┬─────┬─────┐
+    ///         │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │ v2
+    ///         └─────┴─────┴─────┴─────┘       3
+    /// ```
+    ///
+    /// **Example 2**: Split `a` along the second axis, in this case the
+    /// columns, at index 2.<br>
+    /// This produces views u1 and u2 of shapes 3 × 2 and 3 × 2:
+    ///
+    /// ```rust
+    /// # use ndarray::prelude::*;
+    /// # let a = aview2(&[[0; 4]; 3]);
+    /// let (u1, u2) = a.split_at(Axis(1), 2);
+    ///
+    /// ```
+    /// ```text
+    ///              u1             u2
+    ///         ┌─────┬─────┐┊┌─────┬─────┐
+    ///         │ a₀₀ │ a₀₁ │┊│ a₀₂ │ a₀₃ │
+    ///         ├─────┼─────┤┊├─────┼─────┤
+    ///         │ a₁₀ │ a₁₁ │┊│ a₁₂ │ a₁₃ │
+    ///         ├─────┼─────┤┊├─────┼─────┤
+    ///         │ a₂₀ │ a₂₁ │┊│ a₂₂ │ a₂₃ │
+    ///         └─────┴─────┘┊└─────┴─────┘
+    ///         0     1      2      3     4  indices →
+    ///                                      along Axis(1)
+    /// ```
     pub fn split_at(self, axis: Axis, index: Ix) -> (Self, Self) {
         unsafe {
             let (left, right) = self.into_raw_view().split_at(axis, index);