decimal_scaled/rescale.rs
1//! Scale-changing operations for every decimal width.
2//!
3//! Each `Dxx<SCALE>` carries its scale in the type. Converting between
4//! two scales — for instance accumulating cents (`D38<2>`) into a
5//! picometre-precision running total (`D38<12>`) — requires an explicit
6//! rescale.
7//!
8//! Two surfaces, emitted on every width:
9//!
10//! - `rescale::<TARGET>()` — a `const fn` shorthand that uses the
11//! crate-default rounding mode (`HalfToEven` unless overridden by a
12//! `rounding-*` Cargo feature). Suitable for the overwhelming
13//! majority of cases.
14//! - `rescale_with::<TARGET>(mode)` — takes an explicit
15//! [`crate::rounding::RoundingMode`] for users whose accounting rules
16//! mandate a non-default rule.
17//! - `with_scale::<TARGET>()` — builder-style alias for `rescale`.
18//!
19//! Scale-up direction (target > source) is always exact: the stored
20//! integer is multiplied by `10^diff`. Scale-down direction (target <
21//! source) discards fractional digits using the requested rounding
22//! mode.
23//!
24//! Overflow on the scale-up direction is detected via `checked_mul`
25//! and panics with a clear message in both debug and release builds.
26
27use crate::core_type::{D38, D9, D18};
28
29// The rescale / rescale_with methods are emitted by
30// `crate::macros::rescale::decl_decimal_rescale!` — same macro for
31// every width; wide tiers receive it from `macros::full`.
32crate::macros::rescale::decl_decimal_rescale!(D38, i128);
33crate::macros::rescale::decl_decimal_rescale!(D18, i64);
34crate::macros::rescale::decl_decimal_rescale!(D9, i32);