Struct arrow_array::array::PrimitiveArray

source ·

pub struct PrimitiveArray<T: ArrowPrimitiveType> { /* private fields */ }

Expand description

An array of primitive values

§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));

Implementations§

source §

impl<T: ArrowPrimitiveType> PrimitiveArray<T>

source

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));

source

pub fn new_null(length: usize) -> Self

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

source

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()

source

pub fn new_scalar(value: T::Native) -> Scalar<Self>

Create a new Scalar from value

source

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

Deconstruct this array into its constituent parts

source

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]

source

pub fn len(&self) -> usize

Returns the length of this array.

source

pub fn is_empty(&self) -> bool

Returns whether this array is empty.

source

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

Returns the values of this array

source

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

Returns a new primitive array builder

source

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

source

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()

source

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

Returns the primitive value at index i.

§Panics

Panics if index i is out of bounds

source

pub fn from_iter_values<I: IntoIterator<Item = T::Native>>(iter: I) -> Self

Creates a PrimitiveArray based on an iterator of values without nulls

source

pub fn from_value(value: T::Native, count: usize) -> Self

Creates a PrimitiveArray based on a constant value with count elements

source

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

source

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()

source

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

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

source

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();

source

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

Applies an unary and infallible function to a primitive array. 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.

§Implementation

This will apply the function for all values, including those on null slots. This implies that the operation must be infallible for any value of the corresponding type or this function may panic.

§Example

let array = Int32Array::from(vec![Some(5), Some(7), None]);
let c = array.unary(|x| x * 2 + 1);
assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));

source

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

Applies an unary and infallible function to a mutable primitive array. Mutable primitive array means that the buffer is not shared with other arrays. As a result, this mutates the buffer directly without allocating new buffer.

§Implementation

This will apply the function for all values, including those on null slots. This implies that the operation must be infallible for any value of the corresponding type or this function may panic.

§Example

let array = Int32Array::from(vec![Some(5), Some(7), None]);
let c = array.unary_mut(|x| x * 2 + 1).unwrap();
assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));

source

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

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

This is unlike Self::unary which will apply an infallible function to all rows regardless of validity, in many cases this will be significantly faster and should be preferred if op is infallible.

Note: LLVM is currently unable to effectively vectorize fallible operations

source

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

Applies an unary and fallible function to all valid values in a mutable primitive array. Mutable primitive array means that the buffer is not shared with other arrays. As a result, this mutates the buffer directly without allocating new buffer.

This is unlike Self::unary_mut which will apply an infallible function to all rows regardless of validity, in many cases this will be significantly faster and should be preferred if op is infallible.

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

source

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

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

This is unlike Self::unary which will apply an infallible function to all rows regardless of validity, in many cases this will be significantly faster and should be preferred if op is infallible.

Note: LLVM is currently unable to effectively vectorize fallible operations

source

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

Returns PrimitiveBuilder of this primitive array for mutating its values if the underlying data buffer is not shared by others.

source §

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

source

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.

source

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

source

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

source

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

source

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>

source

pub fn iter(&'a self) -> PrimitiveIter<'a, T>

constructs a new iterator

source §

impl<T: ArrowPrimitiveType> PrimitiveArray<T>

source

pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
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.

source §

impl<T: ArrowTimestampType> PrimitiveArray<T>

source

pub fn from_vec(data: Vec<i64>, timezone: Option<String>) -> Self
where Self: From<Vec<i64>>,

👎Deprecated: Use with_timezone_opt instead

Construct a timestamp array from a vec of i64 values and an optional timezone

source

pub fn from_opt_vec(data: Vec<Option<i64>>, timezone: Option<String>) -> Self
where Self: From<Vec<Option<i64>>>,

👎Deprecated: Use with_timezone_opt instead

Construct a timestamp array from a vec of Option<i64> values and an optional timezone

source

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

Returns the timezone of this array if any

source

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

Construct a timestamp array with new timezone

source

pub fn with_timezone_utc(self) -> Self

Construct a timestamp array with UTC

source

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

Construct a timestamp array with an optional timezone

source §

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

source

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.

See validate_decimal_precision_and_scale

source

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

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

source

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

source

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

Returns Self::value formatted as a string

source

pub fn precision(&self) -> u8

Returns the decimal precision of this array

source

pub fn scale(&self) -> i8

Returns the decimal scale of this array

Trait Implementations§

source §

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

source §

fn as_any(&self) -> &dyn Any

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

source §

fn to_data(&self) -> ArrayData

Returns the underlying data of this array

source §

fn into_data(self) -> ArrayData

Returns the underlying data of this array Read more

source §

fn data_type(&self) -> &DataType

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

source §

fn slice(&self, offset: usize, length: usize) -> ArrayRef

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

source §

fn len(&self) -> usize

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

source §

fn is_empty(&self) -> bool

Returns whether this array is empty. Read more

source §

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

source §

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

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

source §

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.

source §

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.

source §

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

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

source §

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

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

source §

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

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

source §

fn null_count(&self) -> usize

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

source §

fn is_nullable(&self) -> bool

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

source §

impl<'a, T: ArrowPrimitiveType> ArrayAccessor for &'a PrimitiveArray<T>

§

type Item = <T as ArrowPrimitiveType>::Native

The Arrow type of the element being accessed.

source §

fn value(&self, index: usize) -> Self::Item

Returns the element at index i Read more

source §

unsafe fn value_unchecked(&self, index: usize) -> Self::Item

Returns the element at index i Read more

source §

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

source §

fn clone(&self) -> Self

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

source §

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

source §

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

Formats the value using the given formatter. Read more

source §