Struct Decimal

Source

#[repr(transparent)]
pub struct Decimal(pub BigDecimal);

Tuple Fields§

§0: BigDecimal

Implementations§

Source §

pub fn negate(self) -> Self

Methods from Deref<Target = BigDecimalInner>§

Source

pub fn to_ref(&self) -> BigDecimalRef<'_>

Make a BigDecimalRef of this value

Source

pub fn decimal_digit_count(&self) -> u64

Count of decimal digits

Zero is considered to be one digit.

Source

pub fn order_of_magnitude(&self) -> i64

Position of most significant digit of this decimal

Equivalent to the exponent when written in scientific notation, or ⌊log10(n)⌋.

The order of magnitude of 0 is 0.

Source

pub fn fractional_digit_count(&self) -> i64

Returns the scale of the BigDecimal, the total number of digits to the right of the decimal point (including insignificant leading zeros)

§Examples

use bigdecimal::BigDecimal;
use std::str::FromStr;

let a = BigDecimal::from(12345);  // No fractional part
let b = BigDecimal::from_str("123.45").unwrap();  // Fractional part
let c = BigDecimal::from_str("0.0000012345").unwrap();  // Completely fractional part
let d = BigDecimal::from_str("5e9").unwrap();  // Negative-fractional part

assert_eq!(a.fractional_digit_count(), 0);
assert_eq!(b.fractional_digit_count(), 2);
assert_eq!(c.fractional_digit_count(), 10);
assert_eq!(d.fractional_digit_count(), -9);

Source

pub fn with_scale(&self, new_scale: i64) -> BigDecimal

Return a new BigDecimal object equivalent to self, with internal scaling set to the number specified. If the new_scale is lower than the current value (indicating a larger power of 10), digits will be dropped (as precision is lower)

Source

pub fn with_scale_round(&self, new_scale: i64, mode: RoundingMode) -> BigDecimal

Return a new BigDecimal after shortening the digits and rounding


let n: BigDecimal = "129.41675".parse().unwrap();

assert_eq!(n.with_scale_round(2, RoundingMode::Up),  "129.42".parse().unwrap());
assert_eq!(n.with_scale_round(-1, RoundingMode::Down),  "120".parse().unwrap());
assert_eq!(n.with_scale_round(4, RoundingMode::HalfEven),  "129.4168".parse().unwrap());

Source

pub fn with_prec(&self, prec: u64) -> BigDecimal

Return a new BigDecimal object with precision set to new value


let n: BigDecimal = "129.41675".parse().unwrap();

assert_eq!(n.with_prec(2),  "130".parse().unwrap());

let n_p12 = n.with_prec(12);
let (i, scale) = n_p12.as_bigint_and_exponent();
assert_eq!(n_p12, "129.416750000".parse().unwrap());
assert_eq!(i, 129416750000_u64.into());
assert_eq!(scale, 9);

Source

pub fn with_precision_round( &self, prec: NonZero<u64>, round: RoundingMode, ) -> BigDecimal

Return this BigDecimal with the given precision, rounding if needed

Source

pub fn sign(&self) -> Sign

Return the sign of the BigDecimal as num::bigint::Sign.


fn sign_of(src: &str) -> Sign {
   let n: BigDecimal = src.parse().unwrap();
   n.sign()
}

assert_eq!(sign_of("-1"), Sign::Minus);
assert_eq!(sign_of("0"),  Sign::NoSign);
assert_eq!(sign_of("1"),  Sign::Plus);

Source

pub fn as_bigint_and_exponent(&self) -> (BigInt, i64)

Return the internal big integer value and an exponent. Note that a positive exponent indicates a negative power of 10.

§Examples

use bigdecimal::{BigDecimal, num_bigint::BigInt};

let n: BigDecimal = "1.23456".parse().unwrap();
let expected = ("123456".parse::<BigInt>().unwrap(), 5);
assert_eq!(n.as_bigint_and_exponent(), expected);

Source

