Skip to main content

astrs_data/array/
structs.rs

1//! [`StructArray`] — a column of named child columns, all the same length.
2//!
3//! A struct array is a record batch that happens to be a column: `n` child
4//! arrays of equal length, plus one validity bitmap that nulls out a whole
5//! row across every child at once. AstRS uses it for compound payloads —
6//! `Pose{position, orientation}`, `Detections{boxes, scores, labels}` — where
7//! the fields must travel together.
8//!
9//! A struct with **no** children carries no length information in its
10//! children, so [`StructArray::try_new`] needs an explicit one; that is what
11//! [`crate::DataError::UnknownStructLength`] reports.
12//!
13//! ```
14//! use astrs_data::array::{Array, Float64Array, IntoArrayRef, StringArray, StructArray};
15//! use astrs_data::{DataType, Field};
16//!
17//! let pose = StructArray::try_new(
18//!     vec![
19//!         Field::new("frame", DataType::Utf8, false),
20//!         Field::new("x", DataType::Float64, false),
21//!     ],
22//!     vec![
23//!         StringArray::from_values(["odom", "map"]).into_array_ref(),
24//!         Float64Array::from_values([1.0, 2.0]).into_array_ref(),
25//!     ],
26//!     None,
27//! )?;
28//!
29//! assert_eq!(pose.len(), 2);
30//! assert_eq!(pose.num_columns(), 2);
31//! assert!(pose.column_by_name("x").is_some());
32//! # Ok::<(), astrs_data::DataError>(())
33//! ```
34
35use std::any::Any;
36use std::fmt;
37use std::sync::Arc;
38
39use crate::array::{Array, ArrayRef, check_validity, clamp_window, slice_array, validity_eq};
40use crate::buffer::Bitmap;
41use crate::datatype::{DataType, Field};
42use crate::error::{DataError, Result};
43use crate::sealed::Sealed;
44
45/// A column of named child columns of equal length.
46#[derive(Clone)]
47pub struct StructArray {
48    /// Always `DataType::Struct(fields)`.
49    data_type: DataType,
50    /// One array per field, in field order, each exactly `len` long.
51    columns: Vec<ArrayRef>,
52    /// Logical length.
53    len: usize,
54    /// Row-level validity, or `None` when every row is valid.
55    validity: Option<Bitmap>,
56}
57
58impl StructArray {
59    /// Builds a struct array from its fields and columns.
60    ///
61    /// # Errors
62    ///
63    /// * [`DataError::ColumnCountMismatch`] when the counts disagree.
64    /// * [`DataError::TypeMismatch`] when a column's type differs from its
65    ///   field's.
66    /// * [`DataError::ColumnLengthMismatch`] when the columns are not all the
67    ///   same length.
68    /// * [`DataError::UnknownStructLength`] when there are no columns.
69    /// * [`DataError::ValidityLengthMismatch`] when the bitmap length is wrong.
70    pub fn try_new(
71        fields: Vec<Field>,
72        columns: Vec<ArrayRef>,
73        validity: Option<Bitmap>,
74    ) -> Result<Self> {
75        let Some(first) = columns.first() else {
76            return Err(DataError::UnknownStructLength);
77        };
78        Self::try_new_with_len(fields, columns.clone(), first.len(), validity)
79    }
80
81    /// Builds a struct array with an explicit length.
82    ///
83    /// Required for the zero-column case, and useful when the caller already
84    /// knows the row count.
85    ///
86    /// # Errors
87    ///
88    /// The same set as [`StructArray::try_new`], minus
89    /// [`DataError::UnknownStructLength`].
90    ///
91    /// ```
92    /// use astrs_data::array::{Array, StructArray};
93    ///
94    /// let empty = StructArray::try_new_with_len(Vec::new(), Vec::new(), 4, None)?;
95    /// assert_eq!(empty.len(), 4);
96    /// assert_eq!(empty.num_columns(), 0);
97    /// # Ok::<(), astrs_data::DataError>(())
98    /// ```
99    pub fn try_new_with_len(
100        fields: Vec<Field>,
101        columns: Vec<ArrayRef>,
102        len: usize,
103        validity: Option<Bitmap>,
104    ) -> Result<Self> {
105        if fields.len() != columns.len() {
106            return Err(DataError::ColumnCountMismatch {
107                fields: fields.len(),
108                columns: columns.len(),
109            });
110        }
111        for (index, (field, column)) in fields.iter().zip(columns.iter()).enumerate() {
112            if field.data_type() != column.data_type() {
113                return Err(DataError::type_mismatch(
114                    field.data_type().clone(),
115                    column.data_type().clone(),
116                ));
117            }
118            if column.len() != len {
119                return Err(DataError::ColumnLengthMismatch {
120                    index,
121                    name: field.name().to_owned(),
122                    expected: len,
123                    actual: column.len(),
124                });
125            }
126        }
127        check_validity(validity.as_ref(), len)?;
128        Ok(Self {
129            data_type: DataType::Struct(fields),
130            columns,
131            len,
132            validity,
133        })
134    }
135
136    /// An all-null struct array of `len` rows.
137    ///
138    /// Every child column is itself all-null, which keeps the layout valid.
139    ///
140    /// # Errors
141    ///
142    /// [`DataError::InvalidFixedSize`] when a child type carries a
143    /// non-positive fixed width.
144    pub fn new_null(fields: Vec<Field>, len: usize) -> Result<Self> {
145        let mut columns = Vec::with_capacity(fields.len());
146        for field in &fields {
147            columns.push(crate::array::new_null_array(field.data_type(), len)?);
148        }
149        Ok(Self {
150            data_type: DataType::Struct(fields),
151            columns,
152            len,
153            validity: Some(Bitmap::new_unset(len)),
154        })
155    }
156
157    /// Assembles the parts without revalidating.
158    ///
159    /// Safe, and crate-internal: see [`crate::array::ListArray::from_parts`].
160    pub(crate) fn from_parts(
161        fields: Vec<Field>,
162        columns: Vec<ArrayRef>,
163        len: usize,
164        validity: Option<Bitmap>,
165    ) -> Self {
166        debug_assert_eq!(fields.len(), columns.len());
167        debug_assert!(columns.iter().all(|column| column.len() == len));
168        Self {
169            data_type: DataType::Struct(fields),
170            columns,
171            len,
172            validity,
173        }
174    }
175
176    /// The struct's fields, in column order.
177    #[must_use]
178    pub fn fields(&self) -> &[Field] {
179        match &self.data_type {
180            DataType::Struct(fields) => fields,
181            // Unreachable: the constructor always stores a `Struct`.
182            _ => &[],
183        }
184    }
185
186    /// The child columns, in field order.
187    #[inline]
188    #[must_use]
189    pub fn columns(&self) -> &[ArrayRef] {
190        &self.columns
191    }
192
193    /// Number of child columns.
194    #[inline]
195    #[must_use]
196    pub const fn num_columns(&self) -> usize {
197        self.columns.len()
198    }
199
200    /// The child column at `index`.
201    #[inline]
202    #[must_use]
203    pub fn column(&self, index: usize) -> Option<&ArrayRef> {
204        self.columns.get(index)
205    }
206
207    /// The first child column named `name`.
208    #[must_use]
209    pub fn column_by_name(&self, name: &str) -> Option<&ArrayRef> {
210        let index = self.fields().iter().position(|f| f.name() == name)?;
211        self.columns.get(index)
212    }
213
214    /// The first child column named `name`.
215    ///
216    /// # Errors
217    ///
218    /// [`DataError::FieldNotFound`] when no field has that name.
219    pub fn try_column_by_name(&self, name: &str) -> Result<&ArrayRef> {
220        self.column_by_name(name)
221            .ok_or_else(|| DataError::FieldNotFound {
222                name: name.to_owned(),
223            })
224    }
225
226    /// The row at `index` as a one-row struct array, ignoring validity.
227    ///
228    /// Returns `None` only when `index` is out of range.
229    #[must_use]
230    pub fn value(&self, index: usize) -> Option<Self> {
231        (index < self.len).then(|| self.slice(index, 1))
232    }
233
234    /// The logical row at `index`: `None` when the row is null or out of range.
235    #[must_use]
236    pub fn get(&self, index: usize) -> Option<Self> {
237        if self.is_valid_index(index) {
238            self.value(index)
239        } else {
240            None
241        }
242    }
243
244    /// A zero-copy sub-range, clamped to the array (the crate-wide slicing
245    /// convention).
246    ///
247    /// Every child column is sliced by the same window.
248    #[must_use]
249    pub fn slice(&self, offset: usize, len: usize) -> Self {
250        let (offset, len) = clamp_window(self.len, offset, len);
251        Self {
252            data_type: self.data_type.clone(),
253            columns: self
254                .columns
255                .iter()
256                .map(|column| slice_array(column, offset, len))
257                .collect(),
258            len,
259            validity: self.validity.as_ref().map(|bits| bits.slice(offset, len)),
260        }
261    }
262
263    /// Checked [`StructArray::slice`].
264    ///
265    /// # Errors
266    ///
267    /// [`DataError::SliceOutOfBounds`] when the window leaves the array.
268    pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self> {
269        if offset.saturating_add(len) > self.len {
270            return Err(DataError::SliceOutOfBounds {
271                offset,
272                len,
273                available: self.len,
274            });
275        }
276        Ok(self.slice(offset, len))
277    }
278
279    /// Returns a copy with a different validity bitmap.
280    ///
281    /// # Errors
282    ///
283    /// [`DataError::ValidityLengthMismatch`] when the bitmap length is wrong.
284    pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self> {
285        check_validity(validity.as_ref(), self.len)?;
286        Ok(Self {
287            data_type: self.data_type.clone(),
288            columns: self.columns.clone(),
289            len: self.len,
290            validity,
291        })
292    }
293
294    /// A struct holding only the columns at `indices`, in the order given.
295    ///
296    /// # Errors
297    ///
298    /// [`DataError::IndexOutOfBounds`] when an index has no column.
299    pub fn project(&self, indices: &[usize]) -> Result<Self> {
300        let fields = self.fields();
301        let mut projected_fields = Vec::with_capacity(indices.len());
302        let mut projected_columns = Vec::with_capacity(indices.len());
303        for &index in indices {
304            let field = fields.get(index).ok_or(DataError::IndexOutOfBounds {
305                index,
306                len: fields.len(),
307            })?;
308            let column = self.columns.get(index).ok_or(DataError::IndexOutOfBounds {
309                index,
310                len: self.columns.len(),
311            })?;
312            projected_fields.push(field.clone());
313            projected_columns.push(Arc::clone(column));
314        }
315        Ok(Self {
316            data_type: DataType::Struct(projected_fields),
317            columns: projected_columns,
318            len: self.len,
319            validity: self.validity.clone(),
320        })
321    }
322
323    /// Whether `index` is inside the array and not null.
324    #[inline]
325    fn is_valid_index(&self, index: usize) -> bool {
326        index < self.len && self.validity.as_ref().is_none_or(|bits| bits.value(index))
327    }
328}
329
330impl Sealed for StructArray {}
331
332impl Array for StructArray {
333    fn as_any(&self) -> &dyn Any {
334        self
335    }
336
337    fn data_type(&self) -> &DataType {
338        &self.data_type
339    }
340
341    fn len(&self) -> usize {
342        self.len
343    }
344
345    fn validity(&self) -> Option<&Bitmap> {
346        self.validity.as_ref()
347    }
348
349    fn slice(&self, offset: usize, len: usize) -> ArrayRef {
350        Arc::new(Self::slice(self, offset, len))
351    }
352
353    fn buffer_memory_size(&self) -> usize {
354        self.columns
355            .iter()
356            .map(|column| column.buffer_memory_size())
357            .sum::<usize>()
358            + self
359                .validity
360                .as_ref()
361                .map_or(0, |bits| bits.buffer().backing_len())
362    }
363
364    fn children(&self) -> Vec<&ArrayRef> {
365        self.columns.iter().collect()
366    }
367
368    fn equals(&self, other: &dyn Array) -> bool {
369        let Some(other) = other.as_any().downcast_ref::<Self>() else {
370            return false;
371        };
372        self.data_type == other.data_type
373            && self.len == other.len
374            && validity_eq(self.validity.as_ref(), other.validity.as_ref(), self.len)
375            && self.columns.len() == other.columns.len()
376            && self
377                .columns
378                .iter()
379                .zip(other.columns.iter())
380                .all(|(a, b)| a == b)
381    }
382}
383
384impl PartialEq for StructArray {
385    #[inline]
386    fn eq(&self, other: &Self) -> bool {
387        self.equals(other)
388    }
389}
390
391impl fmt::Debug for StructArray {
392    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
393        write!(
394            f,
395            "StructArray[len={}, nulls={}] {{",
396            self.len,
397            self.null_count()
398        )?;
399        for (index, (field, column)) in self.fields().iter().zip(self.columns.iter()).enumerate() {
400            if index > 0 {
401                f.write_str(", ")?;
402            }
403            write!(f, "{}: {}", field.name(), column.data_type())?;
404        }
405        f.write_str("}")
406    }
407}
408
409#[cfg(test)]
410mod tests {
411    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
412
413    use super::*;
414    use crate::array::{Float64Array, Int32Array, IntoArrayRef, StringArray};
415
416    fn fields() -> Vec<Field> {
417        vec![
418            Field::new("id", DataType::Int32, false),
419            Field::new("name", DataType::Utf8, true),
420        ]
421    }
422
423    fn sample() -> StructArray {
424        StructArray::try_new(
425            fields(),
426            vec![
427                Int32Array::from_values([1, 2, 3]).into_array_ref(),
428                StringArray::from_opt_iter([Some("a"), None, Some("c")]).into_array_ref(),
429            ],
430            None,
431        )
432        .unwrap()
433    }
434
435    #[test]
436    fn no_null_array() {
437        let strukt = sample();
438        assert_eq!(strukt.len(), 3);
439        assert_eq!(strukt.num_columns(), 2);
440        assert_eq!(strukt.null_count(), 0);
441        assert_eq!(strukt.fields().len(), 2);
442        assert!(strukt.column(0).is_some());
443        assert!(strukt.column(2).is_none());
444        assert!(strukt.column_by_name("name").is_some());
445        assert!(strukt.column_by_name("missing").is_none());
446        assert!(strukt.try_column_by_name("id").is_ok());
447        assert_eq!(
448            strukt.try_column_by_name("nope").unwrap_err(),
449            DataError::FieldNotFound {
450                name: "nope".to_owned()
451            }
452        );
453        assert_eq!(strukt.children().len(), 2);
454    }
455
456    #[test]
457    fn zero_column_struct_needs_an_explicit_length() {
458        assert_eq!(
459            StructArray::try_new(Vec::new(), Vec::new(), None).unwrap_err(),
460            DataError::UnknownStructLength
461        );
462        let empty = StructArray::try_new_with_len(Vec::new(), Vec::new(), 4, None).unwrap();
463        assert_eq!(empty.len(), 4);
464        assert_eq!(empty.num_columns(), 0);
465        assert_eq!(empty.slice(1, 2).len(), 2);
466    }
467
468    #[test]
469    fn empty_array() {
470        let strukt = StructArray::try_new(
471            fields(),
472            vec![
473                Int32Array::from_values([] as [i32; 0]).into_array_ref(),
474                StringArray::from_values([] as [&str; 0]).into_array_ref(),
475            ],
476            None,
477        )
478        .unwrap();
479        assert!(strukt.is_empty());
480        assert!(strukt.get(0).is_none());
481    }
482
483    #[test]
484    fn all_null_array() {
485        let strukt = StructArray::new_null(fields(), 3).unwrap();
486        assert_eq!(strukt.len(), 3);
487        assert_eq!(strukt.null_count(), 3);
488        assert_eq!(strukt.num_columns(), 2);
489        for index in 0..3 {
490            assert!(strukt.get(index).is_none());
491            assert_eq!(strukt.value(index).map(|s| s.len()), Some(1));
492        }
493        assert_eq!(strukt.columns()[0].null_count(), 3);
494    }
495
496    #[test]
497    fn row_level_nulls() {
498        let strukt = sample()
499            .with_validity(Some([true, false, true].into_iter().collect()))
500            .unwrap();
501        assert_eq!(strukt.null_count(), 1);
502        assert!(strukt.get(1).is_none());
503        assert_eq!(strukt.value(1).map(|s| s.len()), Some(1));
504        assert!(strukt.get(0).is_some());
505    }
506
507    #[test]
508    fn column_count_must_match_the_fields() {
509        assert_eq!(
510            StructArray::try_new(
511                fields(),
512                vec![Int32Array::from_values([1]).into_array_ref()],
513                None
514            )
515            .unwrap_err(),
516            DataError::ColumnCountMismatch {
517                fields: 2,
518                columns: 1
519            }
520        );
521    }
522
523    #[test]
524    fn column_types_must_match_the_fields() {
525        let err = StructArray::try_new(
526            fields(),
527            vec![
528                Float64Array::from_values([1.0]).into_array_ref(),
529                StringArray::from_values(["a"]).into_array_ref(),
530            ],
531            None,
532        )
533        .unwrap_err();
534        assert!(matches!(err, DataError::TypeMismatch { .. }));
535    }
536
537    #[test]
538    fn column_lengths_must_agree() {
539        let err = StructArray::try_new(
540            fields(),
541            vec![
542                Int32Array::from_values([1, 2]).into_array_ref(),
543                StringArray::from_values(["a"]).into_array_ref(),
544            ],
545            None,
546        )
547        .unwrap_err();
548        assert_eq!(
549            err,
550            DataError::ColumnLengthMismatch {
551                index: 1,
552                name: "name".to_owned(),
553                expected: 2,
554                actual: 1
555            }
556        );
557    }
558
559    #[test]
560    fn validity_length_is_checked() {
561        assert!(matches!(
562            StructArray::try_new(
563                fields(),
564                vec![
565                    Int32Array::from_values([1]).into_array_ref(),
566                    StringArray::from_values(["a"]).into_array_ref(),
567                ],
568                Some(Bitmap::new_set(5))
569            ),
570            Err(DataError::ValidityLengthMismatch { .. })
571        ));
572    }
573
574    #[test]
575    fn slicing_slices_every_column() {
576        let strukt = StructArray::try_new(
577            fields(),
578            vec![
579                Int32Array::from_values(0..10).into_array_ref(),
580                StringArray::from_values((0..10).map(|i| i.to_string())).into_array_ref(),
581            ],
582            Some((0..10).map(|i| i % 3 != 0).collect()),
583        )
584        .unwrap();
585        let window = strukt.slice(2, 5);
586        assert_eq!(window.len(), 5);
587        for column in window.columns() {
588            assert_eq!(column.len(), 5);
589        }
590        assert_eq!(
591            window.columns()[0]
592                .as_any()
593                .downcast_ref::<Int32Array>()
594                .map(|a| a.values().to_vec()),
595            Some(vec![2, 3, 4, 5, 6])
596        );
597        assert_eq!(window.null_count(), 2);
598        assert_eq!(strukt.slice(9, 99).len(), 1);
599        assert_eq!(strukt.slice(99, 1).len(), 0);
600        assert_eq!(strukt.slice(1, 8).slice(2, 3).len(), 3);
601        assert!(strukt.try_slice(9, 2).is_err());
602    }
603
604    #[test]
605    fn projection_reorders_columns() {
606        let strukt = sample();
607        let projected = strukt.project(&[1, 0]).unwrap();
608        assert_eq!(projected.num_columns(), 2);
609        assert_eq!(projected.fields()[0].name(), "name");
610        assert_eq!(projected.len(), 3);
611        assert_eq!(strukt.project(&[]).unwrap().num_columns(), 0);
612        assert_eq!(
613            strukt.project(&[5]).unwrap_err(),
614            DataError::IndexOutOfBounds { index: 5, len: 2 }
615        );
616    }
617
618    #[test]
619    fn nested_structs() {
620        let inner = sample();
621        let outer = StructArray::try_new(
622            vec![Field::new("inner", inner.data_type().clone(), true)],
623            vec![inner.clone().into_array_ref()],
624            None,
625        )
626        .unwrap();
627        assert_eq!(outer.len(), 3);
628        assert_eq!(outer.num_columns(), 1);
629        let child = outer.column(0).unwrap();
630        assert_eq!(child.as_any().downcast_ref::<StructArray>(), Some(&inner));
631        assert!(outer.buffer_memory_size() > 0);
632    }
633
634    #[test]
635    fn equality_is_by_logical_content() {
636        assert_eq!(sample(), sample());
637        let different = StructArray::try_new(
638            fields(),
639            vec![
640                Int32Array::from_values([1, 2, 9]).into_array_ref(),
641                StringArray::from_opt_iter([Some("a"), None, Some("c")]).into_array_ref(),
642            ],
643            None,
644        )
645        .unwrap();
646        assert_ne!(sample(), different);
647        assert_ne!(sample(), sample().slice(0, 2));
648        assert_ne!(sample(), sample().project(&[0]).unwrap());
649    }
650
651    #[test]
652    fn debug_output_lists_fields() {
653        let rendered = format!("{:?}", sample());
654        assert!(rendered.contains("len=3"), "{rendered}");
655        assert!(rendered.contains("id: Int32"), "{rendered}");
656        assert!(rendered.contains("name: Utf8"), "{rendered}");
657    }
658
659    #[test]
660    fn trait_object_round_trip() {
661        let column: ArrayRef = sample().into_array_ref();
662        assert_eq!(column.len(), 3);
663        assert_eq!(column.children().len(), 2);
664        assert_eq!(Array::slice(column.as_ref(), 1, 1).len(), 1);
665    }
666}