This is an automated email from the ASF dual-hosted git repository.
Jefffrey pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 3954050f43 docs: clarify decimal negative scale behavior (#10304)
3954050f43 is described below
commit 3954050f433b93e773860dcdf22476cb48efc886
Author: ByteBaker <[email protected]>
AuthorDate: Thu Jul 16 05:16:36 2026 +0530
docs: clarify decimal negative scale behavior (#10304)
# Which issue does this PR close?
- Refs #5793.
- Follow-up to #6413.
# Rationale for this change
The issue was discussed in the PR and issue mentioned above and it was
agreed
[here](https://github.com/apache/arrow-rs/issues/5793#issuecomment-2362484895)
that we should update the docs. We just never got to actually doing it.
# What changes are included in this PR?
Updates the `Decimal32`, `Decimal64`, `Decimal128`, and `Decimal256`
docs to explain that negative scale rounds values to the left of the
decimal point, and that precision is the maximum number of non-rounded
digits.
Also adds an example showing how a value is rounded and represented
internally.
# Are these changes tested?
Ran fmt. Doc only changes, no other test required.
No runtime tests were added because this is a documentation-only change.
# Are there any user-facing changes?
Documentation only. No API or behavior changes.
---
arrow-schema/src/datatype.rs | 64 +++++++++++++++++++-------------------------
1 file changed, 28 insertions(+), 36 deletions(-)
diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs
index 927ad221e9..774c2bd69e 100644
--- a/arrow-schema/src/datatype.rs
+++ b/arrow-schema/src/datatype.rs
@@ -356,59 +356,51 @@ pub enum DataType {
Dictionary(Box<DataType>, Box<DataType>),
/// Exact 32-bit width decimal value with precision and scale
///
- /// * precision is the total number of digits
- /// * scale is the number of digits past the decimal
+ /// * precision is the maximum number of digits in the unscaled value
+ /// * scale controls the position of the decimal point
///
- /// For example the number 123.45 has precision 5 and scale 2.
+ /// The represented value is the unscaled integer multiplied by
10^{-scale}.
+ /// For example, the unscaled value 12345 with precision 5 and scale 2
+ /// represents 123.45.
///
- /// In certain situations, scale could be negative number. For
- /// negative scale, it is the number of padding 0 to the right
- /// of the digits.
- ///
- /// For example the number 12300 could be treated as a decimal
- /// has precision 3 and scale -2.
+ /// Scale can also be negative. For example, the unscaled value 12 with
+ /// precision 2 and scale -3 represents 12000.
Decimal32(u8, i8),
/// Exact 64-bit width decimal value with precision and scale
///
- /// * precision is the total number of digits
- /// * scale is the number of digits past the decimal
- ///
- /// For example the number 123.45 has precision 5 and scale 2.
+ /// * precision is the maximum number of digits in the unscaled value
+ /// * scale controls the position of the decimal point
///
- /// In certain situations, scale could be negative number. For
- /// negative scale, it is the number of padding 0 to the right
- /// of the digits.
+ /// The represented value is the unscaled integer multiplied by
10^{-scale}.
+ /// For example, the unscaled value 12345 with precision 5 and scale 2
+ /// represents 123.45.
///
- /// For example the number 12300 could be treated as a decimal
- /// has precision 3 and scale -2.
+ /// Scale can also be negative. For example, the unscaled value 12 with
+ /// precision 2 and scale -3 represents 12000.
Decimal64(u8, i8),
/// Exact 128-bit width decimal value with precision and scale
///
- /// * precision is the total number of digits
- /// * scale is the number of digits past the decimal
+ /// * precision is the maximum number of digits in the unscaled value
+ /// * scale controls the position of the decimal point
///
- /// For example the number 123.45 has precision 5 and scale 2.
+ /// The represented value is the unscaled integer multiplied by
10^{-scale}.
+ /// For example, the unscaled value 12345 with precision 5 and scale 2
+ /// represents 123.45.
///
- /// In certain situations, scale could be negative number. For
- /// negative scale, it is the number of padding 0 to the right
- /// of the digits.
- ///
- /// For example the number 12300 could be treated as a decimal
- /// has precision 3 and scale -2.
+ /// Scale can also be negative. For example, the unscaled value 12 with
+ /// precision 2 and scale -3 represents 12000.
Decimal128(u8, i8),
/// Exact 256-bit width decimal value with precision and scale
///
- /// * precision is the total number of digits
- /// * scale is the number of digits past the decimal
- ///
- /// For example the number 123.45 has precision 5 and scale 2.
+ /// * precision is the maximum number of digits in the unscaled value
+ /// * scale controls the position of the decimal point
///
- /// In certain situations, scale could be negative number. For
- /// negative scale, it is the number of padding 0 to the right
- /// of the digits.
+ /// The represented value is the unscaled integer multiplied by
10^{-scale}.
+ /// For example, the unscaled value 12345 with precision 5 and scale 2
+ /// represents 123.45.
///
- /// For example the number 12300 could be treated as a decimal
- /// has precision 3 and scale -2.
+ /// Scale can also be negative. For example, the unscaled value 12 with
+ /// precision 2 and scale -3 represents 12000.
Decimal256(u8, i8),
/// A Map is a logical nested type that is represented as
///
