astrs_data/tensor/view.rs
1//! [`TensorView`] — an N-dimensional, row-major view over a
2//! [`PrimitiveArray`]'s flat values.
3//!
4//! A [`FixedSizeListArray`](crate::array::FixedSizeListArray) of `FixedSizeList`s already models a tensor one
5//! dimension at a time (its own module doc gives the canonical example: a
6//! `FixedSizeList(FixedSizeList(UInt8, 3), 640)` is one row of RGB pixels).
7//! `TensorView` is the other half of that story — given a flat
8//! [`PrimitiveArray`] and a shape, it hands back checked, zero-copy N-D
9//! indexing and sub-view slicing over that same flat buffer, without ever
10//! materialising the nested nested-array structure. [`crate::tensor::image`]
11//! is the concrete accessor built on it for `std/media/v1/Image`.
12//!
13//! ```
14//! use astrs_data::array::Float32Array;
15//! use astrs_data::tensor::TensorView;
16//!
17//! // A 2x3 matrix, row-major: [[1, 2, 3], [4, 5, 6]].
18//! let values = Float32Array::from_values([1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
19//! let tensor = TensorView::from_primitive(&values, [2, 3])?;
20//!
21//! assert_eq!(tensor.get(&[0, 2])?, 3.0);
22//! assert_eq!(tensor.get(&[1, 0])?, 4.0);
23//! assert_eq!(tensor.as_slice(), Some(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0][..]));
24//!
25//! // Row 1 alone, still zero-copy.
26//! let row = tensor.slice_axis(0, 1, 1)?;
27//! assert_eq!(row.as_slice(), Some(&[4.0, 5.0, 6.0][..]));
28//! # Ok::<(), astrs_data::DataError>(())
29//! ```
30//!
31//! # Validity is the caller's problem
32//!
33//! `TensorView` reads [`PrimitiveArray::values`] — every slot, including the
34//! placeholder AstRS stores in a null one — because a tensor has no room for
35//! a validity bitmap of its own and the layouts it is built for
36//! ([`crate::urn::layouts::media::image_layout`] and friends) declare their
37//! sample columns non-nullable. Check
38//! [`Array::null_count`] first if the
39//! source column's nullability is not already pinned down by its schema.
40
41use crate::array::{Array, PrimitiveArray};
42use crate::datatype::ArrowNativeType;
43use crate::error::{DataError, Result};
44
45/// Row-major (C-order) element strides for `shape`: the last axis is
46/// contiguous (`stride == 1`), and each earlier axis's stride is the product
47/// of every axis after it.
48///
49/// Only ever called after [`checked_shape_len`] has proven `shape`'s full
50/// product fits in a `usize` — every stride computed here is a *partial*
51/// product of the same dimensions, so it is bounded by that same total and
52/// cannot overflow either; `saturating_mul` is therefore never actually
53/// asked to saturate, it is just cheaper than re-deriving a `checked_mul`
54/// proof the caller already has.
55fn row_major_strides(shape: &[usize]) -> Vec<usize> {
56 let mut strides = vec![1usize; shape.len()];
57 for axis in (0..shape.len().saturating_sub(1)).rev() {
58 strides[axis] = strides[axis + 1].saturating_mul(shape[axis + 1]);
59 }
60 strides
61}
62
63/// The product of `shape`'s dimensions, or `None` if it overflows `usize`.
64///
65/// A tensor's total element count and every stride [`row_major_strides`]
66/// derives from it are bounded by this same product, so checking it once
67/// here — instead of letting [`Iterator::product`] panic on overflow in a
68/// debug build (or silently wrap in release) — is what keeps every later
69/// arithmetic step in this module (strides, [`TensorView::flat_index`]'s
70/// running sum) provably in range.
71fn checked_shape_len(shape: &[usize]) -> Option<usize> {
72 shape
73 .iter()
74 .try_fold(1usize, |acc, &dim| acc.checked_mul(dim))
75}
76
77/// A checked, zero-copy N-dimensional view over a [`PrimitiveArray`]'s flat
78/// values.
79///
80/// Owns a clone of the source [`PrimitiveArray`] rather than borrowing it —
81/// cloning one is an `Arc` bump (see [`PrimitiveArray`]'s own layout doc), so
82/// this is still zero-copy, and it is what lets [`ImageView`](super::ImageView)
83/// build one from a value it downcast out of a row's `Arc<dyn Array>`
84/// without fighting a borrow that does not outlive the match arm it came
85/// from.
86///
87/// See the [module documentation](self) for the shape it expects and what it
88/// deliberately does not check (validity).
89#[derive(Debug, Clone)]
90pub struct TensorView<T: ArrowNativeType> {
91 /// The flat backing values. Always at least as long as `offset` plus the
92 /// product of `shape` times the largest stride — never shrunk by
93 /// [`TensorView::slice_axis`], which only adjusts `offset` and `shape`.
94 values: PrimitiveArray<T>,
95 /// Element offset of this view's first logical value inside `values`.
96 offset: usize,
97 /// Extent of each dimension, outermost first.
98 shape: Vec<usize>,
99 /// Element stride of each dimension — how many flat elements to advance
100 /// `values` by to move one step along that axis.
101 strides: Vec<usize>,
102}
103
104impl<T: ArrowNativeType> TensorView<T> {
105 /// Builds a view over `array`'s values with the given `shape`.
106 ///
107 /// # Errors
108 ///
109 /// * [`DataError::TensorShapeOverflow`] when `shape`'s dimensions
110 /// multiply out to more elements than `usize` can represent — checked
111 /// before anything else, so this never panics on a debug build the way
112 /// an unchecked `shape.iter().product()` would.
113 /// * [`DataError::TensorShapeMismatch`] when `array.len()` is not the
114 /// product of `shape`'s dimensions.
115 pub fn from_primitive(array: &PrimitiveArray<T>, shape: impl Into<Vec<usize>>) -> Result<Self> {
116 let shape = shape.into();
117 let expected = checked_shape_len(&shape).ok_or_else(|| DataError::TensorShapeOverflow {
118 shape: shape.clone(),
119 })?;
120 if array.len() != expected {
121 return Err(DataError::TensorShapeMismatch {
122 expected,
123 actual: array.len(),
124 });
125 }
126 let strides = row_major_strides(&shape);
127 Ok(Self {
128 values: array.clone(),
129 offset: 0,
130 shape,
131 strides,
132 })
133 }
134
135 /// Builds a view over freshly supplied values — mainly for tests and
136 /// synthetic tensors that are not already backed by a decoded column.
137 ///
138 /// # Errors
139 ///
140 /// Whatever [`TensorView::from_primitive`] reports.
141 pub fn from_values(
142 values: impl IntoIterator<Item = T>,
143 shape: impl Into<Vec<usize>>,
144 ) -> Result<Self> {
145 Self::from_primitive(&PrimitiveArray::from_values(values), shape)
146 }
147
148 /// Extent of each dimension, outermost first.
149 #[inline]
150 #[must_use]
151 pub fn shape(&self) -> &[usize] {
152 &self.shape
153 }
154
155 /// Element stride of each dimension.
156 #[inline]
157 #[must_use]
158 pub fn strides(&self) -> &[usize] {
159 &self.strides
160 }
161
162 /// Number of dimensions.
163 #[inline]
164 #[must_use]
165 pub fn ndim(&self) -> usize {
166 self.shape.len()
167 }
168
169 /// Total number of logical elements — the product of [`TensorView::shape`],
170 /// `1` for a zero-dimensional (scalar) tensor.
171 #[must_use]
172 pub fn len(&self) -> usize {
173 self.shape.iter().product()
174 }
175
176 /// Returns `true` when any dimension is zero.
177 #[inline]
178 #[must_use]
179 pub fn is_empty(&self) -> bool {
180 self.len() == 0
181 }
182
183 /// Returns `true` when this view's memory is one contiguous run in
184 /// row-major order — true for a freshly built tensor and for any
185 /// [`TensorView::slice_axis`] result on axis 0, false once a slice on
186 /// any other axis has narrowed a dimension with extent greater than one
187 /// that is not the outermost.
188 ///
189 /// A size-one dimension's stride never contributes to which memory a
190 /// read touches (there is only one valid index into it, `0`), so — like
191 /// NumPy's own C-contiguity check — this walks the axes from innermost
192 /// out, skipping any dimension whose extent is `1`, rather than
193 /// comparing every stride against the naive `row_major_strides` verbatim; the
194 /// naive comparison would call a size-one axis "non-contiguous" for
195 /// carrying a stride left over from before it was narrowed to `1`, even
196 /// though no read the shape allows can tell the difference.
197 #[must_use]
198 pub fn is_contiguous(&self) -> bool {
199 let mut expected_stride = 1usize;
200 for axis in (0..self.shape.len()).rev() {
201 let dim = self.shape[axis];
202 if dim == 0 {
203 return true; // an empty tensor has no addresses to disagree on
204 }
205 if dim == 1 {
206 continue; // this axis's stride is unobservable
207 }
208 if self.strides[axis] != expected_stride {
209 return false;
210 }
211 expected_stride = expected_stride.saturating_mul(dim);
212 }
213 true
214 }
215
216 /// The whole view as one flat slice, when [`TensorView::is_contiguous`].
217 ///
218 /// ```
219 /// use astrs_data::array::Int32Array;
220 /// use astrs_data::tensor::TensorView;
221 ///
222 /// let values = Int32Array::from_values(0..12);
223 /// let tensor = TensorView::from_primitive(&values, [3, 4])?;
224 /// assert_eq!(tensor.as_slice().map(<[i32]>::len), Some(12));
225 ///
226 /// // Slicing a non-outermost axis breaks contiguity.
227 /// let column = tensor.slice_axis(1, 1, 1)?;
228 /// assert!(!column.is_contiguous());
229 /// assert_eq!(column.as_slice(), None);
230 /// # Ok::<(), astrs_data::DataError>(())
231 /// ```
232 #[must_use]
233 pub fn as_slice(&self) -> Option<&[T]> {
234 if !self.is_contiguous() {
235 return None;
236 }
237 self.values
238 .values()
239 .get(self.offset..self.offset + self.len())
240 }
241
242 /// The flat element offset `index` names, checked against the shape.
243 ///
244 /// # Errors
245 ///
246 /// * [`DataError::TensorRankMismatch`] when `index.len() != self.ndim()`.
247 /// * [`DataError::TensorIndexOutOfBounds`] when a component is not
248 /// smaller than its axis's extent.
249 pub fn flat_index(&self, index: &[usize]) -> Result<usize> {
250 if index.len() != self.shape.len() {
251 return Err(DataError::TensorRankMismatch {
252 expected: self.shape.len(),
253 actual: index.len(),
254 });
255 }
256 let mut flat = self.offset;
257 for (axis, ((&component, &dim), &stride)) in index
258 .iter()
259 .zip(self.shape.iter())
260 .zip(self.strides.iter())
261 .enumerate()
262 {
263 if component >= dim {
264 return Err(DataError::TensorIndexOutOfBounds {
265 axis,
266 index: component,
267 dim,
268 });
269 }
270 flat += component * stride;
271 }
272 Ok(flat)
273 }
274
275 /// The value at `index`.
276 ///
277 /// # Errors
278 ///
279 /// Whatever [`TensorView::flat_index`] reports.
280 pub fn get(&self, index: &[usize]) -> Result<T> {
281 let flat = self.flat_index(index)?;
282 self.values
283 .values()
284 .get(flat)
285 .copied()
286 .ok_or(DataError::IndexOutOfBounds {
287 index: flat,
288 len: self.values.len(),
289 })
290 }
291
292 /// A zero-copy sub-view: `axis` narrowed to `[start, start + len)`,
293 /// clamped to the axis's extent (the crate-wide slicing convention —
294 /// see [`Array::slice`]).
295 ///
296 /// # Errors
297 ///
298 /// [`DataError::TensorAxisOutOfBounds`] when `axis >= self.ndim()`.
299 pub fn slice_axis(&self, axis: usize, start: usize, len: usize) -> Result<Self> {
300 let dim = *self
301 .shape
302 .get(axis)
303 .ok_or(DataError::TensorAxisOutOfBounds {
304 axis,
305 ndim: self.ndim(),
306 })?;
307 let start = start.min(dim);
308 let len = len.min(dim - start);
309 let mut shape = self.shape.clone();
310 shape[axis] = len;
311 Ok(Self {
312 values: self.values.clone(),
313 offset: self.offset + start * self.strides[axis],
314 shape,
315 strides: self.strides.clone(),
316 })
317 }
318
319 /// Checked [`TensorView::slice_axis`].
320 ///
321 /// # Errors
322 ///
323 /// [`DataError::TensorAxisOutOfBounds`] when `axis >= self.ndim()`, or
324 /// [`DataError::SliceOutOfBounds`] when `[start, start + len)` leaves the
325 /// axis's extent.
326 pub fn try_slice_axis(&self, axis: usize, start: usize, len: usize) -> Result<Self> {
327 let dim = *self
328 .shape
329 .get(axis)
330 .ok_or(DataError::TensorAxisOutOfBounds {
331 axis,
332 ndim: self.ndim(),
333 })?;
334 if start.saturating_add(len) > dim {
335 return Err(DataError::SliceOutOfBounds {
336 offset: start,
337 len,
338 available: dim,
339 });
340 }
341 self.slice_axis(axis, start, len)
342 }
343}
344
345#[cfg(test)]
346mod tests {
347 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
348
349 use super::*;
350 use crate::array::{Float32Array, Int32Array};
351
352 #[test]
353 fn row_major_strides_match_a_hand_worked_example() {
354 // A [2, 3, 4] tensor: moving one step in the outermost axis skips a
355 // whole 3x4 = 12-element plane; the innermost axis is contiguous.
356 assert_eq!(row_major_strides(&[2, 3, 4]), vec![12, 4, 1]);
357 assert_eq!(row_major_strides(&[5]), vec![1]);
358 assert_eq!(row_major_strides(&[]), Vec::<usize>::new());
359 }
360
361 #[test]
362 fn shape_product_overflow_is_a_checked_error_not_a_panic() {
363 // `usize::MAX * 2` overflows regardless of pointer width; a naive
364 // `shape.iter().product()` panics under debug-mode overflow checks
365 // (and silently wraps in release), either of which would violate
366 // this crate's "never panics on data-dependent input" policy.
367 let values = Int32Array::from_values([1, 2]);
368 assert_eq!(
369 TensorView::from_primitive(&values, [usize::MAX, 2]).unwrap_err(),
370 DataError::TensorShapeOverflow {
371 shape: vec![usize::MAX, 2]
372 }
373 );
374 // A shape whose product overflows only partway through must still
375 // be caught, not just one whose very first dimension already does.
376 assert_eq!(
377 TensorView::from_primitive(&values, [2, 3, usize::MAX / 4]).unwrap_err(),
378 DataError::TensorShapeOverflow {
379 shape: vec![2, 3, usize::MAX / 4]
380 }
381 );
382 }
383
384 #[test]
385 fn construction_checks_the_element_count() {
386 let values = Int32Array::from_values(0..12);
387 assert!(TensorView::from_primitive(&values, [3, 4]).is_ok());
388 assert_eq!(
389 TensorView::from_primitive(&values, [3, 3]).unwrap_err(),
390 DataError::TensorShapeMismatch {
391 expected: 9,
392 actual: 12
393 }
394 );
395 }
396
397 #[test]
398 fn a_scalar_tensor_has_one_element_and_no_dimensions() {
399 let values = Int32Array::from_values([7]);
400 let tensor = TensorView::from_primitive(&values, []).unwrap();
401 assert_eq!(tensor.ndim(), 0);
402 assert_eq!(tensor.len(), 1);
403 assert_eq!(tensor.get(&[]), Ok(7));
404 assert_eq!(tensor.as_slice(), Some(&[7][..]));
405 }
406
407 #[test]
408 fn an_empty_dimension_is_a_zero_length_tensor() {
409 let values = Int32Array::from_values([] as [i32; 0]);
410 let tensor = TensorView::from_primitive(&values, [0, 5]).unwrap();
411 assert!(tensor.is_empty());
412 assert_eq!(tensor.len(), 0);
413 }
414
415 #[test]
416 fn indexing_walks_row_major_order() {
417 // [[0, 1, 2], [3, 4, 5]]
418 let tensor = TensorView::from_values(0..6, [2, 3]).unwrap();
419 assert_eq!(tensor.get(&[0, 0]), Ok(0));
420 assert_eq!(tensor.get(&[0, 2]), Ok(2));
421 assert_eq!(tensor.get(&[1, 0]), Ok(3));
422 assert_eq!(tensor.get(&[1, 2]), Ok(5));
423 }
424
425 #[test]
426 fn indexing_rejects_the_wrong_rank() {
427 let tensor = TensorView::from_values(0..6, [2, 3]).unwrap();
428 assert_eq!(
429 tensor.get(&[0]).unwrap_err(),
430 DataError::TensorRankMismatch {
431 expected: 2,
432 actual: 1
433 }
434 );
435 assert_eq!(
436 tensor.get(&[0, 0, 0]).unwrap_err(),
437 DataError::TensorRankMismatch {
438 expected: 2,
439 actual: 3
440 }
441 );
442 }
443
444 #[test]
445 fn indexing_rejects_an_out_of_range_component() {
446 let tensor = TensorView::from_values(0..6, [2, 3]).unwrap();
447 assert_eq!(
448 tensor.get(&[2, 0]).unwrap_err(),
449 DataError::TensorIndexOutOfBounds {
450 axis: 0,
451 index: 2,
452 dim: 2
453 }
454 );
455 assert_eq!(
456 tensor.get(&[0, 3]).unwrap_err(),
457 DataError::TensorIndexOutOfBounds {
458 axis: 1,
459 index: 3,
460 dim: 3
461 }
462 );
463 }
464
465 #[test]
466 fn slicing_the_outermost_axis_stays_contiguous() {
467 let tensor = TensorView::from_values(0..12, [3, 4]).unwrap();
468 let rows = tensor.slice_axis(0, 1, 2).unwrap();
469 assert_eq!(rows.shape(), &[2, 4]);
470 assert!(rows.is_contiguous());
471 assert_eq!(rows.as_slice(), Some(&[4, 5, 6, 7, 8, 9, 10, 11][..]));
472 assert_eq!(rows.get(&[0, 0]), Ok(4));
473 assert_eq!(rows.get(&[1, 3]), Ok(11));
474 }
475
476 #[test]
477 fn slicing_an_inner_axis_breaks_contiguity_but_not_indexing() {
478 let tensor = TensorView::from_values(0..12, [3, 4]).unwrap();
479 let column = tensor.slice_axis(1, 1, 2).unwrap();
480 assert_eq!(column.shape(), &[3, 2]);
481 assert!(!column.is_contiguous());
482 assert_eq!(column.as_slice(), None);
483 // Row 0: [0,1,2,3] -> columns 1..3 -> [1, 2]
484 assert_eq!(column.get(&[0, 0]), Ok(1));
485 assert_eq!(column.get(&[0, 1]), Ok(2));
486 // Row 2: [8,9,10,11] -> columns 1..3 -> [9, 10]
487 assert_eq!(column.get(&[2, 0]), Ok(9));
488 assert_eq!(column.get(&[2, 1]), Ok(10));
489 }
490
491 #[test]
492 fn narrowing_a_middle_axis_to_one_slot_still_leaves_a_gap() {
493 // Contrast with `slices_compose`: here the *outer* axis still has
494 // real (>1) extent when the middle one is narrowed to a single
495 // slot, so consecutive logical elements are not consecutive in
496 // memory — picking one slice out of three leaves the other two
497 // slices' worth of elements in the gap between "row" 0 and "row" 1.
498 let tensor = TensorView::from_values(0..24, [2, 3, 4]).unwrap();
499 let narrowed = tensor.slice_axis(1, 2, 1).unwrap();
500 assert_eq!(narrowed.shape(), &[2, 1, 4]);
501 assert!(!narrowed.is_contiguous());
502 assert_eq!(narrowed.as_slice(), None);
503 assert_eq!(narrowed.get(&[0, 0, 0]), Ok(8));
504 assert_eq!(narrowed.get(&[1, 0, 0]), Ok(20));
505 }
506
507 #[test]
508 fn a_size_one_axis_does_not_block_contiguity_when_it_is_not_sandwiched() {
509 // Unlike the case above, a fresh tensor whose middle dimension is
510 // *already* size 1 (not narrowed down from something bigger) is
511 // genuinely one contiguous run: there is no "other slot" being
512 // skipped, so the middle axis's stride is unobservable either way.
513 let tensor = TensorView::from_values(0..8, [2, 1, 4]).unwrap();
514 assert!(tensor.is_contiguous());
515 assert_eq!(tensor.as_slice(), Some(&[0, 1, 2, 3, 4, 5, 6, 7][..]));
516 }
517
518 #[test]
519 fn slices_compose() {
520 let tensor = TensorView::from_values(0..24, [2, 3, 4]).unwrap();
521 let plane = tensor.slice_axis(0, 1, 1).unwrap();
522 let row = plane.slice_axis(1, 2, 1).unwrap();
523 assert_eq!(row.shape(), &[1, 1, 4]);
524 assert_eq!(row.as_slice(), Some(&[20, 21, 22, 23][..]));
525 }
526
527 #[test]
528 fn slice_axis_clamps_like_every_other_slice_in_the_crate() {
529 let tensor = TensorView::from_values(0..12, [3, 4]).unwrap();
530 assert_eq!(tensor.slice_axis(0, 2, 99).unwrap().shape(), &[1, 4]);
531 assert_eq!(tensor.slice_axis(0, 99, 1).unwrap().shape(), &[0, 4]);
532 }
533
534 #[test]
535 fn slice_axis_rejects_an_axis_that_does_not_exist() {
536 let tensor = TensorView::from_values(0..12, [3, 4]).unwrap();
537 assert_eq!(
538 tensor.slice_axis(2, 0, 1).unwrap_err(),
539 DataError::TensorAxisOutOfBounds { axis: 2, ndim: 2 }
540 );
541 }
542
543 #[test]
544 fn try_slice_axis_reports_out_of_range_instead_of_clamping() {
545 let tensor = TensorView::from_values(0..12, [3, 4]).unwrap();
546 assert!(tensor.try_slice_axis(0, 1, 2).is_ok());
547 assert_eq!(
548 tensor.try_slice_axis(0, 2, 2).unwrap_err(),
549 DataError::SliceOutOfBounds {
550 offset: 2,
551 len: 2,
552 available: 3
553 }
554 );
555 assert_eq!(
556 tensor.try_slice_axis(9, 0, 1).unwrap_err(),
557 DataError::TensorAxisOutOfBounds { axis: 9, ndim: 2 }
558 );
559 }
560
561 #[test]
562 fn from_primitive_shares_the_underlying_buffer() {
563 let values = Float32Array::from_values([1.0, 2.0, 3.0, 4.0]);
564 let tensor = TensorView::from_primitive(&values, [2, 2]).unwrap();
565 assert_eq!(
566 tensor.as_slice().map(<[f32]>::as_ptr),
567 Some(values.values().as_ptr()),
568 "no copy happened"
569 );
570 }
571
572 #[test]
573 fn values_include_whatever_a_null_slot_holds() {
574 // TensorView does not consult validity — see the module doc.
575 let values = Int32Array::from_opt_iter([Some(1), None, Some(3), Some(4)]);
576 let tensor = TensorView::from_primitive(&values, [2, 2]).unwrap();
577 assert_eq!(tensor.get(&[0, 1]), Ok(0), "null slot's placeholder value");
578 }
579}