Struct PrimitiveArray

pub struct PrimitiveArray<T>where
    T: ArrowPrimitiveType,{
    data_type: DataType,
    values: ScalarBuffer<<T as ArrowPrimitiveType>::Native>,
    nulls: Option<NullBuffer>,
}

Expand description

An array of primitive values, of type ArrowPrimitiveType

§Example: From a Vec

let arr: PrimitiveArray<Int32Type> = vec![1, 2, 3, 4].into();
assert_eq!(4, arr.len());
assert_eq!(0, arr.null_count());
assert_eq!(arr.values(), &[1, 2, 3, 4])

§Example: From an optional Vec

let arr: PrimitiveArray<Int32Type> = vec![Some(1), None, Some(3), None].into();
assert_eq!(4, arr.len());
assert_eq!(2, arr.null_count());
// Note: values for null indexes are arbitrary
assert_eq!(arr.values(), &[1, 0, 3, 0])

§Example: From an iterator of values

let arr: PrimitiveArray<Int32Type> = (0..10).map(|x| x + 1).collect();
assert_eq!(10, arr.len());
assert_eq!(0, arr.null_count());
for i in 0..10i32 {
    assert_eq!(i + 1, arr.value(i as usize));
}

§Example: From an iterator of option

let arr: PrimitiveArray<Int32Type> = (0..10).map(|x| (x % 2 == 0).then_some(x)).collect();
assert_eq!(10, arr.len());
assert_eq!(5, arr.null_count());
// Note: values for null indexes are arbitrary
assert_eq!(arr.values(), &[0, 0, 2, 0, 4, 0, 6, 0, 8, 0])

§Example: Using Builder

let mut builder = PrimitiveBuilder::<Int32Type>::new();
builder.append_value(1);
builder.append_null();
builder.append_value(2);
let array = builder.finish();
// Note: values for null indexes are arbitrary
assert_eq!(array.values(), &[1, 0, 2]);
assert!(array.is_null(1));

§Example: Get a `PrimitiveArray` from an `ArrayRef`

// will panic if the array is not a Float32Array
assert_eq!(&DataType::Float32, array.data_type());
let f32_array: Float32Array  = array.as_primitive().clone();
assert_eq!(f32_array, Float32Array::from(vec![1.2, 2.3]));

Fields§

§data_type: DataType§values: ScalarBuffer<<T as ArrowPrimitiveType>::Native>§nulls: Option<NullBuffer>

Implementations§

§

impl<T> PrimitiveArray<T>
where T: ArrowPrimitiveType,

pub fn new( values: ScalarBuffer<<T as ArrowPrimitiveType>::Native>, nulls: Option<NullBuffer>, ) -> PrimitiveArray<T>

Create a new PrimitiveArray from the provided values and nulls

§Panics

Panics if Self::try_new returns an error

§Example

Creating a PrimitiveArray directly from a ScalarBuffer and NullBuffer using this constructor is the most performant approach, avoiding any additional allocations

// [1, 2, 3, 4]
let array = Int32Array::new(vec![1, 2, 3, 4].into(), None);
// [1, null, 3, 4]
let nulls = NullBuffer::from(vec![true, false, true, true]);
let array = Int32Array::new(vec![1, 2, 3, 4].into(), Some(nulls));

pub fn new_null(length: usize) -> PrimitiveArray<T>

Create a new PrimitiveArray of the given length where all values are null

pub fn try_new( values: ScalarBuffer<<T as ArrowPrimitiveType>::Native>, nulls: Option<NullBuffer>, ) -> Result<PrimitiveArray<T>, ArrowError>

Create a new PrimitiveArray from the provided values and nulls

§Errors

Errors if:

values.len() != nulls.len()

pub fn new_scalar( value: <T as ArrowPrimitiveType>::Native, ) -> Scalar<PrimitiveArray<T>>

Create a new Scalar from value

pub fn into_parts( self, ) -> (DataType, ScalarBuffer<<T as ArrowPrimitiveType>::Native>, Option<NullBuffer>)

Deconstruct this array into its constituent parts

pub fn with_data_type(self, data_type: DataType) -> PrimitiveArray<T>

Overrides the DataType of this PrimitiveArray

Prefer using Self::with_timezone or Self::with_precision_and_scale where the primitive type is suitably constrained, as these cannot panic

§Panics

Panics if ![Self::is_compatible]

pub fn len(&self) -> usize

Returns the length of this array.

pub fn is_empty(&self) -> bool

Returns whether this array is empty.

pub fn values(&self) -> &ScalarBuffer<<T as ArrowPrimitiveType>::Native>

Returns the values of this array

pub fn builder(capacity: usize) -> PrimitiveBuilder<T>

Returns a new primitive array builder

pub fn is_compatible(data_type: &DataType) -> bool

Returns if this PrimitiveArray is compatible with the provided DataType

