# Module `Bignum`

`include module type of Bignum0 with module Bignum0.Stable := Bignum0.Stable`
`type t`
`val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state`
`val hash : t -> Base.Hash.hash_value`

Sexp conversions represent values as decimals if possible, or defaults to `(x + y/z)` where `x` is decimal and `y` and `z` are integers. So for example, 1/3 <-> (0.333333333 + 1/3000000000). In string and sexp conversions, values with denominator of zero are special-cased: 0/0 <-> "nan", 1/0 <-> "inf", and -1/0 <-> "-inf".

`include Core_kernel.Sexpable with type t := t`
`type t`
`val t_of_sexp : Base.Sexp.t -> t`
`val sexp_of_t : t -> Base.Sexp.t`
`include Core_kernel.Comparable with type t := t`
`include Core_kernel__.Comparable_intf.S_common`
`include Base.Comparable.S`
`include Base__.Comparable_intf.Polymorphic_compare`
`include Base.Comparisons.Infix`
`type t`
`val (>=) : t -> t -> bool`
`val (<=) : t -> t -> bool`
`val (=) : t -> t -> bool`
`val (>) : t -> t -> bool`
`val (<) : t -> t -> bool`
`val (<>) : t -> t -> bool`
`val equal : t -> t -> bool`
`val compare : t -> t -> int`

`compare t1 t2` returns 0 if `t1` is equal to `t2`, a negative integer if `t1` is less than `t2`, and a positive integer if `t1` is greater than `t2`.

`val min : t -> t -> t`
`val max : t -> t -> t`
`val ascending : t -> t -> int`

`ascending` is identical to `compare`. `descending x y = ascending y x`. These are intended to be mnemonic when used like `List.sort ~compare:ascending` and ```List.sort ~cmp:descending```, since they cause the list to be sorted in ascending or descending order, respectively.

`val descending : t -> t -> int`
`val between : t -> low:t -> high:t -> bool`

`between t ~low ~high` means `low <= t <= high`

`val clamp_exn : t -> min:t -> max:t -> t`

`clamp_exn t ~min ~max` returns `t'`, the closest value to `t` such that `between t' ~low:min ~high:max` is true.

Raises if `not (min <= max)`.

`val clamp : t -> min:t -> max:t -> t Base.Or_error.t`
`include Base.Comparator.S with type t := t`
`type t`
`type comparator_witness`
`val comparator : (t, comparator_witness) Base.Comparator.comparator`
`include Base__.Comparable_intf.Validate with type t := t`
`type t`
`val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check`
`val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check`
`val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check`
`module Replace_polymorphic_compare : Core_kernel__.Comparable_intf.Polymorphic_compare with type t := t`
`module Map : Core_kernel.Map.S with type Key.t = t with type Key.comparator_witness = comparator_witness`
`module Set : Core_kernel.Set.S with type Elt.t = t with type Elt.comparator_witness = comparator_witness`
`include Core_kernel.Hashable with type t := t`
`include Core_kernel.Hashable.Common`
`type t`
`val compare : t -> t -> Core_kernel__.Import.int`
`val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state`
`val hash : t -> Base.Hash.hash_value`
`val hashable : t Core_kernel.Hashtbl.Hashable.t`
`module Table : Core_kernel.Hashtbl.S with type key = t`
`module Hash_set : Core_kernel.Hash_set.S with type elt = t`
`module Hash_queue : Core_kernel.Hash_queue.S with type Key.t = t`
`include Core_kernel.Binable with type t := t`
`type t`
`include Core_kernel__.Binable0.S_only_functions with type t := t`
`type t`
`val bin_size_t : t Bin_prot.Size.sizer`
`val bin_write_t : t Bin_prot.Write.writer`
`val bin_read_t : t Bin_prot.Read.reader`
`val __bin_read_t__ : (int -> t) Bin_prot.Read.reader`

This function only needs implementation if `t` exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variant `t` afterwards.

