Struct sqlx::types::Decimal[−]

pub struct Decimal { /* fields omitted */ }

Decimal represents a 128 bit representation of a fixed-precision decimal number. The finite set of values of type Decimal are of the form m / 10^e, where m is an integer such that -2⁹⁶ < m < 2⁹⁶, and e is an integer between 0 and 28 inclusive.

Implementations

`impl Decimal`

`pub fn new(num: i64, scale: u32) -> Decimal`

Returns a Decimal with a 64 bit m representation and corresponding e scale.

Arguments

num - An i64 that represents the m portion of the decimal number
scale - A u32 representing the e portion of the decimal number.

Example

use rust_decimal::Decimal;

let pi = Decimal::new(3141, 3);
assert_eq!(pi.to_string(), "3.141");

`pub fn from_i128_with_scale(num: i128, scale: u32) -> Decimal`

Creates a Decimal using a 128 bit signed m representation and corresponding e scale.

Arguments

num - An i128 that represents the m portion of the decimal number
scale - A u32 representing the e portion of the decimal number.

Example

use rust_decimal::Decimal;

let pi = Decimal::from_i128_with_scale(3141i128, 3);
assert_eq!(pi.to_string(), "3.141");

`pub const fn from_parts( lo: u32, mid: u32, hi: u32, negative: bool, scale: u32 ) -> Decimal`

Returns a Decimal using the instances constituent parts.

Arguments

lo - The low 32 bits of a 96-bit integer.
mid - The middle 32 bits of a 96-bit integer.
hi - The high 32 bits of a 96-bit integer.
negative - true to indicate a negative number.
scale - A power of 10 ranging from 0 to 28.

Example

use rust_decimal::Decimal;

let pi = Decimal::from_parts(1102470952, 185874565, 1703060790, false, 28);
assert_eq!(pi.to_string(), "3.1415926535897932384626433832");

`pub fn from_scientific(value: &str) -> Result<Decimal, Error>`

Returns a Result which if successful contains the Decimal constitution of the scientific notation provided by value.

Arguments

value - The scientific notation of the Decimal.

Example

use rust_decimal::Decimal;

let value = Decimal::from_scientific("9.7e-7").unwrap();
assert_eq!(value.to_string(), "0.00000097");

`pub const fn scale(&self) -> u32`

Returns the scale of the decimal number, otherwise known as e.

Example

use rust_decimal::Decimal;

let num = Decimal::new(1234, 3);
assert_eq!(num.scale(), 3u32);

`pub fn set_sign(&mut self, positive: bool)`

👎 Deprecated since 1.4.0:

please use set_sign_positive instead

An optimized method for changing the sign of a decimal number.

Arguments

positive: true if the resulting decimal should be positive.

Example

use rust_decimal::Decimal;

let mut one = Decimal::new(1, 0);
one.set_sign(false);
assert_eq!(one.to_string(), "-1");

`pub fn set_sign_positive(&mut self, positive: bool)`

An optimized method for changing the sign of a decimal number.

Arguments

positive: true if the resulting decimal should be positive.

Example

use rust_decimal::Decimal;

let mut one = Decimal::new(1, 0);
one.set_sign_positive(false);
assert_eq!(one.to_string(), "-1");

`pub fn set_sign_negative(&mut self, negative: bool)`

An optimized method for changing the sign of a decimal number.

Arguments

negative: true if the resulting decimal should be negative.

Example

use rust_decimal::Decimal;

let mut one = Decimal::new(1, 0);
one.set_sign_negative(true);
assert_eq!(one.to_string(), "-1");

`pub fn set_scale(&mut self, scale: u32) -> Result<(), Error>`

An optimized method for changing the scale of a decimal number.

Arguments

scale: the new scale of the number

Example

use rust_decimal::Decimal;

let mut one = Decimal::new(1, 0);
one.set_scale(5);
assert_eq!(one.to_string(), "0.00001");

`pub fn rescale(&mut self, scale: u32)`

