Struct arrow::array::PrimitiveArray

source ·

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

Expand description

Array whose elements are of primitive types.

Example: From an iterator of values

use arrow_array::{Array, PrimitiveArray, types::Int32Type};
let arr: PrimitiveArray<Int32Type> = PrimitiveArray::from_iter_values((0..10).map(|x| x + 1));
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));
}

Implementations§

source §

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

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) -> &[<T as ArrowPrimitiveType>::Native]

Returns a slice of the values of this array

source

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

Returns a new primitive array builder

source

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

source

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

source

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

source

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

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 as ArrowPrimitiveType>::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 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()

source

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]

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 as ArrowPrimitiveType>::Native) -> <O as ArrowPrimitiveType>::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 as ArrowPrimitiveType>::Native) -> <T as ArrowPrimitiveType>::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 as ArrowPrimitiveType>::Native) -> Result<<O as ArrowPrimitiveType>::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 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

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>, PrimitiveArray<T>>

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

source §

impl<T> PrimitiveArray<T>where
T: ArrowTemporalType,
i64: From<<T as ArrowPrimitiveType>::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> PrimitiveArray<T>where
T: ArrowPrimitiveType,

source

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

constructs a new iterator

source §

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

source

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.

source §

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

source

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

👎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>, Global>,
 timezone: Option<String>
) -> PrimitiveArray<T>where
 PrimitiveArray<T>: From<Vec<Option<i64>, Global>>,

👎Deprecated: Use with_timezone_opt instead

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

source

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

Construct a timestamp array with new timezone

source

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

Construct a timestamp array with UTC

source

pub fn with_timezone_opt(&self, timezone: Option<String>) -> PrimitiveArray<T>

Construct a timestamp array with an optional timezone

source §

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

source

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

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

Returns an Error if:

precision is zero
precision is larger than T:MAX_PRECISION
scale is larger than T::MAX_SCALE
scale is > precision

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 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> Array for PrimitiveArray<T>where
T: ArrowPrimitiveType,

source §

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

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

source §

fn data(&self) -> &ArrayData

Returns a reference to the underlying data of this array.

source §

fn into_data(self) -> ArrayData

Returns the underlying data of this array.

source §

fn data_ref(&self) -> &ArrayData

Returns a reference-counted pointer to the underlying data of this array.

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) -> Arc<dyn Array + 'static>

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 is_null(&self, index: usize) -> bool

Returns whether the element at index is null. When using this function on a slice, the index is relative to the slice. Read more

source §

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

Returns whether the element at index is not null. When using this function on a slice, the index is relative to the slice. Read more

source §

fn null_count(&self) -> usize

Returns the total number of null values in this array. 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. Read more

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. Read more

source §

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

§

type Item = <T as ArrowPrimitiveType>::Native

The Arrow type of the element being accessed.

source §

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

Returns the element at index i Read more

source §

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

Returns the element at index i Read more

source §

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

source §

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

source §

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

source §

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

Formats the value using the given formatter. Read more

source §