This is equivalent to data_type == T::DATA_TYPE, however ignores timestamp timezones and decimal precision and scale

pub unsafe fn value_unchecked( &self, i: usize, ) -> <T as ArrowPrimitiveType>::Native

Returns the primitive value at index i.

§Safety

caller must ensure that the passed in offset is less than the array len()

pub fn value(&self, i: usize) -> <T as ArrowPrimitiveType>::Native

Returns the primitive value at index i.

§Panics

Panics if index i is out of bounds

pub fn from_iter_values(iter: I) -> PrimitiveArray<T>
where I: IntoIterator<Item = <T as ArrowPrimitiveType>::Native>,

Creates a PrimitiveArray based on an iterator of values without nulls

pub fn from_iter_values_with_nulls( iter: I, nulls: Option<NullBuffer>, ) -> PrimitiveArray<T>
where I: IntoIterator<Item = <T as ArrowPrimitiveType>::Native>,

Creates a PrimitiveArray based on an iterator of values with provided nulls

pub fn from_value( value: <T as ArrowPrimitiveType>::Native, count: usize, ) -> PrimitiveArray<T>

Creates a PrimitiveArray based on a constant value with count elements

pub fn take_iter<'a>( &'a self, indexes: impl Iterator<Item = Option<usize>> + 'a, ) -> impl Iterator<Item = Option<<T as ArrowPrimitiveType>::Native>> + 'a

Returns an iterator that returns the values of array.value(i) for an iterator with each element i

pub unsafe fn take_iter_unchecked<'a>( &'a self, indexes: impl Iterator<Item = Option<usize>> + 'a, ) -> impl Iterator<Item = Option<<T as ArrowPrimitiveType>::Native>> + 'a

Returns an iterator that returns the values of array.value(i) for an iterator with each element i

§Safety

caller must ensure that the offsets in the iterator are less than the array len()

pub fn slice(&self, offset: usize, length: usize) -> PrimitiveArray<T>

Returns a zero-copy slice of this array with the indicated offset and length.

pub fn reinterpret_cast<K>(&self) -> PrimitiveArray<K>
where K: ArrowPrimitiveType<Native = <T as ArrowPrimitiveType>::Native>,

Reinterprets this array’s contents as a different data type without copying

This can be used to efficiently convert between primitive arrays with the same underlying representation

Note: this will not modify the underlying values, and therefore may change the semantic values of the array, e.g. 100 milliseconds in a TimestampNanosecondArray will become 100 seconds in a TimestampSecondArray.

For casts that preserve the semantic value, check out the compute kernels.

let a = Int64Array::from_iter_values([1, 2, 3, 4]);
let b: TimestampNanosecondArray = a.reinterpret_cast();

pub fn unary<F, O>(&self, op: F) -> PrimitiveArray<O>
where O: ArrowPrimitiveType, F: Fn(<T as ArrowPrimitiveType>::Native) -> <O as ArrowPrimitiveType>::Native,

Applies a unary infallible function to a primitive array, producing a new array of potentially different type.

This is the fastest way to perform an operation on a primitive array when the benefits of a vectorized operation outweigh the cost of branching nulls and non-nulls.

§Null Handling

Applies the function for all values, including those on null slots. This will often allow the compiler to generate faster vectorized code, but requires that the operation must be infallible (not error/panic) for any value of the corresponding type or this function may panic.

§Example

let array = Int32Array::from(vec![Some(5), Some(7), None]);
// Create a new array with the value of applying sqrt
let c = array.unary(|x| f32::sqrt(x as f32));
assert_eq!(c, Float32Array::from(vec![Some(2.236068), Some(2.6457512), None]));

pub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
where F: Fn(<T as ArrowPrimitiveType>::Native) -> <T as ArrowPrimitiveType>::Native,

Applies a unary and infallible function to the array in place if possible.

§Buffer Reuse

If the underlying buffers are not shared with other arrays, mutates the underlying buffer in place, without allocating.

If the underlying buffer is shared, returns Err(self)

§Null Handling

See Self::unary for more information on null handling.

§Example

let array = Int32Array::from(vec![Some(5), Some(7), None]);
// Apply x*2+1 to the data in place, no allocations
let c = array.unary_mut(|x| x * 2 + 1).unwrap();
assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));

§Example: modify `ArrayRef` in place, if not shared

It is also possible to modify an ArrayRef if there are no other references to the underlying buffer.

// Convert to Int32Array (panic's if array.data_type is not Int32)
let a = array.as_primitive::<Int32Type>().clone();
// Try to apply x*2+1 to the data in place, fails because array is still shared
a.unary_mut(|x| x * 2 + 1).unwrap_err();
// Try again, this time dropping the last remaining reference
let a = array.as_primitive::<Int32Type>().clone();
drop(array);
// Now we can apply the operation in place
let c = a.unary_mut(|x| x * 2 + 1).unwrap();
assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));

