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

NAME

6       Pervasives - Pervasive operations.
7

Module

9       Module   Pervasives
10

Documentation

12       Module Pervasives
13        : sig end
14
15
16       Pervasive operations.
17
18       This module provides the basic operations over the built-in types (num‐
19       bers, booleans, byte sequences, strings, exceptions, references, lists,
20       arrays, input-output channels, ...).
21
22       This module is included in the toplevel Stdlib module.
23
24
25
26
27
28
29
30       === Exceptions ===
31
32
33       val raise : exn -> 'a
34
35       Raise the given exception value
36
37
38
39       val raise_notrace : exn -> 'a
40
41       A faster version raise which does not record the backtrace.
42
43
44       Since 4.02.0
45
46
47
48       val invalid_arg : string -> 'a
49
50       Raise exception Invalid_argument with the given string.
51
52
53
54       val failwith : string -> 'a
55
56       Raise exception Failure with the given string.
57
58
59
60       exception Exit
61
62
63       The  Exit  exception is not raised by any library function.  It is pro‐
64       vided for use in your programs.
65
66
67
68
69       === Comparisons ===
70
71
72       val (=) : 'a -> 'a -> bool
73
74
75       e1 = e2 tests for structural equality of e1 and e2  .   Mutable  struc‐
76       tures  (e.g. references and arrays) are equal if and only if their cur‐
77       rent contents are structurally equal, even if the two  mutable  objects
78       are  not  the same physical object.  Equality between functional values
79       raises Invalid_argument .  Equality between cyclic data structures  may
80       not terminate.  Left-associative operator at precedence level 4/11.
81
82
83
84       val (<>) : 'a -> 'a -> bool
85
86       Negation  of  Pervasives.(=) .  Left-associative operator at precedence
87       level 4/11.
88
89
90
91       val (<) : 'a -> 'a -> bool
92
93       See Pervasives.(>=) .  Left-associative operator  at  precedence  level
94       4/11.
95
96
97
98       val (>) : 'a -> 'a -> bool
99
100       See  Pervasives.(>=)  .   Left-associative operator at precedence level
101       4/11.
102
103
104
105       val (<=) : 'a -> 'a -> bool
106
107       See Pervasives.(>=) .  Left-associative operator  at  precedence  level
108       4/11.
109
110
111
112       val (>=) : 'a -> 'a -> bool
113
114       Structural  ordering functions. These functions coincide with the usual
115       orderings over integers, characters, strings, byte sequences and float‐
116       ing-point  numbers, and extend them to a total ordering over all types.
117       The ordering is compatible with ( = ) . As in the case of ( = ) , muta‐
118       ble structures are compared by contents.  Comparison between functional
119       values raises Invalid_argument .  Comparison between cyclic  structures
120       may not terminate.  Left-associative operator at precedence level 4/11.
121
122
123
124       val compare : 'a -> 'a -> int
125
126
127       compare  x  y returns 0 if x is equal to y , a negative integer if x is
128       less than y , and a positive integer if x is  greater  than  y  .   The
129       ordering implemented by compare is compatible with the comparison pred‐
130       icates = , < and > defined above,  with one difference on the treatment
131       of  the float value Pervasives.nan .  Namely, the comparison predicates
132       treat nan as different from any other float  value,  including  itself;
133       while  compare  treats  nan  as equal to itself and less than any other
134       float value.  This treatment of nan  ensures  that  compare  defines  a
135       total ordering relation.
136
137
138       compare applied to functional values may raise Invalid_argument .  com‐
139       pare applied to cyclic structures may not terminate.
140
141       The compare function can be used as the comparison function required by
142       the  Set.Make  and  Map.Make  functors,  as  well  as the List.sort and
143       Array.sort functions.
144
145
146
147       val min : 'a -> 'a -> 'a
148
149       Return the smaller of the two arguments.  The result is unspecified  if
150       one of the arguments contains the float value nan .
151
152
153
154       val max : 'a -> 'a -> 'a
155
156       Return  the greater of the two arguments.  The result is unspecified if
157       one of the arguments contains the float value nan .
158
159
160
161       val (==) : 'a -> 'a -> bool
162
163
164       e1 == e2 tests for physical equality of e1 and e2 .  On  mutable  types
165       such as references, arrays, byte sequences, records with mutable fields
166       and objects with mutable instance variables, e1 == e2 is  true  if  and
167       only  if  physical modification of e1 also affects e2 .  On non-mutable
168       types, the behavior of ( == ) is implementation-dependent; however,  it
169       is  guaranteed that e1 == e2 implies compare e1 e2 = 0 .  Left-associa‐
170       tive operator at precedence level 4/11.
171
172
173
174       val (!=) : 'a -> 'a -> bool
175
176       Negation of Pervasives.(==) .  Left-associative operator at  precedence
177       level 4/11.
178
179
180
181
182       === Boolean operations ===
183
184
185       val not : bool -> bool
186
187       The boolean negation.
188
189
190
191       val (&&) : bool -> bool -> bool
192
193       The boolean 'and'. Evaluation is sequential, left-to-right: in e1 && e2
194       , e1 is evaluated first, and if it returns false , e2 is not  evaluated
195       at all.  Right-associative operator at precedence level 3/11.
196
197
198
199       val (&) : bool -> bool -> bool
200
201       Deprecated.
202
203       Pervasives.(&&)  should be used instead.  Right-associative operator at
204       precedence level 3/11.
205
206
207
208       val (||) : bool -> bool -> bool
209
210       The boolean 'or'. Evaluation is sequential, left-to-right: in e1 ||  e2
211       ,  e1  is evaluated first, and if it returns true , e2 is not evaluated
212       at all.  Right-associative operator at precedence level 2/11.
213
214
215
216       val (or) : bool -> bool -> bool
217
218       Deprecated.
219
220       Pervasives.(||) should be used instead.  Right-associative operator  at
221       precedence level 2/11.
222
223
224
225
226       === Debugging ===
227
228
229       val __LOC__ : string
230
231
232       __LOC__  returns  the  location at which this expression appears in the
233       file currently being parsed by the compiler, with  the  standard  error
234       format of OCaml: "File %S, line %d, characters %d-%d".
235
236
237       Since 4.02.0
238
239
240
241       val __FILE__ : string
242
243
244       __FILE__  returns  the  name  of the file currently being parsed by the
245       compiler.
246
247
248       Since 4.02.0
249
250
251
252       val __LINE__ : int
253
254
255       __LINE__ returns the line number at which this  expression  appears  in
256       the file currently being parsed by the compiler.
257
258
259       Since 4.02.0
260
261
262
263       val __MODULE__ : string
264
265
266       __MODULE__ returns the module name of the file being parsed by the com‐
267       piler.
268
269
270       Since 4.02.0
271
272
273
274       val __POS__ : string * int * int * int
275
276
277       __POS__ returns a tuple (file,lnum,cnum,enum) ,  corresponding  to  the
278       location  at  which this expression appears in the file currently being
279       parsed by the compiler.  file is the current filename,  lnum  the  line
280       number, cnum the character position in the line and enum the last char‐
281       acter position in the line.
282
283
284       Since 4.02.0
285
286
287
288       val __LOC_OF__ : 'a -> string * 'a
289
290
291       __LOC_OF__ expr returns a pair (loc, expr) where loc is the location of
292       expr in the file currently being parsed by the compiler, with the stan‐
293       dard error format of OCaml: "File %S, line %d, characters %d-%d".
294
295
296       Since 4.02.0
297
298
299
300       val __LINE_OF__ : 'a -> int * 'a
301
302
303       __LINE_OF__ expr returns a pair (line, expr) , where line is  the  line
304       number at which the expression expr appears in the file currently being
305       parsed by the compiler.
306
307
308       Since 4.02.0
309
310
311
312       val __POS_OF__ : 'a -> (string * int * int * int) * 'a
313
314
315       __POS_OF__ expr returns a pair  (loc,expr)  ,  where  loc  is  a  tuple
316       (file,lnum,cnum,enum)  corresponding  to  the  location  at  which  the
317       expression expr appears in the file currently being parsed by the  com‐
318       piler.   file  is  the current filename, lnum the line number, cnum the
319       character position in the line and enum the last character position  in
320       the line.
321
322
323       Since 4.02.0
324
325
326
327
328       === Composition operators ===
329
330
331       val (|>) : 'a -> ('a -> 'b) -> 'b
332
333       Reverse-application operator: x |> f |> g is exactly equivalent to g (f
334       (x)) .  Left-associative operator at precedence level 4/11.
335
336
337       Since 4.01
338
339
340
341       val (@@) : ('a -> 'b) -> 'a -> 'b
342
343       Application operator: g @@ f @@ x is exactly equivalent to g (f (x))  .
344       Right-associative operator at precedence level 5/11.
345
346
347       Since 4.01
348
349
350
351
352       === Integer arithmetic ===
353
354
355       === Integers are Sys.int_size bits wide.  All operations are taken mod‐
356       ulo 2^{Sys.int_size}.  They do not fail on overflow. ===
357
358
359       val (~-) : int -> int
360
361       Unary negation. You can also write - e instead of ~- e .  Unary  opera‐
362       tor at precedence level 9/11 for - e and 11/11 for ~- e .
363
364
365
366       val (~+) : int -> int
367
368       Unary  addition. You can also write + e instead of ~+ e .  Unary opera‐
369       tor at precedence level 9/11 for + e and 11/11 for ~+ e .
370
371
372       Since 3.12.0
373
374
375
376       val succ : int -> int
377
378
379       succ x is x + 1 .
380
381
382
383       val pred : int -> int
384
385
386       pred x is x - 1 .
387
388
389
390       val (+) : int -> int -> int
391
392       Integer addition.  Left-associative operator at precedence level 6/11.
393
394
395
396       val (-) : int -> int -> int
397
398       Integer subtraction.  Left-associative  operator  at  precedence  level
399       6/11.
400
401
402
403       val ( * ) : int -> int -> int
404
405       Integer  multiplication.  Left-associative operator at precedence level
406       7/11.
407
408
409
410       val (/) : int -> int -> int
411
412       Integer division.  Raise Division_by_zero if the second argument is  0.
413       Integer  division  rounds  the  real  quotient of its arguments towards
414       zero.  More precisely, if x >= 0 and y > 0 , x  /  y  is  the  greatest
415       integer  less than or equal to the real quotient of x by y .  Moreover,
416       (- x) / y = x / (- y) = - (x  /  y)  .   Left-associative  operator  at
417       precedence level 7/11.
418
419
420
421       val (mod) : int -> int -> int
422
423       Integer  remainder.   If y is not zero, the result of x mod y satisfies
424       the following properties: x = (x / y) * y + x mod y and abs(x mod y) <=
425       abs(y) - 1 .  If y = 0 , x mod y raises Division_by_zero .  Note that x
426       mod y is negative only if x < 0 .  Raise Division_by_zero if y is zero.
427       Left-associative operator at precedence level 7/11.
428
429
430
431       val abs : int -> int
432
433       Return the absolute value of the argument.  Note that this may be nega‐
434       tive if the argument is min_int .
435
436
437
438       val max_int : int
439
440       The greatest representable integer.
441
442
443
444       val min_int : int
445
446       The smallest representable integer.
447
448
449
450
451       === Bitwise operations ===
452
453
454       val (land) : int -> int -> int
455
456       Bitwise logical and.  Left-associative  operator  at  precedence  level
457       7/11.
458
459
460
461       val (lor) : int -> int -> int
462
463       Bitwise  logical  or.   Left-associative  operator  at precedence level
464       7/11.
465
466
467
468       val (lxor) : int -> int -> int
469
470       Bitwise logical exclusive or.  Left-associative operator at  precedence
471       level 7/11.
472
473
474
475       val lnot : int -> int
476
477       Bitwise logical negation.
478
479
480
481       val (lsl) : int -> int -> int
482
483
484       n lsl m shifts n to the left by m bits.  The result is unspecified if m
485       < 0 or m > Sys.int_size .   Right-associative  operator  at  precedence
486       level 8/11.
487
488
489
490       val (lsr) : int -> int -> int
491
492
493       n  lsr  m  shifts  n  to the right by m bits.  This is a logical shift:
494       zeroes are inserted regardless of the  sign  of  n  .   The  result  is
495       unspecified  if m < 0 or m > Sys.int_size .  Right-associative operator
496       at precedence level 8/11.
497
498
499
500       val (asr) : int -> int -> int
501
502
503       n asr m shifts n to the right by m bits.  This is an arithmetic  shift:
504       the sign bit of n is replicated.  The result is unspecified if m < 0 or
505       m > Sys.int_size .   Right-associative  operator  at  precedence  level
506       8/11.
507
508
509
510
511       === Floating-point arithmetic OCaml's floating-point numbers follow the
512       IEEE 754 standard, using double precision (64  bits)  numbers.   Float‐
513       ing-point  operations  never raise an exception on overflow, underflow,
514       division by zero, etc. Instead, special IEEE numbers  are  returned  as
515       appropriate,  such as infinity for 1.0 /. 0.0, neg_infinity for -1.0 /.
516       0.0, and nan ('not a number') for 0.0 /.  0.0.  These  special  numbers
517       then  propagate  through  floating-point  computations as expected: for
518       instance, 1.0 /. infinity is 0.0, and any arithmetic operation with nan
519       as argument returns nan as result. ===
520
521
522       val (~-.)  : float -> float
523
524       Unary negation. You can also write -. e instead of ~-. e .  Unary oper‐
525       ator at precedence level 9/11 for -. e and 11/11 for ~-. e .
526
527
528
529       val (~+.)  : float -> float
530
531       Unary addition. You can also write +. e instead of ~+. e .  Unary oper‐
532       ator at precedence level 9/11 for +. e and 11/11 for ~+. e .
533
534
535       Since 3.12.0
536
537
538
539       val (+.)  : float -> float -> float
540
541       Floating-point addition.  Left-associative operator at precedence level
542       6/11.
543
544
545
546       val (-.)  : float -> float -> float
547
548       Floating-point subtraction.  Left-associative  operator  at  precedence
549       level 6/11.
550
551
552
553       val ( *. ) : float -> float -> float
554
555       Floating-point multiplication.  Left-associative operator at precedence
556       level 7/11.
557
558
559
560       val (/.)  : float -> float -> float
561
562       Floating-point division.  Left-associative operator at precedence level
563       7/11.
564
565
566
567       val ( ** ) : float -> float -> float
568
569       Exponentiation.  Right-associative operator at precedence level 8/11.
570
571
572
573       val sqrt : float -> float
574
575       Square root.
576
577
578
579       val exp : float -> float
580
581       Exponential.
582
583
584
585       val log : float -> float
586
587       Natural logarithm.
588
589
590
591       val log10 : float -> float
592
593       Base 10 logarithm.
594
595
596
597       val expm1 : float -> float
598
599
600       expm1  x  computes  exp  x -. 1.0 , giving numerically-accurate results
601       even if x is close to 0.0 .
602
603
604       Since 3.12.0
605
606
607
608       val log1p : float -> float
609
610
611       log1p x computes log(1.0 +.  x)  (natural  logarithm),  giving  numeri‐
612       cally-accurate results even if x is close to 0.0 .
613
614
615       Since 3.12.0
616
617
618
619       val cos : float -> float
620
621       Cosine.  Argument is in radians.
622
623
624
625       val sin : float -> float
626
627       Sine.  Argument is in radians.
628
629
630
631       val tan : float -> float
632
633       Tangent.  Argument is in radians.
634
635
636
637       val acos : float -> float
638
639       Arc  cosine.   The  argument  must  fall within the range [-1.0, 1.0] .
640       Result is in radians and is between 0.0 and pi .
641
642
643
644       val asin : float -> float
645
646       Arc sine.  The argument must  fall  within  the  range  [-1.0,  1.0]  .
647       Result is in radians and is between -pi/2 and pi/2 .
648
649
650
651       val atan : float -> float
652
653       Arc tangent.  Result is in radians and is between -pi/2 and pi/2 .
654
655
656
657       val atan2 : float -> float -> float
658
659
660       atan2 y x returns the arc tangent of y /. x .  The signs of x and y are
661       used to determine the quadrant of the result.  Result is in radians and
662       is between -pi and pi .
663
664
665
666       val hypot : float -> float -> float
667
668
669       hypot  x  y  returns sqrt(x *. x + y *. y) , that is, the length of the
670       hypotenuse of a right-angled triangle with sides of length x  and  y  ,
671       or, equivalently, the distance of the point (x,y) to origin.  If one of
672       x or y is infinite, returns infinity even if the other is nan .
673
674
675       Since 4.00.0
676
677
678
679       val cosh : float -> float
680
681       Hyperbolic cosine.  Argument is in radians.
682
683
684
685       val sinh : float -> float
686
687       Hyperbolic sine.  Argument is in radians.
688
689
690
691       val tanh : float -> float
692
693       Hyperbolic tangent.  Argument is in radians.
694
695
696
697       val ceil : float -> float
698
699       Round above to an integer value.  ceil  f  returns  the  least  integer
700       value greater than or equal to f .  The result is returned as a float.
701
702
703
704       val floor : float -> float
705
706       Round  below to an integer value.  floor f returns the greatest integer
707       value less than or equal to f .  The result is returned as a float.
708
709
710
711       val abs_float : float -> float
712
713
714       abs_float f returns the absolute value of f .
715
716
717
718       val copysign : float -> float -> float
719
720
721       copysign x y returns a float whose absolute value  is  that  of  x  and
722       whose  sign  is that of y .  If x is nan , returns nan .  If y is nan ,
723       returns either x or -. x , but it is not specified which.
724
725
726       Since 4.00.0
727
728
729
730       val mod_float : float -> float -> float
731
732
733       mod_float a b returns the remainder of a  with  respect  to  b  .   The
734       returned  value is a -. n *. b , where n is the quotient a /. b rounded
735       towards zero to an integer.
736
737
738
739       val frexp : float -> float * int
740
741
742       frexp f returns the pair of the significant and the  exponent  of  f  .
743       When  f is zero, the significant x and the exponent n of f are equal to
744       zero.  When f is non-zero, they are defined by f = x *. 2 ** n and  0.5
745       <= x < 1.0 .
746
747
748
749       val ldexp : float -> int -> float
750
751
752       ldexp x n returns x *. 2 ** n .
753
754
755
756       val modf : float -> float * float
757
758
759       modf f returns the pair of the fractional and integral part of f .
760
761
762
763       val float : int -> float
764
765       Same as Pervasives.float_of_int .
766
767
768
769       val float_of_int : int -> float
770
771       Convert an integer to floating-point.
772
773
774
775       val truncate : float -> int
776
777       Same as Pervasives.int_of_float .
778
779
780
781       val int_of_float : float -> int
782
783       Truncate  the given floating-point number to an integer.  The result is
784       unspecified if the argument is nan or falls outside the range of repre‐
785       sentable integers.
786
787
788
789       val infinity : float
790
791       Positive infinity.
792
793
794
795       val neg_infinity : float
796
797       Negative infinity.
798
799
800
801       val nan : float
802
803       A  special  floating-point  value  denoting  the result of an undefined
804       operation such as 0.0 /. 0.0 .  Stands for 'not a number'.  Any  float‐
805       ing-point operation with nan as argument returns nan as result.  As for
806       floating-point comparisons, = , < , <= , > and >= return false  and  <>
807       returns true if one or both of their arguments is nan .
808
809
810
811       val max_float : float
812
813       The largest positive finite value of type float .
814
815
816
817       val min_float : float
818
819       The smallest positive, non-zero, non-denormalized value of type float .
820
821
822
823       val epsilon_float : float
824
825       The  difference  between  1.0  and  the  smallest exactly representable
826       floating-point number greater than 1.0 .
827
828
829       type fpclass =
830        | FP_normal  (* Normal number, none of the below
831        *)
832        | FP_subnormal  (* Number very close to 0.0, has reduced precision
833        *)
834        | FP_zero  (* Number is 0.0 or -0.0
835        *)
836        | FP_infinite  (* Number is positive or negative infinity
837        *)
838        | FP_nan  (* Not a number: result of an undefined operation
839        *)
840
841
842       The five classes of floating-point numbers, as determined by the Perva‐
843       sives.classify_float function.
844
845
846
847       val classify_float : float -> fpclass
848
849       Return the class of the given floating-point number: normal, subnormal,
850       zero, infinite, or not a number.
851
852
853
854
855       === String operations More string operations  are  provided  in  module
856       String. ===
857
858
859       val (^) : string -> string -> string
860
861       String  concatenation.   Right-associative operator at precedence level
862       5/11.
863
864
865
866
867       === Character operations More character operations are provided in mod‐
868       ule Char. ===
869
870
871       val int_of_char : char -> int
872
873       Return the ASCII code of the argument.
874
875
876
877       val char_of_int : int -> char
878
879       Return the character with the given ASCII code.  Raise Invalid_argument
880       char_of_int if the argument is outside the range 0--255.
881
882
883
884
885       === Unit operations ===
886
887
888       val ignore : 'a -> unit
889
890       Discard the value of its  argument  and  return  ()  .   For  instance,
891       ignore(f  x) discards the result of the side-effecting function f .  It
892       is equivalent to f x; () , except that the latter may generate  a  com‐
893       piler warning; writing ignore(f x) instead avoids the warning.
894
895
896
897
898       === String conversion functions ===
899
900
901       val string_of_bool : bool -> string
902
903       Return  the  string representation of a boolean. As the returned values
904       may be shared, the user should not modify them directly.
905
906
907
908       val bool_of_string : string -> bool
909
910       Convert  the  given  string  to  a  boolean.   Raise   Invalid_argument
911       bool_of_string if the string is not true or false .
912
913
914
915       val bool_of_string_opt : string -> bool option
916
917       Convert  the  given  string to a boolean.  Return None if the string is
918       not true or false .
919
920
921       Since 4.05
922
923
924
925       val string_of_int : int -> string
926
927       Return the string representation of an integer, in decimal.
928
929
930
931       val int_of_string : string -> int
932
933       Convert the given string to an integer.  The string is read in  decimal
934       (by  default,  or if the string begins with 0u ), in hexadecimal (if it
935       begins with 0x or 0X ), in octal (if it begins with 0o or 0O ),  or  in
936       binary (if it begins with 0b or 0B ).
937
938       The  0u  prefix reads the input as an unsigned integer in the range [0,
939       2*max_int+1] .  If the input exceeds Pervasives.max_int it is converted
940       to the signed integer min_int + input - max_int - 1 .
941
942       The  _  (underscore) character can appear anywhere in the string and is
943       ignored.  Raise Failure int_of_string if the  given  string  is  not  a
944       valid  representation  of  an  integer,  or  if the integer represented
945       exceeds the range of integers representable in type int .
946
947
948
949       val int_of_string_opt : string -> int option
950
951       Same as int_of_string , but returns None instead of raising.
952
953
954       Since 4.05
955
956
957
958       val string_of_float : float -> string
959
960       Return the string representation of a floating-point number.
961
962
963
964       val float_of_string : string -> float
965
966       Convert the given string to a float.  The string is read in decimal (by
967       default)  or in hexadecimal (marked by 0x or 0X ).  The format of deci‐
968       mal floating-point numbers is [-] dd.ddd  (e|E)  [+|-]  dd  ,  where  d
969       stands  for  a decimal digit.  The format of hexadecimal floating-point
970       numbers is [-] 0(x|X) hh.hhh (p|P) [+|-] dd , where  h  stands  for  an
971       hexadecimal  digit  and d for a decimal digit.  In both cases, at least
972       one of the integer and fractional parts must  be  given;  the  exponent
973       part  is optional.  The _ (underscore) character can appear anywhere in
974       the string and is ignored.  Depending on the execution platforms, other
975       representations  of  floating-point numbers can be accepted, but should
976       not be relied upon.  Raise Failure float_of_string if the given  string
977       is not a valid representation of a float.
978
979
980
981       val float_of_string_opt : string -> float option
982
983       Same as float_of_string , but returns None instead of raising.
984
985
986       Since 4.05
987
988
989
990
991       === Pair operations ===
992
993
994       val fst : 'a * 'b -> 'a
995
996       Return the first component of a pair.
997
998
999
1000       val snd : 'a * 'b -> 'b
1001
1002       Return the second component of a pair.
1003
1004
1005
1006
1007       ===  List  operations More list operations are provided in module List.
1008       ===
1009
1010
1011       val (@) : 'a list -> 'a list -> 'a list
1012
1013       List concatenation.  Not tail-recursive (length of the first argument).
1014       Right-associative operator at precedence level 5/11.
1015
1016
1017
1018
1019       ===  Input/output  Note: all input/output functions can raise Sys_error
1020       when the system calls they invoke fail. ===
1021
1022
1023       type in_channel
1024
1025
1026       The type of input channel.
1027
1028
1029       type out_channel
1030
1031
1032       The type of output channel.
1033
1034
1035
1036       val stdin : in_channel
1037
1038       The standard input for the process.
1039
1040
1041
1042       val stdout : out_channel
1043
1044       The standard output for the process.
1045
1046
1047
1048       val stderr : out_channel
1049
1050       The standard error output for the process.
1051
1052
1053
1054
1055       === Output functions on standard output ===
1056
1057
1058       val print_char : char -> unit
1059
1060       Print a character on standard output.
1061
1062
1063
1064       val print_string : string -> unit
1065
1066       Print a string on standard output.
1067
1068
1069
1070       val print_bytes : bytes -> unit
1071
1072       Print a byte sequence on standard output.
1073
1074
1075       Since 4.02.0
1076
1077
1078
1079       val print_int : int -> unit
1080
1081       Print an integer, in decimal, on standard output.
1082
1083
1084
1085       val print_float : float -> unit
1086
1087       Print a floating-point number, in decimal, on standard output.
1088
1089
1090
1091       val print_endline : string -> unit
1092
1093       Print a string, followed by a newline character, on standard output and
1094       flush standard output.
1095
1096
1097
1098       val print_newline : unit -> unit
1099
1100       Print  a  newline character on standard output, and flush standard out‐
1101       put. This can be used to simulate line buffering of standard output.
1102
1103
1104
1105
1106       === Output functions on standard error ===
1107
1108
1109       val prerr_char : char -> unit
1110
1111       Print a character on standard error.
1112
1113
1114
1115       val prerr_string : string -> unit
1116
1117       Print a string on standard error.
1118
1119
1120
1121       val prerr_bytes : bytes -> unit
1122
1123       Print a byte sequence on standard error.
1124
1125
1126       Since 4.02.0
1127
1128
1129
1130       val prerr_int : int -> unit
1131
1132       Print an integer, in decimal, on standard error.
1133
1134
1135
1136       val prerr_float : float -> unit
1137
1138       Print a floating-point number, in decimal, on standard error.
1139
1140
1141
1142       val prerr_endline : string -> unit
1143
1144       Print a string, followed by a newline character on standard  error  and
1145       flush standard error.
1146
1147
1148
1149       val prerr_newline : unit -> unit
1150
1151       Print a newline character on standard error, and flush standard error.
1152
1153
1154
1155
1156       === Input functions on standard input ===
1157
1158
1159       val read_line : unit -> string
1160
1161       Flush standard output, then read characters from standard input until a
1162       newline character is encountered. Return the string of  all  characters
1163       read, without the newline character at the end.
1164
1165
1166
1167       val read_int : unit -> int
1168
1169       Flush  standard output, then read one line from standard input and con‐
1170       vert it to an integer. Raise Failure int_of_string if the line read  is
1171       not a valid representation of an integer.
1172
1173
1174
1175       val read_int_opt : unit -> int option
1176
1177       Same as read_int_opt , but returns None instead of raising.
1178
1179
1180       Since 4.05
1181
1182
1183
1184       val read_float : unit -> float
1185
1186       Flush  standard output, then read one line from standard input and con‐
1187       vert it to a floating-point number.  The result is unspecified  if  the
1188       line read is not a valid representation of a floating-point number.
1189
1190
1191
1192       val read_float_opt : unit -> float option
1193
1194       Flush  standard output, then read one line from standard input and con‐
1195       vert it to a floating-point number.  Returns None if the line  read  is
1196       not a valid representation of a floating-point number.
1197
1198
1199       Since 4.05.0
1200
1201
1202
1203
1204       === General output functions ===
1205
1206
1207       type open_flag =
1208        | Open_rdonly  (* open for reading.
1209        *)
1210        | Open_wronly  (* open for writing.
1211        *)
1212        | Open_append  (* open for appending: always write at end of file.
1213        *)
1214        | Open_creat  (* create the file if it does not exist.
1215        *)
1216        | Open_trunc  (* empty the file if it already exists.
1217        *)
1218        | Open_excl  (* fail if Open_creat and the file already exists.
1219        *)
1220        | Open_binary  (* open in binary mode (no conversion).
1221        *)
1222        | Open_text  (* open in text mode (may perform conversions).
1223        *)
1224        | Open_nonblock  (* open in non-blocking mode.
1225        *)
1226
1227
1228       Opening modes for Pervasives.open_out_gen and Pervasives.open_in_gen .
1229
1230
1231
1232       val open_out : string -> out_channel
1233
1234       Open  the  named  file  for writing, and return a new output channel on
1235       that file, positioned at the beginning of the file. The file  is  trun‐
1236       cated to zero length if it already exists. It is created if it does not
1237       already exists.
1238
1239
1240
1241       val open_out_bin : string -> out_channel
1242
1243       Same as Pervasives.open_out , but the file is opened in binary mode, so
1244       that  no  translation  takes  place during writes. On operating systems
1245       that do not distinguish between text mode and binary mode,  this  func‐
1246       tion behaves like Pervasives.open_out .
1247
1248
1249
1250       val open_out_gen : open_flag list -> int -> string -> out_channel
1251
1252
1253       open_out_gen  mode  perm  filename opens the named file for writing, as
1254       described above. The extra argument mode specifies  the  opening  mode.
1255       The  extra  argument  perm  specifies the file permissions, in case the
1256       file must be created.  Pervasives.open_out and  Pervasives.open_out_bin
1257       are special cases of this function.
1258
1259
1260
1261       val flush : out_channel -> unit
1262
1263       Flush  the  buffer associated with the given output channel, performing
1264       all pending writes on that channel.  Interactive programs must be care‐
1265       ful  about  flushing  standard  output  and standard error at the right
1266       time.
1267
1268
1269
1270       val flush_all : unit -> unit
1271
1272       Flush all open output channels; ignore errors.
1273
1274
1275
1276       val output_char : out_channel -> char -> unit
1277
1278       Write the character on the given output channel.
1279
1280
1281
1282       val output_string : out_channel -> string -> unit
1283
1284       Write the string on the given output channel.
1285
1286
1287
1288       val output_bytes : out_channel -> bytes -> unit
1289
1290       Write the byte sequence on the given output channel.
1291
1292
1293       Since 4.02.0
1294
1295
1296
1297       val output : out_channel -> bytes -> int -> int -> unit
1298
1299
1300       output oc buf pos len writes len characters from byte  sequence  buf  ,
1301       starting  at  offset  pos  ,  to  the  given output channel oc .  Raise
1302       Invalid_argument output if pos and len do not designate a  valid  range
1303       of buf .
1304
1305
1306
1307       val output_substring : out_channel -> string -> int -> int -> unit
1308
1309       Same  as  output  but  take  a  string  as  argument  instead of a byte
1310       sequence.
1311
1312
1313       Since 4.02.0
1314
1315
1316
1317       val output_byte : out_channel -> int -> unit
1318
1319       Write one 8-bit integer (as the single character with that code) on the
1320       given output channel. The given integer is taken modulo 256.
1321
1322
1323
1324       val output_binary_int : out_channel -> int -> unit
1325
1326       Write  one  integer in binary format (4 bytes, big-endian) on the given
1327       output channel.  The given integer is  taken  modulo  2^32.   The  only
1328       reliable way to read it back is through the Pervasives.input_binary_int
1329       function. The format is compatible across all machines for a given ver‐
1330       sion of OCaml.
1331
1332
1333
1334       val output_value : out_channel -> 'a -> unit
1335
1336       Write  the  representation of a structured value of any type to a chan‐
1337       nel. Circularities and sharing inside the value are detected  and  pre‐
1338       served.   The   object  can  be  read  back,  by  the  function  Perva‐
1339       sives.input_value . See the description  of  module  Marshal  for  more
1340       information.  Pervasives.output_value is equivalent to Marshal.to_chan‐
1341       nel with an empty list of flags.
1342
1343
1344
1345       val seek_out : out_channel -> int -> unit
1346
1347
1348       seek_out chan pos sets the current writing position to pos for  channel
1349       chan . This works only for regular files. On files of other kinds (such
1350       as terminals, pipes and sockets), the behavior is unspecified.
1351
1352
1353
1354       val pos_out : out_channel -> int
1355
1356       Return the current writing position for the given  channel.   Does  not
1357       work  on channels opened with the Open_append flag (returns unspecified
1358       results).
1359
1360
1361
1362       val out_channel_length : out_channel -> int
1363
1364       Return the size (number of characters) of the regular file on which the
1365       given  channel  is  opened.  If the channel is opened on a file that is
1366       not a regular file, the result is meaningless.
1367
1368
1369
1370       val close_out : out_channel -> unit
1371
1372       Close the given channel, flushing all buffered write operations.   Out‐
1373       put  functions  raise  a Sys_error exception when they are applied to a
1374       closed output channel, except close_out and flush ,  which  do  nothing
1375       when  applied  to  an  already closed channel.  Note that close_out may
1376       raise Sys_error if the operating system signals an error when  flushing
1377       or closing.
1378
1379
1380
1381       val close_out_noerr : out_channel -> unit
1382
1383       Same as close_out , but ignore all errors.
1384
1385
1386
1387       val set_binary_mode_out : out_channel -> bool -> unit
1388
1389
1390       set_binary_mode_out  oc  true  sets  the  channel oc to binary mode: no
1391       translations take place during output.   set_binary_mode_out  oc  false
1392       sets  the  channel  oc to text mode: depending on the operating system,
1393       some translations may take place during output.   For  instance,  under
1394       Windows,  end-of-lines will be translated from \n to \r\n .  This func‐
1395       tion has no effect under operating  systems  that  do  not  distinguish
1396       between text mode and binary mode.
1397
1398
1399
1400
1401       === General input functions ===
1402
1403
1404       val open_in : string -> in_channel
1405
1406       Open the named file for reading, and return a new input channel on that
1407       file, positioned at the beginning of the file.
1408
1409
1410
1411       val open_in_bin : string -> in_channel
1412
1413       Same as Pervasives.open_in , but the file is opened in binary mode,  so
1414       that no translation takes place during reads. On operating systems that
1415       do not distinguish between text mode and  binary  mode,  this  function
1416       behaves like Pervasives.open_in .
1417
1418
1419
1420       val open_in_gen : open_flag list -> int -> string -> in_channel
1421
1422
1423       open_in_gen  mode  perm  filename  opens the named file for reading, as
1424       described above. The extra arguments mode and perm specify the  opening
1425       mode    and    file   permissions.    Pervasives.open_in   and   Perva‐
1426       sives.open_in_bin are special cases of this function.
1427
1428
1429
1430       val input_char : in_channel -> char
1431
1432       Read one character from the given input channel.  Raise End_of_file  if
1433       there are no more characters to read.
1434
1435
1436
1437       val input_line : in_channel -> string
1438
1439       Read characters from the given input channel, until a newline character
1440       is encountered. Return the string of all characters read,  without  the
1441       newline character at the end.  Raise End_of_file if the end of the file
1442       is reached at the beginning of line.
1443
1444
1445
1446       val input : in_channel -> bytes -> int -> int -> int
1447
1448
1449       input ic buf pos len reads up to len characters from the given  channel
1450       ic  ,  storing them in byte sequence buf , starting at character number
1451       pos .  It returns the actual number of characters read, between  0  and
1452       len  (inclusive).   A  return value of 0 means that the end of file was
1453       reached.  A return value between 0 and len exclusive means that not all
1454       requested  len  characters were read, either because no more characters
1455       were available at that time, or because  the  implementation  found  it
1456       convenient to do a partial read; input must be called again to read the
1457       remaining characters, if desired.   (See  also  Pervasives.really_input
1458       for  reading exactly len characters.)  Exception Invalid_argument input
1459       is raised if pos and len do not designate a valid range of buf .
1460
1461
1462
1463       val really_input : in_channel -> bytes -> int -> int -> unit
1464
1465
1466       really_input ic buf pos len reads len  characters  from  channel  ic  ,
1467       storing  them in byte sequence buf , starting at character number pos .
1468       Raise End_of_file if the end of file is reached before  len  characters
1469       have  been read.  Raise Invalid_argument really_input if pos and len do
1470       not designate a valid range of buf .
1471
1472
1473
1474       val really_input_string : in_channel -> int -> string
1475
1476
1477       really_input_string ic len reads len characters  from  channel  ic  and
1478       returns  them in a new string.  Raise End_of_file if the end of file is
1479       reached before len characters have been read.
1480
1481
1482       Since 4.02.0
1483
1484
1485
1486       val input_byte : in_channel -> int
1487
1488       Same as Pervasives.input_char , but return the 8-bit integer represent‐
1489       ing the character.  Raise End_of_file if an end of file was reached.
1490
1491
1492
1493       val input_binary_int : in_channel -> int
1494
1495       Read an integer encoded in binary format (4 bytes, big-endian) from the
1496       given  input  channel.  See   Pervasives.output_binary_int   .    Raise
1497       End_of_file if an end of file was reached while reading the integer.
1498
1499
1500
1501       val input_value : in_channel -> 'a
1502
1503       Read  the  representation  of a structured value, as produced by Perva‐
1504       sives.output_value , and return the corresponding value.  This function
1505       is  identical  to  Marshal.from_channel ; see the description of module
1506       Marshal for more information, in particular concerning the lack of type
1507       safety.
1508
1509
1510
1511       val seek_in : in_channel -> int -> unit
1512
1513
1514       seek_in  chan  pos sets the current reading position to pos for channel
1515       chan . This works only for regular files. On files of other kinds,  the
1516       behavior is unspecified.
1517
1518
1519
1520       val pos_in : in_channel -> int
1521
1522       Return the current reading position for the given channel.
1523
1524
1525
1526       val in_channel_length : in_channel -> int
1527
1528       Return the size (number of characters) of the regular file on which the
1529       given channel is opened.  If the channel is opened on a  file  that  is
1530       not  a regular file, the result is meaningless.  The returned size does
1531       not take into account the end-of-line translations  that  can  be  per‐
1532       formed when reading from a channel opened in text mode.
1533
1534
1535
1536       val close_in : in_channel -> unit
1537
1538       Close  the  given channel.  Input functions raise a Sys_error exception
1539       when they are applied to a closed  input  channel,  except  close_in  ,
1540       which does nothing when applied to an already closed channel.
1541
1542
1543
1544       val close_in_noerr : in_channel -> unit
1545
1546       Same as close_in , but ignore all errors.
1547
1548
1549
1550       val set_binary_mode_in : in_channel -> bool -> unit
1551
1552
1553       set_binary_mode_in  ic  true  sets  the  channel  ic to binary mode: no
1554       translations take place during  input.   set_binary_mode_out  ic  false
1555       sets  the  channel  ic to text mode: depending on the operating system,
1556       some translations may take place during  input.   For  instance,  under
1557       Windows,  end-of-lines will be translated from \r\n to \n .  This func‐
1558       tion has no effect under operating  systems  that  do  not  distinguish
1559       between text mode and binary mode.
1560
1561
1562
1563
1564       === Operations on large files ===
1565
1566
1567       module LargeFile : sig end
1568
1569
1570       Operations on large files.  This sub-module provides 64-bit variants of
1571       the channel functions that manipulate file positions  and  file  sizes.
1572       By  representing  positions  and sizes by 64-bit integers (type int64 )
1573       instead of regular integers (type  int  ),  these  alternate  functions
1574       allow operating on files whose sizes are greater than max_int .
1575
1576
1577
1578
1579       === References ===
1580
1581
1582       type 'a ref = {
1583
1584       mutable contents : 'a ;
1585        }
1586
1587
1588       The  type  of references (mutable indirection cells) containing a value
1589       of type 'a .
1590
1591
1592
1593       val ref : 'a -> 'a ref
1594
1595       Return a fresh reference containing the given value.
1596
1597
1598
1599       val (!)  : 'a ref -> 'a
1600
1601
1602       !r returns the current contents of reference r .  Equivalent to  fun  r
1603       -> r.contents .  Unary operator at precedence level 11/11.
1604
1605
1606
1607       val (:=) : 'a ref -> 'a -> unit
1608
1609
1610       r := a stores the value of a in reference r .  Equivalent to fun r v ->
1611       r.contents <- v .  Right-associative operator at precedence level 1/11.
1612
1613
1614
1615       val incr : int ref -> unit
1616
1617       Increment the integer contained in the given reference.  Equivalent  to
1618       fun r -> r := succ !r .
1619
1620
1621
1622       val decr : int ref -> unit
1623
1624       Decrement  the integer contained in the given reference.  Equivalent to
1625       fun r -> r := pred !r .
1626
1627
1628
1629
1630       === Result type ===
1631
1632
1633       type ('a, 'b) result =
1634        | Ok of 'a
1635        | Error of 'b
1636
1637
1638       Since 4.03.0
1639
1640
1641
1642
1643       === Operations on format strings ===
1644
1645
1646       === Format strings are character strings with special  lexical  conven‐
1647       tions  that  defines  the functionality of formatted input/output func‐
1648       tions. Format strings are used to read data with formatted input  func‐
1649       tions  from  module Scanf and to print data with formatted output func‐
1650       tions from modules Printf and Format.  Format strings are made of three
1651       kinds of entities: - conversions specifications, introduced by the spe‐
1652       cial character '%' followed by one or more characters  specifying  what
1653       kind of argument to read or print, - formatting indications, introduced
1654       by the special character '@' followed by one or more characters  speci‐
1655       fying  how  to  read or print the argument, - plain characters that are
1656       regular characters with usual  lexical  conventions.  Plain  characters
1657       specify  string literals to be read in the input or printed in the out‐
1658       put.  There is an additional lexical rule to escape the special charac‐
1659       ters  '%'  and  '@' in format strings: if a special character follows a
1660       '%' character, it is treated as a plain character. In other  words,  %%
1661       is  considered as a plain '%' and %@ as a plain '@'.  For more informa‐
1662       tion about conversion specifications and formatting indications  avail‐
1663       able, read the documentation of modules Scanf, Printf and Format. ===
1664
1665
1666       ===  Format strings have a general and highly polymorphic type ('a, 'b,
1667       'c, 'd, 'e, 'f) format6.  The two simplified types, format and  format4
1668       below  are included for backward compatibility with earlier releases of
1669       OCaml.  The meaning of format string type parameters is as  follows:  -
1670       'a  is  the  type  of the parameters of the format for formatted output
1671       functions (printf-style functions); 'a is the type of the  values  read
1672       by the format for formatted input functions (scanf-style functions).  -
1673       'b is the type of input source for formatted input  functions  and  the
1674       type of output target for formatted output functions.  For printf-style
1675       functions  from  module  Printf,  'b  is  typically  out_channel;   for
1676       printf-style  functions from module Format, 'b is typically Format.for‐
1677       matter; for scanf-style functions from module Scanf,  'b  is  typically
1678       Scanf.Scanning.in_channel.   Type  argument  'b is also the type of the
1679       first argument given to user's defined printing functions for %a and %t
1680       conversions, and user's defined reading functions for %r conversion.  -
1681       'c is the type of the result of the %a and %t printing  functions,  and
1682       also  the  type  of  the  argument transmitted to the first argument of
1683       kprintf-style functions or to the kscanf-style functions.  - 'd is  the
1684       type  of parameters for the scanf-style functions.  - 'e is the type of
1685       the receiver function for the scanf-style functions.  - 'f is the final
1686       result  type  of  a formatted input/output function invocation: for the
1687       printf-style functions, it is typically unit; for the scanf-style func‐
1688       tions, it is typically the result type of the receiver function.  ===
1689
1690
1691       type  ('a,  'b, 'c, 'd, 'e, 'f) format6 = ('a, 'b, 'c, 'd, 'e, 'f) Cam‐
1692       linternalFormatBasics.format6
1693
1694
1695
1696
1697       type ('a, 'b, 'c, 'd) format4 = ('a, 'b, 'c, 'c, 'c, 'd) format6
1698
1699
1700
1701
1702       type ('a, 'b, 'c) format = ('a, 'b, 'c, 'c) format4
1703
1704
1705
1706
1707
1708       val string_of_format : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> string
1709
1710       Converts a format string into a string.
1711
1712
1713
1714       val format_of_string : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> ('a, 'b, 'c,
1715       'd, 'e, 'f) format6
1716
1717
1718       format_of_string s returns a format string read from the string literal
1719       s .  Note: format_of_string can not convert a string argument  that  is
1720       not  a  literal.  If  you need this functionality, use the more general
1721       Scanf.format_from_string function.
1722
1723
1724
1725       val (^^) : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> ('f, 'b, 'c, 'e, 'g, 'h)
1726       format6 -> ('a, 'b, 'c, 'd, 'g, 'h) format6
1727
1728
1729       f1  ^^  f2  catenates format strings f1 and f2 . The result is a format
1730       string that behaves as the concatenation of format strings f1 and f2  :
1731       in  case of formatted output, it accepts arguments from f1 , then argu‐
1732       ments from f2 ; in case of formatted input, it returns results from  f1
1733       ,  then  results  from  f2  .  Right-associative operator at precedence
1734       level 5/11.
1735
1736
1737
1738
1739       === Program termination ===
1740
1741
1742       val exit : int -> 'a
1743
1744       Terminate the process, returning the given status code to the operating
1745       system:  usually  0 to indicate no errors, and a small positive integer
1746       to indicate  failure.   All  open  output  channels  are  flushed  with
1747       flush_all .  An implicit exit 0 is performed each time a program termi‐
1748       nates normally.  An implicit exit 2 is performed if the program  termi‐
1749       nates early because of an uncaught exception.
1750
1751
1752
1753       val at_exit : (unit -> unit) -> unit
1754
1755       Register  the  given function to be called at program termination time.
1756       The functions registered with at_exit will be called when  the  program
1757       does any of the following:
1758
1759       -executes Pervasives.exit
1760
1761
1762       -terminates, either normally or because of an uncaught exception
1763
1764       -executes  the  C function caml_shutdown .  The functions are called in
1765       'last in, first out' order:  the  function  most  recently  added  with
1766       at_exit is called first.
1767
1768
1769
1770
1771
1772
1773OCamldoc                          2018-07-14                     Pervasives(3)
Impressum