pub struct DecimalData { /* private fields */ }Expand description
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 canonical widths for each precision 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
Storage width is still independent of precision during the canonical decimal migration.
Existing vortex.decimal nodes and DecimalByteParts assembly can produce noncanonical storage.
For example, an array with precision 39 can currently use an i8 buffer when all values fit,
while an array with precision 2 can use a Buffer<i256>. DecimalDataParts preserves the
actual width for conversion into canonical decimal leaves, optionally under
Widen.
§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
Canonical decimal leaves select one of these native types from 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§
Source§impl DecimalData
impl DecimalData
Sourcepub fn new<T: NativeDecimalType>(
buffer: Buffer<T>,
decimal_dtype: DecimalDType,
) -> Self
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.
Sourcepub fn new_handle(
values: BufferHandle,
values_type: DecimalType,
decimal_dtype: DecimalDType,
) -> Self
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.
Sourcepub fn try_new<T: NativeDecimalType>(
buffer: Buffer<T>,
decimal_dtype: DecimalDType,
) -> VortexResult<Self>
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.
Sourcepub fn try_new_handle(
values: BufferHandle,
values_type: DecimalType,
decimal_dtype: DecimalDType,
) -> VortexResult<Self>
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
Returns an error if the buffer length is not a multiple of the width of values_type, or
if the buffer is not aligned to that width.
Sourcepub unsafe fn new_unchecked<T: NativeDecimalType>(
buffer: Buffer<T>,
decimal_dtype: DecimalDType,
) -> Self
pub unsafe fn new_unchecked<T: NativeDecimalType>( buffer: Buffer<T>, decimal_dtype: DecimalDType, ) -> Self
Creates a new DecimalArray without validation from these components:
bufferis a typed buffer containing the decimal values.decimal_dtypespecifies the decimal precision and scale.
Values are not checked against the precision of decimal_dtype, either here, in
DecimalArray::try_new, or when an array is read from a file. Code that turns stored values
into scalars must use a fallible path such as
Scalar::try_decimal.
§Safety
buffer is a typed Buffer<T>, so there are no further requirements on the caller.
Sourcepub unsafe fn new_unchecked_handle(
values: BufferHandle,
values_type: DecimalType,
decimal_dtype: DecimalDType,
) -> Self
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.
As with DecimalArray::new_unchecked, values are not checked against the precision of
decimal_dtype.
§Safety
- The length of
valuesmust be a multiple of the byte width ofvalues_type. valuesmust be aligned to the native type ofvalues_type.
Breaking either rule does not cause undefined behavior, but DecimalData::buffer panics.
Sourcepub unsafe fn new_unchecked_from_byte_buffer(
byte_buffer: ByteBuffer,
values_type: DecimalType,
decimal_dtype: DecimalDType,
) -> Self
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_buffercontains valid data for the specifiedvalues_type - The buffer length is compatible with the
values_type(i.e., divisible by the type size) - If
validityisValidity::Array, its length must equal the number of elements
Sourcepub fn buffer_handle(&self) -> &BufferHandle
pub fn buffer_handle(&self) -> &BufferHandle
Returns the underlying ByteBuffer of the array.
pub fn buffer<T: NativeDecimalType>(&self) -> Buffer<T>
Sourcepub fn values_type(&self) -> DecimalType
pub fn values_type(&self) -> DecimalType
Return the DecimalType used to represent the values in the array.
Sourcepub fn decimal_dtype(&self) -> DecimalDType
pub fn decimal_dtype(&self) -> DecimalDType
Returns the decimal type information.
pub fn precision(&self) -> u8
pub fn scale(&self) -> i8
Trait Implementations§
Source§impl ArrayEq for DecimalData
impl ArrayEq for DecimalData
Source§impl ArrayHash for DecimalData
impl ArrayHash for DecimalData
Source§impl Clone for DecimalData
impl Clone for DecimalData
Source§impl Debug for DecimalData
impl Debug for DecimalData
Auto Trait Implementations§
impl !RefUnwindSafe for DecimalData
impl !UnwindSafe for DecimalData
impl Freeze for DecimalData
impl Send for DecimalData
impl Sync for DecimalData
impl Unpin for DecimalData
impl UnsafeUnpin for DecimalData
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> DynArrayDataEq for Twhere
T: ArrayEq + 'static,
impl<T> DynArrayDataEq for Twhere
T: ArrayEq + 'static,
Source§impl<T> DynArrayDataHash for T
impl<T> DynArrayDataHash for T
fn dyn_array_hash(&self, state: &mut dyn Hasher, eq_mode: EqMode)
Source§impl<T> FmtForward for T
impl<T> FmtForward for T
Source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self to use its Binary implementation when Debug-formatted.Source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self to use its Display implementation when
Debug-formatted.Source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self to use its LowerExp implementation when
Debug-formatted.Source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self to use its LowerHex implementation when
Debug-formatted.Source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self to use its Octal implementation when Debug-formatted.Source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self to use its Pointer implementation when
Debug-formatted.Source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self to use its UpperExp implementation when
Debug-formatted.Source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self to use its UpperHex implementation when
Debug-formatted.Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
Source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the foreground set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red() and
green(), which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg():
use yansi::{Paint, Color};
painted.fg(Color::White);Set foreground color to white using white().
use yansi::Paint;
painted.white();Source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
Source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
Source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
Source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
Source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
Source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
Source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the background set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red() and
on_green(), which have the same functionality but
are pithier.
§Example
Set background color to red using fg():
use yansi::{Paint, Color};
painted.bg(Color::Red);Set background color to red using on_red().
use yansi::Paint;
painted.on_red();Source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
Source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
Source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
Source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute value.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold() and
underline(), which have the same functionality
but are pithier.
§Example
Make text bold using attr():
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);Make text bold using using bold().
use yansi::Paint;
painted.bold();Source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi Quirk value.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask() and
wrap(), which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk():
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);Enable wrapping using wrap().
use yansi::Paint;
painted.wrap();Source§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
fn clear(&self) -> Painted<&T>
renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
Source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted only when both stdout and stderr are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);Source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
Source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
Source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
Source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R,
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
Source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self, then passes self.as_ref() into the pipe function.Source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self, then passes self.as_mut() into the pipe
function.Source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self, then passes self.deref() into the pipe function.impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
Source§impl<T> Tap for T
impl<T> Tap for T
Source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B> of a value. Read moreSource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B> of a value. Read moreSource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R> view of a value. Read moreSource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R> view of a value. Read moreSource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap() only in debug builds, and is erased in release builds.Source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut() only in debug builds, and is erased in release
builds.Source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref() only in debug builds, and is erased in release
builds.Source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut() only in debug builds, and is erased in release
builds.Source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref() only in debug builds, and is erased in release
builds.