Module BignumSource

Arbitrary-precision rational numbers.

type t
include Ppx_hash_lib.Hashable.S with type t := t

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.Sexpable with type t := t
Sourceval t_of_sexp : Sexplib0.Sexp.t -> t
Sourceval sexp_of_t : t -> Sexplib0.Sexp.t
include Core.Comparable with type t := t
include Base.Comparable.S with type t := 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 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
type comparator_witness
val comparator : (t, comparator_witness) Base__.Comparator.comparator
Sourceval validate_lbound : min:t Core.Maybe_bound.t -> t Validate.check
Sourceval validate_ubound : max:t Core.Maybe_bound.t -> t Validate.check
Sourceval validate_bound : min:t Core.Maybe_bound.t -> max:t Core.Maybe_bound.t -> t Validate.check
Sourcemodule Replace_polymorphic_compare : Base.Comparable.Polymorphic_compare with type t := t
include Core.Hashable with type t := t
include Ppx_compare_lib.Comparable.S with type t := t
val compare : t Base__Ppx_compare_lib.compare
include Ppx_hash_lib.Hashable.S with type t := t
Sourceval hash_fold_t : t Base__Ppx_hash_lib.hash_fold
Sourceval hash : t -> Base__Ppx_hash_lib.Std.Hash.hash_value
Sourcemodule Table : Core.Hashtbl.S with type key = t
Sourcemodule Hash_set : Core.Hash_set.S with type elt = t
include Core.Equal.S with type t := t
val equal : t Base__Equal.equal

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.Quickcheckable with type t := t
Sourceval quickcheck_generator : t Base_quickcheck.Generator.t
Sourceval quickcheck_observer : t Base_quickcheck.Observer.t
Sourceval quickcheck_shrinker : t Base_quickcheck.Shrinker.t
val zero : t
Sourceval one : t
Sourceval ten : t
Sourceval hundred : t
Sourceval thousand : t
Sourceval million : t
Sourceval billion : t
Sourceval trillion : t
Sourceval tenth : t
Sourceval hundredth : t
Sourceval thousandth : t
Sourceval millionth : t
Sourceval billionth : t
Sourceval 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
Sourceval (**) : 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
Sourceval inverse : t -> t

Note that inverse zero is infinity, not an error.

Sourceval sum : t list -> t
Sourceval 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.

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

Sourceval round_as_bigint : ?dir:[ `Down | `Up | `Nearest | `Zero ] -> ?to_multiple_of:Bigint.t -> t -> Bigint.t option
Sourceval 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.

Sourceval round_as_bigint_exn : ?dir:[ `Down | `Up | `Nearest | `Zero ] -> ?to_multiple_of:Bigint.t -> t -> Bigint.t
Sourceval 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.

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

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

Sourceval to_string_decimal_accurate : t -> string Core.Or_error.t

As above, returns Or_error.t instead of raising

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

Sourceval is_nan : t -> bool

true if and only if the number is undefined.

Sourceval is_integer : t -> bool

true iff the number is an integer.

Sourceval to_bigint_opt : t -> Bigint.t option

Returns Some bigint if is_integer t would return true.

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

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

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

Sourceval of_float_dyadic : float -> t
Sourceval of_float : float -> t
  • deprecated [since 2017-03]: Use [of_float_decimal] or [of_float_dyadic]
Sourceval to_int : t -> int option

Rounds toward zero. None if the conversion would overflow

Sourceval to_int_exn : t -> int
Sourceval is_zero : t -> bool
Sourceval 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.

Sourceval sign_exn : t -> Core.Sign.t

The sign of a Bignum. Raises on nan.

Sourceval sign_or_nan : t -> Core.Sign_or_nan.t
Sourceval of_string : string -> t
val of_int : int -> t
Sourceval num : t -> t

num t returns the numerator of the numeric

Sourceval den : t -> t

den t returns the denominator of the numeric

Sourceval of_bigint : Bigint.t -> t
Sourceval num_as_bigint : t -> Bigint.t
Sourceval den_as_bigint : t -> Bigint.t
Sourceval pp_hum : Format.formatter -> t -> unit
Sourceval pp_accurate : Format.formatter -> t -> unit

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

Sourceval gen_uniform_excl : t -> t -> t Core.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.

Sourceval gen_incl : t -> t -> t Core.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.

Sourcemodule Stable : sig ... end
Sourcemodule Unstable : sig ... end
Sourcemodule O : sig ... end
Sourceval to_string : t -> string
  • deprecated [since 2018-02]: Use [to_string_hum] or another [to_string_*] function
Sourceval pp : Format.formatter -> t -> unit
  • deprecated [since 2018-02]: Use [pp_hum] or [pp_accurate]
Sourcemodule For_testing : sig ... end
  • deprecated [since 2019-10] use module V2 or Unstable instead
  • deprecated [since 2019-10] use module V2 or Unstable instead
  • deprecated [since 2019-10] use module V2 or Unstable instead
Sourceval __bin_read_t__ : (int -> t) Core.Bin_prot.Read.reader
  • deprecated [since 2019-10] use module V2 or Unstable instead
  • deprecated [since 2019-10] use module V2 or Unstable instead
  • deprecated [since 2019-10] use module V2 or Unstable instead
  • deprecated [since 2019-10] use module V2 or Unstable instead