1use 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
31pub fn structure(column: &ArrayRef) -> Result<&StructArray> {
37 column
38 .downcast::<StructArray>()
39 .ok_or_else(|| type_error("Struct", column))
40}
41
42pub fn list(column: &ArrayRef) -> Result<&ListArray> {
48 column
49 .downcast::<ListArray>()
50 .ok_or_else(|| type_error("List", column))
51}
52
53pub fn fixed_list(column: &ArrayRef) -> Result<&FixedSizeListArray> {
59 column
60 .downcast::<FixedSizeListArray>()
61 .ok_or_else(|| type_error("FixedSizeList", column))
62}
63
64pub fn field<'a>(array: &'a StructArray, name: &str) -> Result<&'a ArrayRef> {
70 array.try_column_by_name(name)
71}
72
73pub fn child<'a>(column: &'a ArrayRef, name: &str) -> Result<&'a ArrayRef> {
81 field(structure(column)?, name)
82}
83
84pub 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
97pub fn f64_at(column: &ArrayRef, row: usize) -> Result<f64> {
103 primitive_at::<f64>(column, row)
104}
105
106pub fn f32_at(column: &ArrayRef, row: usize) -> Result<f32> {
112 primitive_at::<f32>(column, row)
113}
114
115pub 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
127pub 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
139pub 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
151pub 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
163pub 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
180pub 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
218pub 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
246pub 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
264pub 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
277fn type_error(expected: &'static str, column: &ArrayRef) -> DataError {
279 DataError::DowncastFailed {
280 expected,
281 actual: Box::new(column.data_type().clone()),
282 }
283}
284
285fn type_error_for(expected: &DataType, column: &ArrayRef) -> DataError {
287 DataError::type_mismatch(expected.clone(), column.data_type().clone())
288}
289
290fn 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}