Skip to main content

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}