1use std::fmt::Display;
5use std::fmt::Formatter;
6
7use itertools::Itertools;
8use smallvec::smallvec;
9use vortex_buffer::Alignment;
10use vortex_buffer::BitBufferMut;
11use vortex_buffer::Buffer;
12use vortex_buffer::BufferMut;
13use vortex_buffer::ByteBuffer;
14use vortex_error::VortexExpect;
15use vortex_error::VortexResult;
16use vortex_error::vortex_ensure;
17use vortex_error::vortex_panic;
18
19use crate::ArrayRef;
20use crate::ArraySlots;
21use crate::ExecutionCtx;
22use crate::IntoArray;
23use crate::array::Array;
24use crate::array::ArrayParts;
25use crate::array::TypedArrayRef;
26use crate::array::child_to_validity;
27use crate::array::validity_to_child;
28use crate::array_slots;
29use crate::arrays::Decimal;
30use crate::arrays::DecimalArray;
31use crate::arrays::PrimitiveArray;
32use crate::arrays::primitive::PrimitiveArrayExt;
33use crate::buffer::BufferHandle;
34use crate::dtype::BigCast;
35use crate::dtype::DType;
36use crate::dtype::DecimalDType;
37use crate::dtype::DecimalType;
38use crate::dtype::IntegerPType;
39use crate::dtype::NativeDecimalType;
40use crate::dtype::Nullability;
41use crate::match_each_decimal_value_type;
42use crate::match_each_unsigned_integer_ptype;
43use crate::patches::Patches;
44use crate::validity::Validity;
45
46#[array_slots(Decimal)]
47pub struct DecimalSlots {
48 #[slot(0)]
50 pub validity: Option<ArrayRef>,
51}
52
53#[derive(Clone, Debug)]
111pub struct DecimalData {
112 pub(super) decimal_dtype: DecimalDType,
113 pub(super) values: BufferHandle,
114 pub(super) values_type: DecimalType,
116}
117
118impl Display for DecimalData {
119 fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
120 write!(
121 f,
122 "decimal_dtype: {}, values_type: {}",
123 self.decimal_dtype, self.values_type
124 )
125 }
126}
127
128pub struct DecimalDataParts {
130 pub decimal_dtype: DecimalDType,
132 pub values: BufferHandle,
134 pub values_type: DecimalType,
142 pub validity: Validity,
144}
145
146pub trait DecimalArrayExt: TypedArrayRef<Decimal> {
147 fn decimal_dtype(&self) -> DecimalDType {
148 match self.dtype() {
149 DType::Decimal(decimal_dtype, _) => *decimal_dtype,
150 _ => unreachable!("DecimalArrayExt requires a decimal dtype"),
151 }
152 }
153
154 fn nullability(&self) -> Nullability {
155 match self.dtype() {
156 DType::Decimal(_, nullability) => *nullability,
157 _ => unreachable!("DecimalArrayExt requires a decimal dtype"),
158 }
159 }
160
161 fn validity_child(&self) -> Option<&ArrayRef> {
162 self.slots()[DecimalSlots::VALIDITY].as_ref()
163 }
164
165 fn validity(&self) -> Validity {
166 child_to_validity(
167 self.slots()[DecimalSlots::VALIDITY].as_ref(),
168 self.nullability(),
169 )
170 }
171
172 fn values_type(&self) -> DecimalType {
173 self.values_type
174 }
175
176 fn precision(&self) -> u8 {
177 self.decimal_dtype().precision()
178 }
179
180 fn scale(&self) -> i8 {
181 self.decimal_dtype().scale()
182 }
183
184 fn buffer_handle(&self) -> &BufferHandle {
185 &self.values
186 }
187
188 fn buffer<T: NativeDecimalType>(&self) -> Buffer<T> {
189 DecimalData::buffer::<T>(self)
190 }
191}
192impl<T: TypedArrayRef<Decimal>> DecimalArrayExt for T {}
193
194impl DecimalData {
195 pub(super) fn make_slots(validity: &Validity, len: usize) -> ArraySlots {
197 smallvec![validity_to_child(validity, len)]
198 }
199
200 pub fn new<T: NativeDecimalType>(buffer: Buffer<T>, decimal_dtype: DecimalDType) -> Self {
207 Self::try_new(buffer, decimal_dtype).vortex_expect("DecimalArray construction failed")
208 }
209
210 pub fn new_handle(
218 values: BufferHandle,
219 values_type: DecimalType,
220 decimal_dtype: DecimalDType,
221 ) -> Self {
222 Self::try_new_handle(values, values_type, decimal_dtype)
223 .vortex_expect("DecimalArray construction failed")
224 }
225
226 pub fn try_new<T: NativeDecimalType>(
235 buffer: Buffer<T>,
236 decimal_dtype: DecimalDType,
237 ) -> VortexResult<Self> {
238 let values = BufferHandle::new_host(buffer.into_byte_buffer());
239 let values_type = T::DECIMAL_TYPE;
240
241 Self::try_new_handle(values, values_type, decimal_dtype)
242 }
243
244 pub fn try_new_handle(
253 values: BufferHandle,
254 values_type: DecimalType,
255 decimal_dtype: DecimalDType,
256 ) -> VortexResult<Self> {
257 Self::validate(&values, values_type)?;
258
259 Ok(unsafe { Self::new_unchecked_handle(values, values_type, decimal_dtype) })
262 }
263
264 pub unsafe fn new_unchecked<T: NativeDecimalType>(
278 buffer: Buffer<T>,
279 decimal_dtype: DecimalDType,
280 ) -> Self {
281 unsafe {
283 Self::new_unchecked_handle(
284 BufferHandle::new_host(buffer.into_byte_buffer()),
285 T::DECIMAL_TYPE,
286 decimal_dtype,
287 )
288 }
289 }
290
291 pub unsafe fn new_unchecked_handle(
303 values: BufferHandle,
304 values_type: DecimalType,
305 decimal_dtype: DecimalDType,
306 ) -> Self {
307 Self {
308 decimal_dtype,
309 values,
310 values_type,
311 }
312 }
313
314 pub(crate) fn validate(buffer: &BufferHandle, values_type: DecimalType) -> VortexResult<()> {
318 let byte_width = values_type.byte_width();
319 vortex_ensure!(
320 buffer.len().is_multiple_of(byte_width),
321 "decimal buffer size {} is not divisible by element width {}",
322 buffer.len(),
323 byte_width,
324 );
325 match_each_decimal_value_type!(values_type, |D| {
326 vortex_ensure!(
327 buffer.is_aligned_to(Alignment::of::<D>()),
328 "decimal buffer alignment {:?} is invalid for values type {:?}",
329 buffer.alignment(),
330 D::DECIMAL_TYPE,
331 );
332 Ok::<(), vortex_error::VortexError>(())
333 })?;
334 Ok(())
335 }
336
337 pub unsafe fn new_unchecked_from_byte_buffer(
346 byte_buffer: ByteBuffer,
347 values_type: DecimalType,
348 decimal_dtype: DecimalDType,
349 ) -> Self {
350 unsafe {
352 Self::new_unchecked_handle(
353 BufferHandle::new_host(byte_buffer),
354 values_type,
355 decimal_dtype,
356 )
357 }
358 }
359
360 pub fn len(&self) -> usize {
362 self.values.len() / self.values_type.byte_width()
363 }
364
365 pub fn is_empty(&self) -> bool {
367 self.len() == 0
368 }
369
370 pub fn buffer_handle(&self) -> &BufferHandle {
372 &self.values
373 }
374
375 pub fn buffer<T: NativeDecimalType>(&self) -> Buffer<T> {
376 if self.values_type != T::DECIMAL_TYPE {
377 vortex_panic!(
378 "Cannot extract Buffer<{:?}> for DecimalArray with values_type {:?}",
379 T::DECIMAL_TYPE,
380 self.values_type,
381 );
382 }
383 Buffer::<T>::from_byte_buffer(self.values.as_host().clone())
384 }
385
386 pub fn values_type(&self) -> DecimalType {
388 self.values_type
389 }
390
391 pub fn decimal_dtype(&self) -> DecimalDType {
393 self.decimal_dtype
394 }
395
396 pub fn precision(&self) -> u8 {
397 self.decimal_dtype.precision()
398 }
399
400 pub fn scale(&self) -> i8 {
401 self.decimal_dtype.scale()
402 }
403}
404
405impl Array<Decimal> {
406 pub fn into_data_parts(self) -> DecimalDataParts {
407 let validity = DecimalArrayExt::validity(&self);
408 let decimal_dtype = DecimalArrayExt::decimal_dtype(&self);
409 let data = self.into_data();
410 DecimalDataParts {
411 decimal_dtype,
412 values: data.values,
413 values_type: data.values_type,
414 validity,
415 }
416 }
417}
418
419impl Array<Decimal> {
420 pub fn new<T: NativeDecimalType>(
422 buffer: Buffer<T>,
423 decimal_dtype: DecimalDType,
424 validity: Validity,
425 ) -> Self {
426 Self::try_new(buffer, decimal_dtype, validity)
427 .vortex_expect("DecimalArray construction failed")
428 }
429
430 pub unsafe fn new_unchecked<T: NativeDecimalType>(
436 buffer: Buffer<T>,
437 decimal_dtype: DecimalDType,
438 validity: Validity,
439 ) -> Self {
440 let dtype = DType::Decimal(decimal_dtype, validity.nullability());
441 let len = buffer.len();
442 let slots = DecimalData::make_slots(&validity, len);
443 let data = unsafe { DecimalData::new_unchecked(buffer, decimal_dtype) };
444 unsafe {
445 Self::from_decimal_parts_unchecked(ArrayParts::new(Decimal, dtype, len, data, slots))
446 }
447 }
448
449 pub fn try_new<T: NativeDecimalType>(
451 buffer: Buffer<T>,
452 decimal_dtype: DecimalDType,
453 validity: Validity,
454 ) -> VortexResult<Self> {
455 let dtype = DType::Decimal(decimal_dtype, validity.nullability());
456 let len = buffer.len();
457 let slots = DecimalData::make_slots(&validity, len);
458 let data = DecimalData::try_new(buffer, decimal_dtype)?;
459 Self::try_from_decimal_parts(ArrayParts::new(Decimal, dtype, len, data, slots))
460 }
461
462 unsafe fn from_decimal_parts_unchecked(parts: ArrayParts<Decimal>) -> Self {
471 unsafe { Array::from_parts_unchecked(parts) }
472 }
473
474 fn try_from_decimal_parts(parts: ArrayParts<Decimal>) -> VortexResult<Self> {
479 Array::try_from_parts(parts)
480 }
481
482 #[expect(
484 clippy::same_name_method,
485 reason = "intentionally named from_iter like Iterator::from_iter"
486 )]
487 pub fn from_iter<T: NativeDecimalType, I: IntoIterator<Item = T>>(
488 iter: I,
489 decimal_dtype: DecimalDType,
490 ) -> Self {
491 Self::new(
492 BufferMut::from_iter(iter).freeze(),
493 decimal_dtype,
494 Validity::NonNullable,
495 )
496 }
497
498 pub fn from_option_iter<T: NativeDecimalType, I: IntoIterator<Item = Option<T>>>(
500 iter: I,
501 decimal_dtype: DecimalDType,
502 ) -> Self {
503 let iter = iter.into_iter();
504 let mut values = BufferMut::with_capacity(iter.size_hint().0);
505 let mut validity = BitBufferMut::with_capacity(values.capacity());
506
507 for value in iter {
508 match value {
509 Some(value) => {
510 values.push(value);
511 validity.append(true);
512 }
513 None => {
514 values.push(T::default());
515 validity.append(false);
516 }
517 }
518 }
519
520 Self::new(
521 values.freeze(),
522 decimal_dtype,
523 Validity::from(validity.freeze()),
524 )
525 }
526
527 pub fn new_handle(
529 values: BufferHandle,
530 values_type: DecimalType,
531 decimal_dtype: DecimalDType,
532 validity: Validity,
533 ) -> Self {
534 Self::try_new_handle(values, values_type, decimal_dtype, validity)
535 .vortex_expect("DecimalArray construction failed")
536 }
537
538 pub fn try_new_handle(
540 values: BufferHandle,
541 values_type: DecimalType,
542 decimal_dtype: DecimalDType,
543 validity: Validity,
544 ) -> VortexResult<Self> {
545 let dtype = DType::Decimal(decimal_dtype, validity.nullability());
546 let len = values.len() / values_type.byte_width();
547 let slots = DecimalData::make_slots(&validity, len);
548 let data = DecimalData::try_new_handle(values, values_type, decimal_dtype)?;
549 Array::try_from_parts(ArrayParts::new(Decimal, dtype, len, data, slots))
550 }
551
552 pub unsafe fn new_unchecked_handle(
558 values: BufferHandle,
559 values_type: DecimalType,
560 decimal_dtype: DecimalDType,
561 validity: Validity,
562 ) -> Self {
563 let dtype = DType::Decimal(decimal_dtype, validity.nullability());
564 let len = values.len() / values_type.byte_width();
565 let slots = DecimalData::make_slots(&validity, len);
566 let data = unsafe { DecimalData::new_unchecked_handle(values, values_type, decimal_dtype) };
567 unsafe { Array::from_parts_unchecked(ArrayParts::new(Decimal, dtype, len, data, slots)) }
568 }
569
570 #[expect(
571 clippy::cognitive_complexity,
572 reason = "patching depends on both patch and value physical types"
573 )]
574 pub fn patch(self, patches: &Patches, ctx: &mut ExecutionCtx) -> VortexResult<Self> {
575 let offset = patches.offset();
576 let dtype = self.dtype().clone();
577 let len = self.len();
578 let patch_indices = patches.indices().clone().execute::<PrimitiveArray>(ctx)?;
579 let patch_values = patches.values().clone().execute::<DecimalArray>(ctx)?;
580
581 let patch_validity = patch_values.validity()?;
582 let patched_validity = self.validity()?.patch(
583 self.len(),
584 offset,
585 &patch_indices.clone().into_array(),
586 &patch_validity,
587 ctx,
588 )?;
589 assert_eq!(self.decimal_dtype(), patch_values.decimal_dtype());
590
591 let data = self.into_data();
592 let patch_indices_unsigned =
595 patch_indices.reinterpret_cast(patch_indices.ptype().to_unsigned());
596 let data = match_each_unsigned_integer_ptype!(patch_indices_unsigned.ptype(), |I| {
597 let patch_indices = patch_indices_unsigned.as_slice::<I>();
598 match_each_decimal_value_type!(patch_values.values_type(), |PatchDVT| {
599 let patch_values = patch_values.buffer::<PatchDVT>();
600 match_each_decimal_value_type!(data.values_type(), |ValuesDVT| {
601 let buffer = data.buffer::<ValuesDVT>().into_mut();
602 patch_typed(
603 buffer,
604 data.decimal_dtype(),
605 patch_indices,
606 offset,
607 patch_values,
608 )
609 })
610 })
611 });
612 let slots = DecimalData::make_slots(&patched_validity, len);
613 Ok(unsafe {
614 Array::from_parts_unchecked(ArrayParts::new(Decimal, dtype, len, data, slots))
615 })
616 }
617}
618
619fn patch_typed<I, ValuesDVT, PatchDVT>(
620 mut buffer: BufferMut<ValuesDVT>,
621 decimal_dtype: DecimalDType,
622 patch_indices: &[I],
623 patch_indices_offset: usize,
624 patch_values: Buffer<PatchDVT>,
625) -> DecimalData
626where
627 I: IntegerPType,
628 PatchDVT: NativeDecimalType,
629 ValuesDVT: NativeDecimalType,
630{
631 if !ValuesDVT::DECIMAL_TYPE.is_compatible_decimal_value_type(decimal_dtype) {
632 vortex_panic!(
633 "patch_typed: {:?} cannot represent every value in {}.",
634 ValuesDVT::DECIMAL_TYPE,
635 decimal_dtype
636 )
637 }
638
639 for (idx, value) in patch_indices.iter().zip_eq(patch_values) {
640 buffer[idx.as_() - patch_indices_offset] = <ValuesDVT as BigCast>::from(value).vortex_expect(
641 "values of a given DecimalDType are representable in all compatible NativeDecimalType",
642 );
643 }
644
645 DecimalData::new(buffer.freeze(), decimal_dtype)
646}