1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

// Copyright Materialize, Inc. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License in the LICENSE file at the
// root of this repository, or online at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! dec is a decimal arithmetic library for Rust.
//!
//! # Introduction
//!
//! From the [Decimal Arithmetic FAQ][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<sup>-1</sup>). 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. This type requires Rust's `min_const_generics`
//!    feature, which is scheduled to stabilize in Rust 1.51.0. This type is
//!    only available when the `arbitrary-precision` feature is activated.
//!
//!  * [`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 std::error::Error;
//! 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");
//!
//! # Ok::<_, Box<dyn Error>>(())
//! ```
//!
//! [faq]: http://speleotrove.com/decimal/decifaq.html
//! [libdecnumber]: http://speleotrove.com/decimal/decarith.html
//! [decnumber-sys]: https://docs.rs/decnumber-sys

#![deny(missing_debug_implementations, missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

mod context;
#[macro_use]
mod conv;
#[cfg(feature = "arbitrary-precision")]
#[cfg_attr(docsrs, doc(cfg(feature = "arbitrary-precision")))]
mod decimal;
mod decimal128;
mod decimal32;
mod decimal64;
mod error;
mod ordered;
#[cfg(tests)]
mod tests;

pub use context::{Class, Context, Rounding, Status};
#[cfg(feature = "arbitrary-precision")]
pub use decimal::Decimal;
pub use decimal128::Decimal128;
pub use decimal32::Decimal32;
pub use decimal64::Decimal64;
pub use error::{InvalidExponentError, InvalidPrecisionError, ParseDecimalError};
pub use ordered::OrderedDecimal;