Struct DictionaryArray

pub struct DictionaryArray<K: DictionaryKey> { /* private fields */ }

An Array whose values are stored as indices. This Array is useful when the cardinality of values is low compared to the length of the Array.

Safety

This struct guarantees that each item of DictionaryArray::keys is castable to usize and its value is smaller than DictionaryArray::values.len(). In other words, you can safely use unchecked calls to retrieve the values

Implementations

impl<K: DictionaryKey> DictionaryArray<K>

pub fn try_new( dtype: ArrowDataType, keys: PrimitiveArray<K>, values: Box<dyn Array>, ) -> PolarsResult<Self>

Returns a new DictionaryArray.

Implementation

This function is O(N) where N is the length of keys

Errors

This function errors iff

• the dtype’s logical type is not a DictionaryArray
• the dtype’s keys is not compatible with keys
• the dtype’s values’s dtype is not equal with values.dtype()
• any of the keys’s values is not represented in usize or is >= values.len()

pub fn try_from_keys( keys: PrimitiveArray<K>, values: Box<dyn Array>, ) -> PolarsResult<Self>

Returns a new DictionaryArray.

Implementation

This function is O(N) where N is the length of keys

Errors

This function errors iff

• any of the keys’s values is not represented in usize or is >= values.len()

pub unsafe fn try_new_unchecked( dtype: ArrowDataType, keys: PrimitiveArray<K>, values: Box<dyn Array>, ) -> PolarsResult<Self>

Returns a new DictionaryArray.

Errors

This function errors iff

• the dtype’s logical type is not a DictionaryArray
• the dtype’s keys is not compatible with keys
• the dtype’s values’s dtype is not equal with values.dtype()

Safety

The caller must ensure that every keys’s values is represented in usize and is < values.len()

pub fn new_empty(dtype: ArrowDataType) -> Self

Returns a new empty DictionaryArray.

pub fn new_null(dtype: ArrowDataType, length: usize) -> Self

Returns an DictionaryArray whose all elements are null

pub fn iter( &self, ) -> ZipValidity<Box<dyn Scalar>, DictionaryValuesIter<'_, K>, BitmapIter<'_>>

Returns an iterator of Option<Box<dyn Scalar>>.

Implementation

This function will allocate a new Scalar per item and is usually not performant. Consider calling keys_iter and values, downcasting values, and iterating over that.

pub fn values_iter(&self) -> DictionaryValuesIter<'_, K>

Returns an iterator of Box<dyn Scalar>

Implementation

This function will allocate a new Scalar per item and is usually not performant. Consider calling keys_iter and values, downcasting values, and iterating over that.

pub fn values_iter_typed<V: DictValue>( &self, ) -> PolarsResult<DictionaryValuesIterTyped<'_, K, V>>

Returns an iterator over the values [V::IterValue].

Panics

Panics if the keys of this DictionaryArray has any nulls. If they do DictionaryArray::iter_typed should be used.

pub fn iter_typed<V: DictValue>( &self, ) -> PolarsResult<DictionaryIterTyped<'_, K, V>>

Returns an iterator over the optional values of Option<V::IterValue>.

pub fn dtype(&self) -> &ArrowDataType

Returns the ArrowDataType of this DictionaryArray

pub fn is_ordered(&self) -> bool

Returns whether the values of this DictionaryArray are ordered

pub fn slice(&mut self, offset: usize, length: usize)

Slices this DictionaryArray.

Panics

iff offset + length > self.len().

pub unsafe fn slice_unchecked(&mut self, offset: usize, length: usize)

Slices this DictionaryArray.

Safety

Safe iff offset + length <= self.len().

pub fn sliced(self, offset: usize, length: usize) -> Self

Returns this array sliced.

Implementation

This function is O(1).

Panics

iff offset + length > self.len().

pub unsafe fn sliced_unchecked(self, offset: usize, length: usize) -> Self

Returns this array sliced.

Implementation

This function is O(1).

Safety

The caller must ensure that offset + length <= self.len().

pub fn with_validity(self, validity: Option<Bitmap>) -> Self

Returns this DictionaryArray with a new validity.

Panic

This function panics iff validity.len() != self.len().

pub fn set_validity(&mut self, validity: Option<Bitmap>)

Sets the validity of the keys of this DictionaryArray.

Panics

This function panics iff validity.len() != self.len().

pub fn boxed(self) -> Box<dyn Array>

Boxes this array into a Box<dyn Array>.

pub fn arced(self) -> Arc<dyn Array>

Arcs this array into a std::sync::Arc<dyn Array>.

pub fn len(&self) -> usize

Returns the length of this array

pub fn validity(&self) -> Option<&Bitmap>

The optional validity. Equivalent to self.keys().validity().

pub fn keys(&self) -> &PrimitiveArray<K>

