Module decimal 

Definitions and implementations of decimal vector types.

The types that hold data are DVector and DVectorMut, which are generic over types D that implement NativeDecimalType.

DecimalVector and DecimalVectorMut are enums that wrap all of the different possible DVectors. There are several macros defined in this crate to make working with these primitive vector types easier.

Examples

Creating and building decimal vectors

use vortex_dtype::{PrecisionScale};
use vortex_vector::decimal::{DVectorMut};
use vortex_vector::VectorMutOps;

// Create a decimal vector with precision=9, scale=2 (e.g., up to 9999999.99).
let ps = PrecisionScale::<i32>::new(9, 2);
let mut vec = DVectorMut::<i32>::with_capacity(ps, 5);
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 5);

// Values are stored as integers scaled by 10^scale.
// For scale=2: 123.45 is stored as 12345.
vec.try_push(12345).unwrap();  // Represents 123.45.
vec.try_push(9999).unwrap();   // Represents 99.99.
assert_eq!(vec.len(), 2);

// Values that exceed precision will fail.
let too_large = 10_i32.pow(9);  // Would represent 10000000.00.
assert!(vec.try_push(too_large).is_err());

// Create from buffers with validation.
use vortex_buffer::BufferMut;
use vortex_mask::MaskMut;
let elements = BufferMut::from_iter([100_i32, 200, 300]);  // 1.00, 2.00, 3.00.
let validity = MaskMut::new_true(3);
let decimal_vec = DVectorMut::<i32>::new(ps, elements, validity);
assert_eq!(decimal_vec.len(), 3);

Working with nulls and validity

use vortex_buffer::BufferMut;
use vortex_dtype::{PrecisionScale};
use vortex_mask::MaskMut;
use vortex_vector::decimal::DVectorMut;
use vortex_vector::VectorMutOps;

// Create a decimal vector with nulls.
let ps = PrecisionScale::<i32>::new(5, 2); // Up to 999.99.

// Create with some null values (validity mask: true = not null, false = null).
let elements = BufferMut::from_iter([1000_i32, 0, 2500, 0]);  // 10.00, null, 25.00, null.
let mut validity = MaskMut::with_capacity(4);
validity.append_n(true, 1);   // index 0: valid
validity.append_n(false, 1);  // index 1: null
validity.append_n(true, 1);   // index 2: valid
validity.append_n(false, 1);  // index 3: null
let mut vec = DVectorMut::new(ps, elements, validity);

// Check element access with nulls.
assert_eq!(vec.get(0), Some(&1000));  // 10.00.
assert_eq!(vec.get(1), None);         // Null.
assert_eq!(vec.get(2), Some(&2500));  // 25.00.

// Append null values.
vec.append_nulls(3);
assert_eq!(vec.len(), 7);

Extending and manipulating vectors

use vortex_dtype::{PrecisionScale};
use vortex_vector::decimal::DVectorMut;
use vortex_vector::VectorMutOps;

// Create two decimal vectors with scale=3 (3 decimal places).
let ps = PrecisionScale::<i64>::new(10, 3);
let mut vec1 = DVectorMut::<i64>::with_capacity(ps, 10);
vec1.try_push(1234567).unwrap();  // 1234.567.
vec1.try_push(2345678).unwrap();  // 2345.678.

let mut vec2 = DVectorMut::<i64>::with_capacity(ps, 10);
vec2.try_push(3456789).unwrap();  // 3456.789.
vec2.try_push(4567890).unwrap();  // 4567.890.

// Extend from an immutable vector.
let immutable = vec2.freeze();
vec1.extend_from_vector(&immutable);
assert_eq!(vec1.len(), 4);

// Split vector at index 3.
let mut split = vec1.split_off(3);
assert_eq!(vec1.len(), 3);
assert_eq!(split.len(), 1);

// Reserve capacity for future operations.
vec1.reserve(10);
assert!(vec1.capacity() >= 13);

// Rejoin the vectors.
vec1.unsplit(split);
assert_eq!(vec1.len(), 4);

Converting between mutable and immutable

use vortex_dtype::{PrecisionScale};
use vortex_vector::decimal::DVectorMut;
use vortex_vector::{VectorMutOps, VectorOps};

// Create a mutable decimal vector.
let ps = PrecisionScale::<i128>::new(18, 6);  // High precision with 6 decimal places.
let mut vec_mut = DVectorMut::<i128>::with_capacity(ps, 3);
vec_mut.try_push(1000000).unwrap();    // 1.000000.
vec_mut.try_push(2500000).unwrap();    // 2.500000.
vec_mut.try_push(3333333).unwrap();    // 3.333333.

// Freeze into an immutable vector.
let vec_immutable = vec_mut.freeze();
assert_eq!(vec_immutable.len(), 3);

// Access elements from the immutable vector.
assert_eq!(vec_immutable.get(0), Some(&1000000));
assert_eq!(vec_immutable.get(1), Some(&2500000));

// Can also convert immutable back to mutable using try_into_mut.
// Note: This may fail if the buffer is shared.
// let vec_mut_again = vec_immutable.try_into_mut().unwrap();
// assert_eq!(vec_mut_again.len(), 3);

Structs

DScalar

Represents a decimal scalar value with a specific native decimal type.

DVector

An immutable vector of generic decimal values.

DVectorMut

A mutable vector of decimal values with fixed precision and scale.

Enums

DecimalScalar

Represents a decimal scalar value.

DecimalVector

An enum over all supported decimal mutable vector types.

DecimalVectorMut

An enum over all supported decimal mutable vector types.