Trait Array

pub trait Array:
    Debug
    + Send
    + Sync
    + Sized
    + 'static
    + Into<ArrayImpl>
    + EstimateSize {
    type RefItem<'a>: ScalarRef<'a, ScalarType = Self::OwnedItem>
       where Self: 'a;
    type OwnedItem: Clone + Debug + EstimateSize + for<'a> Scalar<ScalarRefType<'a> = Self::RefItem<'a>>;
    type Builder: ArrayBuilder<ArrayType = Self>;

    // Required methods
    unsafe fn raw_value_at_unchecked(&self, idx: usize) -> Self::RefItem<'_>;
    fn len(&self) -> usize;
    fn to_protobuf(&self) -> PbArray;
    fn null_bitmap(&self) -> &Bitmap;
    fn into_null_bitmap(self) -> Bitmap;
    fn set_bitmap(&mut self, bitmap: Bitmap);
    fn data_type(&self) -> DataType;

    // Provided methods
    fn value_at(&self, idx: usize) -> Option<Self::RefItem<'_>> { ... }
    unsafe fn value_at_unchecked(&self, idx: usize) -> Option<Self::RefItem<'_>> { ... }
    fn iter(&self) -> ArrayIterator<'_, Self>  { ... }
    fn raw_iter(&self) -> impl ExactSizeIterator<Item = Self::RefItem<'_>> { ... }
    fn is_null(&self, idx: usize) -> bool { ... }
    unsafe fn is_null_unchecked(&self, idx: usize) -> bool { ... }
    fn hash_at<H: Hasher>(&self, idx: usize, state: &mut H) { ... }
    fn hash_vec<H: Hasher>(&self, hashers: &mut [H], vis: &Bitmap) { ... }
    fn is_empty(&self) -> bool { ... }
    fn create_builder(&self, capacity: usize) -> Self::Builder { ... }
    fn into_ref(self) -> ArrayRef { ... }
}

A trait over all array.

Array must be built with an ArrayBuilder. The array trait provides several unified interface on an array, like len, value_at and iter.

The Builder associated type is the builder for this array.

The Iter associated type is the iterator of this array. And the RefItem is the item you could retrieve from this array. For example, PrimitiveArray could return an Option<u32>, and Utf8Array will return an Option<&str>.

In some cases, we will need to store owned data. For example, when aggregating min and max, we need to store current maximum in the aggregator. In this case, we could use A::OwnedItem in aggregator struct.

Required Associated Types

type RefItem<'a>: ScalarRef<'a, ScalarType = Self::OwnedItem> where Self: 'a

A reference to item in array, as well as return type of value_at, which is reciprocal to Self::OwnedItem.

type OwnedItem: Clone + Debug + EstimateSize + for<'a> Scalar<ScalarRefType<'a> = Self::RefItem<'a>>

Owned type of item in array, which is reciprocal to Self::RefItem.

type Builder: ArrayBuilder<ArrayType = Self>

Corresponding builder of this array, which is reciprocal to Array.

Required Methods

unsafe fn raw_value_at_unchecked(&self, idx: usize) -> Self::RefItem<'_>

Retrieve a reference to value regardless of whether it is null without checking the index boundary.

The returned value for NULL values is the default value.

Safety

Index must be within the bounds.

fn len(&self) -> usize

Number of items of array.

fn to_protobuf(&self) -> PbArray

Serialize to protobuf

fn null_bitmap(&self) -> &Bitmap

Get the null Bitmap from Array.

fn into_null_bitmap(self) -> Bitmap

Get the owned null Bitmap from Array.

fn set_bitmap(&mut self, bitmap: Bitmap)

fn data_type(&self) -> DataType

Provided Methods

fn value_at(&self, idx: usize) -> Option<Self::RefItem<'_>>

Retrieve a reference to value.

unsafe fn value_at_unchecked(&self, idx: usize) -> Option<Self::RefItem<'_>>

Safety

Retrieve a reference to value without checking the index boundary.

fn iter(&self) -> ArrayIterator<'_, Self>

Get iterator of current array.

fn raw_iter(&self) -> impl ExactSizeIterator<Item = Self::RefItem<'_>>

Get raw iterator of current array.

The raw iterator simply iterates values without checking the null bitmap. The returned value for NULL values is undefined.

fn is_null(&self, idx: usize) -> bool

Check if an element is null or not.

unsafe fn is_null_unchecked(&self, idx: usize) -> bool

Safety

The unchecked version of is_null, ignore index out of bound check. It is the caller’s responsibility to ensure the index is valid.

fn hash_at<H: Hasher>(&self, idx: usize, state: &mut H)

Feed the value at idx into the given Hasher.

fn hash_vec<H: Hasher>(&self, hashers: &mut [H], vis: &Bitmap)

fn is_empty(&self) -> bool

fn create_builder(&self, capacity: usize) -> Self::Builder

fn into_ref(self) -> ArrayRef

Converts the array into an ArrayRef.

Object Safety

This trait is not object safe.

Implementors

impl Array for BoolArray

type Builder = BoolArrayBuilder

type OwnedItem = bool

type RefItem<'a> = bool

impl Array for BytesArray

type Builder = BytesArrayBuilder

type OwnedItem = Box<[u8]>

type RefItem<'a> = &'a [u8]

impl Array for JsonbArray

type Builder = JsonbArrayBuilder

type OwnedItem = JsonbVal

type RefItem<'a> = JsonbRef<'a>

impl Array for ListArray

type Builder = ListArrayBuilder

type OwnedItem = ListValue

type RefItem<'a> = ListRef<'a>

impl Array for MapArray

type Builder = MapArrayBuilder

type OwnedItem = MapValue

type RefItem<'a> = MapRef<'a>

impl Array for Int256Array

type Builder = Int256ArrayBuilder

type OwnedItem = Int256

type RefItem<'a> = Int256Ref<'a>

impl Array for StructArray

type Builder = StructArrayBuilder

type OwnedItem = StructValue

type RefItem<'a> = StructRef<'a>

impl Array for Utf8Array

type Builder = Utf8ArrayBuilder

type OwnedItem = Box<str>

type RefItem<'a> = &'a str

impl<T: PrimitiveArrayItemType> Array for PrimitiveArray<T>

type Builder = PrimitiveArrayBuilder<T>

type OwnedItem = T

type RefItem<'a> = T