pub struct GenericListArray<OffsetSize: OffsetSizeTrait> { /* private fields */ }
Expand description
An array of variable length lists, similar to JSON arrays
(e.g. ["A", "B", "C"]
).
Lists are represented using offsets
into a values
child
array. Offsets are stored in two adjacent entries of an
OffsetBuffer
.
Arrow defines ListArray
with i32
offsets and
LargeListArray
with i64
offsets.
Use GenericListBuilder
to construct a GenericListArray
.
§Representation
A ListArray
can represent a list of values of any other
supported Arrow type. Each element of the ListArray
itself is
a list which may be empty, may contain NULL and non-null values,
or may itself be NULL.
For example, the ListArray
shown in the following diagram stores
lists of strings. Note that []
represents an empty (length
0), but non NULL list.
┌─────────────┐
│ [A,B,C] │
├─────────────┤
│ [] │
├─────────────┤
│ NULL │
├─────────────┤
│ [D] │
├─────────────┤
│ [NULL, F] │
└─────────────┘
The values
are stored in a child StringArray
and the offsets
are stored in an OffsetBuffer
as shown in the following
diagram. The logical values and offsets are shown on the left, and
the actual ListArray
encoding on the right.
┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
┌ ─ ─ ─ ─ ─ ─ ┐ │
┌─────────────┐ ┌───────┐ │ ┌───┐ ┌───┐ ┌───┐ ┌───┐
│ [A,B,C] │ │ (0,3) │ │ 1 │ │ 0 │ │ │ 1 │ │ A │ │ 0 │
├─────────────┤ ├───────┤ │ ├───┤ ├───┤ ├───┤ ├───┤
│ [] │ │ (3,3) │ │ 1 │ │ 3 │ │ │ 1 │ │ B │ │ 1 │
├─────────────┤ ├───────┤ │ ├───┤ ├───┤ ├───┤ ├───┤
│ NULL │ │ (3,4) │ │ 0 │ │ 3 │ │ │ 1 │ │ C │ │ 2 │
├─────────────┤ ├───────┤ │ ├───┤ ├───┤ ├───┤ ├───┤
│ [D] │ │ (4,5) │ │ 1 │ │ 4 │ │ │ ? │ │ ? │ │ 3 │
├─────────────┤ ├───────┤ │ ├───┤ ├───┤ ├───┤ ├───┤
│ [NULL, F] │ │ (5,7) │ │ 1 │ │ 5 │ │ │ 1 │ │ D │ │ 4 │
└─────────────┘ └───────┘ │ └───┘ ├───┤ ├───┤ ├───┤
│ 7 │ │ │ 0 │ │ ? │ │ 5 │
│ Validity └───┘ ├───┤ ├───┤
Logical Logical (nulls) Offsets │ │ 1 │ │ F │ │ 6 │
Values Offsets │ └───┘ └───┘
│ Values │ │
(offsets[i], │ ListArray (Array)
offsets[i+1]) └ ─ ─ ─ ─ ─ ─ ┘ │
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
Implementations§
Source§impl<OffsetSize: OffsetSizeTrait> GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> GenericListArray<OffsetSize>
Sourcepub const DATA_TYPE_CONSTRUCTOR: fn(_: FieldRef) -> DataType = _
pub const DATA_TYPE_CONSTRUCTOR: fn(_: FieldRef) -> DataType = _
The data type constructor of list array.
The input is the schema of the child array and
the output is the DataType
, List or LargeList.
Sourcepub fn try_new(
field: FieldRef,
offsets: OffsetBuffer<OffsetSize>,
values: ArrayRef,
nulls: Option<NullBuffer>,
) -> Result<Self, ArrowError>
pub fn try_new( field: FieldRef, offsets: OffsetBuffer<OffsetSize>, values: ArrayRef, nulls: Option<NullBuffer>, ) -> Result<Self, ArrowError>
Create a new GenericListArray
from the provided parts
§Errors
Errors if
offsets.len() - 1 != nulls.len()
offsets.last() > values.len()
!field.is_nullable() && values.is_nullable()
field.data_type() != values.data_type()
Sourcepub fn new(
field: FieldRef,
offsets: OffsetBuffer<OffsetSize>,
values: ArrayRef,
nulls: Option<NullBuffer>,
) -> Self
pub fn new( field: FieldRef, offsets: OffsetBuffer<OffsetSize>, values: ArrayRef, nulls: Option<NullBuffer>, ) -> Self
Create a new GenericListArray
from the provided parts
§Panics
Panics if Self::try_new
returns an error
Sourcepub fn new_null(field: FieldRef, len: usize) -> Self
pub fn new_null(field: FieldRef, len: usize) -> Self
Create a new GenericListArray
of length len
where all values are null
Sourcepub fn into_parts(
self,
) -> (FieldRef, OffsetBuffer<OffsetSize>, ArrayRef, Option<NullBuffer>)
pub fn into_parts( self, ) -> (FieldRef, OffsetBuffer<OffsetSize>, ArrayRef, Option<NullBuffer>)
Deconstruct this array into its constituent parts
Sourcepub fn offsets(&self) -> &OffsetBuffer<OffsetSize>
pub fn offsets(&self) -> &OffsetBuffer<OffsetSize>
Returns a reference to the offsets of this list
Unlike Self::value_offsets
this returns the OffsetBuffer
allowing for zero-copy cloning
Sourcepub fn value_type(&self) -> DataType
pub fn value_type(&self) -> DataType
Returns a clone of the value type of this list.
Sourcepub unsafe fn value_unchecked(&self, i: usize) -> ArrayRef
pub unsafe fn value_unchecked(&self, i: usize) -> ArrayRef
Returns ith value of this list array.
§Safety
Caller must ensure that the index is within the array bounds
Sourcepub fn value_offsets(&self) -> &[OffsetSize]
pub fn value_offsets(&self) -> &[OffsetSize]
Returns the offset values in the offsets buffer
Sourcepub fn value_length(&self, i: usize) -> OffsetSize
pub fn value_length(&self, i: usize) -> OffsetSize
Returns the length for value at index i
.
Sourcepub fn iter<'a>(&'a self) -> GenericListArrayIter<'a, OffsetSize>
pub fn iter<'a>(&'a self) -> GenericListArrayIter<'a, OffsetSize>
constructs a new iterator
Sourcepub fn slice(&self, offset: usize, length: usize) -> Self
pub fn slice(&self, offset: usize, length: usize) -> Self
Returns a zero-copy slice of this array with the indicated offset and length.
Sourcepub fn from_iter_primitive<T, P, I>(iter: I) -> Selfwhere
T: ArrowPrimitiveType,
P: IntoIterator<Item = Option<<T as ArrowPrimitiveType>::Native>>,
I: IntoIterator<Item = Option<P>>,
pub fn from_iter_primitive<T, P, I>(iter: I) -> Selfwhere
T: ArrowPrimitiveType,
P: IntoIterator<Item = Option<<T as ArrowPrimitiveType>::Native>>,
I: IntoIterator<Item = Option<P>>,
Creates a GenericListArray
from an iterator of primitive values
§Example
let data = vec![
Some(vec![Some(0), Some(1), Some(2)]),
None,
Some(vec![Some(3), None, Some(5)]),
Some(vec![Some(6), Some(7)]),
];
let list_array = ListArray::from_iter_primitive::<Int32Type, _, _>(data);
println!("{:?}", list_array);
Trait Implementations§
Source§impl<OffsetSize: OffsetSizeTrait> Array for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> Array for GenericListArray<OffsetSize>
Source§fn slice(&self, offset: usize, length: usize) -> ArrayRef
fn slice(&self, offset: usize, length: usize) -> ArrayRef
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 null_count(&self) -> usize
fn null_count(&self) -> usize
Source§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<'a, OffsetSize: OffsetSizeTrait> ArrayAccessor for &'a GenericListArray<OffsetSize>
impl<'a, OffsetSize: OffsetSizeTrait> ArrayAccessor for &'a GenericListArray<OffsetSize>
Source§impl<OffsetSize: OffsetSizeTrait> Clone for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> Clone for GenericListArray<OffsetSize>
Source§impl<OffsetSize: OffsetSizeTrait> Debug for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> Debug for GenericListArray<OffsetSize>
Source§impl<OffsetSize: OffsetSizeTrait> From<ArrayData> for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> From<ArrayData> for GenericListArray<OffsetSize>
Source§impl<OffsetSize: OffsetSizeTrait> From<FixedSizeListArray> for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> From<FixedSizeListArray> for GenericListArray<OffsetSize>
Source§fn from(value: FixedSizeListArray) -> Self
fn from(value: FixedSizeListArray) -> Self
Source§impl<OffsetSize: OffsetSizeTrait> From<GenericListArray<OffsetSize>> for ArrayData
impl<OffsetSize: OffsetSizeTrait> From<GenericListArray<OffsetSize>> for ArrayData
Source§fn from(array: GenericListArray<OffsetSize>) -> Self
fn from(array: GenericListArray<OffsetSize>) -> Self
Source§impl<OffsetSize: OffsetSizeTrait> From<GenericListArray<OffsetSize>> for GenericStringArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> From<GenericListArray<OffsetSize>> for GenericStringArray<OffsetSize>
Source§fn from(v: GenericListArray<OffsetSize>) -> Self
fn from(v: GenericListArray<OffsetSize>) -> Self
Source§impl<T: OffsetSizeTrait> From<GenericListArray<T>> for GenericBinaryArray<T>
impl<T: OffsetSizeTrait> From<GenericListArray<T>> for GenericBinaryArray<T>
Source§fn from(v: GenericListArray<T>) -> Self
fn from(v: GenericListArray<T>) -> Self
Source§impl<OffsetSize: OffsetSizeTrait> PartialEq for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> PartialEq for GenericListArray<OffsetSize>
Auto Trait Implementations§
impl<OffsetSize> Freeze for GenericListArray<OffsetSize>
impl<OffsetSize> !RefUnwindSafe for GenericListArray<OffsetSize>
impl<OffsetSize> Send for GenericListArray<OffsetSize>
impl<OffsetSize> Sync for GenericListArray<OffsetSize>
impl<OffsetSize> Unpin for GenericListArray<OffsetSize>where
OffsetSize: Unpin,
impl<OffsetSize> !UnwindSafe for GenericListArray<OffsetSize>
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
)