This crate provides a fast implementation of Decimal fixed-point arithmetics. It is targeted at typical business applications, dealing with numbers representing quantities, money and the like, not at scientific computations, for which the accuracy of floating point math is - in most cases - sufficient.

Objectives

At the binary level a Decimal number is represented as a coefficient (stored as an i128 value) combined with a value specifying the number of fractional decimal digits (stored as a u8). The latter is limited to a value given by the constant MAX_N_FRAC_DIGITS = 18.

Status

Work in progess, but most of the API is stable.

Getting started

Add fpdec to your Cargo.toml:

toml [dependencies] fpdec = "0.8"

Usage

A Decimal number can be created in different ways.

The easiest method is to use the procedural macro Dec:

```rust

use fpdec::{Dec, Decimal};

let d = Dec!(-17.5); asserteq!(d.tostring(), "-17.5"); ```

Alternatively you can convert an integer, a float or a string to a Decimal:

```rust

use fpdec::Decimal;

let d = Decimal::from(297i32); asserteq!(d.to_string(), "297"); ```

```rust

use fpdec::{Decimal, DecimalError};

use core::convert::TryFrom;

let d = Decimal::tryfrom(83.25f64)?; asserteq!(d.tostring(), "83.25");

Ok::<(), DecimalError>(())

```

```rust

use fpdec::{Decimal, ParseDecimalError};

use core::str::FromStr;

let d = Decimal::fromstr("38.2070")?; asserteq!(d.to_string(), "38.2070");

Ok::<(), ParseDecimalError>(())

```

The sign of a Decimal can be inverted using the unary minus operator and a Decimal instance can be compared to other instances of type Decimal or all basic types of integers (besides u128):

```rust

use fpdec::{Dec, Decimal};

let x = Dec!(129.24); let y = -x; asserteq!(y.tostring(), "-129.24"); assert!(-129i64 > y); let z = -y; asserteq!(x, z); let z = Dec!(0.00097); assert!(x > z); assert!(y <= z); assert!(z != 7u32); assert!(7u32 == Dec!(7.00)); ```

Decimal supports all five binary numerical operators +, -, *, /, and %, with two Decimals or with a Decimal and a basic integer (besides u128):

```rust

use fpdec::{Dec, Decimal};

let x = Dec!(17.5); let y = Dec!(6.40); let z = x + y; asserteq!(z.tostring(), "23.90"); let z = x - y; asserteq!(z.tostring(), "11.10"); let z = x * y; asserteq!(z.tostring(), "112.000"); let z = x / y; asserteq!(z.tostring(), "2.734375"); let z = x % y; asserteq!(z.tostring(), "4.70"); ```

```rust

use fpdec::{Dec, Decimal};

let x = Dec!(17.5); let y = -5i64; let z = x + y; asserteq!(z.tostring(), "12.5"); let z = x - y; asserteq!(z.tostring(), "22.5"); let z = y * x; asserteq!(z.tostring(), "-87.5"); let z = x / y; asserteq!(z.tostring(), "-3.5"); let z = x % y; asserteq!(z.tostring(), "2.5"); `` The results of Multiplication or Division are not exact in any case. If the number of fractional decimal digits of the exact result would exceed MAXNFRACDIGITS` fractional decimal digits, the result given is rounded to fit this limit.

```rust

use fpdec::{Dec, Decimal};

let x = Dec!(1e-10); let y = Dec!(75e-9); let z = x * y; asserteq!(z.tostring(), "0.000000000000000008"); let x = Dec!(1.); let y = Dec!(3.); let z = x / y; asserteq!(z.tostring(), "0.333333333333333333"); ```

All these binary numeric operators panic if the result is not representable as a Decimal according to the constraints stated above. In addition, there are functions implementing "checked" variants of the operators which return Option::None instead of panicking.

For Multiplication and Division there are also functions which return a result rounded to a given number of fractional digits:

```rust

use fpdec::{Dec, Decimal, DivRounded, MulRounded};

let x = Dec!(17.5); let y = Dec!(6.47); let z: Decimal = x.mulrounded(y, 1); asserteq!(z.tostring(), "113.2"); let z: Decimal = x.divrounded(y, 3); asserteq!(z.tostring(), "2.705"); ```

Crate features

By default, only the feature std is enabled.

Ecosystem

Optional dependencies