Modifies the Decimal to the given scale, attempting to do so without changing the underlying number itself.

Note that setting the scale to something less then the current Decimals scale will cause the newly created Decimal to have some rounding. Scales greater than the maximum precision supported by Decimal will be automatically rounded to Decimal::MAX_PRECISION. Rounding leverages the half up strategy.

Arguments

scale: The scale to use for the new Decimal number.

Example

use rust_decimal::Decimal;

let mut number = Decimal::new(1_123, 3);
number.rescale(6);
assert_eq!(number, Decimal::new(1_123_000, 6));
let mut round = Decimal::new(145, 2);
round.rescale(1);
assert_eq!(round, Decimal::new(15, 1));

`pub const fn serialize(&self) -> [u8; 16]`

Returns a serialized version of the decimal number. The resulting byte array will have the following representation:

Bytes 1-4: flags
Bytes 5-8: lo portion of m
Bytes 9-12: mid portion of m
Bytes 13-16: high portion of m

`pub const fn deserialize(bytes: [u8; 16]) -> Decimal`

Deserializes the given bytes into a decimal number. The deserialized byte representation must be 16 bytes and adhere to the followign convention:

Bytes 1-4: flags
Bytes 5-8: lo portion of m
Bytes 9-12: mid portion of m
Bytes 13-16: high portion of m

`pub fn is_negative(&self) -> bool`

👎 Deprecated since 0.6.3:

please use is_sign_negative instead

Returns true if the decimal is negative.

`pub fn is_positive(&self) -> bool`

👎 Deprecated since 0.6.3:

please use is_sign_positive instead

Returns true if the decimal is positive.

`pub const fn is_sign_negative(&self) -> bool`

Returns true if the sign bit of the decimal is negative.

`pub const fn is_sign_positive(&self) -> bool`

Returns true if the sign bit of the decimal is positive.

`pub const fn min_value() -> Decimal`

Returns the minimum possible number that Decimal can represent.

`pub const fn max_value() -> Decimal`

Returns the maximum possible number that Decimal can represent.

`pub fn trunc(&self) -> Decimal`

Returns a new Decimal integral with no fractional portion. This is a true truncation whereby no rounding is performed.

Example

use rust_decimal::Decimal;

let pi = Decimal::new(3141, 3);
let trunc = Decimal::new(3, 0);
// note that it returns a decimal
assert_eq!(pi.trunc(), trunc);

`pub fn fract(&self) -> Decimal`

Returns a new Decimal representing the fractional portion of the number.

Example

use rust_decimal::Decimal;

let pi = Decimal::new(3141, 3);
let fract = Decimal::new(141, 3);
// note that it returns a decimal
assert_eq!(pi.fract(), fract);

`pub fn abs(&self) -> Decimal`

Computes the absolute value of self.

Example

use rust_decimal::Decimal;

let num = Decimal::new(-3141, 3);
assert_eq!(num.abs().to_string(), "3.141");

`pub fn floor(&self) -> Decimal`

Returns the largest integer less than or equal to a number.

Example

use rust_decimal::Decimal;

let num = Decimal::new(3641, 3);
assert_eq!(num.floor().to_string(), "3");

`pub fn ceil(&self) -> Decimal`

Returns the smallest integer greater than or equal to a number.

Example

use rust_decimal::Decimal;

let num = Decimal::new(3141, 3);
assert_eq!(num.ceil().to_string(), "4");
let num = Decimal::new(3, 0);
assert_eq!(num.ceil().to_string(), "3");

`pub fn max(self, other: Decimal) -> Decimal`

Returns the maximum of the two numbers.

use rust_decimal::Decimal;

let x = Decimal::new(1, 0);
let y = Decimal::new(2, 0);
assert_eq!(y, x.max(y));

`pub fn min(self, other: Decimal) -> Decimal`

Returns the minimum of the two numbers.

use rust_decimal::Decimal;

let x = Decimal::new(1, 0);
let y = Decimal::new(2, 0);
assert_eq!(x, x.min(y));