pub fn try_unary<F, O, E>(&self, op: F) -> Result<PrimitiveArray<O>, E>
where O: ArrowPrimitiveType, F: Fn(<T as ArrowPrimitiveType>::Native) -> Result<<O as ArrowPrimitiveType>::Native, E>,

Applies a unary fallible function to all valid values in a primitive array, producing a new array of potentially different type.

Applies op to only rows that are valid, which is often significantly slower than Self::unary, which should be preferred if op is fallible.

Note: LLVM is currently unable to effectively vectorize fallible operations

pub fn try_unary_mut<F, E>( self, op: F, ) -> Result<Result<PrimitiveArray<T>, E>, PrimitiveArray<T>>
where F: Fn(<T as ArrowPrimitiveType>::Native) -> Result<<T as ArrowPrimitiveType>::Native, E>,

Applies a unary fallible function to all valid values in a mutable primitive array.

§Null Handling

See Self::try_unary for more information on null handling.

§Buffer Reuse

See Self::unary_mut for more information on buffer reuse.

This returns an Err when the input array is shared buffer with other array. In the case, returned Err wraps input array. If the function encounters an error during applying on values. In the case, this returns an Err within an Ok which wraps the actual error.

Note: LLVM is currently unable to effectively vectorize fallible operations

pub fn unary_opt<F, O>(&self, op: F) -> PrimitiveArray<O>
where O: ArrowPrimitiveType, F: Fn(<T as ArrowPrimitiveType>::Native) -> Option<<O as ArrowPrimitiveType>::Native>,

Applies a unary and nullable function to all valid values in a primitive array

Applies op to only rows that are valid, which is often significantly slower than Self::unary, which should be preferred if op is fallible.

Note: LLVM is currently unable to effectively vectorize fallible operations

pub fn from_unary<U, F>(left: U, op: F) -> PrimitiveArray<T>
where U: ArrayAccessor, F: FnMut(::Item) -> <T as ArrowPrimitiveType>::Native,

Applies a unary infallible function to each value in an array, producing a new primitive array.

§Null Handling

See Self::unary for more information on null handling.

§Example: create an `Int16Array` from an `ArrayAccessor` with item type `&[u8]`

use arrow_array::{Array, FixedSizeBinaryArray, Int16Array};
let input_arg = vec![ vec![1, 0], vec![2, 0], vec![3, 0] ];
let arr = FixedSizeBinaryArray::try_from_iter(input_arg.into_iter()).unwrap();
let c = Int16Array::from_unary(&arr, |x| i16::from_le_bytes(x[..2].try_into().unwrap()));
assert_eq!(c, Int16Array::from(vec![Some(1i16), Some(2i16), Some(3i16)]));

pub fn into_builder(self) -> Result<PrimitiveBuilder<T>, PrimitiveArray<T>>

Returns a PrimitiveBuilder for this array, suitable for mutating values in place.

§Buffer Reuse

If the underlying data buffer has no other outstanding references, the buffer is used without copying.

If the underlying data buffer does have outstanding references, returns Err(self)

§

impl<T> PrimitiveArray<T>
where T: ArrowTemporalType, i64: From<<T as ArrowPrimitiveType>::Native>,

pub fn value_as_datetime(&self, i: usize) -> Option<NaiveDateTime>

Returns value as a chrono NaiveDateTime, handling time resolution

If a data type cannot be converted to NaiveDateTime, a None is returned. A valid value is expected, thus the user should first check for validity.

pub fn value_as_datetime_with_tz( &self, i: usize, tz: Tz, ) -> Option<DateTime<Tz>>

Returns value as a chrono NaiveDateTime, handling time resolution with the provided tz

functionally it is same as value_as_datetime, however it adds the passed tz to the to-be-returned NaiveDateTime

pub fn value_as_date(&self, i: usize) -> Option<NaiveDate>

Returns value as a chrono NaiveDate by using Self::datetime()

If a data type cannot be converted to NaiveDate, a None is returned

pub fn value_as_time(&self, i: usize) -> Option<NaiveTime>

Returns a value as a chrono NaiveTime

Date32 and Date64 return UTC midnight as they do not have time resolution

pub fn value_as_duration(&self, i: usize) -> Option<TimeDelta>

Returns a value as a chrono Duration

If a data type cannot be converted to Duration, a None is returned

§

impl<'a, T> PrimitiveArray<T>
where T: ArrowPrimitiveType,

