pub struct PrimitiveArray<T: ArrowPrimitiveType> { /* private fields */ }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]));Implementations§
Source§impl<T: ArrowPrimitiveType> PrimitiveArray<T>
impl<T: ArrowPrimitiveType> PrimitiveArray<T>
Sourcepub fn new(values: ScalarBuffer<T::Native>, nulls: Option<NullBuffer>) -> Self
pub fn new(values: ScalarBuffer<T::Native>, nulls: Option<NullBuffer>) -> Self
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));Sourcepub fn new_null(length: usize) -> Self
pub fn new_null(length: usize) -> Self
Create a new PrimitiveArray of the given length where all values are null
Sourcepub fn try_new(
values: ScalarBuffer<T::Native>,
nulls: Option<NullBuffer>,
) -> Result<Self, ArrowError>
pub fn try_new( values: ScalarBuffer<T::Native>, nulls: Option<NullBuffer>, ) -> Result<Self, ArrowError>
Create a new PrimitiveArray from the provided values and nulls
§Errors
Errors if:
values.len() != nulls.len()
Sourcepub fn new_scalar(value: T::Native) -> Scalar<Self>
pub fn new_scalar(value: T::Native) -> Scalar<Self>
Create a new Scalar from value
Sourcepub fn into_parts(
self,
) -> (DataType, ScalarBuffer<T::Native>, Option<NullBuffer>)
pub fn into_parts( self, ) -> (DataType, ScalarBuffer<T::Native>, Option<NullBuffer>)
Deconstruct this array into its constituent parts
Sourcepub fn with_data_type(self, data_type: DataType) -> Self
pub fn with_data_type(self, data_type: DataType) -> Self
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]
Sourcepub fn values(&self) -> &ScalarBuffer<T::Native>
pub fn values(&self) -> &ScalarBuffer<T::Native>
Returns the values of this array
Sourcepub fn builder(capacity: usize) -> PrimitiveBuilder<T>
pub fn builder(capacity: usize) -> PrimitiveBuilder<T>
Returns a new primitive array builder
Sourcepub fn is_compatible(data_type: &DataType) -> bool
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
Sourcepub unsafe fn value_unchecked(&self, i: usize) -> T::Native
pub unsafe fn value_unchecked(&self, i: usize) -> T::Native
Returns the primitive value at index i.
§Safety
caller must ensure that the passed in offset is less than the array len()
Sourcepub fn from_iter_values<I: IntoIterator<Item = T::Native>>(iter: I) -> Self
pub fn from_iter_values<I: IntoIterator<Item = T::Native>>(iter: I) -> Self
Creates a PrimitiveArray based on an iterator of values without nulls
Sourcepub fn from_iter_values_with_nulls<I: IntoIterator<Item = T::Native>>(
iter: I,
nulls: Option<NullBuffer>,
) -> Self
pub fn from_iter_values_with_nulls<I: IntoIterator<Item = T::Native>>( iter: I, nulls: Option<NullBuffer>, ) -> Self
Creates a PrimitiveArray based on an iterator of values with provided nulls
Sourcepub fn from_value(value: T::Native, count: usize) -> Self
pub fn from_value(value: T::Native, count: usize) -> Self
Creates a PrimitiveArray based on a constant value with count elements
Sourcepub fn take_iter<'a>(
&'a self,
indexes: impl Iterator<Item = Option<usize>> + 'a,
) -> impl Iterator<Item = Option<T::Native>> + 'a
pub fn take_iter<'a>( &'a self, indexes: impl Iterator<Item = Option<usize>> + 'a, ) -> impl Iterator<Item = Option<T::Native>> + 'a
Returns an iterator that returns the values of array.value(i) for an iterator with each element i
Sourcepub unsafe fn take_iter_unchecked<'a>(
&'a self,
indexes: impl Iterator<Item = Option<usize>> + 'a,
) -> impl Iterator<Item = Option<T::Native>> + 'a
pub unsafe fn take_iter_unchecked<'a>( &'a self, indexes: impl Iterator<Item = Option<usize>> + 'a, ) -> impl Iterator<Item = Option<T::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()
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 reinterpret_cast<K>(&self) -> PrimitiveArray<K>where
K: ArrowPrimitiveType<Native = T::Native>,
pub fn reinterpret_cast<K>(&self) -> PrimitiveArray<K>where
K: ArrowPrimitiveType<Native = T::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();Sourcepub fn unary<F, O>(&self, op: F) -> PrimitiveArray<O>
pub fn unary<F, O>(&self, op: F) -> PrimitiveArray<O>
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.
See also
Self::unary_mutfor in place modification.Self::try_unaryfor fallible operations.arrow::compute::binaryfor binary operations
§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]));Sourcepub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
pub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
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]));Sourcepub fn try_unary<F, O, E>(&self, op: F) -> Result<PrimitiveArray<O>, E>
pub fn try_unary<F, O, E>(&self, op: F) -> Result<PrimitiveArray<O>, 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
Sourcepub fn try_unary_mut<F, E>(
self,
op: F,
) -> Result<Result<PrimitiveArray<T>, E>, PrimitiveArray<T>>
pub fn try_unary_mut<F, E>( self, op: F, ) -> Result<Result<PrimitiveArray<T>, E>, PrimitiveArray<T>>
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
Sourcepub fn unary_opt<F, O>(&self, op: F) -> PrimitiveArray<O>
pub fn unary_opt<F, O>(&self, op: F) -> PrimitiveArray<O>
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
Sourcepub fn from_unary<U: ArrayAccessor, F>(left: U, op: F) -> Self
pub fn from_unary<U: ArrayAccessor, F>(left: U, op: F) -> Self
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)]));Sourcepub fn into_builder(self) -> Result<PrimitiveBuilder<T>, Self>
pub fn into_builder(self) -> Result<PrimitiveBuilder<T>, Self>
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)
Source§impl<T: ArrowTemporalType> PrimitiveArray<T>
impl<T: ArrowTemporalType> PrimitiveArray<T>
Sourcepub fn value_as_datetime(&self, i: usize) -> Option<NaiveDateTime>
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.
Sourcepub fn value_as_datetime_with_tz(
&self,
i: usize,
tz: Tz,
) -> Option<DateTime<Tz>>
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
Sourcepub fn value_as_date(&self, i: usize) -> Option<NaiveDate>
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
Sourcepub fn value_as_time(&self, i: usize) -> Option<NaiveTime>
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
Sourcepub fn value_as_duration(&self, i: usize) -> Option<Duration>
pub fn value_as_duration(&self, i: usize) -> Option<Duration>
Returns a value as a chrono Duration
If a data type cannot be converted to Duration, a None is returned
Source§impl<'a, T: ArrowPrimitiveType> PrimitiveArray<T>
impl<'a, T: ArrowPrimitiveType> PrimitiveArray<T>
Sourcepub fn iter(&'a self) -> PrimitiveIter<'a, T>
pub fn iter(&'a self) -> PrimitiveIter<'a, T>
constructs a new iterator
Source§impl<T: ArrowPrimitiveType> PrimitiveArray<T>
impl<T: ArrowPrimitiveType> PrimitiveArray<T>
Sourcepub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
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.
Source§impl<T: ArrowTimestampType> PrimitiveArray<T>
impl<T: ArrowTimestampType> PrimitiveArray<T>
Sourcepub fn with_timezone(self, timezone: impl Into<Arc<str>>) -> Self
pub fn with_timezone(self, timezone: impl Into<Arc<str>>) -> Self
Construct a timestamp array with new timezone
Sourcepub fn with_timezone_utc(self) -> Self
pub fn with_timezone_utc(self) -> Self
Construct a timestamp array with UTC
Source§impl<T: DecimalType + ArrowPrimitiveType> PrimitiveArray<T>
impl<T: DecimalType + ArrowPrimitiveType> PrimitiveArray<T>
Sourcepub fn with_precision_and_scale(
self,
precision: u8,
scale: i8,
) -> Result<Self, ArrowError>
pub fn with_precision_and_scale( self, precision: u8, scale: i8, ) -> Result<Self, ArrowError>
Returns a Decimal array with the same data as self, with the specified precision and scale.
Sourcepub fn validate_decimal_precision(
&self,
precision: u8,
) -> Result<(), ArrowError>
pub fn validate_decimal_precision( &self, precision: u8, ) -> Result<(), ArrowError>
Validates values in this array can be properly interpreted with the specified precision.
Sourcepub fn null_if_overflow_precision(&self, precision: u8) -> Self
pub fn null_if_overflow_precision(&self, precision: u8) -> Self
Validates the Decimal Array, if the value of slot is overflow for the specified precision, and will be casted to Null
Sourcepub fn value_as_string(&self, row: usize) -> String
pub fn value_as_string(&self, row: usize) -> String
Returns Self::value formatted as a string
Trait Implementations§
Source§impl<T: ArrowPrimitiveType> Array for PrimitiveArray<T>
impl<T: ArrowPrimitiveType> Array for PrimitiveArray<T>
Source§fn slice(&self, offset: usize, length: usize) -> ArrayRef
fn slice(&self, offset: usize, length: usize) -> ArrayRef
Source§fn shrink_to_fit(&mut self)
fn shrink_to_fit(&mut self)
Source§fn offset(&self) -> usize
fn offset(&self) -> usize
0. Read moreSource§fn nulls(&self) -> Option<&NullBuffer>
fn nulls(&self) -> Option<&NullBuffer>
Source§fn logical_null_count(&self) -> usize
fn logical_null_count(&self) -> usize
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 is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false if the array is guaranteed to not contain any logical nulls Read moreSource§impl<T: ArrowPrimitiveType> ArrayAccessor for &PrimitiveArray<T>
impl<T: ArrowPrimitiveType> ArrayAccessor for &PrimitiveArray<T>
Source§impl<T: ArrowPrimitiveType> Clone for PrimitiveArray<T>
impl<T: ArrowPrimitiveType> Clone for PrimitiveArray<T>
Source§impl<T: ArrowPrimitiveType> Debug for PrimitiveArray<T>
impl<T: ArrowPrimitiveType> Debug for PrimitiveArray<T>
Source§impl<T: ArrowPrimitiveType> From<ArrayData> for PrimitiveArray<T>
Constructs a PrimitiveArray from an array data reference.
impl<T: ArrowPrimitiveType> From<ArrayData> for PrimitiveArray<T>
Constructs a PrimitiveArray from an array data reference.