Crate dec

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");

Structs

• Context
  A context for performing decimal operations.
• Decimal
  An arbitrary-precision decimal number.
• Decimal32
  A 32-bit decimal floating-point number.
• Decimal64
  A 64-bit decimal floating-point number.
• Decimal128
  A 128-bit decimal floating-point number.
• InvalidExponentError
  An error indicating that a minimum exponent or maximum exponent is not valid for a given context.
• InvalidPrecisionError
  An error indicating that a precision is not valid for a given context.
• OrderedDecimal
  A wrapper for a decimal number that provides an implementation of Ord and Hash.
• ParseDecimalError
  An error indicating that a string is not a valid decimal number.
• Status
  Represents exceptional conditions resulting from operations on decimal numbers.
• TryFromDecimalError
  An error indicating that a value cannot be cast to a primitive type.

Enums

• Class
  The class of a decimal number.
• Rounding
  Algorithms for rounding decimal numbers.