1Float(3)                         OCaml library                        Float(3)
2
3
4

NAME

6       Float - Floating-point arithmetic.
7

Module

9       Module   Float
10

Documentation

12       Module Float
13        : sig end
14
15
16       Floating-point arithmetic.
17
18       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
28
29       Since 4.07.0
30
31
32
33
34
35
36       val zero : float
37
38       The floating point 0.
39
40
41       Since 4.08.0
42
43
44
45       val one : float
46
47       The floating-point 1.
48
49
50       Since 4.08.0
51
52
53
54       val minus_one : float
55
56       The floating-point -1.
57
58
59       Since 4.08.0
60
61
62
63       val neg : float -> float
64
65       Unary negation.
66
67
68
69       val add : float -> float -> float
70
71       Floating-point addition.
72
73
74
75       val sub : float -> float -> float
76
77       Floating-point subtraction.
78
79
80
81       val mul : float -> float -> float
82
83       Floating-point multiplication.
84
85
86
87       val div : float -> float -> float
88
89       Floating-point division.
90
91
92
93       val fma : float -> float -> float -> float
94
95
96       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
100       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
105
106       Since 4.08.0
107
108
109
110       val rem : float -> float -> float
111
112
113       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
117
118
119       val succ : float -> float
120
121
122       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
125
126       Since 4.08.0
127
128
129
130       val pred : float -> float
131
132
133       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
137
138       Since 4.08.0
139
140
141
142       val abs : float -> float
143
144
145       abs f returns the absolute value of f .
146
147
148
149       val infinity : float
150
151       Positive infinity.
152
153
154
155       val neg_infinity : float
156
157       Negative infinity.
158
159
160
161       val nan : float
162
163       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
169
170
171       val pi : float
172
173       The constant pi.
174
175
176
177       val max_float : float
178
179       The largest positive finite value of type float .
180
181
182
183       val min_float : float
184
185       The smallest positive, non-zero, non-denormalized value of type float .
186
187
188
189       val epsilon : float
190
191       The  difference  between  1.0  and  the  smallest exactly representable
192       floating-point number greater than 1.0 .
193
194
195
196       val is_finite : float -> bool
197
198
199       is_finite x is true if and only if x is finite i.e., not  infinite  and
200       not Float.nan .
201
202
203       Since 4.08.0
204
205
206
207       val is_infinite : float -> bool
208
209
210       is_infinite   x  is  true  if  and  only  if  x  is  Float.infinity  or
211       Float.neg_infinity .
212
213
214       Since 4.08.0
215
216
217
218       val is_nan : float -> bool
219
220
221       is_nan x is true if and only if x is not a number (see Float.nan ).
222
223
224       Since 4.08.0
225
226
227
228       val is_integer : float -> bool
229
230
231       is_integer x is true if and only if x is an integer.
232
233
234       Since 4.08.0
235
236
237
238       val of_int : int -> float
239
240       Convert an integer to floating-point.
241
242
243
244       val to_int : float -> int
245
246       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
250
251
252       val of_string : string -> float
253
254       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
266
267       Raises Failure if the given string is not a valid representation  of  a
268       float.
269
270
271
272       val of_string_opt : string -> float option
273
274       Same as of_string , but returns None instead of raising.
275
276
277
278       val to_string : float -> string
279
280       Return a string representation of a floating-point number.
281
282       This  conversion  can  involve a loss of precision. For greater control
283       over the manner in which the number is printed, see Printf .
284
285       This function is an alias for string_of_float .
286
287
288       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
300
301       The five classes  of  floating-point  numbers,  as  determined  by  the
302       Float.classify_float function.
303
304
305
306       val classify_float : float -> fpclass
307
308       Return the class of the given floating-point number: normal, subnormal,
309       zero, infinite, or not a number.
310
311
312
313       val pow : float -> float -> float
314
315       Exponentiation.
316
317
318
319       val sqrt : float -> float
320
321       Square root.
322
323
324
325       val cbrt : float -> float
326
327       Cube root.
328
329
330       Since 4.13.0
331
332
333
334       val exp : float -> float
335
336       Exponential.
337
338
339
340       val exp2 : float -> float
341
342       Base 2 exponential function.
343
344
345       Since 4.13.0
346
347
348
349       val log : float -> float
350
351       Natural logarithm.
352
353
354
355       val log10 : float -> float
356
357       Base 10 logarithm.
358
359
360
361       val log2 : float -> float
362
363       Base 2 logarithm.
364
365
366       Since 4.13.0
367
368
369
370       val expm1 : float -> float
371
372
373       expm1 x computes exp x -. 1.0  ,  giving  numerically-accurate  results
374       even if x is close to 0.0 .
375
376
377
378       val log1p : float -> float
379
380
381       log1p  x  computes  log(1.0  +.  x) (natural logarithm), giving numeri‐
382       cally-accurate results even if x is close to 0.0 .
383
384
385
386       val cos : float -> float
387
388       Cosine.  Argument is in radians.
389
390
391
392       val sin : float -> float
393
394       Sine.  Argument is in radians.
395
396
397
398       val tan : float -> float
399
400       Tangent.  Argument is in radians.
401
402
403
404       val acos : float -> float
405
406       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
409
410
411       val asin : float -> float
412
413       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
416
417
418       val atan : float -> float
419
420       Arc tangent.  Result is in radians and is between -pi/2 and pi/2 .
421
422
423
424       val atan2 : float -> float -> float
425
426
427       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
431
432
433       val hypot : float -> float -> float
434
435
436       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
441
442
443       val cosh : float -> float
444
445       Hyperbolic cosine.  Argument is in radians.
446
447
448
449       val sinh : float -> float
450
451       Hyperbolic sine.  Argument is in radians.
452
453
454
455       val tanh : float -> float
456
457       Hyperbolic tangent.  Argument is in radians.
458
459
460
461       val acosh : float -> float
462
463       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
466
467       Since 4.13.0
468
469
470
471       val asinh : float -> float
472
473       Hyperbolic arc sine.  The argument and result  range  over  the  entire
474       real line.  Result is in radians.
475
476
477       Since 4.13.0
478
479
480
481       val atanh : float -> float
482
483       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
486
487       Since 4.13.0
488
489
490
491       val erf : float -> float
492
493       Error function.  The argument ranges over the entire  real  line.   The
494       result is always within [-1.0, 1.0] .
495
496
497       Since 4.13.0
498
499
500
501       val erfc : float -> float
502
503       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
507
508       Since 4.13.0
509
510
511
512       val trunc : float -> float
513
514
515       trunc  x  rounds  x to the nearest integer whose absolute value is less
516       than or equal to x .
517
518
519       Since 4.08.0
520
521
522
523       val round : float -> float
524
525
526       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
531       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
534
535       Since 4.08.0
536
537
538
539       val ceil : float -> float
540
541       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
544
545
546       val floor : float -> float
547
548       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
551
552
553       val next_after : float -> float -> float
554
555
556       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
565
566
567       Since 4.08.0
568
569
570
571       val copy_sign : float -> float -> float
572
573
574       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
578
579
580       val sign_bit : float -> bool
581
582
583       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
587
588       Since 4.08.0
589
590
591
592       val frexp : float -> float * int
593
594
595       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
600
601
602       val ldexp : float -> int -> float
603
604
605       ldexp x n returns x *. 2 ** n .
606
607
608
609       val modf : float -> float * float
610
611
612       modf f returns the pair of the fractional and integral part of f .
613
614
615       type t = float
616
617
618       An alias for the type of floating-point numbers.
619
620
621
622       val compare : t -> t -> int
623
624
625       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
631
632
633       val equal : t -> t -> bool
634
635       The  equal  function  for  floating-point   numbers,   compared   using
636       Float.compare .
637
638
639
640       val min : t -> t -> t
641
642
643       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
646
647
648       Since 4.08.0
649
650
651
652       val max : float -> float -> float
653
654
655       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
658
659
660       Since 4.08.0
661
662
663
664       val min_max : float -> float -> float * float
665
666
667       min_max x y is (min x y, max x y) , just more efficient.
668
669
670       Since 4.08.0
671
672
673
674       val min_num : t -> t -> t
675
676
677       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
681
682
683       Since 4.08.0
684
685
686
687       val max_num : t -> t -> t
688
689
690       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
694
695
696       Since 4.08.0
697
698
699
700       val min_max_num : float -> float -> float * float
701
702
703       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
707
708       Since 4.08.0
709
710
711
712       val hash : t -> int
713
714       The hash function for floating-point numbers.
715
716
717       module Array : sig end
718
719
720       Float arrays with packed representation.
721
722
723       module ArrayLabels : sig end
724
725
726       Float arrays with packed representation (labeled functions).
727
728
729
730
731
732OCamldoc                          2023-01-23                          Float(3)
Impressum