Struct arrow_array::array::PrimitiveArray

source ·

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>

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

source

pub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
where F: Fn(T::Native) -> T::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]));

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

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

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

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

source

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