pub fn iter(&'a self) -> ArrayIter<&'a PrimitiveArray<T>> ⓘ

constructs a new iterator

§

impl<T> PrimitiveArray<T>
where T: ArrowPrimitiveType,

pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> PrimitiveArray<T>
where P: Borrow<Option<<T as ArrowPrimitiveType>::Native>>, I: IntoIterator<Item = P>,

Creates a PrimitiveArray from an iterator of trusted length.

§Safety

The iterator must be TrustedLen. I.e. that size_hint().1 correctly reports its length.

§

impl<T> PrimitiveArray<T>
where T: ArrowTimestampType,

pub fn timezone(&self) -> Option<&str>

Returns the timezone of this array if any

pub fn with_timezone(self, timezone: impl Into<Arc<str>>) -> PrimitiveArray<T>

Construct a timestamp array with new timezone

pub fn with_timezone_utc(self) -> PrimitiveArray<T>

Construct a timestamp array with UTC

pub fn with_timezone_opt<S>(self, timezone: Option<S>) -> PrimitiveArray<T>
where S: Into<Arc<str>>,

Construct a timestamp array with an optional timezone

§

impl<T> PrimitiveArray<T>
where T: DecimalType + ArrowPrimitiveType,

pub fn with_precision_and_scale( self, precision: u8, scale: i8, ) -> Result<PrimitiveArray<T>, ArrowError>

Returns a Decimal array with the same data as self, with the specified precision and scale.

See validate_decimal_precision_and_scale

pub fn validate_decimal_precision( &self, precision: u8, ) -> Result<(), ArrowError>

Validates values in this array can be properly interpreted with the specified precision.

pub fn null_if_overflow_precision(&self, precision: u8) -> PrimitiveArray<T>

Validates the Decimal Array, if the value of slot is overflow for the specified precision, and will be casted to Null

pub fn value_as_string(&self, row: usize) -> String

Returns Self::value formatted as a string

pub fn precision(&self) -> u8

Returns the decimal precision of this array

pub fn scale(&self) -> i8

Returns the decimal scale of this array

Trait Implementations§

§

impl<T> Array for PrimitiveArray<T>
where T: ArrowPrimitiveType,

§

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

Returns the array as Any so that it can be downcasted to a specific implementation. Read more

§

fn to_data(&self) -> ArrayData

Returns the underlying data of this array

§

fn into_data(self) -> ArrayData

Returns the underlying data of this array Read more

§

fn data_type(&self) -> &DataType

Returns a reference to the DataType of this array. Read more

§

fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>

Returns a zero-copy slice of this array with the indicated offset and length. Read more

§

fn len(&self) -> usize

Returns the length (i.e., number of elements) of this array. Read more

§

fn is_empty(&self) -> bool

Returns whether this array is empty. Read more

§

fn shrink_to_fit(&mut self)

Shrinks the capacity of any exclusively owned buffer as much as possible Read more

§

fn offset(&self) -> usize

Returns the offset into the underlying data used by this array(-slice). Note that the underlying data can be shared by many arrays. This defaults to 0. Read more

§

fn nulls(&self) -> Option<&NullBuffer>

Returns the null buffer of this array if any. Read more

§

fn logical_null_count(&self) -> usize

Returns the total number of logical null values in this array. Read more

§

fn get_buffer_memory_size(&self) -> usize

Returns the total number of bytes of memory pointed to by this array. The buffers store bytes in the Arrow memory format, and include the data as well as the validity map. Note that this does not always correspond to the exact memory usage of an array, since multiple arrays can share the same buffers or slices thereof.

§

fn get_array_memory_size(&self) -> usize

Returns the total number of bytes of memory occupied physically by this array. This value will always be greater than returned by get_buffer_memory_size() and includes the overhead of the data structures that contain the pointers to the various buffers.

§

fn logical_nulls(&self) -> Option<NullBuffer>

Returns a potentially computed NullBuffer that represents the logical null values of this array, if any. Read more

§

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

Returns whether the element at index is null according to Array::nulls Read more

§

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

Returns whether the element at index is not null, the opposite of Self::is_null. Read more

§

fn null_count(&self) -> usize

Returns the total number of physical null values in this array. Read more

§

fn is_nullable(&self) -> bool

Returns false if the array is guaranteed to not contain any logical nulls Read more

§

impl<T> ArrayAccessor for &PrimitiveArray<T>
where T: ArrowPrimitiveType,

§

type Item = <T as ArrowPrimitiveType>::Native

The Arrow type of the element being accessed.

§

fn value(&self, index: usize) -> <&PrimitiveArray<T> as ArrayAccessor>::Item

Returns the element at index i Read more

§

unsafe fn value_unchecked( &self, index: usize, ) -> <&PrimitiveArray<T> as ArrayAccessor>::Item

Returns the element at index i Read more

§

impl<T> Clone for PrimitiveArray<T>
where T: ArrowPrimitiveType,

§

fn clone(&self) -> PrimitiveArray<T>

Returns a copy of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

§

impl<T> Debug for PrimitiveArray<T>
where T: ArrowPrimitiveType,

§

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

Formats the value using the given formatter. Read more

§