pub struct GenericListArray<OffsetSize: OffsetSizeTrait> {
data_type: DataType,
nulls: Option<NullBuffer>,
values: ArrayRef,
value_offsets: OffsetBuffer<OffsetSize>,
}
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]) └ ─ ─ ─ ─ ─ ─ ┘ │
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
Fields§
§data_type: DataType
§nulls: Option<NullBuffer>
§values: ArrayRef
§value_offsets: OffsetBuffer<OffsetSize>
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
fn get_type(data_type: &DataType) -> Option<&DataType>
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);
Source§impl<OffsetSize: OffsetSizeTrait> GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> GenericListArray<OffsetSize>
fn try_new_from_array_data(data: ArrayData) -> Result<Self, ArrowError>
Trait Implementations§
Source§impl<OffsetSize: OffsetSizeTrait> Array for GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> Array for GenericListArray<OffsetSize>
Source§fn data_type(&self) -> &DataType
fn data_type(&self) -> &DataType
DataType
] of this array. Read moreSource§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 logical_null_count(&self) -> usize
fn logical_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<OffsetSize: OffsetSizeTrait> ArrayAccessor for &GenericListArray<OffsetSize>
impl<OffsetSize: OffsetSizeTrait> ArrayAccessor for &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
)