Struct PrimitiveDictionaryBuilder 

pub struct PrimitiveDictionaryBuilder<K, V>
where
    K: ArrowPrimitiveType,
    V: ArrowPrimitiveType,
{ /* private fields */ }

Builder for DictionaryArray of PrimitiveArray

Example:

let mut builder = PrimitiveDictionaryBuilder::<UInt8Type, UInt32Type>::new();
 builder.append(12345678).unwrap();
 builder.append_null();
 builder.append(22345678).unwrap();
 let array = builder.finish();

 assert_eq!(
     array.keys(),
     &UInt8Array::from(vec![Some(0), None, Some(1)])
 );

 // Values are polymorphic and so require a downcast.
 let av = array.values();
 let ava: &UInt32Array = av.as_any().downcast_ref::<UInt32Array>().unwrap();
 let avs: &[u32] = ava.values();

 assert!(!array.is_null(0));
 assert!(array.is_null(1));
 assert!(!array.is_null(2));

 assert_eq!(avs, &[12345678, 22345678]);

Implementations

impl<K, V> PrimitiveDictionaryBuilder<K, V>

where K: ArrowPrimitiveType, V: ArrowPrimitiveType,

pub fn new() -> PrimitiveDictionaryBuilder<K, V>

Creates a new PrimitiveDictionaryBuilder.

pub fn new_from_empty_builders( keys_builder: PrimitiveBuilder<K>, values_builder: PrimitiveBuilder<V>, ) -> PrimitiveDictionaryBuilder<K, V>

Creates a new PrimitiveDictionaryBuilder from the provided keys and values builders.

Panics

This method panics if keys_builder or values_builder is not empty.

pub unsafe fn new_from_builders( keys_builder: PrimitiveBuilder<K>, values_builder: PrimitiveBuilder<V>, ) -> PrimitiveDictionaryBuilder<K, V>

Creates a new PrimitiveDictionaryBuilder from existing PrimitiveBuilders of keys and values.

Safety

caller must ensure that the passed in builders are valid for DictionaryArray.

pub fn with_capacity( keys_capacity: usize, values_capacity: usize, ) -> PrimitiveDictionaryBuilder<K, V>

Creates a new PrimitiveDictionaryBuilder with the provided capacities

keys_capacity: the number of keys, i.e. length of array to build values_capacity: the number of distinct dictionary values, i.e. size of dictionary

pub fn try_new_from_builder<K2>( source: PrimitiveDictionaryBuilder<K2, V>, ) -> Result<PrimitiveDictionaryBuilder<K, V>, ArrowError>

where <K as ArrowPrimitiveType>::Native: NumCast, K2: ArrowDictionaryKeyType, <K2 as ArrowPrimitiveType>::Native: NumCast,

Creates a new PrimitiveDictionaryBuilder from the existing builder with the same keys and values, but with a new data type for the keys.

Example

let mut u8_keyed_builder = PrimitiveDictionaryBuilder::<UInt8Type, UInt64Type>::new();

// appending too many values causes the dictionary to overflow
for i in 0..256 {
    u8_keyed_builder.append_value(i);
}
let result = u8_keyed_builder.append(256);
assert!(matches!(result, Err(ArrowError::DictionaryKeyOverflowError{})));

// we need to upgrade to a larger key type
let mut u16_keyed_builder = PrimitiveDictionaryBuilder::<UInt16Type, UInt64Type>::try_new_from_builder(u8_keyed_builder).unwrap();
let dictionary_array = u16_keyed_builder.finish();
let keys = dictionary_array.keys();

assert_eq!(keys, &UInt16Array::from_iter(0..256));

impl<K, V> PrimitiveDictionaryBuilder<K, V>

where K: ArrowDictionaryKeyType, V: ArrowPrimitiveType,

pub fn append( &mut self, value: <V as ArrowPrimitiveType>::Native, ) -> Result<<K as ArrowPrimitiveType>::Native, ArrowError>

Append a primitive value to the array. Return an existing index if already present in the values array or a new index if the value is appended to the values array.

pub fn append_n( &mut self, value: <V as ArrowPrimitiveType>::Native, count: usize, ) -> Result<<K as ArrowPrimitiveType>::Native, ArrowError>

Append a value multiple times to the array. This is the same as append but allows to append the same value multiple times without doing multiple lookups.

Returns an error if the new index would overflow the key type.

pub fn append_value(&mut self, value: <V as ArrowPrimitiveType>::Native)

