Struct bigdecimal::BigDecimal

source ·

pub struct BigDecimal { /* private fields */ }

Expand description

A big decimal type.

Implementations§

source §

impl BigDecimal

source

pub fn new(digits: BigInt, scale: i64) -> BigDecimal

Creates and initializes a BigDecimal.

source

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

Make a BigDecimalRef of this value

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 parse_bytes(buf: &[u8], radix: u32) -> Option<BigDecimal>

Creates and initializes a BigDecimal.

Decodes using str::from_utf8 and forwards to BigDecimal::from_str_radix. Only base-10 is supported.

§Examples

use bigdecimal::{BigDecimal, Zero};

assert_eq!(BigDecimal::parse_bytes(b"0", 10).unwrap(), BigDecimal::zero());
assert_eq!(BigDecimal::parse_bytes(b"13", 10).unwrap(), BigDecimal::from(13));

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: NonZeroU64, 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 into_bigint_and_exponent(self) -> (BigInt, i64)

Convert into 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::<num_bigint::BigInt>().unwrap(), 5);
assert_eq!(n.into_bigint_and_exponent(), expected);

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 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 normalized(&self) -> BigDecimal

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: Write>(&self, w: &mut W) -> Result

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: Write>(&self, w: &mut W) -> Result

Write bigdecimal in engineering notation to writer w

impl FromStr for BigDecimal

§

type Err = ParseBigDecimalError

The associated error which can be returned from parsing.

source §

fn from_str(s: &str) -> Result<BigDecimal, ParseBigDecimalError>

Parses a string s to return a value of this type. Read more

source §

impl Hash for BigDecimal

source §

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more

1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more

source §

impl Neg for BigDecimal

§

type Output = BigDecimal

The resulting type after applying the - operator.

source §

fn neg(self) -> BigDecimal

Performs the unary - operation. Read more

source §

fn is_one(&self) -> bool
where Self: PartialEq,

Returns true if self is equal to the multiplicative identity. Read more

source §

impl Ord for BigDecimal

source §

fn cmp(&self, other: &BigDecimal) -> Ordering

Complete ordering implementation for BigDecimal

§Example

use std::str::FromStr;

let a = bigdecimal::BigDecimal::from_str("-1").unwrap();
let b = bigdecimal::BigDecimal::from_str("1").unwrap();
assert!(a < b);
assert!(b > a);
let c = bigdecimal::BigDecimal::from_str("1").unwrap();
assert!(b >= c);
assert!(c >= b);
let d = bigdecimal::BigDecimal::from_str("10.0").unwrap();
assert!(d > c);
let e = bigdecimal::BigDecimal::from_str(".5").unwrap();
assert!(e < c);