Module Decimal

This is an implementation of decimal floating point arithmetic based on the General Decimal Arithmetic Specification:

http://speleotrove.com/decimal/decarith.html

and IEEE standard 854-1987:

http://en.wikipedia.org/wiki/IEEE_854-1987

Decimal floating point has finite precision with arbitrarily large bounds. The purpose of this module is to support arithmetic using familiar "schoolhouse" rules and to avoid some of the tricky representation issues associated with binary floating point. The package is especially useful for financial applications or for contexts where users have expectations that are at odds with binary floating point (for instance, in binary floating point, 1.00 mod 0.1 gives 0.09999999999999995 instead of 0.0; Decimal.(of_string "1.00" mod of_string "0.1") returns the expected "0.00").

module Signal : sig ... end

Signals are used to control the behaviour of the decimal functions under exceptional conditions.

module Context : sig ... end

Settings that control precision, rounding mode, exceptional behaviour, etc.

type t

A decimal floating-point number. All operations are done in radix (base) 10.

include Stdlib.Map.OrderedType with type t := t
val compare : t -> t -> int
include Stdlib.Hashtbl.HashedType with type t := t
val equal : t -> t -> bool
val hash : t -> int
val infinity : t
val neg_infinity : t
val nan : t
val one : t
val zero : t
val is_nan : t -> bool
val is_normal : ?context:Context.t -> t -> bool
val is_finite : t -> bool
val is_infinite : t -> bool
val is_signed : t -> bool
val is_integral : t -> bool

is_integral t is whether t is an integer (whole number) or not.

  • since 0.4.0
val of_bigint : Z.t -> t
val of_int : int -> t
val of_string : ?context:Context.t -> string -> t

of_string ?context str is str parsed into a decimal value with context (or the default context if none provided).

Note that a convenience syntax, e.g. 1.1m, is provided to write decimal literals in source code. See the readme for instructions on how to use it via the ppx_decimal PPX.

val of_yojson : [> `Int of int | `Float of float | `String of string ] -> (t, string) Stdlib.result

of_yojson json is the result of parsing a JSON value into a decimal:

  • integer is parsed
  • float is parsed with the usual caveat about float imprecision
  • string is parsed
  • anything else fails to parse
  • since 0.3.0
val of_float : ?context:Context.t -> float -> t

of_float ?context float is the decimal representation of the float. This suffers from floating-point precision loss; the other constructors should be preferred.

  • alert lossy Suffers from floating-point precision loss. Other constructors should be preferred.
val to_bigint : t -> Z.t

to_bigint t is t converted to a bigint and truncated if necessary.

val to_bool : t -> bool
val to_rational : t -> Q.t
val to_string : ?format:[ `standard | `eng | `plain ] -> ?context:Context.t -> t -> string

to_string ?format ?context t is the string representation of t. format is optional, with the options being:

  • `standard: the default. Numbers are represented as decimals until 6 decimal points, at which point they are represented as scientific notation
  • `eng: engineering notation, where the exponent of 10 is always a multiple of 3
  • `plain: 'normal' decimal notation
val to_yojson : t -> [> `String of string ]

to_yojson t is the JSON representation of decimal value t. Note that it is encoded as a string to avoid losing precision.

  • since 0.3.0
val to_float : ?context:Context.t -> t -> float

to_float ?context decimal is the float representation of the decimal. This suffers from floating-point precision loss; the other serializations should be preferred.

  • since 0.4.0
  • alert lossy Suffers from floating-point precision loss. Other serializations should be preferred.
val pp : Stdlib.Format.formatter -> t -> unit
val to_tuple : t -> int * string * int

to_tuple t is a representation of the internals of t as a triple of (sign, coefficient, exponent) for debugging purposes.

val abs : ?round:bool -> ?context:Context.t -> t -> t

abs ?round ?context t is the absolute value of t, rounded only if round is true.

val copy_abs : t -> t

copy_abs t is the absolute value of t without rounding.

val adjusted : t -> int

adjusted t is the exponent of t after adjusting its coefficient (significand) into standard form, i.e. scientific notation.

E.g., Decimal.("314" |> of_string |> adjusted) is 2 because it is 3.14e2 in standard form. And, Decimal.("42e-10" |> of_string |> adjusted) is -9 because it is 4.2e-9 in standard form.

val negate : ?context:Context.t -> t -> t

negate ?context t is t negated, and rounded under context if necessary.

val copy_negate : t -> t

copy_negate t is t negated without rounding.

val posate : ?context:Context.t -> t -> t

Opposite of negate; t's sign is left unchanged but t is rounded under context if necessary.

val quantize : ?context:Context.t -> ?round:Context.round -> exp:t -> t -> t

quantize ?context ?round ~exp t is t quantized so that its exponent is the same as that of exp.

val round : ?n:int -> t -> t

round ?n t is t rounded to the nearest integer, or to a given precision. If n is None, round t to the nearest integer. If t lies exactly halfway between two integers then it is rounded to the even integer.

  • alert exn Invalid_argument if t is ∞ or NaN
val shift : ?context:Context.t -> t -> t -> t

shift ?context t1 t2 shifts t1 by t2 decimal places, where t2 must be integral.

  • since 0.4.0
val sign : t -> int

sign t is -1 if t is negative, and 1 otherwise.

val min : t -> t -> t

min t1 t2 is the smaller of t1 and t2.

val max : t -> t -> t

max t1 t2 is the larger of t1 and t2.

val add : ?context:Context.t -> t -> t -> t
val sub : ?context:Context.t -> t -> t -> t
val mul : ?context:Context.t -> t -> t -> t
val div : ?context:Context.t -> t -> t -> t
val div_rem : ?context:Context.t -> t -> t -> t * t

div_rem ?context t1 t2 is (t1 / t2, t1 mod t2).

val rem : ?context:Context.t -> t -> t -> t

rem ?context t1 t2 is t1 mod t2.

val fma : ?context:Context.t -> first_mul:t -> then_add:t -> t -> t

fma ?context ~first_mul ~then_add t is fused multiply-add: t * first_mul + then_add with no rounding of the intermediate product.

t and first_mul are multiplied together, then then_add is added to the product, then a final rounding is performed.

val sqrt : ?context:Context.t -> t -> t

sqrt ?context x is the square root of x.

  • since 0.4.0
val scaleb : ?context:Context.t -> t -> t -> t

scaleb ?context t1 t2 returns t1 after scaling its exponent by t2.

  • since 0.4.0
val (~-) : t -> t
val (~+) : t -> t
val (=) : t -> t -> bool
val (<>) : t -> t -> bool
val (==) : t -> t -> bool
  • alert phys_eq Physical equality of decimals is rarely useful
val (!=) : t -> t -> bool
  • alert phys_eq Physical equality of decimals is rarely useful
val (<) : t -> t -> bool
val (>) : t -> t -> bool
val (<=) : t -> t -> bool
val (>=) : t -> t -> bool
val (+) : t -> t -> t
val (-) : t -> t -> t
val (*) : t -> t -> t
val (/) : t -> t -> t
val (mod) : t -> t -> t