Struct DecimalArray

pub struct DecimalArray { /* 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:

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

Examples

use vortex_array::arrays::DecimalArray;
use vortex_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 DecimalArray

pub fn patch(self, patches: &Patches) -> VortexResult<Self>

impl DecimalArray

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

Creates a new DecimalArray from a Buffer and Validity, without checking any invariants.

Panics

Panics if the validity length is not compatible with the buffer length.

pub fn byte_buffer(&self) -> ByteBuffer

Returns the underlying ByteBuffer of the array.

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

pub fn decimal_dtype(&self) -> DecimalDType

Returns the decimal type information

pub fn values_type(&self) -> DecimalValueType

pub fn precision(&self) -> u8

pub fn scale(&self) -> i8

pub fn from_option_iter<T: NativeDecimalType, I: IntoIterator<Item = Option<T>>>( iter: I, decimal_dtype: DecimalDType, ) -> Self

Methods from Deref<Target = dyn Array>

pub fn display_values(&self) -> impl Display

Display logical values of the array

For example, an i16 typed array containing the first five non-negative integers is displayed as: [0i16, 1i16, 2i16, 3i16, 4i16].

Examples

let array = buffer![0_i16, 1, 2, 3, 4].into_array();
assert_eq!(
    format!("{}", array.display_values()),
    "[0i16, 1i16, 2i16, 3i16, 4i16]",
)

See also: Array::display_as, DisplayArrayAs, and DisplayOptions.

pub fn display_as(&self, options: DisplayOptions) -> impl Display

Display the array as specified by the options.

See DisplayOptions for examples.

pub fn display_tree(&self) -> impl Display

Display the tree of encodings of this array as an indented lists.

While some metadata (such as length, bytes and validity-rate) are included, the logical values of the array are not displayed. To view the logical values see Array::display_as and DisplayOptions.

Examples

let array = buffer![0_i16, 1, 2, 3, 4].into_array();
let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
  metadata: EmptyMetadata
  buffer (align=2): 10 B (100.00%)
";
assert_eq!(format!("{}", array.display_tree()), expected);

pub fn as_<V: VTable>(&self) -> &V::Array

Returns the array downcast to the given A.

pub fn as_opt<V: VTable>(&self) -> Option<&V::Array>

Returns the array downcast to the given A.

pub fn is<V: VTable>(&self) -> bool

Is self an array with encoding from vtable V.

pub fn is_constant(&self) -> bool

pub fn is_constant_opts(&self, cost: Cost) -> bool

pub fn as_constant(&self) -> Option<Scalar>

pub fn nbytes(&self) -> u64

Total size of the array in bytes, including all children and buffers.

pub fn to_array_iterator(&self) -> impl ArrayIterator + 'static

Create an ArrayIterator over the array.

pub fn serialize( &self, ctx: &ArrayContext, options: &SerializeOptions, ) -> VortexResult<Vec<ByteBuffer>>

Serialize the array into a sequence of byte buffers that should be written contiguously. This function returns a vec to avoid copying data buffers.

Optionally, padding can be included to guarantee buffer alignment and ensure zero-copy reads within the context of an external file or stream. In this case, the alignment of the first byte buffer should be respected when writing the buffers to the stream or file.

The format of this blob is a sequence of data buffers, possible with prefixed padding, followed by a flatbuffer containing an fba::Array message, and ending with a little-endian u32 describing the length of the flatbuffer message.

pub fn to_array_stream(&self) -> impl ArrayStream + 'static

Create an ArrayStream over the array.

pub fn as_null_typed(&self) -> NullTyped<'_>

Downcasts the array for null-specific behavior.

pub fn as_bool_typed(&self) -> BoolTyped<'_>

Downcasts the array for bool-specific behavior.

pub fn as_primitive_typed(&self) -> PrimitiveTyped<'_>

Downcasts the array for primitive-specific behavior.

pub fn as_decimal_typed(&self) -> DecimalTyped<'_>

Downcasts the array for decimal-specific behavior.

pub fn as_utf8_typed(&self) -> Utf8Typed<'_>

Downcasts the array for utf8-specific behavior.

pub fn as_binary_typed(&self) -> BinaryTyped<'_>

Downcasts the array for binary-specific behavior.

pub fn as_struct_typed(&self) -> StructTyped<'_>

Downcasts the array for struct-specific behavior.

pub fn as_list_typed(&self) -> ListTyped<'_>

Downcasts the array for list-specific behavior.

pub fn as_extension_typed(&self) -> ExtensionTyped<'_>

Downcasts the array for extension-specific behavior.

Trait Implementations

impl AsRef<dyn Array> for DecimalArray

fn as_ref(&self) -> &dyn Array

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for DecimalArray

fn clone(&self) -> DecimalArray

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DecimalArray

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

Formats the value using the given formatter.

impl Deref for DecimalArray

type Target = dyn Array

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<DecimalArray> for ArrayRef

fn from(value: DecimalArray) -> ArrayRef

Converts to this type from the input type.

impl IntoArray for DecimalArray

fn into_array(self) -> ArrayRef

impl ValidityHelper for DecimalArray

fn validity(&self) -> &Validity