1use 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#[derive(Clone)]
47pub struct StructArray {
48 data_type: DataType,
50 columns: Vec<ArrayRef>,
52 len: usize,
54 validity: Option<Bitmap>,
56}
57
58impl StructArray {
59 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 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 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 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 #[must_use]
178 pub fn fields(&self) -> &[Field] {
179 match &self.data_type {
180 DataType::Struct(fields) => fields,
181 _ => &[],
183 }
184 }
185
186 #[inline]
188 #[must_use]
189 pub fn columns(&self) -> &[ArrayRef] {
190 &self.columns
191 }
192
193 #[inline]
195 #[must_use]
196 pub const fn num_columns(&self) -> usize {
197 self.columns.len()
198 }
199
200 #[inline]
202 #[must_use]
203 pub fn column(&self, index: usize) -> Option<&ArrayRef> {
204 self.columns.get(index)
205 }
206
207 #[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 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 #[must_use]
230 pub fn value(&self, index: usize) -> Option<Self> {
231 (index < self.len).then(|| self.slice(index, 1))
232 }
233
234 #[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 #[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 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 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 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 #[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}