Returns the keys of the DictionaryArray. These keys can be used to fetch values from values.

pub fn keys_values_iter(&self) -> impl TrustedLen<Item = usize> + Clone + '_

Returns an iterator of the keys’ values of the DictionaryArray as usize

pub fn keys_iter(&self) -> impl TrustedLen<Item = Option<usize>> + Clone + '_

Returns an iterator of the keys’ of the DictionaryArray as usize

pub fn key_value(&self, index: usize) -> usize

Returns the keys’ value of the DictionaryArray as usize

Panics

This function panics iff index >= self.len()

pub fn values(&self) -> &Box<dyn Array>

Returns the values of the DictionaryArray.

pub fn value(&self, index: usize) -> Box<dyn Scalar>

Returns the value of the DictionaryArray at position i.

Implementation

This function will allocate a new Scalar and is usually not performant. Consider calling keys and values, downcasting values, and iterating over that.

Panic

This function panics iff index >= self.len()

Trait Implementations

impl<K: DictionaryKey> Array for DictionaryArray<K>

fn as_any(&self) -> &dyn Any

Converts itself to a reference of Any, which enables downcasting to concrete types.

fn as_any_mut(&mut self) -> &mut dyn Any

Converts itself to a mutable reference of Any, which enables mutable downcasting to concrete types.

fn len(&self) -> usize

The length of the Array. Every array has a length corresponding to the number of elements (slots).

fn dtype(&self) -> &ArrowDataType

The ArrowDataType of the Array. In combination with Array::as_any, this can be used to downcast trait objects (dyn Array) to concrete arrays.

fn split_at_boxed(&self, offset: usize) -> (Box<dyn Array>, Box<dyn Array>)

Split Self at offset into two boxed Arrays where offset <= self.len().

unsafe fn split_at_boxed_unchecked( &self, offset: usize, ) -> (Box<dyn Array>, Box<dyn Array>)

Split Self at offset into two boxed Arrays without checking offset <= self.len().

fn slice(&mut self, offset: usize, length: usize)

Slices this Array.

unsafe fn slice_unchecked(&mut self, offset: usize, length: usize)

Slices the Array.

fn to_boxed(&self) -> Box<dyn Array>

Clone a &dyn Array to an owned Box<dyn Array>.

fn validity(&self) -> Option<&Bitmap>

The validity of the Array: every array has an optional Bitmap that, when available specifies whether the array slot is valid or not (null). When the validity is None, all slots are valid.

fn with_validity(&self, validity: Option<Bitmap>) -> Box<dyn Array>

Clones this Array with a new assigned bitmap.

fn is_empty(&self) -> bool

whether the array is empty

fn null_count(&self) -> usize

The number of null slots on this Array.

fn has_nulls(&self) -> bool

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

Returns whether slot i is null.

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

Returns whether slot i is null.

fn is_valid(&self, i: usize) -> bool

Returns whether slot i is valid.

fn sliced(&self, offset: usize, length: usize) -> Box<dyn Array>

Returns a slice of this Array.

unsafe fn sliced_unchecked( &self, offset: usize, length: usize, ) -> Box<dyn Array>

Returns a slice of this Array.

impl<K: Clone + DictionaryKey> Clone for DictionaryArray<K>

fn clone(&self) -> DictionaryArray<K>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: DictionaryKey> Debug for DictionaryArray<K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: DictionaryKey> From<GrowableDictionary<'a, T>> for DictionaryArray<T>

fn from(val: GrowableDictionary<'a, T>) -> Self

Converts to this type from the input type.

impl<K: DictionaryKey, M: MutableArray> From<MutableDictionaryArray<K, M>> for DictionaryArray<K>

fn from(other: MutableDictionaryArray<K, M>) -> Self

Converts to this type from the input type.

impl<'a, K: DictionaryKey> IntoIterator for &'a DictionaryArray<K>

type Item = Option<Box<dyn Scalar>>

The type of the elements being iterated over.

type IntoIter = ZipValidity<Box<dyn Scalar>, DictionaryValuesIter<'a, K>, BitmapIter<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K: DictionaryKey> PartialEq<&(dyn Array + 'static)> for DictionaryArray<K>

fn eq(&self, other: &&dyn Array) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K: DictionaryKey> PartialEq for DictionaryArray<K>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K: DictionaryKey> Splitable for DictionaryArray<K>

fn check_bound(&self, offset: usize) -> bool

unsafe fn _split_at_unchecked(&self, offset: usize) -> (Self, Self)

Internal implementation of split_at_unchecked. For any usage, prefer the using split_at or split_at_unchecked.

fn split_at(&self, offset: usize) -> (Self, Self)

Split Self at offset where offset <= self.len().

unsafe fn split_at_unchecked(&self, offset: usize) -> (Self, Self)

Split Self at offset without checking offset <= self.len().