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,
impl<T> PrimitiveArray<T>where
T: ArrowPrimitiveType,
pub fn new(
values: ScalarBuffer<<T as ArrowPrimitiveType>::Native>,
nulls: Option<NullBuffer>,
) -> PrimitiveArray<T>
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>
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>
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>>
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>)
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>
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 values(&self) -> &ScalarBuffer<<T as ArrowPrimitiveType>::Native>
pub fn values(&self) -> &ScalarBuffer<<T as ArrowPrimitiveType>::Native>
Returns the values of this array
pub fn builder(capacity: usize) -> PrimitiveBuilder<T>
pub fn builder(capacity: usize) -> PrimitiveBuilder<T>
Returns a new primitive array builder
pub 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
pub unsafe fn value_unchecked(
&self,
i: usize,
) -> <T as ArrowPrimitiveType>::Native
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
pub fn value(&self, i: usize) -> <T as ArrowPrimitiveType>::Native
pub fn from_iter_values<I>(iter: I) -> PrimitiveArray<T>
pub fn from_iter_values<I>(iter: I) -> PrimitiveArray<T>
Creates a PrimitiveArray based on an iterator of values without nulls
pub fn from_iter_values_with_nulls<I>(
iter: I,
nulls: Option<NullBuffer>,
) -> PrimitiveArray<T>
pub fn from_iter_values_with_nulls<I>( iter: I, nulls: Option<NullBuffer>, ) -> PrimitiveArray<T>
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>
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
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
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>
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>
pub fn reinterpret_cast<K>(&self) -> PrimitiveArray<K>
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,
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.
See also
Self::unary_mut
for in place modification.Self::try_unary
for fallible operations.arrow::compute::binary
for 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]));
pub 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]));
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>,
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>>
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
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>,
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>
pub fn from_unary<U, F>(left: U, op: F) -> PrimitiveArray<T>
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>>
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>
impl<T> PrimitiveArray<T>
pub 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.
pub 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
pub 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
pub 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
pub fn value_as_duration(&self, i: usize) -> Option<TimeDelta>
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,
impl<'a, T> PrimitiveArray<T>where
T: ArrowPrimitiveType,
pub fn iter(&'a self) -> ArrayIter<&'a PrimitiveArray<T>> ⓘ
pub fn iter(&'a self) -> ArrayIter<&'a PrimitiveArray<T>> ⓘ
constructs a new iterator
§impl<T> PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> PrimitiveArray<T>where
T: ArrowPrimitiveType,
pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> PrimitiveArray<T>
pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> PrimitiveArray<T>
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,
impl<T> PrimitiveArray<T>where
T: ArrowTimestampType,
pub fn with_timezone(self, timezone: impl Into<Arc<str>>) -> PrimitiveArray<T>
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>
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>
pub fn with_timezone_opt<S>(self, timezone: Option<S>) -> PrimitiveArray<T>
Construct a timestamp array with an optional timezone
§impl<T> PrimitiveArray<T>where
T: DecimalType + ArrowPrimitiveType,
impl<T> PrimitiveArray<T>where
T: DecimalType + ArrowPrimitiveType,
pub fn with_precision_and_scale(
self,
precision: u8,
scale: i8,
) -> Result<PrimitiveArray<T>, ArrowError>
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.
pub 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.
pub fn null_if_overflow_precision(&self, precision: u8) -> PrimitiveArray<T>
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
pub fn value_as_string(&self, row: usize) -> String
Returns Self::value
formatted as a string
Trait Implementations§
§impl<T> Array for PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> Array for PrimitiveArray<T>where
T: ArrowPrimitiveType,
§fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
§fn shrink_to_fit(&mut self)
fn shrink_to_fit(&mut self)
§fn offset(&self) -> usize
fn offset(&self) -> usize
0
. Read more§fn nulls(&self) -> Option<&NullBuffer>
fn nulls(&self) -> Option<&NullBuffer>
§fn logical_null_count(&self) -> usize
fn logical_null_count(&self) -> usize
§fn get_buffer_memory_size(&self) -> usize
fn get_buffer_memory_size(&self) -> usize
§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.§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 more§fn null_count(&self) -> usize
fn null_count(&self) -> usize
§fn is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false
if the array is guaranteed to not contain any logical nulls Read more§impl<T> ArrayAccessor for &PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> ArrayAccessor for &PrimitiveArray<T>where
T: ArrowPrimitiveType,
§type Item = <T as ArrowPrimitiveType>::Native
type Item = <T as ArrowPrimitiveType>::Native
§fn value(&self, index: usize) -> <&PrimitiveArray<T> as ArrayAccessor>::Item
fn value(&self, index: usize) -> <&PrimitiveArray<T> as ArrayAccessor>::Item
i
Read more§unsafe fn value_unchecked(
&self,
index: usize,
) -> <&PrimitiveArray<T> as ArrayAccessor>::Item
unsafe fn value_unchecked( &self, index: usize, ) -> <&PrimitiveArray<T> as ArrayAccessor>::Item
i
Read more§impl<T> Clone for PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> Clone for PrimitiveArray<T>where
T: ArrowPrimitiveType,
§fn clone(&self) -> PrimitiveArray<T>
fn clone(&self) -> PrimitiveArray<T>
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl<T> Debug for PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> Debug for PrimitiveArray<T>where
T: ArrowPrimitiveType,
§impl<T> From<ArrayData> for PrimitiveArray<T>where
T: ArrowPrimitiveType,
impl<T> From<ArrayData> for PrimitiveArray<T>where
T: ArrowPrimitiveType,
Constructs a PrimitiveArray
from an array data reference.