Skip to main content

astrs_node_api/message/
read.rs

1//! Column accessors shared by every [`AstrsMessage`](super::AstrsMessage)
2//! implementation.
3//!
4//! The mirror of [`build`](super::build): four shapes to read back, plus the
5//! bounds and type checks that turn "this payload is not what the port
6//! promised" into a named error rather than a wrong number.
7//!
8//! Every accessor here is total and checked. A payload arrives from another
9//! process — possibly an older build, possibly a `type: any` port, possibly a
10//! ROS 2 bridge — so a decoder that indexed without checking would be reading
11//! whatever the sender happened to send.
12//!
13//! # Examples
14//!
15//! ```
16//! use astrs_node_api::message::{build, read};
17//!
18//! let column = build::structure(vec![("x", build::primitive::<f64>(&[2.5]))])?;
19//! let row = read::structure(&column)?;
20//! assert_eq!(read::f64_at(read::field(row, "x")?, 0)?, 2.5);
21//! assert!(read::field(row, "missing").is_err());
22//! # Ok::<(), astrs_data::DataError>(())
23//! ```
24
25use astrs_data::array::{
26    Array, ArrayExt, ArrayRef, BinaryArray, BooleanArray, FixedSizeListArray, ListArray,
27    PrimitiveArray, StringArray, StructArray, TimestampArray,
28};
29use astrs_data::{ArrowNativeType, DataError, DataType, Result};
30
31/// The struct array behind a column, or a named error.
32///
33/// # Errors
34///
35/// [`DataError`] when the column is not a `Struct`.
36pub fn structure(column: &ArrayRef) -> Result<&StructArray> {
37    column
38        .downcast::<StructArray>()
39        .ok_or_else(|| type_error("Struct", column))
40}
41
42/// The list array behind a column.
43///
44/// # Errors
45///
46/// [`DataError`] when the column is not a `List`.
47pub fn list(column: &ArrayRef) -> Result<&ListArray> {
48    column
49        .downcast::<ListArray>()
50        .ok_or_else(|| type_error("List", column))
51}
52
53/// The fixed-size list array behind a column.
54///
55/// # Errors
56///
57/// [`DataError`] when the column is not a `FixedSizeList`.
58pub fn fixed_list(column: &ArrayRef) -> Result<&FixedSizeListArray> {
59    column
60        .downcast::<FixedSizeListArray>()
61        .ok_or_else(|| type_error("FixedSizeList", column))
62}
63
64/// One named child column of a struct.
65///
66/// # Errors
67///
68/// [`DataError`] when the struct has no such field.
69pub fn field<'a>(array: &'a StructArray, name: &str) -> Result<&'a ArrayRef> {
70    array.try_column_by_name(name)
71}
72
73/// A named child of the struct behind `column`.
74///
75/// The two-step form callers use most: `read::child(column, "position")`.
76///
77/// # Errors
78///
79/// As [`structure`] and [`field`].
80pub fn child<'a>(column: &'a ArrayRef, name: &str) -> Result<&'a ArrayRef> {
81    field(structure(column)?, name)
82}
83
84/// One value of a primitive column.
85///
86/// # Errors
87///
88/// [`DataError`] when the column is not of `T`'s type, or `row` is out
89/// of range, or the slot is null (the std layouts have no nullable fields).
90pub fn primitive_at<T: ArrowNativeType>(column: &ArrayRef, row: usize) -> Result<T> {
91    let array = column
92        .downcast::<PrimitiveArray<T>>()
93        .ok_or_else(|| type_error_for(&T::DATA_TYPE, column))?;
94    array.value(row).ok_or_else(|| row_error(row, array.len()))
95}
96
97/// One `Float64` value.
98///
99/// # Errors
100///
101/// As [`primitive_at`].
102pub fn f64_at(column: &ArrayRef, row: usize) -> Result<f64> {
103    primitive_at::<f64>(column, row)
104}
105
106/// One `Float32` value.
107///
108/// # Errors
109///
110/// As [`primitive_at`].
111pub fn f32_at(column: &ArrayRef, row: usize) -> Result<f32> {
112    primitive_at::<f32>(column, row)
113}
114
115/// One `Bool` value.
116///
117/// # Errors
118///
119/// As [`primitive_at`].
120pub fn bool_at(column: &ArrayRef, row: usize) -> Result<bool> {
121    let array = column
122        .downcast::<BooleanArray>()
123        .ok_or_else(|| type_error("Bool", column))?;
124    array.value(row).ok_or_else(|| row_error(row, array.len()))
125}
126
127/// One `Utf8` value.
128///
129/// # Errors
130///
131/// As [`primitive_at`].
132pub fn str_at(column: &ArrayRef, row: usize) -> Result<&str> {
133    let array = column
134        .downcast::<StringArray>()
135        .ok_or_else(|| type_error("Utf8", column))?;
136    array.value(row).ok_or_else(|| row_error(row, array.len()))
137}
138
139/// One `Binary` value.
140///
141/// # Errors
142///
143/// As [`primitive_at`].
144pub fn bytes_at(column: &ArrayRef, row: usize) -> Result<&[u8]> {
145    let array = column
146        .downcast::<BinaryArray>()
147        .ok_or_else(|| type_error("Binary", column))?;
148    array.value(row).ok_or_else(|| row_error(row, array.len()))
149}
150
151/// One `Timestamp(ns)` value, in nanoseconds.
152///
153/// # Errors
154///
155/// As [`primitive_at`].
156pub fn timestamp_at(column: &ArrayRef, row: usize) -> Result<i64> {
157    let array = column
158        .downcast::<TimestampArray>()
159        .ok_or_else(|| type_error("Timestamp", column))?;
160    array.value(row).ok_or_else(|| row_error(row, array.len()))
161}
162
163/// The primitive values of one list entry, copied out.
164///
165/// # Errors
166///
167/// [`DataError`] when the column is not a `List<T>`, or `row` is out of
168/// range.
169pub fn primitive_list_at<T: ArrowNativeType>(column: &ArrayRef, row: usize) -> Result<Vec<T>> {
170    let lists = list(column)?;
171    let values = lists
172        .value(row)
173        .ok_or_else(|| row_error(row, lists.len()))?;
174    let array = values
175        .downcast::<PrimitiveArray<T>>()
176        .ok_or_else(|| type_error_for(&T::DATA_TYPE, &values))?;
177    Ok(array.values().to_vec())
178}
179
180/// The flattened values of one `List<FixedSizeList<T, width>>` entry, plus
181/// the tuple width actually found.
182///
183/// # Errors
184///
185/// [`DataError`] when the column is not that shape, or `row` is out of
186/// range.
187pub fn fixed_tuple_list_at<T: ArrowNativeType>(
188    column: &ArrayRef,
189    row: usize,
190) -> Result<(Vec<T>, usize)> {
191    let lists = list(column)?;
192    let entry = lists
193        .value(row)
194        .ok_or_else(|| row_error(row, lists.len()))?;
195    let tuples = fixed_list(&entry)?;
196    let width = match tuples.data_type() {
197        DataType::FixedSizeList(_, size) => usize::try_from(*size).unwrap_or(0),
198        other => {
199            return Err(DataError::type_mismatch(
200                DataType::fixed_size_list(astrs_data::Field::required("v", T::DATA_TYPE), 1),
201                other.clone(),
202            ));
203        }
204    };
205    let mut flat = Vec::with_capacity(tuples.len() * width);
206    for index in 0..tuples.len() {
207        let tuple = tuples
208            .value(index)
209            .ok_or_else(|| row_error(index, tuples.len()))?;
210        let array = tuple
211            .downcast::<PrimitiveArray<T>>()
212            .ok_or_else(|| type_error_for(&T::DATA_TYPE, &tuple))?;
213        flat.extend_from_slice(array.values());
214    }
215    Ok((flat, width))
216}
217
218/// The values of one `FixedSizeList<T, width>` row, copied out.
219///
220/// # Errors
221///
222/// [`DataError`] when the column is not that shape, `row` is out of
223/// range, or the tuple is not `expected` wide.
224pub fn fixed_tuple_at<T: ArrowNativeType>(
225    column: &ArrayRef,
226    row: usize,
227    expected: usize,
228) -> Result<Vec<T>> {
229    let tuples = fixed_list(column)?;
230    let tuple = tuples
231        .value(row)
232        .ok_or_else(|| row_error(row, tuples.len()))?;
233    let array = tuple
234        .downcast::<PrimitiveArray<T>>()
235        .ok_or_else(|| type_error_for(&T::DATA_TYPE, &tuple))?;
236    let values = array.values();
237    if values.len() != expected {
238        return Err(DataError::ChildLengthMismatch {
239            expected,
240            actual: values.len(),
241        });
242    }
243    Ok(values.to_vec())
244}
245
246/// The nested child column and the `(offset, length)` window of one list row.
247///
248/// For list elements that are themselves structs, where copying the values
249/// out would mean decoding them twice.
250///
251/// # Errors
252///
253/// [`DataError`] when the column is not a `List`, or `row` is out of
254/// range.
255pub fn list_window(column: &ArrayRef, row: usize) -> Result<(ArrayRef, usize)> {
256    let lists = list(column)?;
257    let values = lists
258        .value(row)
259        .ok_or_else(|| row_error(row, lists.len()))?;
260    let len = values.len();
261    Ok((values, len))
262}
263
264/// Checks that `row` is addressable in a column of `len` rows.
265///
266/// # Errors
267///
268/// [`DataError`] when it is not.
269pub fn check_row(row: usize, len: usize) -> Result<()> {
270    if row < len {
271        Ok(())
272    } else {
273        Err(row_error(row, len))
274    }
275}
276
277/// A "wrong shape" error naming what was expected and what was found.
278fn type_error(expected: &'static str, column: &ArrayRef) -> DataError {
279    DataError::DowncastFailed {
280        expected,
281        actual: Box::new(column.data_type().clone()),
282    }
283}
284
285/// The same, when the expectation is expressible as a [`DataType`].
286fn type_error_for(expected: &DataType, column: &ArrayRef) -> DataError {
287    DataError::type_mismatch(expected.clone(), column.data_type().clone())
288}
289
290/// An out-of-range row error.
291fn row_error(row: usize, len: usize) -> DataError {
292    DataError::IndexOutOfBounds { index: row, len }
293}
294
295#[cfg(test)]
296mod tests {
297    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
298
299    use super::*;
300    use crate::message::build;
301
302    #[test]
303    fn primitives_are_read_back_by_row() {
304        let column = build::primitive::<f64>(&[1.0, 2.0, 3.0]);
305        assert_eq!(f64_at(&column, 0).unwrap(), 1.0);
306        assert_eq!(f64_at(&column, 2).unwrap(), 3.0);
307        assert!(f64_at(&column, 3).is_err(), "out of range");
308        assert!(f32_at(&column, 0).is_err(), "wrong element type");
309    }
310
311    #[test]
312    fn booleans_strings_bytes_and_timestamps_read_back() {
313        assert!(bool_at(&build::boolean(&[true]), 0).unwrap());
314        assert_eq!(str_at(&build::strings(&["hello"]), 0).unwrap(), "hello");
315        assert_eq!(
316            bytes_at(&build::binaries(&[&b"raw"[..]]), 0).unwrap(),
317            b"raw"
318        );
319        assert_eq!(timestamp_at(&build::timestamps(&[42]), 0).unwrap(), 42);
320
321        let wrong = build::primitive::<i32>(&[1]);
322        assert!(bool_at(&wrong, 0).is_err());
323        assert!(str_at(&wrong, 0).is_err());
324        assert!(bytes_at(&wrong, 0).is_err());
325        assert!(timestamp_at(&wrong, 0).is_err());
326    }
327
328    #[test]
329    fn struct_children_are_found_by_name() {
330        let column = build::structure(vec![
331            ("x", build::primitive::<f64>(&[1.0])),
332            ("y", build::primitive::<f64>(&[2.0])),
333        ])
334        .unwrap();
335        assert_eq!(f64_at(child(&column, "y").unwrap(), 0).unwrap(), 2.0);
336        assert!(child(&column, "z").is_err());
337        assert!(structure(&build::primitive::<f64>(&[1.0])).is_err());
338    }
339
340    #[test]
341    fn primitive_lists_read_back_per_row() {
342        let column =
343            build::primitive_lists::<f32>("range", &[&[1.0, 2.0][..], &[][..], &[3.0][..]])
344                .unwrap();
345        assert_eq!(
346            primitive_list_at::<f32>(&column, 0).unwrap(),
347            vec![1.0, 2.0]
348        );
349        assert!(primitive_list_at::<f32>(&column, 1).unwrap().is_empty());
350        assert_eq!(primitive_list_at::<f32>(&column, 2).unwrap(), vec![3.0]);
351        assert!(primitive_list_at::<f32>(&column, 3).is_err());
352        assert!(primitive_list_at::<f64>(&column, 0).is_err());
353    }
354
355    #[test]
356    fn fixed_tuple_lists_read_back_flat_with_their_width() {
357        let column = build::fixed_tuple_lists::<f32>(
358            "xywh",
359            "v",
360            4,
361            &[&[0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0][..]],
362        )
363        .unwrap();
364        let (flat, width) = fixed_tuple_list_at::<f32>(&column, 0).unwrap();
365        assert_eq!(width, 4);
366        assert_eq!(flat.len(), 8);
367        assert_eq!(flat[4], 4.0);
368        assert!(fixed_tuple_list_at::<f32>(&column, 1).is_err());
369    }
370
371    #[test]
372    fn fixed_tuples_check_their_width() {
373        let flat: Vec<f64> = (0..9).map(f64::from).collect();
374        let column = build::fixed_tuples::<f64>("v", 9, &flat).unwrap();
375        assert_eq!(fixed_tuple_at::<f64>(&column, 0, 9).unwrap().len(), 9);
376        assert!(
377            fixed_tuple_at::<f64>(&column, 0, 36).is_err(),
378            "a 9-wide covariance is not a 36-wide one"
379        );
380        assert!(fixed_tuple_at::<f64>(&column, 1, 9).is_err());
381    }
382
383    #[test]
384    fn list_windows_expose_the_nested_child() {
385        let child =
386            build::structure(vec![("v", build::primitive::<f64>(&[1.0, 2.0, 3.0]))]).unwrap();
387        let item_type = child.data_type().clone();
388        let column = build::nested_lists("item", item_type, &[2, 1], child).unwrap();
389        let (values, len) = list_window(&column, 0).unwrap();
390        assert_eq!(len, 2);
391        assert_eq!(values.len(), 2);
392        assert!(list_window(&column, 5).is_err());
393    }
394
395    #[test]
396    fn row_bounds_are_checked_explicitly() {
397        assert!(check_row(0, 1).is_ok());
398        assert!(check_row(1, 1).is_err());
399        assert!(check_row(0, 0).is_err());
400    }
401
402    #[test]
403    fn shape_errors_name_what_was_expected() {
404        let column = build::primitive::<f64>(&[1.0]);
405        let error = list(&column).unwrap_err();
406        assert!(error.to_string().contains("List"), "{error}");
407        let error = fixed_list(&column).unwrap_err();
408        assert!(error.to_string().contains("FixedSizeList"), "{error}");
409        assert!(matches!(error, DataError::DowncastFailed { .. }));
410    }
411}