Introduction to decimal128
==============================================================================
ver 0.1.2

.. image:: https://raw.githubusercontent.com/yglukhov/nimble-tag/master/nimble.png
   :height: 34
   :width: 131
   :alt: nimble
   :target: https://nimble.directory/pkg/decimal128

.. image:: https://repo.support/img/rst-banner.png
   :height: 34
   :width: 131
   :alt: repo.support
   :target: https://repo.support/gh/JohnAD/decimal128

This library creates a data type called ``Decimal128`` that allows one to
store and manipulate decimal numbers.

By storing a number as decimal digits you can avoid the ambiguity and rounding
errors encountered when converting values back-and-forth from binary floating
point numbers (base 2) and the decimal notation typically used by humans (base 10).

This is especially useful for applications that are not tolerant of such
rounding errors such as accounting, banking, and finance.

STANDARD USED
-------------

The specification specifically conforms to the IEEE 754-2008 standard that
is formally available at https://standards.ieee.org/standard/754-2008.html

A more informal copy of that spec can be seen at
http://speleotrove.com/decimal/decbits.html , though that spec only shows
the Densely Packed Binary (DPD) version of storing the coefficient. This library
supports both DPD and the unsigned binary integer storage (BID) method when
for serializing and unserializing from binary images.

The BID method is used by BSON and MongoDB.

EXAMPLES OF USE
--------------

.. code:: nim

    import decimal128

    let a = newDecimal128("4003.250")

    assert a.getPrecision == 7
    assert a.getScale == 3
    assert a.toFloat == 4003.25
    assert a.toInt == 4003
    assert $a == "4003.250"

    assert a === newDecimal128("4003250E-3")
    assert a === newDecimal128("4.003250E+3")

    # interpret a segment of data from a BSON file:
    let b = decodeDecimal128("2FF83CD7450BE3F39FA2D32880000000", encoding=ceBID)

    assert $b == "0.001234000000000000000000000000000000"
    assert b.getPrecision == 34
    assert b.getScale == 36
    assert b.toFloat == 0.001234

    assert $(newDecimal128("423.77") + newDecimal128("20.9362")) == "444.71"



Table Of Contents
=================

1. `Introduction to decimal128 <https://github.com/JohnAD/decimal128>`__
2. Appendices

    A. `decimal128 Reference <https://github.com/JohnAD/decimal128/blob/master/docs/decimal128-ref.rst>`__