Skip to content

Commit 52bc1f9

Browse files
authored
Merge pull request #565 from rust-ndarray/box-art-illustrations
Use box drawing art for illustrating an example for ArrayView::split_at
2 parents ea82bf4 + 2ab3e9e commit 52bc1f9

File tree

2 files changed

+89
-3
lines changed

2 files changed

+89
-3
lines changed

src/impl_methods.rs

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1117,6 +1117,28 @@ where
11171117
/// **Panics** if any dimension of `window_size` is zero.<br>
11181118
/// (**Panics** if `D` is `IxDyn` and `window_size` does not match the
11191119
/// number of array axes.)
1120+
///
1121+
/// This is an illustration of the 2×2 windows in a 3×4 array:
1122+
///
1123+
/// ```text
1124+
/// ──▶ Axis(1)
1125+
///
1126+
/// │ ┏━━━━━┳━━━━━┱─────┬─────┐ ┌─────┲━━━━━┳━━━━━┱─────┐ ┌─────┬─────┲━━━━━┳━━━━━┓
1127+
/// ▼ ┃ a₀₀ ┃ a₀₁ ┃ │ │ │ ┃ a₀₁ ┃ a₀₂ ┃ │ │ │ ┃ a₀₂ ┃ a₀₃ ┃
1128+
/// Axis(0) ┣━━━━━╋━━━━━╉─────┼─────┤ ├─────╊━━━━━╋━━━━━╉─────┤ ├─────┼─────╊━━━━━╋━━━━━┫
1129+
/// ┃ a₁₀ ┃ a₁₁ ┃ │ │ │ ┃ a₁₁ ┃ a₁₂ ┃ │ │ │ ┃ a₁₂ ┃ a₁₃ ┃
1130+
/// ┡━━━━━╇━━━━━╃─────┼─────┤ ├─────╄━━━━━╇━━━━━╃─────┤ ├─────┼─────╄━━━━━╇━━━━━┩
1131+
/// │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
1132+
/// └─────┴─────┴─────┴─────┘ └─────┴─────┴─────┴─────┘ └─────┴─────┴─────┴─────┘
1133+
///
1134+
/// ┌─────┬─────┬─────┬─────┐ ┌─────┬─────┬─────┬─────┐ ┌─────┬─────┬─────┬─────┐
1135+
/// │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
1136+
/// ┢━━━━━╈━━━━━╅─────┼─────┤ ├─────╆━━━━━╈━━━━━╅─────┤ ├─────┼─────╆━━━━━╈━━━━━┪
1137+
/// ┃ a₁₀ ┃ a₁₁ ┃ │ │ │ ┃ a₁₁ ┃ a₁₂ ┃ │ │ │ ┃ a₁₂ ┃ a₁₃ ┃
1138+
/// ┣━━━━━╋━━━━━╉─────┼─────┤ ├─────╊━━━━━╋━━━━━╉─────┤ ├─────┼─────╊━━━━━╋━━━━━┫
1139+
/// ┃ a₂₀ ┃ a₂₁ ┃ │ │ │ ┃ a₂₁ ┃ a₂₂ ┃ │ │ │ ┃ a₂₂ ┃ a₂₃ ┃
1140+
/// ┗━━━━━┻━━━━━┹─────┴─────┘ └─────┺━━━━━┻━━━━━┹─────┘ └─────┴─────┺━━━━━┻━━━━━┛
1141+
/// ```
11201142
pub fn windows<E>(&self, window_size: E) -> Windows<'_, A, D>
11211143
where
11221144
E: IntoDimension<Dim = D>,

src/impl_views.rs

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,74 @@ where
124124
///
125125
/// **Panics** if `axis` or `index` is out of bounds.
126126
///
127-
/// Below, an illustration of `.split_at(Axis(2), 2)` on
128-
/// an array with shape 3 × 5 × 5.
127+
/// **Examples:**
128+
/// ```rust
129+
/// # use ndarray::prelude::*;
130+
/// let a = aview2(&[[0, 1, 2, 3],
131+
/// [4, 5, 6, 7],
132+
/// [8, 9, 0, 1]]);
129133
///
130-
/// <img src="https://rust-ndarray.github.io/ndarray/images/split_at.svg" width="300px" height="271px">
134+
/// ```
135+
/// The array view `a` has two axes and shape 3 × 4:
136+
/// ```text
137+
/// ──▶ Axis(1)
138+
/// ┌─────┬─────┬─────┬─────┐ 0
139+
/// │ │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │
140+
/// ▼ ├─────┼─────┼─────┼─────┤ 1
141+
/// Axis(0)│ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
142+
/// ├─────┼─────┼─────┼─────┤ 2
143+
/// │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │
144+
/// └─────┴─────┴─────┴─────┘ 3 ↑
145+
/// 0 1 2 3 4 ← possible split_at indices.
146+
/// ```
147+
///
148+
/// Row indices increase along `Axis(0)`, and column indices increase along
149+
/// `Axis(1)`. Note that we split “before” an element index, and that
150+
/// both 0 and the endpoint are valid split indices.
151+
///
152+
/// **Example 1**: Split `a` along the first axis, in this case the rows, at
153+
/// index 1.<br>
154+
/// This produces views v1 and v2 of shapes 1 × 4 and 2 × 4:
155+
///
156+
/// ```rust
157+
/// # use ndarray::prelude::*;
158+
/// # let a = aview2(&[[0; 4]; 3]);
159+
/// let (v1, v2) = a.split_at(Axis(0), 1);
160+
/// ```
161+
/// ```text
162+
/// ┌─────┬─────┬─────┬─────┐ 0 ↓ indices
163+
/// │ a₀₀ │ a₀₁ │ a₀₂ │ a₀₃ │ along Axis(0)
164+
/// ├─────┼─────┼─────┼─────┤ v1 1
165+
/// │ a₁₀ │ a₁₁ │ a₁₂ │ a₁₃ │
166+
/// └─────┴─────┴─────┴─────┘
167+
/// ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ 2
168+
/// ┌─────┬─────┬─────┬─────┐
169+
/// │ a₂₀ │ a₂₁ │ a₂₂ │ a₂₃ │ v2
170+
/// └─────┴─────┴─────┴─────┘ 3
171+
/// ```
172+
///
173+
/// **Example 2**: Split `a` along the second axis, in this case the
174+
/// columns, at index 2.<br>
175+
/// This produces views u1 and u2 of shapes 3 × 2 and 3 × 2:
176+
///
177+
/// ```rust
178+
/// # use ndarray::prelude::*;
179+
/// # let a = aview2(&[[0; 4]; 3]);
180+
/// let (u1, u2) = a.split_at(Axis(1), 2);
181+
///
182+
/// ```
183+
/// ```text
184+
/// u1 u2
185+
/// ┌─────┬─────┐┊┌─────┬─────┐
186+
/// │ a₀₀ │ a₀₁ │┊│ a₀₂ │ a₀₃ │
187+
/// ├─────┼─────┤┊├─────┼─────┤
188+
/// │ a₁₀ │ a₁₁ │┊│ a₁₂ │ a₁₃ │
189+
/// ├─────┼─────┤┊├─────┼─────┤
190+
/// │ a₂₀ │ a₂₁ │┊│ a₂₂ │ a₂₃ │
191+
/// └─────┴─────┘┊└─────┴─────┘
192+
/// 0 1 2 3 4 indices →
193+
/// along Axis(1)
194+
/// ```
131195
pub fn split_at(self, axis: Axis, index: Ix) -> (Self, Self) {
132196
unsafe {
133197
let (left, right) = self.into_raw_view().split_at(axis, index);

0 commit comments

Comments
 (0)