`val bin_shape_t : Bin_prot.Shape.t`
`val bin_writer_t : t Bin_prot.Type_class.writer`
`val bin_reader_t : t Bin_prot.Type_class.reader`
`val bin_t : t Bin_prot.Type_class.t`

`gen` produces values with an order of magnitude (roughly the number of digits) in the numerator and denominator proportional to `Quickcheck.Generator.size`. Also includes values with zero in the denominator.

`include Core_kernel.Quickcheckable with type t := t`
`type t`
`val quickcheck_generator : t Base_quickcheck.Generator.t`
`val quickcheck_observer : t Base_quickcheck.Observer.t`
`val quickcheck_shrinker : t Base_quickcheck.Shrinker.t`
`val zero : t`
`val one : t`
`val ten : t`
`val hundred : t`
`val thousand : t`
`val million : t`
`val billion : t`
`val trillion : t`
`val tenth : t`
`val hundredth : t`
`val thousandth : t`
`val millionth : t`
`val billionth : t`
`val trillionth : t`
`val (+) : t -> t -> t`
`val (-) : t -> t -> t`
`val (/) : t -> t -> t`

Note that division by zero will not raise, but will return inf, -inf, or nan.

`val (//) : int -> int -> t`

`m // n` is equivalent to `of_int m / of_int n`. Example: `Bigint.O.(2 // 3)`.

`val (*) : t -> t -> t`
`val (**) : t -> int -> t`

Beware: `2 ** 8_000_000` will take at least a megabyte to store the result, and multiplying numbers a megabyte long is slow no matter how clever your algorithm. Be careful to ensure the second argument is reasonably-sized.

`val abs : t -> t`
`val neg : t -> t`
`val inverse : t -> t`

Note that `inverse zero` is `infinity`, not an error.

`val sum : t list -> t`
`val round : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> ?⁠to_multiple_of:t -> t -> t`

