Struct DecimalData 

pub struct DecimalData { /* private fields */ }

A decimal array that stores fixed-precision decimal numbers with configurable scale.

This mirrors the Apache Arrow Decimal encoding and provides exact arithmetic for financial and scientific computations where floating-point precision loss is unacceptable.

Storage Format

Decimals are stored as scaled integers in a supported scalar value type.

The precisions supported for each scalar type are:

• i8: precision 1-2 digits
• i16: precision 3-4 digits
• i32: precision 5-9 digits
• i64: precision 10-18 digits
• i128: precision 19-38 digits
• i256: precision 39-76 digits

These are just the maximal ranges for each scalar type, but it is perfectly legal to store values with precision that does not match this exactly. For example, a valid DecimalArray with precision=39 may store its values in an i8 if all of the actual values fit into it.

Similarly, a DecimalArray can be built that stores a set of precision=2 values in a Buffer<i256>.

Precision and Scale

• Precision: Total number of significant digits (1-76, u8 range)
• Scale: Number of digits after the decimal point (-128 to 127, i8 range)
• Value: stored_integer / 10^scale

For example, with precision=5 and scale=2:

• Stored value 12345 represents 123.45
• Range: -999.99 to 999.99

Valid Scalar Types

The underlying storage uses these native types based on precision:

• DecimalType::I8, I16, I32, I64, I128, I256
• Type selection is automatic based on the required precision

Examples

use vortex_array::arrays::DecimalArray;
use vortex_array::dtype::DecimalDType;
use vortex_buffer::{buffer, Buffer};
use vortex_array::validity::Validity;

// Create a decimal array with precision=5, scale=2 (e.g., 123.45)
let decimal_dtype = DecimalDType::new(5, 2);
let values = buffer![12345i32, 67890i32, -12300i32]; // 123.45, 678.90, -123.00
let array = DecimalArray::new(values, decimal_dtype, Validity::NonNullable);

assert_eq!(array.precision(), 5);
assert_eq!(array.scale(), 2);
assert_eq!(array.len(), 3);

Implementations

impl DecimalData

pub fn new<T: NativeDecimalType>( buffer: Buffer<T>, decimal_dtype: DecimalDType, ) -> Self

Creates a new DecimalArray using a host-native buffer.

Panics

Panics if the provided components do not satisfy the invariants documented in DecimalArray::new_unchecked.

pub fn new_handle( values: BufferHandle, values_type: DecimalType, decimal_dtype: DecimalDType, ) -> Self

Creates a new DecimalArray from a BufferHandle of values that may live in host or device memory.

Panics

Panics if the provided components do not satisfy the invariants documented in DecimalArray::new_unchecked.

pub fn try_new<T: NativeDecimalType>( buffer: Buffer<T>, decimal_dtype: DecimalDType, ) -> VortexResult<Self>

Constructs a new DecimalArray.

See DecimalArray::new_unchecked for more information.

Errors

Returns an error if the provided components do not satisfy the invariants documented in DecimalArray::new_unchecked.

pub fn try_new_handle( values: BufferHandle, values_type: DecimalType, decimal_dtype: DecimalDType, ) -> VortexResult<Self>

Constructs a new DecimalArray with validation from a BufferHandle.

This pathway allows building new decimal arrays that may come from host or device memory.

Errors

See DecimalArray::new_unchecked for invariants that are checked.

pub unsafe fn new_unchecked<T: NativeDecimalType>( buffer: Buffer<T>, decimal_dtype: DecimalDType, ) -> Self

Creates a new DecimalArray without validation from these components:

• buffer is a typed buffer containing the decimal values.
• decimal_dtype specifies the decimal precision and scale.
• validity holds the null values.

Safety

The caller must ensure all of the following invariants are satisfied:

• All non-null values in buffer must be representable within the specified precision.
• For example, with precision=5 and scale=2, all values must be in range [-999.99, 999.99].
• If validity is Validity::Array, its length must exactly equal buffer.len().

pub unsafe fn new_unchecked_handle( values: BufferHandle, values_type: DecimalType, decimal_dtype: DecimalDType, ) -> Self

Create a new array with decimal values backed by the given buffer handle.

Safety

The caller must ensure all of the following invariants are satisfied:

• All non-null values in values must be representable within the specified precision.
• For example, with precision=5 and scale=2, all values must be in range [-999.99, 999.99].
• If validity is Validity::Array, its length must exactly equal buffer.len().

pub unsafe fn new_unchecked_from_byte_buffer( byte_buffer: ByteBuffer, values_type: DecimalType, decimal_dtype: DecimalDType, ) -> Self

Creates a new DecimalArray from a raw byte buffer without validation.

Safety

The caller must ensure:

• The byte_buffer contains valid data for the specified values_type
• The buffer length is compatible with the values_type (i.e., divisible by the type size)
• All non-null values are representable within the specified precision
• If validity is Validity::Array, its length must equal the number of elements

pub fn len(&self) -> usize

Returns the length of this array.

pub fn is_empty(&self) -> bool

Returns true if this array is empty.

pub fn buffer_handle(&self) -> &BufferHandle

Returns the underlying ByteBuffer of the array.

pub fn buffer<T: NativeDecimalType>(&self) -> Buffer<T>

pub fn values_type(&self) -> DecimalType

Return the DecimalType used to represent the values in the array.

pub fn decimal_dtype(&self) -> DecimalDType

Returns the decimal type information.

pub fn precision(&self) -> u8

pub fn scale(&self) -> i8

Trait Implementations

impl ArrayEq for DecimalData

fn array_eq(&self, other: &Self, precision: Precision) -> bool

impl ArrayHash for DecimalData

fn array_hash<H: Hasher>(&self, state: &mut H, precision: Precision)

impl Clone for DecimalData

fn clone(&self) -> DecimalData

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DecimalData

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

Formats the value using the given formatter.

impl Display for DecimalData

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

Formats the value using the given formatter.