Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
558 lines (420 sloc) 17.6 KB
(*
* ExtFloat - Extended floats
* Copyright (C) 2007 Bluestorm <bluestorm dot dylc on-the-server gmail dot com>
* 2009 David Rajchenbach-Teller, LIFO, Universite d'Orleans
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version,
* with the special exception on linking described in file LICENSE.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
(**Operations on floating-point numbers.
Caml's floating-point numbers follow the IEEE 754 standard, using
double precision (64 bits) numbers. Floating-point operations never
raise an exception on overflow, underflow, division by zero,
etc. Instead, special IEEE numbers are returned as appropriate,
such as [infinity] for [1.0 /. 0.0], [neg_infinity] for [-1.0 /. 0.0], and
[nan] (``not a number'') for [0.0 /. 0.0]. These special numbers then
propagate through floating-point computations as expected: for
instance, [1.0 /. infinity] is [0.0], and any operation with [nan] as
argument returns [nan] as result.
For more precision, see
{{:http://en.wikipedia.org/wiki/IEEE_754}The Wikipedia entry on
standard IEEE 754}.
@author Gabriel Scherer
@author David Teller
@author Edgar Friendly
@documents Float
*)
type t = float
(**The type of floating-point numbers.
Floating-point numbers are the default representation of
real numbers by OCaml. *)
(**
{6 Usual operations}
*)
val zero : float
(** Floating number zero. This is the same thing as [0.]*)
val one : float
(** Floating number one. This is the same thing as [1.]*)
external neg : float -> float = "%negfloat"
(** Returns the negation of the input, i.e. (fun x -> ~-. x) *)
val succ : float -> float
(** Add [1.] to a floating number. Note that, as per IEEE 754,
if [x] is a large enough float number, [succ x] might be
equal to [x], due to rounding.*)
val pred : float -> float
(** Substract [1.] from a floating number. Note that, as per
IEEE 754, if [x] is a large enough float number, [pred x]
might be equal to [x], due to rounding.*)
external abs : float -> float = "%absfloat"
(** The absolute value of a floating point number.*)
val add : float -> float -> float
val sub : float -> float -> float
val mul : float -> float -> float
val div : float -> float -> float
external modulo : float -> float -> float = "caml_fmod_float" "fmod" "float"
external pow : float -> float -> float = "caml_power_float" "pow" "float"
val min_num : float
val max_num : float
val compare : float -> float -> int
val equal : float -> float -> bool
val ord : float -> float -> BatOrd.order
external of_int : int -> float = "%floatofint"
external to_int : float -> int = "%intoffloat"
external of_float : float -> float = "%identity"
external to_float : float -> float = "%identity"
val of_string : string -> float
val to_string : float -> string
external ( + ) : t -> t -> t = "%addfloat"
external ( - ) : t -> t -> t = "%subfloat"
external ( * ) : t -> t -> t = "%mulfloat"
external ( / ) : t -> t -> t = "%divfloat"
external ( ** ) : t -> t -> t = "caml_power_float" "pow" "float"
(* Available only in `Compare` submodule
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 ( -- ): t -> t -> t BatEnum.t
val ( --- ): t -> t -> t BatEnum.t
val operations : t BatNumber.numeric
(**
{6 Operations specific to floating-point numbers}
*)
external sqrt : float -> float = "caml_sqrt_float" "sqrt" "float"
(** Square root. *)
external exp : float -> float = "caml_exp_float" "exp" "float"
(** Exponential. *)
external log : float -> float = "caml_log_float" "log" "float"
(** Natural logarithm. *)
external log10 : float -> float = "caml_log10_float" "log10" "float"
(** Base 10 logarithm. *)
external cos : float -> float = "caml_cos_float" "cos" "float"
(** See {!atan2}. *)
external sin : float -> float = "caml_sin_float" "sin" "float"
(** See {!atan2}. *)
external tan : float -> float = "caml_tan_float" "tan" "float"
(** See {!atan2}. *)
external acos : float -> float = "caml_acos_float" "acos" "float"
(** See {!atan2}. *)
external asin : float -> float = "caml_asin_float" "asin" "float"
(** See {!atan2}. *)
external atan : float -> float = "caml_atan_float" "atan" "float"
(** See {!atan2}. *)
external atan2 : float -> float -> float = "caml_atan2_float" "atan2" "float"
(** The usual trigonometric functions. *)
external cosh : float -> float = "caml_cosh_float" "cosh" "float"
(** See {!tanh}. *)
external sinh : float -> float = "caml_sinh_float" "sinh" "float"
(** See {!tanh}. *)
external tanh : float -> float = "caml_tanh_float" "tanh" "float"
(** The usual hyperbolic trigonometric functions. *)
external ceil : float -> float = "caml_ceil_float" "ceil" "float"
(** See {!floor}. *)
external floor : float -> float = "caml_floor_float" "floor" "float"
(** Round the given float to an integer value.
[floor f] returns the greatest integer value less than or
equal to [f].
[ceil f] returns the least integer value greater than or
equal to [f]. *)
val round : float -> float
(** [round x] rounds [x] to the nearest integral floating-point
(the nearest of [floor x] and [ceil x]). In case the fraction
of x is exactly 0.5, we round away from 0. : [round 1.5] is
[2.] but [round (-3.5)] is [-4.]. *)
val round_to_int : float -> int
(** [round_to_int x] is [int_of_float (round x)].
@since 2.0 *)
val round_to_string : ?digits:int -> float -> string
(** [round_to_string ~digits:d x] will return a string
representation of [x] -- in base 10 -- rounded to [d] digits
after the decimal point. By default, [digits] is [0], we round
to the nearest integer.
@raise Invalid_argument if the ~digits argument is negative.
This is strictly a convenience function for simple end-user
printing and you should not rely on its behavior. One possible
implementation is to rely on C `sprintf` internally, which
means:
- no guarantee is given on the round-at-half behavior; it may
not be consistent with [round] or [round_to_int]
- [round_to_string ~digits:0 3.] may return "3" instead of
"3." as [string_of_float] would
- no guarantee is given on the behavior for abusively high
number of digits precision; for example [round_to_string
~digits:max_int x] may return the empty string.
@since 2.0 *)
(** [root x n] calculates the nth root of x.
@raises Invalid_argument if n is negative or if the result would
be imaginary *)
val root: float -> int -> float
(** @return True if the sign bit of [x] is set. This usually indicates thet [x] is negative. @since 2.0*)
val signbit: float -> bool
(** [copysign x y] returns a copy of [x] with the same sign as [y]. @since 2.0*)
val copysign: float -> float -> float
val is_nan : float -> bool
(** [is_nan f] returns [true] if [f] is [nan], [false] otherwise.*)
val is_special : float -> bool
(** [is_special f] returns [true] if [f] is [nan] or [+/- infinity],
[false] otherwise.
@since 2.0 *)
val is_finite : float -> bool
(** [is_finite f] returns [true] if [f] is not [nan] or [+/- infinity],
[false] otherwise.
@since 2.0 *)
(** {6 Constants} *)
(** Special float constants. It may not be safe to compare
directly with these, as they have multiple internal
representations. Instead use the [is_special], [is_nan],
etc. tests *)
val infinity : float
(** Positive infinity. *)
val neg_infinity : float
(** Negative infinity. *)
val nan : float
(** A special floating-point value denoting the result of an
undefined operation such as [0.0 /. 0.0]. Stands for ``not
a number''. Any floating-point operation with [nan] as
argument returns [nan] as result. As for floating-point
comparisons, [=], [<], [<=], [>] and [>=] return [false] and
[<>] returns [true] if one or both of their arguments is
[nan]. *)
(** Numeric constants *)
(** The smallest positive float [x] such that [1.0 +. x <> 1.0]. *)
val epsilon : float
(** Euler? ... Euler? ... Euler? @since 2.0*)
val e: float
(** [Math.log2 e] @since 2.0 *)
val log2e: float
(** [log10 e] @since 2.0 *)
val log10e: float
(** [log 2] @since 2.0 *)
val ln2: float
(** [log 10] @since 2.0 *)
val ln10: float
(** The constant pi (3.14159...) *)
val pi : float
(** [pi /. 2.] @since 2.0 *)
val pi2: float
(** [pi /. 4.] @since 2.0 *)
val pi4: float
(** [1. /. pi] @since 2.0 *)
val invpi: float
(** [2. /. pi] @since 2.0 *)
val invpi2: float
(** [2. *. sqrt pi] @since 2.0 *)
val sqrtpi2: float
(** [sqrt 2.] @since 2.0 *)
val sqrt2: float
(** [1. /. sqrt 2.] @since 2.0 *)
val invsqrt2: float
(** {6 Operations on the internal representation of floating-point
numbers}*)
external frexp : float -> float * int = "caml_frexp_float"
(** [frexp f] returns the pair of the significant and the exponent
of [f]. When [f] is zero, the significant [x] and the
exponent [n] of [f] are equal to zero. When [f] is non-zero,
they are defined by [f = x *. 2 ** n] and [0.5 <= x < 1.0]. *)
external ldexp : float -> int -> float = "caml_ldexp_float"
(** [ldexp x n] returns [x *. 2 ** n]. *)
external modf : float -> float * float = "caml_modf_float"
(** [modf f] returns the pair of the fractional and integral
part of [f]. *)
(** Classes of floating point numbers*)
type fpkind = Pervasives.fpclass =
FP_normal (** Normal number, none of the below *)
| FP_subnormal (** Number very close to 0.0, has reduced precision *)
| FP_zero (** Number is 0.0 or -0.0 *)
| FP_infinite (** Number is positive or negative infinity *)
| FP_nan (** Not a number: result of an undefined operation *)
(** The five classes of floating-point numbers, as determined by
the {!classify} function. *)
external classify : float -> fpkind = "caml_classify_float"
(** Return the class of the given floating-point number:
normal, subnormal, zero, infinite, or not a number. *)
val approx_equal : ?epsilon:float -> float -> float -> bool
(** Test whether two floats are approximately equal (i.e. within
epsilon of each other). [epsilon] defaults to 1e-5. *)
(** {6 Submodules grouping all infix operators} *)
module Infix : sig
include BatNumber.Infix with type bat__infix_t = t
val (=~) : ?epsilon:float -> float -> float -> bool
(** Approximate comparison of two floats, as [approx_equal].
[epsilon] defaults to 1e-5. *)
end
module Compare : BatNumber.Compare with type bat__compare_t = t
(** {6 Boilerplate code}*)
(** {7 Printing}*)
val print: 'a BatInnerIO.output -> t -> unit
val t_printer : t BatValuePrinter.t
(**Operations on floating-point numbers, with exceptions raised in
case of error.
The operations implemented in this module are the same as the operations
implemented in module {!Float}, with the exception that no operation returns
[nan], [infinity] or [neg_infinity]. In case of overflow, instead of returning
[infinity] or [neg_infinity], operations raise exception {!Number.Overflow}.
In case of [nan], operations raise exception {!Number.NaN}.
Caml's floating-point numbers follow the IEEE 754 standard, using
double precision (64 bits) numbers. Floating-point operations never
raise an exception on overflow, underflow, division by zero,
etc. Instead, special IEEE numbers are returned as appropriate,
such as [infinity] for [1.0 /. 0.0], [neg_infinity] for [-1.0 /. 0.0], and
[nan] (``not a number'') for [0.0 /. 0.0]. These special numbers then
propagate through floating-point computations as expected: for
instance, [1.0 /. infinity] is [0.0], and any operation with [nan] as
argument returns [nan] as result.
For more precision, see
{{:http://en.wikipedia.org/wiki/IEEE_754}The Wikipedia entry on
standard IEEE 754}.
@author David Teller
@documents Safe_float
*)
module Safe_float :
sig
type t = float
(**The type of floating-point numbers.
Floating-point numbers are the default representation of
real numbers by OCaml. *)
(**
{6 Usual operations}
*)
val zero : float
(** Floating number zero. This is the same thing as [0.]*)
val one : float
(** Floating number one. This is the same thing as [1.]*)
val neg : float -> float
val succ : float -> float
(** Add [1.] to a floating number. Note that, as per IEEE 754,
if [x] is a large enough float number, [succ x] might be
equal to [x], due to rounding.*)
val pred : float -> float
(** Substract [1.] from a floating number. Note that, as per
IEEE 754, if [x] is a large enough float number, [pred x]
might be equal to [x], due to rounding.*)
val abs : float -> float
(** The absolute value of a floating point number.*)
val add : float -> float -> float
val sub : float -> float -> float
val mul : float -> float -> float
val div : float -> float -> float
val modulo : float -> float -> float
val pow : float -> float -> float
val min_num : float
val max_num : float
val compare : float -> float -> int
val of_int : int -> float
val to_int : float -> int
external of_float : float -> float = "%identity"
external to_float : float -> float = "%identity"
val of_string : string -> float
val to_string : float -> string
val ( + ) : t -> t -> t
val ( - ) : t -> t -> t
val ( * ) : t -> t -> t
val ( / ) : t -> t -> t
val ( ** ) : t -> t -> t
(* Available only in `Compare` submodule
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 operations : t BatNumber.numeric
(**
{6 Operations specific to floating-point numbers}
*)
val exp : float -> float
(** Exponential. *)
val log : float -> float
(** Natural logarithm. *)
val log10 : float -> float
(** Base 10 logarithm. *)
val cos : float -> float
(** See {!atan2}. *)
val sin : float -> float
(** See {!atan2}. *)
val tan : float -> float
(** See {!atan2}. *)
val acos : float -> float
(** See {!atan2}. *)
val asin : float -> float
(** See {!atan2}. *)
val atan : float -> float
(** See {!atan2}. *)
val atan2 : float -> float -> float
(** The usual trigonometric functions. *)
val cosh : float -> float
(** See {!tanh}. *)
val sinh : float -> float
(** See {!tanh}. *)
val tanh : float -> float
(** The usual hyperbolic trigonometric functions. *)
val ceil : float -> float
(** See {!floor}. *)
val floor : float -> float
(** Round the given float to an integer value.
[floor f] returns the greatest integer value less than or
equal to [f].
[ceil f] returns the least integer value greater than or
equal to [f]. *)
val infinity : float
(** Positive infinity. *)
val neg_infinity : float
(** Negative infinity. *)
val nan : float
(** A special floating-point value denoting the result of an
undefined operation such as [0.0 /. 0.0]. Stands for
``not a number''. Any floating-point operation with [nan] as
argument returns [nan] as result. As for floating-point comparisons,
[=], [<], [<=], [>] and [>=] return [false] and [<>] returns [true]
if one or both of their arguments is [nan]. *)
val is_nan : float -> bool
(** [is_nan f] returns [true] if [f] is [nan], [false] otherwise.*)
val epsilon : float
(** The smallest positive float [x] such that [1.0 +. x <> 1.0]. *)
val pi : float
(** The constant pi (3.14159...) *)
(** {6 Operations on the internal representation of floating-point numbers}*)
val frexp : float -> float * int
(** [frexp f] returns the pair of the significant
and the exponent of [f]. When [f] is zero, the
significant [x] and the exponent [n] of [f] are equal to
zero. When [f] is non-zero, they are defined by
[f = x *. 2 ** n] and [0.5 <= x < 1.0]. *)
val ldexp : float -> int -> float
(** [ldexp x n] returns [x *. 2 ** n]. *)
val modf : float -> float * float
(** [modf f] returns the pair of the fractional and integral
part of [f]. *)
(** Classes of floating point numbers*)
type fpkind = Pervasives.fpclass =
FP_normal (** Normal number, none of the below *)
| FP_subnormal (** Number very close to 0.0, has reduced precision *)
| FP_zero (** Number is 0.0 or -0.0 *)
| FP_infinite (** Number is positive or negative infinity *)
| FP_nan (** Not a number: result of an undefined operation *)
(** The five classes of floating-point numbers, as determined by
the {!classify} function. *)
external classify : float -> fpkind = "caml_classify_float"
(** Return the class of the given floating-point number:
normal, subnormal, zero, infinite, or not a number. *)
(** {6 Boilerplate code}*)
(** {7 Printing}*)
val print: 'a BatInnerIO.output -> t -> unit
val t_printer : t BatValuePrinter.t
end
Something went wrong with that request. Please try again.