# Decimal

A Decimal implementation written in pure Rust suitable for financial calculations that require significant integral and fractional digits with no round-off errors.

The binary representation consists of a 96 bit integer number, a scaling factor used to specify the decimal fraction and a 1 bit sign. Because of this representation, trailing zeros are preserved and may be exposed when in string form. These can be truncated using the `normalize` or `round_dp` functions.

## Getting started

To get started, add `rust_decimal` and optionally `rust_decimal_macros` to your `Cargo.toml`:

``````[dependencies]
rust_decimal = "1.20"
rust_decimal_macros = "1.20"``````

## Usage

Decimal numbers can be created in a few distinct ways. The easiest and most optimal method of creating a Decimal is to use the procedural macro within the `rust_decimal_macros` crate:

``````// Procedural macros need importing directly
use rust_decimal_macros::dec;

let number = dec!(-1.23);
assert_eq!("-1.23", number.to_string());``````

Alternatively you can also use one of the Decimal number convenience functions:

``````// Using the prelude can help importing trait based functions (e.g. core::str::FromStr).
use rust_decimal::prelude::*;

// Using an integer followed by the decimal points
let scaled = Decimal::new(202, 2);
assert_eq!("2.02", scaled.to_string());

// From a string representation
let from_string = Decimal::from_str("2.02").unwrap();
assert_eq!("2.02", from_string.to_string());

// From a string representation in a different base
assert_eq!("65535", from_string_base16.to_string());

// Using the `Into` trait
let my_int: Decimal = 3i32.into();
assert_eq!("3", my_int.to_string());

// Using the raw decimal representation
let pi = Decimal::from_parts(1102470952, 185874565, 1703060790, false, 28);
assert_eq!("3.1415926535897932384626433832", pi.to_string());``````

Once you have instantiated your `Decimal` number you can perform calculations with it just like any other number:

``````use rust_decimal::prelude::*;

let amount = Decimal::from_str("25.12").unwrap();
let tax = Decimal::from_str("0.085").unwrap();
let total = amount + (amount * tax).round_dp(2);
assert_eq!(total.to_string(), "27.26");``````

## Features

Behavior / Functionality

Database

Serde

### `c-repr`

Forces `Decimal` to use `[repr(C)]`. The corresponding target layout is 128 bit aligned.

### `db-postgres`

This feature enables a PostgreSQL communication module. It allows for reading and writing the `Decimal` type by transparently serializing/deserializing into the `NUMERIC` data type within PostgreSQL.

### `db-tokio-postgres`

Enables the tokio postgres module allowing for async communication with PostgreSQL.

### `db-diesel-postgres`

Enable `diesel` PostgreSQL support.

### `db-diesel-mysql`

Enable `diesel` MySQL support.

### `legacy-ops`

As of `1.10` the algorithms used to perform basic operations have changed which has benefits of significant speed improvements. To maintain backwards compatibility this can be opted out of by enabling the `legacy-ops` feature.

### `maths`

The `maths` feature enables additional complex mathematical functions such as `pow`, `ln`, `enf`, `exp` etc. Documentation detailing the additional functions can be found on the `MathematicalOps` trait.

Please note that `ln` and `log10` will panic on invalid input with `checked_ln` and `checked_log10` the preferred functions to curb against this. When the `maths` feature was first developed the library would return `0` on invalid input. To re-enable this non-panicking behavior, please use the feature: `maths-nopanic`.

### `rocket-traits`

Enable support for Rocket forms by implementing the `FromFormField` trait.

### `rust-fuzz`

Enable `rust-fuzz` support by implementing the `Arbitrary` trait.

### `serde-float`

Note: it is recommended to use the `serde-with-*` features for greater control. This allows configurability at the data level.

Enable this so that JSON serialization of `Decimal` types are sent as a float instead of a string (default).

e.g. with this turned on, JSON serialization would output:

``````{
"value": 1.234
}``````

### `serde-str`

Note: it is recommended to use the `serde-with-*` features for greater control. This allows configurability at the data level.

This is typically useful for `bincode` or `csv` like implementations.

Since `bincode` does not specify type information, we need to ensure that a type hint is provided in order to correctly be able to deserialize. Enabling this feature on its own will force deserialization to use `deserialize_str` instead of `deserialize_any`.

If, for some reason, you also have `serde-float` enabled then this will use `deserialize_f64` as a type hint. Because converting to `f64` loses precision, it's highly recommended that you do NOT enable this feature when working with `bincode`. That being said, this will only use 8 bytes so is slightly more efficient in terms of storage size.

### `serde-arbitrary-precision`

Note: it is recommended to use the `serde-with-*` features for greater control. This allows configurability at the data level.

This is used primarily with `serde_json` and consequently adds it as a "weak dependency". This supports the `arbitrary_precision` feature inside `serde_json` when parsing decimals.

This is recommended when parsing "float" looking data as it will prevent data loss.

### `serde-with-float`

Enable this to access the module for serialising `Decimal` types to a float. This can be use in `struct` definitions like so:

``````#[derive(Serialize, Deserialize)]
pub struct FloatExample {
#[serde(with = "rust_decimal::serde::float")]
value: Decimal,
}``````

### `serde-with-str`

Enable this to access the module for serialising `Decimal` types to a `String`. This can be use in `struct` definitions like so:

``````#[derive(Serialize, Deserialize)]
pub struct StrExample {
#[serde(with = "rust_decimal::serde::str")]
value: Decimal,
}``````

### `serde-with-arbitrary-precision`

Enable this to access the module for serialising `Decimal` types to a `String`. This can be use in `struct` definitions like so:

``````#[derive(Serialize, Deserialize)]
pub struct ArbitraryExample {
#[serde(with = "rust_decimal::serde::arbitrary_precision")]
value: Decimal,
}``````

### `std`

Enable `std` library support. This is enabled by default, however in the future will be opt in. For now, to support `no_std` libraries, this crate can be compiled with `--no-default-features`.

## Minimum Rust Compiler Version

The current minimum compiler version is `1.51.0` which was released on `2021-03-25` and included support for "const generics".

### Updating the minimum supported version

This library maintains support for rust compiler versions that are 5 minor versions away from the current stable rust compiler version. For example, if the current stable compiler version is `1.50.0` then we will guarantee support up to and including `1.45.0`. Of note, we will only update the minimum supported version if and when required.

# Rust Decimal

## A Decimal Implementation written in pure Rust suitable for financial calculations.

### Rust Decimal Info

⭐ Stars 542
🔗 Homepage docs.rs
🔗 Source Code github.com
🕒 Last Update 4 months ago
🕒 Created 6 years ago
🐞 Open Issues 18
➗ Star-Issue Ratio 30
😎 Author paupino