268 lines
11 KiB
OCaml
268 lines
11 KiB
OCaml
(**************************************************************************)
|
|
(* *)
|
|
(* OCaml *)
|
|
(* *)
|
|
(* Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
|
|
(* Nicolas Ojeda Bar, LexiFi *)
|
|
(* *)
|
|
(* Copyright 2018 Institut National de Recherche en Informatique et *)
|
|
(* en Automatique. *)
|
|
(* *)
|
|
(* All rights reserved. This file is distributed under the terms of *)
|
|
(* the GNU Lesser General Public License version 2.1, with the *)
|
|
(* special exception on linking described in the file LICENSE. *)
|
|
(* *)
|
|
(**************************************************************************)
|
|
|
|
(** {1 Floating-point arithmetic}
|
|
|
|
OCaml'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 arithmetic operation with [nan]
|
|
as argument returns [nan] as result.
|
|
|
|
@since 4.07.0
|
|
*)
|
|
|
|
external neg : float -> float = "%negfloat"
|
|
(** Unary negation. *)
|
|
|
|
external add : float -> float -> float = "%addfloat"
|
|
(** Floating-point addition. *)
|
|
|
|
external sub : float -> float -> float = "%subfloat"
|
|
(** Floating-point subtraction. *)
|
|
|
|
external mul : float -> float -> float = "%mulfloat"
|
|
(** Floating-point multiplication. *)
|
|
|
|
external div : float -> float -> float = "%divfloat"
|
|
(** Floating-point division. *)
|
|
|
|
external rem : float -> float -> float = "caml_fmod_float" "fmod"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [rem a b] returns the remainder of [a] with respect to [b]. The returned
|
|
value is [a -. n *. b], where [n] is the quotient [a /. b] rounded towards
|
|
zero to an integer. *)
|
|
|
|
external abs : float -> float = "%absfloat"
|
|
(** [abs f] returns the absolute value of [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 pi : float
|
|
(** The constant pi. *)
|
|
|
|
val max_float : float
|
|
(** The largest positive finite value of type [float]. *)
|
|
|
|
val min_float : float
|
|
(** The smallest positive, non-zero, non-denormalized value of type [float]. *)
|
|
|
|
val epsilon : float
|
|
(** The difference between [1.0] and the smallest exactly representable
|
|
floating-point number greater than [1.0]. *)
|
|
|
|
external of_int : int -> float = "%floatofint"
|
|
(** Convert an integer to floating-point. *)
|
|
|
|
external to_int : float -> int = "%intoffloat"
|
|
(** Truncate the given floating-point number to an integer.
|
|
The result is unspecified if the argument is [nan] or falls outside the
|
|
range of representable integers. *)
|
|
|
|
external of_string : string -> float = "caml_float_of_string"
|
|
(** Convert the given string to a float. The string is read in decimal
|
|
(by default) or in hexadecimal (marked by [0x] or [0X]).
|
|
The format of decimal floating-point numbers is
|
|
[ [-] dd.ddd (e|E) [+|-] dd ], where [d] stands for a decimal digit.
|
|
The format of hexadecimal floating-point numbers is
|
|
[ [-] 0(x|X) hh.hhh (p|P) [+|-] dd ], where [h] stands for an
|
|
hexadecimal digit and [d] for a decimal digit.
|
|
In both cases, at least one of the integer and fractional parts must be
|
|
given; the exponent part is optional.
|
|
The [_] (underscore) character can appear anywhere in the string
|
|
and is ignored.
|
|
Depending on the execution platforms, other representations of
|
|
floating-point numbers can be accepted, but should not be relied upon.
|
|
Raise [Failure "float_of_string"] if the given string is not a valid
|
|
representation of a float. *)
|
|
|
|
val of_string_opt: string -> float option
|
|
(** Same as [of_string], but returns [None] instead of raising. *)
|
|
|
|
val to_string : float -> string
|
|
(** Return the string representation of a floating-point number. *)
|
|
|
|
type fpclass = Stdlib.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_float} function. *)
|
|
|
|
external classify_float : (float [@unboxed]) -> fpclass =
|
|
"caml_classify_float" "caml_classify_float_unboxed" [@@noalloc]
|
|
(** Return the class of the given floating-point number:
|
|
normal, subnormal, zero, infinite, or not a number. *)
|
|
|
|
external pow : float -> float -> float = "caml_power_float" "pow"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Exponentiation. *)
|
|
|
|
external sqrt : float -> float = "caml_sqrt_float" "sqrt"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Square root. *)
|
|
|
|
external exp : float -> float = "caml_exp_float" "exp" [@@unboxed] [@@noalloc]
|
|
(** Exponential. *)
|
|
|
|
external log : float -> float = "caml_log_float" "log" [@@unboxed] [@@noalloc]
|
|
(** Natural logarithm. *)
|
|
|
|
external log10 : float -> float = "caml_log10_float" "log10"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Base 10 logarithm. *)
|
|
|
|
external expm1 : float -> float = "caml_expm1_float" "caml_expm1"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [expm1 x] computes [exp x -. 1.0], giving numerically-accurate results
|
|
even if [x] is close to [0.0]. *)
|
|
|
|
external log1p : float -> float = "caml_log1p_float" "caml_log1p"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [log1p x] computes [log(1.0 +. x)] (natural logarithm),
|
|
giving numerically-accurate results even if [x] is close to [0.0]. *)
|
|
|
|
external cos : float -> float = "caml_cos_float" "cos" [@@unboxed] [@@noalloc]
|
|
(** Cosine. Argument is in radians. *)
|
|
|
|
external sin : float -> float = "caml_sin_float" "sin" [@@unboxed] [@@noalloc]
|
|
(** Sine. Argument is in radians. *)
|
|
|
|
external tan : float -> float = "caml_tan_float" "tan" [@@unboxed] [@@noalloc]
|
|
(** Tangent. Argument is in radians. *)
|
|
|
|
external acos : float -> float = "caml_acos_float" "acos"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Arc cosine. The argument must fall within the range [[-1.0, 1.0]].
|
|
Result is in radians and is between [0.0] and [pi]. *)
|
|
|
|
external asin : float -> float = "caml_asin_float" "asin"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Arc sine. The argument must fall within the range [[-1.0, 1.0]].
|
|
Result is in radians and is between [-pi/2] and [pi/2]. *)
|
|
|
|
external atan : float -> float = "caml_atan_float" "atan"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Arc tangent.
|
|
Result is in radians and is between [-pi/2] and [pi/2]. *)
|
|
|
|
external atan2 : float -> float -> float = "caml_atan2_float" "atan2"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [atan2 y x] returns the arc tangent of [y /. x]. The signs of [x]
|
|
and [y] are used to determine the quadrant of the result.
|
|
Result is in radians and is between [-pi] and [pi]. *)
|
|
|
|
external hypot : float -> float -> float = "caml_hypot_float" "caml_hypot"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [hypot x y] returns [sqrt(x *. x + y *. y)], that is, the length
|
|
of the hypotenuse of a right-angled triangle with sides of length
|
|
[x] and [y], or, equivalently, the distance of the point [(x,y)]
|
|
to origin. If one of [x] or [y] is infinite, returns [infinity]
|
|
even if the other is [nan]. *)
|
|
|
|
external cosh : float -> float = "caml_cosh_float" "cosh"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Hyperbolic cosine. Argument is in radians. *)
|
|
|
|
external sinh : float -> float = "caml_sinh_float" "sinh"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Hyperbolic sine. Argument is in radians. *)
|
|
|
|
external tanh : float -> float = "caml_tanh_float" "tanh"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Hyperbolic tangent. Argument is in radians. *)
|
|
|
|
external ceil : float -> float = "caml_ceil_float" "ceil"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Round above to an integer value.
|
|
[ceil f] returns the least integer value greater than or equal to [f].
|
|
The result is returned as a float. *)
|
|
|
|
external floor : float -> float = "caml_floor_float" "floor"
|
|
[@@unboxed] [@@noalloc]
|
|
(** Round below to an integer value.
|
|
[floor f] returns the greatest integer value less than or
|
|
equal to [f].
|
|
The result is returned as a float. *)
|
|
|
|
external copysign : float -> float -> float
|
|
= "caml_copysign_float" "caml_copysign"
|
|
[@@unboxed] [@@noalloc]
|
|
(** [copysign x y] returns a float whose absolute value is that of [x]
|
|
and whose sign is that of [y]. If [x] is [nan], returns [nan].
|
|
If [y] is [nan], returns either [x] or [-. x], but it is not
|
|
specified which. *)
|
|
|
|
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 [@unboxed]) -> (int [@untagged]) -> (float [@unboxed]) =
|
|
"caml_ldexp_float" "caml_ldexp_float_unboxed" [@@noalloc]
|
|
(** [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]. *)
|
|
|
|
type t = float
|
|
(** An alias for the type of floating-point numbers. *)
|
|
|
|
val compare: t -> t -> int
|
|
(** [compare x y] returns [0] if [x] is equal to [y], a negative integer if [x]
|
|
is less than [y], and a positive integer if [x] is greater than
|
|
[y]. [compare] treats [nan] as equal to itself and less than any other float
|
|
value. This treatment of [nan] ensures that [compare] defines a total
|
|
ordering relation. *)
|
|
|
|
val equal: t -> t -> bool
|
|
(** The equal function for floating-point numbers, compared using {!compare}. *)
|
|
|
|
val hash: t -> int
|
|
(** The hash function for floating-point numbers. *)
|
|
|
|
module Array : sig
|
|
type t = floatarray
|
|
external create : int -> t = "caml_floatarray_create"
|
|
external length : t -> int = "%floatarray_length"
|
|
external get : t -> int -> float = "%floatarray_safe_get"
|
|
external set : t -> int -> float -> unit = "%floatarray_safe_set"
|
|
external unsafe_get : t -> int -> float = "%floatarray_unsafe_get"
|
|
external unsafe_set : t -> int -> float -> unit = "%floatarray_unsafe_set"
|
|
end
|