## Decimals.jl: Arbitrary precision decimal floating point arithmetics in Julia

The `Decimals`

package provides basic data type and functions for arbitrary precision decimal floating point arithmetic in Julia. It supports addition, subtraction, negation, multiplication, division, and equality operations.

Why is this needed? The following code in Julia gives an answer

```
julia> 0.1 + 0.2
0.30000000000000004
```

In words, the binary floating point arithmetics implemented in computers has finite resolution - not all real numbers (even within the limits) can be expressed exactly. While many scientific and engineering fields can handle this behavior, it is not acceptable in fields like finance, where it's important to be able to trust that $0.30 is actually 30 cents, rather than 30.000000000000004 cents.

## Installation

```
julia> Pkg.add("Decimals")
```

or just `Ctrl`

+`]`

and

```
(v1.2) pkg> add Decimals
```

## Usage

```
julia> using Decimals
```

### Creating the `Decimal`

object

You can parse `Decimal`

objects from strings:

```
julia> parse(Decimal, "0.2")
Decimal(0,2,-1)
julia> parse(Decimal, "-2.5e6")
Decimal(1,25,5)
```

You can also construct `Decimal`

objects from real numbers in Julia:

```
julia> Decimal(0.1)
Decimal(0,1,-1)
julia> Decimal(-1003)
Decimal(1, 1003, 0)
```

Or can create `Decimal`

objects from either strings or numbers using `decimal`

:

```
julia> decimal("0.2")
Decimal(0,2,-1)
julia> decimal(0.1)
Decimal(0,1,-1)
julia> decimal("-2.5e6")
Decimal(1,25,5)
```

To convert back to a string or a number (float in this case):

```
julia> x = decimal("0.2");
julia> string(x)
"0.2"
julia> number(x)
0.2
```

It is also possible to call the Decimal constructor directly, by specifying the sign (`s`

), coefficient (`c`

), and exponent (`q`

):

```
julia> Decimal(1,2,-2)
```

The numerical value of a Decimal is given by `(-1)^s * c * 10^q`

. `s`

must be 0 (positive) or 1 (negative); `c`

must be non-negative; `c`

and `q`

must be integers.

### Operations

```
julia> x, y = decimal("0.2"), decimal("0.1");
```

#### Addition

```
julia> string(x + y)
"0.3"
```

#### Subtraction

```
julia> string(x - y)
"0.1"
```

#### Negation

```
julia> string(-x)
"-0.2"
```

#### Multiplication

```
julia> string(x * y)
"0.02"
```

#### Division

```
julia> string(x / y)
"2"
```

#### Inversion

```
julia> string(inv(x))
"5"
```

#### Broadcasting

```
julia> [x y] .* 2
2-element Array{Decimal,1}:
Decimal(0,1,-1)
Decimal(0,5,-2)
```

#### Equals (`==`

and `isequal`

)

```
julia> x == decimal("0.2")
true
julia> x != decimal("0.1")
true
```

#### Inequality

```
julia> x >= y
true
julia> isless(x, y)
false
```

`==`

returns true for Decimal vs. Number comparisons

```
julia> x == 0.2
true
```

#### Rounding

```
julia> round(decimal(3.1415), digits=2)
Decimal(0,314,-2)
julia> string(ans)
"3.14"
```

## Comparison with other packages

Unlike another Julia package called `DecFP`

, which aims at implementing the IEEE 754-2008 standard introducing 32, 64, and 64-bit precisions (decimal32, decimal64 and decimal128, respectively), this package allows arbitrary precision. Note, however, that in comparision with `DecFP`

, which is is essentially a wrapper for a specialized Intel® Decimal Floating-Point Math Library, the present package is more computationally demanding. If more computational efficiency is demanded, functions from `libmpdec`

library can be called directly.

The closest equivalent (and inspiration) for the present package in Python is the standard built-in `decimal`

package, which is based on General Decimal Arithmetic Specification by IBM. Since version 3.3 of Python, it is actually `libmpdec`

/`cdecimal`

that is under the hood.

## Further reading

- What Every Programmer Should Know About Floating-Point Arithmetic!?! or Why don’t my numbers add up? floating-point-gui.de.
- Decimal Floating Point https://en.wikipedia.org/wiki/Decimal_floating_point
- IEEE 754-2008 revision https://en.wikipedia.org/wiki/IEEE_754-2008_revision
- 754-2008 - IEEE Standard for Floating-Point Arithmetic https://ieeexplore.ieee.org/document/4610935 Superseeded by 754-2019 - IEEE Standard for Floating-Point Arithmetic https://ieeexplore.ieee.org/document/8766229
- Intel® Decimal Floating-Point Math Library https://software.intel.com/en-us/blogs/2008/03/06/intel-decimal-floating-point-math-library/
- General Decimal Arithmetic Specification, IBM, Version 1.70 – 7 Apr 2009 http://speleotrove.com/decimal/decarith.html
`mpdecimal`

,`libmpdec`

- C/C++ library http://www.bytereef.org/mpdecimal/index.html`decimal`

- Decimal fixed point and floating point arithmetic, module for Python https://docs.python.org/2/library/decimal.html