Module DecimalSource

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

Sourcemodule Signal : sig ... end

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

Sourcemodule Context : sig ... end

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

Sourcetype t

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

include Map.OrderedType with type t := t
Sourceval compare : t -> t -> int

A total ordering function over the keys. This is a two-argument function f such that f e1 e2 is zero if the keys e1 and e2 are equal, f e1 e2 is strictly negative if e1 is smaller than e2, and f e1 e2 is strictly positive if e1 is greater than e2. Example: a suitable ordering function is the generic structural comparison function Stdlib.compare.

include Hashtbl.HashedType with type t := t
Sourceval equal : t -> t -> bool

The equality predicate used to compare keys.

Sourceval hash : t -> int

A hashing function on keys. It must be such that if two keys are equal according to equal, then they have identical hash values as computed by hash. Examples: suitable (equal, hash) pairs for arbitrary key types include

  • ((=), hash) for comparing objects by structure (provided objects do not contain floats)
  • ((fun x y -> compare x y = 0), hash) for comparing objects by structure and handling Stdlib.nan correctly
  • ((==), hash) for comparing objects by physical equality (e.g. for mutable or cyclic objects).
Sourceval infinity : t
Sourceval neg_infinity : t
Sourceval nan : t
Sourceval one : t
Sourceval zero : t
Sourceval of_bigint : Z.t -> t
Sourceval of_int : int -> t
Sourceval of_string : ?context:Context.t -> string -> t
Sourceval 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.
Sourceval to_bigint : t -> Z.t

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

Sourceval to_bool : t -> bool
Sourceval to_rational : t -> Q.t
Sourceval to_string : ?eng:bool -> ?context:Context.t -> t -> string
Sourceval pp : Format.formatter -> t -> unit
Sourceval 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.

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

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

Sourceval copy_abs : t -> t

copy_abs t is the absolute value of t without rounding.

Sourceval 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.

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

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

Sourceval copy_negate : t -> t

copy_negate t is t negated without rounding.

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

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

Sourceval 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.

Sourceval 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 is ∞ or NaN then raises an exception. If t lies exactly halfway between two integers then it is rounded to the even integer.

Sourceval sign : t -> int

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

Sourceval min : t -> t -> t

min t1 t2 is the smaller of t1 and t2.

Sourceval max : t -> t -> t

max t1 t2 is the larger of t1 and t2.

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

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

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

rem ?context t1 t2 is t1 mod t2.

Sourceval 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.

Sourceval (~-) : t -> t
Sourceval (~+) : t -> t
Sourceval (=) : t -> t -> bool
Sourceval (<) : t -> t -> bool
Sourceval (>) : t -> t -> bool
Sourceval (<=) : t -> t -> bool
Sourceval (>=) : t -> t -> bool
Sourceval (+) : t -> t -> t
Sourceval (-) : t -> t -> t
Sourceval (*) : t -> t -> t
Sourceval (/) : t -> t -> t
Sourceval (mod) : t -> t -> t