pub fn as_bigint_and_scale(&self) -> (Cow<'_, BigInt>, i64)

Return digits as borrowed Cow of integer digits, and its scale

Scale is number of digits after the decimal point, can be negative.

Source

pub fn digits(&self) -> u64

Number of digits in the non-scaled integer representation

Source

pub fn abs(&self) -> BigDecimal

Compute the absolute value of number

let n: BigDecimal = "123.45".parse().unwrap();
assert_eq!(n.abs(), "123.45".parse().unwrap());

let n: BigDecimal = "-123.45".parse().unwrap();
assert_eq!(n.abs(), "123.45".parse().unwrap());

Source

pub fn double(&self) -> BigDecimal

Multiply decimal by 2 (efficiently)

let n: BigDecimal = "123.45".parse().unwrap();
assert_eq!(n.double(), "246.90".parse().unwrap());

Source

pub fn half(&self) -> BigDecimal

Divide decimal by 2 (efficiently)

Note: If the last digit in the decimal is odd, the precision will increase by 1

let n: BigDecimal = "123.45".parse().unwrap();
assert_eq!(n.half(), "61.725".parse().unwrap());

Source

pub fn square(&self) -> BigDecimal

Square a decimal: x²

No rounding or truncating of digits; this is the full result of the squaring operation.

Note: doubles the scale of bigdecimal, which might lead to accidental exponential-complexity if used in a loop.

let n: BigDecimal = "1.1156024145937225657484".parse().unwrap();
assert_eq!(n.square(), "1.24456874744734405154288399835406316085210256".parse().unwrap());

let n: BigDecimal = "-9.238597585E+84".parse().unwrap();
assert_eq!(n.square(), "8.5351685337567832225E+169".parse().unwrap());

Source

pub fn cube(&self) -> BigDecimal

Cube a decimal: x³

No rounding or truncating of digits; this is the full result of the cubing operation.

Note: triples the scale of bigdecimal, which might lead to accidental exponential-complexity if used in a loop.

let n: BigDecimal = "1.1156024145937225657484".parse().unwrap();
assert_eq!(n.cube(), "1.388443899780141911774491376394890472130000455312878627147979955904".parse().unwrap());

let n: BigDecimal = "-9.238597585E+84".parse().unwrap();
assert_eq!(n.cube(), "-7.88529874035334084567570176625E+254".parse().unwrap());

Source

pub fn powi(&self, exp: i64) -> BigDecimal

Raises the number to an integer power

Uses default-precision, set from build time environment variable

let n: BigDecimal = 2.into();
assert_eq!(n.powi(3000000000), "9.816204233623505350831385407878283564899139328691307267002649220552261820356883420275966921502700387e903089986".parse().unwrap());

Source

pub fn powi_with_context(&self, exp: i64, ctx: &Context) -> BigDecimal

Raises the number to an integer power, using context for precision and rounding

Source

pub fn sqrt(&self) -> Option<BigDecimal>

Take the square root of the number

Uses default-precision, set from build time environment variable

If the value is < 0, None is returned

let n: BigDecimal = "1.1156024145937225657484".parse().unwrap();
assert_eq!(n.sqrt().unwrap(), "1.056220817156016181190291268045893004363809142172289919023269377496528394924695970851558013658193913".parse().unwrap());

let n: BigDecimal = "-9.238597585E+84".parse().unwrap();
assert_eq!(n.sqrt(), None);

Source

pub fn sqrt_with_context(&self, ctx: &Context) -> Option<BigDecimal>

Take the square root of the number, using context for precision and rounding

Source

pub fn cbrt(&self) -> BigDecimal

Take the cube root of the number, using default context

Source

pub fn cbrt_with_context(&self, ctx: &Context) -> BigDecimal

Take cube root of self, using properties of context

Source

pub fn inverse(&self) -> BigDecimal

Compute the reciprical of the number: x^-1

Source

pub fn inverse_with_context(&self, ctx: &Context) -> BigDecimal

Return inverse of self, rounding with ctx

Source

pub fn mul_with_context<'a, T>(&'a self, rhs: T, ctx: &Context) -> BigDecimal
where T: Into<BigDecimalRef<'a>>,

Multiply by rhs, limiting precision using context

Source

pub fn round(&self, round_digits: i64) -> BigDecimal

Return given number rounded to ‘round_digits’ precision after the decimal point, using default rounding mode

Default rounding mode is HalfEven, but can be configured at compile-time by the environment variable: RUST_BIGDECIMAL_DEFAULT_ROUNDING_MODE (or by patching build.rs )

Source

pub fn is_integer(&self) -> bool

Return true if this number has zero fractional part (is equal to an integer)

Source

pub fn is_one_quickcheck(&self) -> Option<bool>

Try to determine if decimal is 1.0, without allocating

Source

pub fn exp(&self) -> BigDecimal

Evaluate the natural-exponential function e^x

Source

pub fn normalized(&self) -> BigDecimal

Source

pub fn to_plain_string(&self) -> String

Create string of decimal in standard decimal notation.

Unlike standard formatter, this never prints the number in scientific notation.

§Panics

If the magnitude of the exponent is very large, this may cause out-of-memory errors, or overflowing panics.

§Examples

let n: BigDecimal = "123.45678".parse().unwrap();
assert_eq!(&n.to_plain_string(), "123.45678");

let n: BigDecimal = "1e-10".parse().unwrap();
assert_eq!(&n.to_plain_string(), "0.0000000001");

Source

pub fn write_plain_string<W>(&self, wtr: &mut W) -> Result<(), Error>
where W: Write,

Write decimal value in decimal notation to the writer object.

§Panics

If the exponent is very large or very small, the number of this will print that many trailing or leading zeros. If exabytes, this will likely panic.

Source

pub fn to_scientific_notation(&self) -> String

Create string of this bigdecimal in scientific notation

let n = BigDecimal::from(12345678);
assert_eq!(&n.to_scientific_notation(), "1.2345678e7");

Source

pub fn write_scientific_notation<W>(&self, w: &mut W) -> Result<(), Error>
where W: Write,

Write bigdecimal in scientific notation to writer w

Source

pub fn to_engineering_notation(&self) -> String

Create string of this bigdecimal in engineering notation

Engineering notation is scientific notation with the exponent coerced to a multiple of three

let n = BigDecimal::from(12345678);
assert_eq!(&n.to_engineering_notation(), "12.345678e6");

Source

pub fn write_engineering_notation<W>(&self, w: &mut W) -> Result<(), Error>
where W: Write,

Write bigdecimal in engineering notation to writer w

Trait Implementations§

Source §

impl Clone for Decimal

Source §

fn clone(&self) -> Decimal

Returns a duplicate of the value. Read more

1.0.0§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source §

impl Debug for Decimal

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Source §

impl Default for Decimal

Source §

fn default() -> Self

Returns the “default value” for a type. Read more

Source §

impl Deref for Decimal

Source §

type Target = BigDecimal

The resulting type after dereferencing.

Source §

fn deref(&self) -> &Self::Target

Dereferences the value.

Source §

impl<'de> Deserialize<'de> for Decimal

Source §

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more

Source §

impl Display for Decimal

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Source §