Default rounding direction is ``Nearest`. `to_multiple_of` defaults to `one` and must not be `zero`.

`val iround : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> ?⁠to_multiple_of:int -> t -> int option`

`None` if the result would overflow or `to_multiple_of` is zero.

`val round_as_bigint : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> ?⁠to_multiple_of:Bigint.t -> t -> Bigint.t option`
`val iround_exn : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> ?⁠to_multiple_of:int -> t -> int`

Exception if the result would overflow or `to_multiple_of` is zero.

`val round_as_bigint_exn : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> ?⁠to_multiple_of:Bigint.t -> t -> Bigint.t`
`val round_decimal : ?⁠dir:[ `Down | `Up | `Nearest | `Zero ] -> digits:int -> t -> t`

Convenience wrapper around `round` to round to the specified number of decimal digits. This raises if the number is infinite or undefined.

`val round_decimal_to_nearest_half_to_even : digits:int -> t -> t`
`val to_float : t -> float`
`val to_string_decimal_accurate_exn : t -> string`

Accurate if possible. If this number is not representable as a finite decimal fraction, it raises instead.

`val to_string_decimal_accurate : t -> string Core_kernel.Or_error.t`

As above, returns Or_error.t instead of raising

`val is_representable_as_decimal : t -> bool`

`true` if and only if `to_string_decimal_accurate_exn` doesn't raise.

`val is_real : t -> bool`

`true` if and only if the number is non-infinity and non-undefined.

`val is_nan : t -> bool`

`true` if and only if the number is undefined.

`val to_string_hum : ?⁠delimiter:char -> ?⁠decimals:int -> ?⁠strip_zero:bool -> t -> string`

Pretty print bignum in an approximate decimal form or print inf, -inf, nan. For example ```to_string_hum ~delimiter:',' ~decimals:3 ~strip_zero:false 1234.1999 = "1,234.200"```. No delimiters are inserted to the right of the decimal.

`val to_string_accurate : t -> string`

Always accurate. If the number is representable as a finite decimal, it will return this decimal string. If the denomiator is zero, it would return "nan", "inf" or "-inf". Finally, if the bignum is a rational non representable as a decimal, `to_string_accurate t` returns an expression that evaluates to the right value. Example: ```to_string_accurate (Bignum.of_string "1/3") = "(0.333333333 + 1/3000000000)"```.

Since the introduction of that function in the API, `of_string` is able to read any value returned by this function, and would yield the original bignum. That is:

``fun bignum -> bignum |> to_string_accurate |> of_string``

is the identity in `Bignum`.

`val of_float_decimal : float -> t`

Transforming a `float` into a `Bignum.t` needs to be done with care. Most rationals and decimals are not exactly representable as floats, thus their float representation includes some small imprecision at the end of their decimal form (typically after the 17th digits). It is very likely that when transforming a `float` into a `Bignum.t`, it is best to try to determine which was the original value and retrieve it instead of honoring the noise coming from its imprecise float representation.

Given that the original value is not available in the context of a function whose type is `float -> Bignum.t`, it is not possible to solve that problem in a principled way. However, a very reasonable approximation is to build the `Bignum` from a short string-representation of the float that guarantees the round-trip ```float |> to_string |> of_string```. In particular, if the float was obtained from a short decimal string, this heuristic in practice succeeds at retrieving the original value.

In the context where it is assumed that a float is a perfect representative of the value meant to be modelled, the actual `Bignum.t` value for it may be built using `of_float_dyadic`.

For example:

`3.14` is not a representable decimal, thus:

``of_float_dyadic (Float.of_string "3.14") = (3.14 + 7/56294995342131200)``
``of_float_decimal (Float.of_string "3.14") = 3.14``

`of_float_dyadic` used to be called `of_float` but we think it is not the right default choice, thus `of_float` was deprecated, and we introduced different names for this operation to force some explicit decision at call site.

After some time has passed, `of_float_decimal` will be renamed to `of_float`, thus re-introducing `of_float` in the API.

`val of_float_dyadic : float -> t`
`val of_float : float -> t`
`val to_int : t -> int option`

Rounds toward zero. `None` if the conversion would overflow

`val to_int_exn : t -> int`
`val is_zero : t -> bool`
`val sign : t -> int`

Do not use this function in new code. See `sign_exn` or `sign_or_nan` instead.

Returns -1, 0, or 1 according to the sign of the input. Due to an accidental oversight, `sign nan` = -1.

`val sign_exn : t -> Core_kernel.Sign.t`

The sign of a Bignum. Raises on nan.

`val sign_or_nan : t -> Core_kernel.Sign_or_nan.t`
`val of_string : string -> t`
`val of_int : int -> t`
`val num : t -> t`

`num t` returns the numerator of the numeric

`val den : t -> t`

`den t` returns the denominator of the numeric

`val of_bigint : Bigint.t -> t`
`val num_as_bigint : t -> Bigint.t`
`val den_as_bigint : t -> Bigint.t`
`val pp_hum : Stdlib.Format.formatter -> t -> unit`
`val pp_accurate : Stdlib.Format.formatter -> t -> unit`
`val gen_finite : t Core_kernel.Quickcheck.Generator.t`

`gen_finite` is like `gen` but excludes values with zero in the denominator.

`val gen_uniform_excl : t -> t -> t Core_kernel.Quickcheck.Generator.t`

`gen_uniform_excl lower_bound upper_bound` produces a uniform distribution between `lower_bound` and `upper_bound`, exclusive, in units based on the fractional parts of the bounds plus a number of decimal places proportional to `Quickcheck.Generator.size`.

`val gen_incl : t -> t -> t Core_kernel.Quickcheck.Generator.t`

`gen_incl lower_bound upper_bound` produces a distribution of values between `lower_bound` and `upper_bound`, inclusive, that is approximately uniform with extra weight given to producing the endpoints `lower_bound` and `upper_bound`.

`module Stable = Bignum0.Stable`
`module O = Bignum0.O`
`val to_string : t -> string`
`val pp : Stdlib.Format.formatter -> t -> unit`
`module Stable : sig ... end`
`module Bignum0 : sig ... end`
`module Std : sig ... end`