Struct UnionArray
pub struct UnionArray {
data_type: DataType,
type_ids: ScalarBuffer<i8>,
offsets: Option<ScalarBuffer<i32>>,
fields: Vec<Option<Arc<dyn Array>>>,
}
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::ScalarBuffer;
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_ids = [0, 1, 0].into_iter().collect::<ScalarBuffer<i8>>();
let offsets = [0, 0, 1].into_iter().collect::<ScalarBuffer<i32>>();
let union_fields = [
(0, Arc::new(Field::new("A", DataType::Int32, false))),
(1, Arc::new(Field::new("B", DataType::Float64, false))),
].into_iter().collect::<UnionFields>();
let children = vec![
Arc::new(int_array) as Arc<dyn Array>,
Arc::new(float_array),
];
let array = UnionArray::try_new(
union_fields,
type_ids,
Some(offsets),
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::ScalarBuffer;
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_ids = [0_i8, 1, 0].into_iter().collect::<ScalarBuffer<i8>>();
let union_fields = [
(0, Arc::new(Field::new("A", DataType::Int32, false))),
(1, Arc::new(Field::new("B", DataType::Float64, false))),
].into_iter().collect::<UnionFields>();
let children = vec![
Arc::new(int_array) as Arc<dyn Array>,
Arc::new(float_array),
];
let array = UnionArray::try_new(
union_fields,
type_ids,
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);
Fields§
§data_type: DataType
§type_ids: ScalarBuffer<i8>
§offsets: Option<ScalarBuffer<i32>>
§fields: Vec<Option<Arc<dyn Array>>>
Implementations§
§impl UnionArray
impl UnionArray
pub unsafe fn new_unchecked(
fields: UnionFields,
type_ids: ScalarBuffer<i8>,
offsets: Option<ScalarBuffer<i32>>,
children: Vec<Arc<dyn Array>>,
) -> UnionArray
pub unsafe fn new_unchecked( fields: UnionFields, type_ids: ScalarBuffer<i8>, offsets: Option<ScalarBuffer<i32>>, children: Vec<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
values should be positive and must match one of the type ids of the fields provided in fields
.
These values are used to index into the children
arrays.
The offsets
is provided in the case of a dense union, sparse unions should use None
.
If provided the offsets
values should be positive and must be less than the length of the
corresponding array.
In both cases above we use signed integer types to maintain compatibility with other Arrow implementations.
pub fn try_new(
fields: UnionFields,
type_ids: ScalarBuffer<i8>,
offsets: Option<ScalarBuffer<i32>>,
children: Vec<Arc<dyn Array>>,
) -> Result<UnionArray, ArrowError>
pub fn try_new( fields: UnionFields, type_ids: ScalarBuffer<i8>, offsets: Option<ScalarBuffer<i32>>, children: Vec<Arc<dyn Array>>, ) -> Result<UnionArray, ArrowError>
Attempts to create a new UnionArray
, validating the inputs provided.
The order of child arrays child array order must match the fields order
pub 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
.
pub 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
pub fn type_ids(&self) -> &ScalarBuffer<i8>
pub fn type_ids(&self) -> &ScalarBuffer<i8>
Returns the type_ids
buffer for this array
pub fn offsets(&self) -> Option<&ScalarBuffer<i32>>
pub fn offsets(&self) -> Option<&ScalarBuffer<i32>>
Returns the offsets
buffer if this is a dense array
pub 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.
pub fn type_names(&self) -> Vec<&str>
pub fn type_names(&self) -> Vec<&str>
Returns the names of the types in the union.
pub 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.
pub fn into_parts(
self,
) -> (UnionFields, ScalarBuffer<i8>, Option<ScalarBuffer<i32>>, Vec<Arc<dyn Array>>)
pub fn into_parts( self, ) -> (UnionFields, ScalarBuffer<i8>, Option<ScalarBuffer<i32>>, Vec<Arc<dyn Array>>)
Deconstruct this array into its constituent parts
§Example
let mut builder = UnionBuilder::new_dense();
builder.append::<Int32Type>("a", 1).unwrap();
let union_array = builder.build()?;
// Deconstruct into parts
let (union_fields, type_ids, offsets, children) = union_array.into_parts();
// Reconstruct from parts
let union_array = UnionArray::try_new(
union_fields,
type_ids,
offsets,
children,
);
Trait Implementations§
§impl Array for UnionArray
impl Array for UnionArray
§fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
§fn offset(&self) -> usize
fn offset(&self) -> usize
0
. Read more§fn nulls(&self) -> Option<&NullBuffer>
fn nulls(&self) -> Option<&NullBuffer>
§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 more§fn is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false
if the array is guaranteed to not contain any logical nulls Read more§fn get_buffer_memory_size(&self) -> usize
fn get_buffer_memory_size(&self) -> usize
§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.§fn null_count(&self) -> usize
fn null_count(&self) -> usize
§impl Clone for UnionArray
impl Clone for UnionArray
§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 more§impl Debug for UnionArray
impl Debug for UnionArray
§impl From<ArrayData> for UnionArray
impl From<ArrayData> for UnionArray
§fn from(data: ArrayData) -> UnionArray
fn from(data: ArrayData) -> UnionArray
§impl From<UnionArray> for ArrayData
impl From<UnionArray> for ArrayData
§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§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)