rust-dec

libdecnumber bindings for the Rust programming language.

dec

A decimal arithmetic library providing high-level, safe bindings to libdecnumber.

# Cargo.toml
[dependencies]
dec = "0.4.9"

View documentation.

decnumber-sys

Low-level bindings to libdecnumber.

# Cargo.toml
[dependencies]
decnumber-sys = "0.1.5"

View documentation.

lib.rs:

dec is a decimal arithmetic library for Rust.

Introduction

From the Decimal Arithmetic FAQ:

Most people in the world use decimal (base 10) arithmetic. When large or small values are needed, exponents which are powers of ten are used. However, most computers have only binary (base two) arithmetic, and when exponents are used (in floating-poing numbers) they are powers of two.

Binary floating-point numbers can only approximate common decimal numbers. The value 0.1, for example, would need an infinitely recurring binary fraction. In contrast, a decimal number system can represent 0.1 exactly, as one tenth (that is, 10^-1). Consequently, binary floating-point cannot be used for financial calculations, or indeed for any calculations where the results achieved are required to match those which might be calculated by hand.

dec is an implementation of the General Decimal Arithmetic standard, which precisely describes both a limited-precision floating-point decimal arithmetic and an arbitrary precision floating-point decimal arithmetic.

The latest draft of the standard is available online at http://speleotrove.com/decimal/decarith.html. The floating-point arithmetic additionally conforms to the IEEE 754-2008 specification, but this specification is not freely available.

Details

dec is a safe Rust API atop the C reference implementation, libdecnumber. Unsafe C bindings to libdecnumber are available in the decnumber-sys crate.

The main types exposed by this library are as follows:

• Decimal32, a 32-bit decimal floating-point representation which provides 7 decimal digits of precision in a compressed format. This type is intended for storage and interchange only and so does not support any arithmetic functions.

• Decimal64, a 64-bit decimal floating-point representation which provides 16 decimal digits of precision in a compressed format along with various arithmetic functions.

• Decimal128, a 128-bit decimal floating-point representation which provides 34 decimal digits of precision in a compressed format along with various arithmetic functions.

• Decimal, a decimal representation whose precision is configurable via its generic N parameter.

• Context, which hosts most of the actual functions on the above types. A context configures the behavior of the various operations (e.g., rounding mode) and accumulates exceptional conditions (e.g., overflow).

Examples

The following example demonstrates the basic usage of the library:

use dec::Decimal128;

let x: Decimal128 = ".1".parse()?;
let y: Decimal128 = ".2".parse()?;
let z: Decimal128 = ".3".parse()?;

assert_eq!(x + y, z);
assert_eq!((x + y + z).to_string(), "0.6");