Infallibly append a value to this builder

Panics

Panics if the resulting length of the dictionary values array would exceed T::Native::MAX

pub fn append_values( &mut self, value: <V as ArrowPrimitiveType>::Native, count: usize, )

Infallibly append a value to this builder repeatedly count times. This is the same as append_value but allows to append the same value multiple times without doing multiple lookups.

Panics

Panics if the resulting length of the dictionary values array would exceed T::Native::MAX

pub fn append_null(&mut self)

Appends a null slot into the builder

pub fn append_nulls(&mut self, n: usize)

Append n null slots into the builder

pub fn append_option( &mut self, value: Option<<V as ArrowPrimitiveType>::Native>, )

Append an Option value into the builder

Panics

Panics if the resulting length of the dictionary values array would exceed T::Native::MAX

pub fn append_options( &mut self, value: Option<<V as ArrowPrimitiveType>::Native>, count: usize, )

Append an Option value into the builder repeatedly count times. This is the same as append_option but allows to append the same value multiple times without doing multiple lookups.

Panics

Panics if the resulting length of the dictionary values array would exceed T::Native::MAX

pub fn extend_dictionary( &mut self, dictionary: &TypedDictionaryArray<'_, K, PrimitiveArray<V>>, ) -> Result<(), ArrowError>

Extends builder with dictionary

This is the same as Self::extend but is faster as it translates the dictionary values once rather than doing a lookup for each item in the iterator

when dictionary values are null (the actual mapped values) the keys are null

pub fn finish(&mut self) -> DictionaryArray<K>

Builds the DictionaryArray and reset this builder.

pub fn finish_cloned(&self) -> DictionaryArray<K>

Builds the DictionaryArray without resetting the builder.

pub fn finish_preserve_values(&mut self) -> DictionaryArray<K>

Builds the DictionaryArray without resetting the values builder or the internal de-duplication map.

The advantage of doing this is that the values will represent the entire set of what has been built so-far by this builder and ensures consistency in the assignment of keys to values across multiple calls to finish_preserve_values. This enables ipc writers to efficiently emit delta dictionaries.

The downside to this is that building the record requires creating a copy of the values, which can become slowly more expensive if the dictionary grows.

Additionally, if record batches from multiple different dictionary builders for the same column are fed into a single ipc writer, beware that entire dictionaries are likely to be re-sent frequently even when the majority of the values are not used by the current record batch.

pub fn values_slice(&self) -> &[<V as ArrowPrimitiveType>::Native]

Returns the current dictionary values buffer as a slice

pub fn values_slice_mut(&mut self) -> &mut [<V as ArrowPrimitiveType>::Native]

Returns the current dictionary values buffer as a mutable slice

pub fn validity_slice(&self) -> Option<&[u8]>

Returns the current null buffer as a slice

Trait Implementations

impl<K, V> ArrayBuilder for PrimitiveDictionaryBuilder<K, V>

where K: ArrowDictionaryKeyType, V: ArrowPrimitiveType,

fn as_any(&self) -> &(dyn Any + 'static)

Returns the builder as an non-mutable Any reference.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the builder as an mutable Any reference.

fn into_box_any(self: Box<PrimitiveDictionaryBuilder<K, V>>) -> Box<dyn Any>

Returns the boxed builder as a box of Any.

fn len(&self) -> usize

Returns the number of array slots in the builder

fn finish(&mut self) -> Arc<dyn Array>

Builds the array and reset this builder.

fn finish_cloned(&self) -> Arc<dyn Array>

Builds the array without resetting the builder.

fn is_empty(&self) -> bool

Returns whether number of array slots is zero

impl<K, V> Debug for PrimitiveDictionaryBuilder<K, V>

where K: Debug + ArrowPrimitiveType, V: Debug + ArrowPrimitiveType, <V as ArrowPrimitiveType>::Native: Debug,

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

Formats the value using the given formatter.

impl<K, V> Default for PrimitiveDictionaryBuilder<K, V>

where K: ArrowPrimitiveType, V: ArrowPrimitiveType,

fn default() -> PrimitiveDictionaryBuilder<K, V>

Returns the “default value” for a type.

impl<K, P> Extend<Option<<P as ArrowPrimitiveType>::Native>> for PrimitiveDictionaryBuilder<K, P>

where K: ArrowDictionaryKeyType, P: ArrowPrimitiveType,

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Option<<P as ArrowPrimitiveType>::Native>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.