1Float(3) OCaml library Float(3)
2
6 Float - Floating-point arithmetic.
7
9 Module Float
10
12 Module Float
13 : sig end
14 Floating-point arithmetic.
17 OCaml's floating-point numbers follow the IEEE 754 standard, using dou‐
19 ble precision (64 bits) numbers. Floating-point operations never raise
20 an exception on overflow, underflow, division by zero, etc. Instead,
21 special IEEE numbers are returned as appropriate, such as infinity for
22 1.0 /. 0.0 , neg_infinity for -1.0 /. 0.0 , and nan ('not a number')
23 for 0.0 /. 0.0 . These special numbers then propagate through float‐
24 ing-point computations as expected: for instance, 1.0 /. infinity is
25 0.0 , basic arithmetic operations ( +. , -. , *. , /. ) with nan as
26 an argument return nan , ...
27 Since 4.07.0
30 val zero : float
37 The floating point 0.
39 Since 4.08.0
42 val one : float
46 The floating-point 1.
48 Since 4.08.0
51 val minus_one : float
55 The floating-point -1.
57 Since 4.08.0
60 val neg : float -> float
64 Unary negation.
66 val add : float -> float -> float
70 Floating-point addition.
72 val sub : float -> float -> float
76 Floating-point subtraction.
78 val mul : float -> float -> float
82 Floating-point multiplication.
84 val div : float -> float -> float
88 Floating-point division.
90 val fma : float -> float -> float -> float
94 fma x y z returns x * y + z , with a best effort for computing this ex‐
97 pression with a single rounding, using either hardware instructions
98 (providing full IEEE compliance) or a software emulation.
99 On 64-bit Cygwin, 64-bit mingw-w64 and MSVC 2017 and earlier, this
101 function may be emulated owing to known bugs on limitations on these
102 platforms. Note: since software emulation of the fma is costly, make
103 sure that you are using hardware fma support if performance matters.
104 Since 4.08.0
107 val rem : float -> float -> float
111 rem a b returns the remainder of a with respect to b . The returned
114 value is a -. n *. b , where n is the quotient a /. b rounded towards
115 zero to an integer.
116 val succ : float -> float
120 succ x returns the floating point number right after x i.e., the small‐
123 est floating-point number greater than x . See also Float.next_after .
124 Since 4.08.0
127 val pred : float -> float
131 pred x returns the floating-point number right before x i.e., the
134 greatest floating-point number smaller than x . See also
135 Float.next_after .
136 Since 4.08.0
139 val abs : float -> float
143 abs f returns the absolute value of f .
146 val infinity : float
150 Positive infinity.
152 val neg_infinity : float
156 Negative infinity.
158 val nan : float
162 A special floating-point value denoting the result of an undefined op‐
164 eration such as 0.0 /. 0.0 . Stands for 'not a number'. Any float‐
165 ing-point operation with nan as argument returns nan as result. As for
166 floating-point comparisons, = , < , <= , > and >= return false and <>
167 returns true if one or both of their arguments is nan .
168 val pi : float
172 The constant pi.
174 val max_float : float
178 The largest positive finite value of type float .
180 val min_float : float
184 The smallest positive, non-zero, non-denormalized value of type float .
186 val epsilon : float
190 The difference between 1.0 and the smallest exactly representable
192 floating-point number greater than 1.0 .
193 val is_finite : float -> bool
197 is_finite x is true if and only if x is finite i.e., not infinite and
200 not Float.nan .
201 Since 4.08.0
204 val is_infinite : float -> bool
208 is_infinite x is true if and only if x is Float.infinity or
211 Float.neg_infinity .
212 Since 4.08.0
215 val is_nan : float -> bool
219 is_nan x is true if and only if x is not a number (see Float.nan ).
222 Since 4.08.0
225 val is_integer : float -> bool
229 is_integer x is true if and only if x is an integer.
232 Since 4.08.0
235 val of_int : int -> float
239 Convert an integer to floating-point.
241 val to_int : float -> int
245 Truncate the given floating-point number to an integer. The result is
247 unspecified if the argument is nan or falls outside the range of repre‐
248 sentable integers.
249 val of_string : string -> float
253 Convert the given string to a float. The string is read in decimal (by
255 default) or in hexadecimal (marked by 0x or 0X ). The format of deci‐
256 mal floating-point numbers is [-] dd.ddd (e|E) [+|-] dd , where d
257 stands for a decimal digit. The format of hexadecimal floating-point
258 numbers is [-] 0(x|X) hh.hhh (p|P) [+|-] dd , where h stands for an
259 hexadecimal digit and d for a decimal digit. In both cases, at least
260 one of the integer and fractional parts must be given; the exponent
261 part is optional. The _ (underscore) character can appear anywhere in
262 the string and is ignored. Depending on the execution platforms, other
263 representations of floating-point numbers can be accepted, but should
264 not be relied upon.
265 Raises Failure if the given string is not a valid representation of a
268 float.
269 val of_string_opt : string -> float option
273 Same as of_string , but returns None instead of raising.
275 val to_string : float -> string
279 Return a string representation of a floating-point number.
281 This conversion can involve a loss of precision. For greater control
283 over the manner in which the number is printed, see Printf .
284 This function is an alias for string_of_float .
286 type fpclass = fpclass =
289 | FP_normal (* Normal number, none of the below
290 *)
291 | FP_subnormal (* Number very close to 0.0, has reduced precision
292 *)
293 | FP_zero (* Number is 0.0 or -0.0
294 *)
295 | FP_infinite (* Number is positive or negative infinity
296 *)
297 | FP_nan (* Not a number: result of an undefined operation
298 *)
299 The five classes of floating-point numbers, as determined by the
302 Float.classify_float function.
303 val classify_float : float -> fpclass
307 Return the class of the given floating-point number: normal, subnormal,
309 zero, infinite, or not a number.
310 val pow : float -> float -> float
314 Exponentiation.
316 val sqrt : float -> float
320 Square root.
322 val cbrt : float -> float
326 Cube root.
328 Since 4.13.0
331 val exp : float -> float
335 Exponential.
337 val exp2 : float -> float
341 Base 2 exponential function.
343 Since 4.13.0
346 val log : float -> float
350 Natural logarithm.
352 val log10 : float -> float
356 Base 10 logarithm.
358 val log2 : float -> float
362 Base 2 logarithm.
364 Since 4.13.0
367 val expm1 : float -> float
371 expm1 x computes exp x -. 1.0 , giving numerically-accurate results
374 even if x is close to 0.0 .
375 val log1p : float -> float
379 log1p x computes log(1.0 +. x) (natural logarithm), giving numeri‐
382 cally-accurate results even if x is close to 0.0 .
383 val cos : float -> float
387 Cosine. Argument is in radians.
389 val sin : float -> float
393 Sine. Argument is in radians.
395 val tan : float -> float
399 Tangent. Argument is in radians.
401 val acos : float -> float
405 Arc cosine. The argument must fall within the range [-1.0, 1.0] . Re‐
407 sult is in radians and is between 0.0 and pi .
408 val asin : float -> float
412 Arc sine. The argument must fall within the range [-1.0, 1.0] . Re‐
414 sult is in radians and is between -pi/2 and pi/2 .
415 val atan : float -> float
419 Arc tangent. Result is in radians and is between -pi/2 and pi/2 .
421 val atan2 : float -> float -> float
425 atan2 y x returns the arc tangent of y /. x . The signs of x and y are
428 used to determine the quadrant of the result. Result is in radians and
429 is between -pi and pi .
430 val hypot : float -> float -> float
434 hypot x y returns sqrt(x *. x + y *. y) , that is, the length of the
437 hypotenuse of a right-angled triangle with sides of length x and y ,
438 or, equivalently, the distance of the point (x,y) to origin. If one of
439 x or y is infinite, returns infinity even if the other is nan .
440 val cosh : float -> float
444 Hyperbolic cosine. Argument is in radians.
446 val sinh : float -> float
450 Hyperbolic sine. Argument is in radians.
452 val tanh : float -> float
456 Hyperbolic tangent. Argument is in radians.
458 val acosh : float -> float
462 Hyperbolic arc cosine. The argument must fall within the range [1.0,
464 inf] . Result is in radians and is between 0.0 and inf .
465 Since 4.13.0
468 val asinh : float -> float
472 Hyperbolic arc sine. The argument and result range over the entire
474 real line. Result is in radians.
475 Since 4.13.0
478 val atanh : float -> float
482 Hyperbolic arc tangent. The argument must fall within the range [-1.0,
484 1.0] . Result is in radians and ranges over the entire real line.
485 Since 4.13.0
488 val erf : float -> float
492 Error function. The argument ranges over the entire real line. The
494 result is always within [-1.0, 1.0] .
495 Since 4.13.0
498 val erfc : float -> float
502 Complementary error function ( erfc x = 1 - erf x ). The argument
504 ranges over the entire real line. The result is always within [-1.0,
505 1.0] .
506 Since 4.13.0
509 val trunc : float -> float
513 trunc x rounds x to the nearest integer whose absolute value is less
516 than or equal to x .
517 Since 4.08.0
520 val round : float -> float
524 round x rounds x to the nearest integer with ties (fractional values of
527 0.5) rounded away from zero, regardless of the current rounding direc‐
528 tion. If x is an integer, +0. , -0. , nan , or infinite, x itself is
529 returned.
530 On 64-bit mingw-w64, this function may be emulated owing to a bug in
532 the C runtime library (CRT) on this platform.
533 Since 4.08.0
536 val ceil : float -> float
540 Round above to an integer value. ceil f returns the least integer
542 value greater than or equal to f . The result is returned as a float.
543 val floor : float -> float
547 Round below to an integer value. floor f returns the greatest integer
549 value less than or equal to f . The result is returned as a float.
550 val next_after : float -> float -> float
554 next_after x y returns the next representable floating-point value fol‐
557 lowing x in the direction of y . More precisely, if y is greater
558 (resp. less) than x , it returns the smallest (resp. largest) repre‐
559 sentable number greater (resp. less) than x . If x equals y , the
560 function returns y . If x or y is nan , a nan is returned. Note that
561 next_after max_float infinity = infinity and that next_after 0. infin‐
562 ity is the smallest denormalized positive number. If x is the smallest
563 denormalized positive number, next_after x 0. = 0.
564 Since 4.08.0
568 val copy_sign : float -> float -> float
572 copy_sign x y returns a float whose absolute value is that of x and
575 whose sign is that of y . If x is nan , returns nan . If y is nan ,
576 returns either x or -. x , but it is not specified which.
577 val sign_bit : float -> bool
581 sign_bit x is true if and only if the sign bit of x is set. For exam‐
584 ple sign_bit 1. and signbit 0. are false while sign_bit (-1.) and
585 sign_bit (-0.) are true .
586 Since 4.08.0
589 val frexp : float -> float * int
593 frexp f returns the pair of the significant and the exponent of f .
596 When f is zero, the significant x and the exponent n of f are equal to
597 zero. When f is non-zero, they are defined by f = x *. 2 ** n and 0.5
598 <= x < 1.0 .
599 val ldexp : float -> int -> float
603 ldexp x n returns x *. 2 ** n .
606 val modf : float -> float * float
610 modf f returns the pair of the fractional and integral part of f .
613 type t = float
616 An alias for the type of floating-point numbers.
619 val compare : t -> t -> int
623 compare x y returns 0 if x is equal to y , a negative integer if x is
626 less than y , and a positive integer if x is greater than y . compare
627 treats nan as equal to itself and less than any other float value.
628 This treatment of nan ensures that compare defines a total ordering re‐
629 lation.
630 val equal : t -> t -> bool
634 The equal function for floating-point numbers, compared using
636 Float.compare .
637 val min : t -> t -> t
641 min x y returns the minimum of x and y . It returns nan when x or y is
644 nan . Moreover min (-0.) (+0.) = -0.
645 Since 4.08.0
649 val max : float -> float -> float
653 max x y returns the maximum of x and y . It returns nan when x or y is
656 nan . Moreover max (-0.) (+0.) = +0.
657 Since 4.08.0
661 val min_max : float -> float -> float * float
665 min_max x y is (min x y, max x y) , just more efficient.
668 Since 4.08.0
671 val min_num : t -> t -> t
675 min_num x y returns the minimum of x and y treating nan as missing val‐
678 ues. If both x and y are nan , nan is returned. Moreover min_num
679 (-0.) (+0.) = -0.
680 Since 4.08.0
684 val max_num : t -> t -> t
688 max_num x y returns the maximum of x and y treating nan as missing val‐
691 ues. If both x and y are nan nan is returned. Moreover max_num (-0.)
692 (+0.) = +0.
693 Since 4.08.0
697 val min_max_num : float -> float -> float * float
701 min_max_num x y is (min_num x y, max_num x y) , just more efficient.
704 Note that in particular min_max_num x nan = (x, x) and min_max_num nan
705 y = (y, y) .
706 Since 4.08.0
709 val hash : t -> int
713 The hash function for floating-point numbers.
715 module Array : sig end
718 Float arrays with packed representation.
721 module ArrayLabels : sig end
724 Float arrays with packed representation (labeled functions).
727OCamldoc 2023-07-20 Float(3)