Struct arrow::array::UnionArray
source · pub struct UnionArray { /* private fields */ }
Expand description
An array of values of varying types
Each slot in a UnionArray can have a value chosen from a number
of types. Each of the possible types are named like the fields of
a StructArray
. A UnionArray
can
have two possible memory layouts, “dense” or “sparse”. For more
information on please see the
specification.
UnionBuilder can be used to
create UnionArray’s of primitive types. UnionArray
’s of nested
types are also supported but not via UnionBuilder
, see the tests
for examples.
§Examples
§Create a dense UnionArray [1, 3.2, 34]
use arrow_buffer::Buffer;
use arrow_schema::*;
use std::sync::Arc;
use arrow_array::{Array, Int32Array, Float64Array, UnionArray};
let int_array = Int32Array::from(vec![1, 34]);
let float_array = Float64Array::from(vec![3.2]);
let type_id_buffer = Buffer::from_slice_ref(&[0_i8, 1, 0]);
let value_offsets_buffer = Buffer::from_slice_ref(&[0_i32, 0, 1]);
let children: Vec<(Field, Arc<dyn Array>)> = vec![
(Field::new("A", DataType::Int32, false), Arc::new(int_array)),
(Field::new("B", DataType::Float64, false), Arc::new(float_array)),
];
let array = UnionArray::try_new(
&vec![0, 1],
type_id_buffer,
Some(value_offsets_buffer),
children,
).unwrap();
let value = array.value(0).as_any().downcast_ref::<Int32Array>().unwrap().value(0);
assert_eq!(1, value);
let value = array.value(1).as_any().downcast_ref::<Float64Array>().unwrap().value(0);
assert!(3.2 - value < f64::EPSILON);
let value = array.value(2).as_any().downcast_ref::<Int32Array>().unwrap().value(0);
assert_eq!(34, value);
§Create a sparse UnionArray [1, 3.2, 34]
use arrow_buffer::Buffer;
use arrow_schema::*;
use std::sync::Arc;
use arrow_array::{Array, Int32Array, Float64Array, UnionArray};
let int_array = Int32Array::from(vec![Some(1), None, Some(34)]);
let float_array = Float64Array::from(vec![None, Some(3.2), None]);
let type_id_buffer = Buffer::from_slice_ref(&[0_i8, 1, 0]);
let children: Vec<(Field, Arc<dyn Array>)> = vec![
(Field::new("A", DataType::Int32, false), Arc::new(int_array)),
(Field::new("B", DataType::Float64, false), Arc::new(float_array)),
];
let array = UnionArray::try_new(
&vec![0, 1],
type_id_buffer,
None,
children,
).unwrap();
let value = array.value(0).as_any().downcast_ref::<Int32Array>().unwrap().value(0);
assert_eq!(1, value);
let value = array.value(1).as_any().downcast_ref::<Float64Array>().unwrap().value(0);
assert!(3.2 - value < f64::EPSILON);
let value = array.value(2).as_any().downcast_ref::<Int32Array>().unwrap().value(0);
assert_eq!(34, value);
Implementations§
source§impl UnionArray
impl UnionArray
sourcepub unsafe fn new_unchecked(
field_type_ids: &[i8],
type_ids: Buffer,
value_offsets: Option<Buffer>,
child_arrays: Vec<(Field, Arc<dyn Array>)>,
) -> UnionArray
pub unsafe fn new_unchecked( field_type_ids: &[i8], type_ids: Buffer, value_offsets: Option<Buffer>, child_arrays: Vec<(Field, Arc<dyn Array>)>, ) -> UnionArray
Creates a new UnionArray
.
Accepts type ids, child arrays and optionally offsets (for dense unions) to create
a new UnionArray
. This method makes no attempt to validate the data provided by the
caller and assumes that each of the components are correct and consistent with each other.
See try_new
for an alternative that validates the data provided.
§Safety
The type_ids
Buffer
should contain i8
values. These values should be greater than
zero and must be less than the number of children provided in child_arrays
. These values
are used to index into the child_arrays
.
The value_offsets
Buffer
is only provided in the case of a dense union, sparse unions
should use None
. If provided the value_offsets
Buffer
should contain i32
values.
The values in this array should be greater than zero and must be less than the length of the
overall array.
In both cases above we use signed integer types to maintain compatibility with other Arrow implementations.
In both of the cases above we are accepting Buffer
’s which are assumed to be representing
i8
and i32
values respectively. Buffer
objects are untyped and no attempt is made
to ensure that the data provided is valid.
sourcepub fn try_new(
field_type_ids: &[i8],
type_ids: Buffer,
value_offsets: Option<Buffer>,
child_arrays: Vec<(Field, Arc<dyn Array>)>,
) -> Result<UnionArray, ArrowError>
pub fn try_new( field_type_ids: &[i8], type_ids: Buffer, value_offsets: Option<Buffer>, child_arrays: Vec<(Field, Arc<dyn Array>)>, ) -> Result<UnionArray, ArrowError>
Attempts to create a new UnionArray
, validating the inputs provided.
sourcepub fn child(&self, type_id: i8) -> &Arc<dyn Array>
pub fn child(&self, type_id: i8) -> &Arc<dyn Array>
Accesses the child array for type_id
.
§Panics
Panics if the type_id
provided is not present in the array’s DataType
in the Union
.
sourcepub fn type_id(&self, index: usize) -> i8
pub fn type_id(&self, index: usize) -> i8
Returns the type_id
for the array slot at index
.
§Panics
Panics if index
is greater than or equal to the number of child arrays
sourcepub fn type_ids(&self) -> &ScalarBuffer<i8>
pub fn type_ids(&self) -> &ScalarBuffer<i8>
Returns the type_ids
buffer for this array
sourcepub fn offsets(&self) -> Option<&ScalarBuffer<i32>>
pub fn offsets(&self) -> Option<&ScalarBuffer<i32>>
Returns the offsets
buffer if this is a dense array
sourcepub fn value_offset(&self, index: usize) -> usize
pub fn value_offset(&self, index: usize) -> usize
Returns the offset into the underlying values array for the array slot at index
.
§Panics
Panics if index
is greater than or equal the length of the array.
sourcepub fn type_names(&self) -> Vec<&str>
pub fn type_names(&self) -> Vec<&str>
Returns the names of the types in the union.
sourcepub fn slice(&self, offset: usize, length: usize) -> UnionArray
pub fn slice(&self, offset: usize, length: usize) -> UnionArray
Returns a zero-copy slice of this array with the indicated offset and length.
Trait Implementations§
source§impl Array for UnionArray
impl Array for UnionArray
source§fn is_null(&self, _index: usize) -> bool
fn is_null(&self, _index: usize) -> bool
Union types always return non null as there is no validity buffer. To check validity correctly you must check the underlying vector.
source§fn is_valid(&self, _index: usize) -> bool
fn is_valid(&self, _index: usize) -> bool
Union types always return non null as there is no validity buffer. To check validity correctly you must check the underlying vector.
source§fn null_count(&self) -> usize
fn null_count(&self) -> usize
Union types always return 0 null count as there is no validity buffer. To get null count correctly you must check the underlying vector.
source§fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
source§fn offset(&self) -> usize
fn offset(&self) -> usize
0
. Read moresource§fn nulls(&self) -> Option<&NullBuffer>
fn nulls(&self) -> Option<&NullBuffer>
source§fn get_buffer_memory_size(&self) -> usize
fn get_buffer_memory_size(&self) -> usize
source§fn get_array_memory_size(&self) -> usize
fn get_array_memory_size(&self) -> usize
get_buffer_memory_size()
and
includes the overhead of the data structures that contain the pointers to the various buffers.source§fn logical_nulls(&self) -> Option<NullBuffer>
fn logical_nulls(&self) -> Option<NullBuffer>
NullBuffer
that represents the logical
null values of this array, if any. Read moresource§fn is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false
if the array is guaranteed to not contain any logical nulls Read moresource§impl Clone for UnionArray
impl Clone for UnionArray
source§fn clone(&self) -> UnionArray
fn clone(&self) -> UnionArray
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for UnionArray
impl Debug for UnionArray
source§impl From<ArrayData> for UnionArray
impl From<ArrayData> for UnionArray
source§fn from(data: ArrayData) -> UnionArray
fn from(data: ArrayData) -> UnionArray
source§impl From<UnionArray> for ArrayData
impl From<UnionArray> for ArrayData
source§fn from(array: UnionArray) -> ArrayData
fn from(array: UnionArray) -> ArrayData
Auto Trait Implementations§
impl Freeze for UnionArray
impl !RefUnwindSafe for UnionArray
impl Send for UnionArray
impl Sync for UnionArray
impl Unpin for UnionArray
impl !UnwindSafe for UnionArray
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)