`pub fn normalize(&self) -> Decimal`

Strips any trailing zero's from a Decimal and converts -0 to 0.

Example

use rust_decimal::Decimal;

let number = Decimal::new(3100, 3);
// note that it returns a decimal, without the extra scale
assert_eq!(number.normalize().to_string(), "3.1");

`pub fn round(&self) -> Decimal`

Returns a new Decimal number with no fractional portion (i.e. an integer). Rounding currently follows "Bankers Rounding" rules. e.g. 6.5 -> 6, 7.5 -> 8

Example

use rust_decimal::Decimal;

// Demonstrating bankers rounding...
let number_down = Decimal::new(65, 1);
let number_up   = Decimal::new(75, 1);
assert_eq!(number_down.round().to_string(), "6");
assert_eq!(number_up.round().to_string(), "8");

`pub fn round_dp_with_strategy( &self, dp: u32, strategy: RoundingStrategy ) -> Decimal`

Returns a new Decimal number with the specified number of decimal points for fractional portion. Rounding is performed using the provided [RoundingStrategy]

Arguments

dp: the number of decimal points to round to.
strategy: the [RoundingStrategy] to use.

Example

use rust_decimal::{Decimal, RoundingStrategy};
use core::str::FromStr;

let tax = Decimal::from_str("3.4395").unwrap();
assert_eq!(tax.round_dp_with_strategy(2, RoundingStrategy::RoundHalfUp).to_string(), "3.44");

`pub fn round_dp(&self, dp: u32) -> Decimal`

Returns a new Decimal number with the specified number of decimal points for fractional portion. Rounding currently follows "Bankers Rounding" rules. e.g. 6.5 -> 6, 7.5 -> 8

Arguments

dp: the number of decimal points to round to.

Example

use rust_decimal::Decimal;
use core::str::FromStr;

let pi = Decimal::from_str("3.1415926535897932384626433832").unwrap();
assert_eq!(pi.round_dp(2).to_string(), "3.14");

`pub const fn unpack(&self) -> UnpackedDecimal`

Convert Decimal to an internal representation of the underlying struct. This is useful for debugging the internal state of the object.

Important Disclaimer

This is primarily intended for library maintainers. The internal representation of a Decimal is considered "unstable" for public use.

Example

use rust_decimal::Decimal;
use core::str::FromStr;

let pi = Decimal::from_str("3.1415926535897932384626433832").unwrap();
assert_eq!(format!("{:?}", pi), "3.1415926535897932384626433832");
assert_eq!(format!("{:?}", pi.unpack()), "UnpackedDecimal { \
    is_negative: false, scale: 28, hi: 1703060790, mid: 185874565, lo: 1102470952 \
}");

`pub fn checked_add(self, other: Decimal) -> Option<Decimal>`

Checked addition. Computes self + other, returning None if overflow occurred.

`pub fn checked_sub(self, other: Decimal) -> Option<Decimal>`

Checked subtraction. Computes self - other, returning None if overflow occurred.

`pub fn checked_mul(self, other: Decimal) -> Option<Decimal>`

Checked multiplication. Computes self * other, returning None if overflow occurred.

`pub fn checked_div(self, other: Decimal) -> Option<Decimal>`

Checked division. Computes self / other, returning None if other == 0.0 or the division results in overflow.

`pub fn checked_rem(self, other: Decimal) -> Option<Decimal>`

Checked remainder. Computes self % other, returning None if other == 0.0.

`pub fn exp(&self) -> Decimal`

The estimated exponential function, e^x, rounded to 8 decimal places. Stops calculating when it is within tolerance is roughly 0.000002 in order to prevent multiplication overflow.

`pub fn exp_with_tolerance(&self, tolerance: Decimal) -> Decimal`

The estimated exponential function, e^x, rounded to 8 decimal places. Stops calculating when it is within tolerance. Multiplication overflows are likely if you are not careful with the size of tolerance. It is recommended to set the tolerance larger for larger numbers and smaller for smaller numbers to avoid multiplication overflow.