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

NAME

6       Pervasives - The initially opened module.
7

Module

9       Module   Pervasives
10

Documentation

12       Module Pervasives
13        : sig end
14
15
16       The initially opened module.
17
18       This module provides the basic operations over the built-in types (num‐
19       bers,  booleans,  strings,  exceptions,  references,   lists,   arrays,
20       input-output channels, ...)
21
22       This  module  is automatically opened at the beginning of each compila‐
23       tion.  All components of this module can therefore be referred by their
24       short name, without prefixing them by Pervasives .
25
26
27
28
29
30
31
32
33       === Exceptions ===
34
35
36       val raise : exn -> 'a
37
38       Raise the given exception value
39
40
41
42
43       val invalid_arg : string -> 'a
44
45       Raise exception Invalid_argument with the given string.
46
47
48
49
50       val failwith : string -> 'a
51
52       Raise exception Failure with the given string.
53
54
55
56
57       exception Exit
58
59
60       The  Exit  exception is not raised by any library function.  It is pro‐
61       vided for use in your programs.
62
63
64
65
66
67       === Comparisons ===
68
69
70       val (=) : 'a -> 'a -> bool
71
72
73       e1 = e2 tests for structural equality of e1 and e2  .   Mutable  struc‐
74       tures  (e.g. references and arrays) are equal if and only if their cur‐
75       rent contents are structurally equal, even if the two  mutable  objects
76       are  not  the same physical object.  Equality between functional values
77       raises Invalid_argument .  Equality between cyclic data structures  may
78       not terminate.
79
80
81
82
83       val (<>) : 'a -> 'a -> bool
84
85       Negation of Pervasives.(=) .
86
87
88
89
90       val (<) : 'a -> 'a -> bool
91
92       See Pervasives.(>=) .
93
94
95
96
97       val (>) : 'a -> 'a -> bool
98
99       See Pervasives.(>=) .
100
101
102
103
104       val (<=) : 'a -> 'a -> bool
105
106       See Pervasives.(>=) .
107
108
109
110
111       val (>=) : 'a -> 'a -> bool
112
113       Structural  ordering functions. These functions coincide with the usual
114       orderings over integers, characters, strings  and  floating-point  num‐
115       bers, and extend them to a total ordering over all types.  The ordering
116       is compatible with (=) . As in the case of (=) , mutable structures are
117       compared  by  contents.   Comparison  between  functional values raises
118       Invalid_argument .  Comparison between cyclic structures may not termi‐
119       nate.
120
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
148       val min : 'a -> 'a -> 'a
149
150       Return the smaller of the two arguments.  The result is unspecified  if
151       one of the arguments contains the float value nan .
152
153
154
155
156       val max : 'a -> 'a -> 'a
157
158       Return  the greater of the two arguments.  The result is unspecified if
159       one of the arguments contains the float value nan .
160
161
162
163
164       val (==) : 'a -> 'a -> bool
165
166
167       e1 == e2 tests for physical equality of e1 and e2 .  On mutable  struc‐
168       tures, e1 == e2 is true if and only if physical modification of e1 also
169       affects e2 .  On non-mutable structures, the behavior of (==) is imple‐
170       mentation-dependent;  however,  it  is guaranteed that e1 == e2 implies
171       compare e1 e2 = 0 .
172
173
174
175
176       val (!=) : 'a -> 'a -> bool
177
178       Negation of Pervasives.(==) .
179
180
181
182
183
184       === Boolean operations ===
185
186
187       val not : bool -> bool
188
189       The boolean negation.
190
191
192
193
194       val (&&) : bool -> bool -> bool
195
196       The boolean ``and''. Evaluation is sequential, left-to-right: in e1  &&
197       e2  , e1 is evaluated first, and if it returns false , e2 is not evalu‐
198       ated at all.
199
200
201
202
203       val (&) : bool -> bool -> bool
204
205       Deprecated.
206
207       Pervasives.(&&) should be used instead.
208
209
210
211
212       val (||) : bool -> bool -> bool
213
214       The boolean ``or''. Evaluation is sequential, left-to-right: in  e1  ||
215       e2  ,  e1 is evaluated first, and if it returns true , e2 is not evalu‐
216       ated at all.
217
218
219
220
221       val (or) : bool -> bool -> bool
222
223       Deprecated.
224
225       Pervasives.(||) should be used instead.
226
227
228
229
230
231       === Integer arithmetic ===
232
233
234       === Integers are 31 bits wide (or 63 bits on 64-bit  processors).   All
235       operations  are  taken  modulo 2^{31} (or 2^{63}).  They do not fail on
236       overflow. ===
237
238
239       val (~-) : int -> int
240
241       Unary negation. You can also write -e instead of ~-e .
242
243
244
245
246       val succ : int -> int
247
248
249       succ x is x+1 .
250
251
252
253
254       val pred : int -> int
255
256
257       pred x is x-1 .
258
259
260
261
262       val (+) : int -> int -> int
263
264       Integer addition.
265
266
267
268
269       val (-) : int -> int -> int
270
271       Integer subtraction.
272
273
274
275
276       val ( * ) : int -> int -> int
277
278       Integer multiplication.
279
280
281
282
283       val (/) : int -> int -> int
284
285       Integer division.  Raise Division_by_zero if the second argument is  0.
286       Integer  division  rounds  the  real  quotient of its arguments towards
287       zero.  More precisely, if x >= 0 and y > 0 , x  /  y  is  the  greatest
288       integer  less than or equal to the real quotient of x by y .  Moreover,
289       (-x) / y = x / (-y) = -(x / y) .
290
291
292
293
294       val (mod) : int -> int -> int
295
296       Integer remainder.  If y is not zero, the result of x mod  y  satisfies
297       the following properties: x = (x / y) * y + x mod y and abs(x mod y) <=
298       abs(y)-1 .  If y = 0 , x mod y raises Division_by_zero .  Notice that x
299       mod  y is nonpositive if and only if x < 0 .  Raise Division_by_zero if
300       y is zero.
301
302
303
304
305       val abs : int -> int
306
307       Return the absolute value of the argument.  Note that this may be nega‐
308       tive if the argument is min_int .
309
310
311
312
313       val max_int : int
314
315       The greatest representable integer.
316
317
318
319
320       val min_int : int
321
322       The smallest representable integer.
323
324
325
326
327
328       === Bitwise operations ===
329
330
331       val (land) : int -> int -> int
332
333       Bitwise logical and.
334
335
336
337
338       val (lor) : int -> int -> int
339
340       Bitwise logical or.
341
342
343
344
345       val (lxor) : int -> int -> int
346
347       Bitwise logical exclusive or.
348
349
350
351
352       val lnot : int -> int
353
354       Bitwise logical negation.
355
356
357
358
359       val (lsl) : int -> int -> int
360
361
362       n lsl m shifts n to the left by m bits.  The result is unspecified if m
363       < 0 or m >= bitsize , where bitsize is 32 on a 32-bit platform  and  64
364       on a 64-bit platform.
365
366
367
368
369       val (lsr) : int -> int -> int
370
371
372       n  lsr  m  shifts  n  to the right by m bits.  This is a logical shift:
373       zeroes are inserted regardless of the  sign  of  n  .   The  result  is
374       unspecified if m < 0 or m >= bitsize .
375
376
377
378
379       val (asr) : int -> int -> int
380
381
382       n  asr m shifts n to the right by m bits.  This is an arithmetic shift:
383       the sign bit of n is replicated.  The result is unspecified if m < 0 or
384       m >= bitsize .
385
386
387
388
389
390       ===  Floating-point arithmetic Caml's floating-point numbers follow the
391       IEEE 754 standard, using double precision (64  bits)  numbers.   Float‐
392       ing-point  operations  never raise an exception on overflow, underflow,
393       division by zero, etc. Instead, special IEEE numbers  are  returned  as
394       appropriate,  such as infinity for 1.0 /. 0.0, neg_infinity for -1.0 /.
395       0.0, and nan (``not a number'') for 0.0 /. 0.0. These  special  numbers
396       then  propagate  through  floating-point  computations as expected: for
397       instance, 1.0 /. infinity is 0.0, and any arithmetic operation with nan
398       as argument returns nan as result. ===
399
400
401       val (~-.)  : float -> float
402
403       Unary negation. You can also write -.e instead of ~-.e .
404
405
406
407
408       val (+.)  : float -> float -> float
409
410       Floating-point addition
411
412
413
414
415       val (-.)  : float -> float -> float
416
417       Floating-point subtraction
418
419
420
421
422       val ( *. ) : float -> float -> float
423
424       Floating-point multiplication
425
426
427
428
429       val (/.)  : float -> float -> float
430
431       Floating-point division.
432
433
434
435
436       val ( ** ) : float -> float -> float
437
438       Exponentiation.
439
440
441
442
443       val sqrt : float -> float
444
445       Square root.
446
447
448
449
450       val exp : float -> float
451
452       Exponential.
453
454
455
456
457       val log : float -> float
458
459       Natural logarithm.
460
461
462
463
464       val log10 : float -> float
465
466       Base 10 logarithm.
467
468
469
470
471       val cos : float -> float
472
473
474       cos a returns the cosine of angle a measured in radians.
475
476
477
478
479       val sin : float -> float
480
481
482       sin a returns the sine of angle a measured in radians.
483
484
485
486
487       val tan : float -> float
488
489
490       tan a returns the tangent of angle a measured in radians.
491
492
493
494
495       val acos : float -> float
496
497
498       acos  f  returns  the arc cosine of f . The return angle is measured in
499       radians.
500
501
502
503
504       val asin : float -> float
505
506
507       asin f returns the arc sine of f . The  return  angle  is  measured  in
508       radians.
509
510
511
512
513       val atan : float -> float
514
515
516       atan  f  returns the arc tangent of f . The return angle is measured in
517       radians.
518
519
520
521
522       val atan2 : float -> float -> float
523
524
525       atan2 y x returns the principal value of the arc tangent of  y  /  x  ,
526       using  the  signs  of  both  arguments to determine the quadrant of the
527       result. The return angle is measured in radians.
528
529
530
531
532       val cosh : float -> float
533
534
535       cosh a returns the hyperbolic cosine of angle a measured in radians.
536
537
538
539
540       val sinh : float -> float
541
542
543       sinh a returns the hyperbolic sine of angle a measured in radians.
544
545
546
547
548       val tanh : float -> float
549
550
551       tanh f returns the hyperbolic tangent of angle a measured in radians.
552
553
554
555
556       val ceil : float -> float
557
558       Round the given float to an integer value.  ceil f  returns  the  least
559       integer value greater than or equal to f .  See also Pervasives.floor .
560
561
562
563
564       val floor : float -> float
565
566       Round  the given float to an integer value.  floor f returns the great‐
567       est integer value less than or equal to f .  See also Pervasives.ceil .
568
569
570
571
572       val abs_float : float -> float
573
574
575       abs_float f returns the absolute value of f .
576
577
578
579
580       val mod_float : float -> float -> float
581
582
583       mod_float a b returns the remainder of a  with  respect  to  b  .   The
584       returned  value is a -. n *. b , where n is the quotient a /. b rounded
585       towards zero to an integer.
586
587
588
589
590       val frexp : float -> float * int
591
592
593       frexp f returns the pair of the significant and the  exponent  of  f  .
594       When  f is zero, the significant x and the exponent n of f are equal to
595       zero.  When f is non-zero, they are defined by f = x *. 2 ** n and  0.5
596       <= x < 1.0 .
597
598
599
600
601       val ldexp : float -> int -> float
602
603
604       ldexp x n returns x *. 2 ** n .
605
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
616
617       val float : int -> float
618
619       Same as Pervasives.float_of_int .
620
621
622
623
624       val float_of_int : int -> float
625
626       Convert an integer to floating-point.
627
628
629
630
631       val truncate : float -> int
632
633       Same as Pervasives.int_of_float .
634
635
636
637
638       val int_of_float : float -> int
639
640       Truncate  the given floating-point number to an integer.  The result is
641       unspecified if the argument is nan or falls outside the range of repre‐
642       sentable integers.
643
644
645
646
647       val infinity : float
648
649       Positive infinity.
650
651
652
653
654       val neg_infinity : float
655
656       Negative infinity.
657
658
659
660
661       val nan : float
662
663       A  special  floating-point  value  denoting  the result of an undefined
664       operation such as 0.0 /. 0.0 .   Stands  for  ``not  a  number''.   Any
665       floating-point  operation  with  nan as argument returns nan as result.
666       As for floating-point comparisons, = , < , <= , > and >=  return  false
667       and <> returns true if one or both of their arguments is nan .
668
669
670
671
672       val max_float : float
673
674       The largest positive finite value of type float .
675
676
677
678
679       val min_float : float
680
681       The smallest positive, non-zero, non-denormalized value of type float .
682
683
684
685
686       val epsilon_float : float
687
688       The  difference  between  1.0  and  the  smallest exactly representable
689       floating-point number greater than 1.0 .
690
691
692
693       type fpclass =
694        | FP_normal  (* Normal number, none of the below *)
695        | FP_subnormal  (* Number very close to 0.0, has reduced precision *)
696        | FP_zero  (* Number is 0.0 or -0.0 *)
697        | FP_infinite  (* Number is positive or negative infinity *)
698        | FP_nan  (* Not a number: result of an undefined operation *)
699
700
701       The five classes of floating-point numbers, as determined by the Perva‐
702       sives.classify_float function.
703
704
705
706
707       val classify_float : float -> fpclass
708
709       Return the class of the given floating-point number: normal, subnormal,
710       zero, infinite, or not a number.
711
712
713
714
715
716       === String operations More string operations  are  provided  in  module
717       String. ===
718
719
720       val (^) : string -> string -> string
721
722       String concatenation.
723
724
725
726
727
728       === Character operations More character operations are provided in mod‐
729       ule Char. ===
730
731
732       val int_of_char : char -> int
733
734       Return the ASCII code of the argument.
735
736
737
738
739       val char_of_int : int -> char
740
741       Return the character with the given ASCII code.  Raise Invalid_argument
742       char_of_int if the argument is outside the range 0--255.
743
744
745
746
747
748       === Unit operations ===
749
750
751       val ignore : 'a -> unit
752
753       Discard  the  value  of  its  argument  and  return () .  For instance,
754       ignore(f x) discards the result of the side-effecting function f .   It
755       is  equivalent  to f x; () , except that the latter may generate a com‐
756       piler warning; writing ignore(f x) instead avoids the warning.
757
758
759
760
761
762       === String conversion functions ===
763
764
765       val string_of_bool : bool -> string
766
767       Return the string representation of a boolean.
768
769
770
771
772       val bool_of_string : string -> bool
773
774       Convert  the  given  string  to  a  boolean.   Raise   Invalid_argument
775       bool_of_string if the string is not true or false .
776
777
778
779
780       val string_of_int : int -> string
781
782       Return the string representation of an integer, in decimal.
783
784
785
786
787       val int_of_string : string -> int
788
789       Convert  the given string to an integer.  The string is read in decimal
790       (by default) or in hexadecimal (if it begins with 0x or 0X ), octal (if
791       it  begins  with  0o  or 0O ), or binary (if it begins with 0b or 0B ).
792       Raise Failure int_of_string if the given string is not a  valid  repre‐
793       sentation  of  an  integer,  or  if the integer represented exceeds the
794       range of integers representable in type int .
795
796
797
798
799       val string_of_float : float -> string
800
801       Return the string representation of a floating-point number.
802
803
804
805
806       val float_of_string : string -> float
807
808       Convert the given string to a float.  Raise Failure float_of_string  if
809       the given string is not a valid representation of a float.
810
811
812
813
814
815       === Pair operations ===
816
817
818       val fst : 'a * 'b -> 'a
819
820       Return the first component of a pair.
821
822
823
824
825       val snd : 'a * 'b -> 'b
826
827       Return the second component of a pair.
828
829
830
831
832
833       ===  List  operations More list operations are provided in module List.
834       ===
835
836
837       val (@) : 'a list -> 'a list -> 'a list
838
839       List concatenation.
840
841
842
843
844
845       === Input/output ===
846
847
848       type in_channel
849
850
851       The type of input channel.
852
853
854
855       type out_channel
856
857
858       The type of output channel.
859
860
861
862
863       val stdin : in_channel
864
865       The standard input for the process.
866
867
868
869
870       val stdout : out_channel
871
872       The standard output for the process.
873
874
875
876
877       val stderr : out_channel
878
879       The standard error ouput for the process.
880
881
882
883
884
885       === Output functions on standard output ===
886
887
888       val print_char : char -> unit
889
890       Print a character on standard output.
891
892
893
894
895       val print_string : string -> unit
896
897       Print a string on standard output.
898
899
900
901
902       val print_int : int -> unit
903
904       Print an integer, in decimal, on standard output.
905
906
907
908
909       val print_float : float -> unit
910
911       Print a floating-point number, in decimal, on standard output.
912
913
914
915
916       val print_endline : string -> unit
917
918       Print a string, followed by a newline character, on standard output and
919       flush standard output.
920
921
922
923
924       val print_newline : unit -> unit
925
926       Print  a  newline character on standard output, and flush standard out‐
927       put. This can be used to simulate line buffering of standard output.
928
929
930
931
932
933       === Output functions on standard error ===
934
935
936       val prerr_char : char -> unit
937
938       Print a character on standard error.
939
940
941
942
943       val prerr_string : string -> unit
944
945       Print a string on standard error.
946
947
948
949
950       val prerr_int : int -> unit
951
952       Print an integer, in decimal, on standard error.
953
954
955
956
957       val prerr_float : float -> unit
958
959       Print a floating-point number, in decimal, on standard error.
960
961
962
963
964       val prerr_endline : string -> unit
965
966       Print a string, followed by a newline character on standard  error  and
967       flush standard error.
968
969
970
971
972       val prerr_newline : unit -> unit
973
974       Print a newline character on standard error, and flush standard error.
975
976
977
978
979
980       === Input functions on standard input ===
981
982
983       val read_line : unit -> string
984
985       Flush standard output, then read characters from standard input until a
986       newline character is encountered. Return the string of  all  characters
987       read, without the newline character at the end.
988
989
990
991
992       val read_int : unit -> int
993
994       Flush  standard output, then read one line from standard input and con‐
995       vert it to an integer. Raise Failure int_of_string if the line read  is
996       not a valid representation of an integer.
997
998
999
1000
1001       val read_float : unit -> float
1002
1003       Flush  standard output, then read one line from standard input and con‐
1004       vert it to a floating-point number.  The result is unspecified  if  the
1005       line read is not a valid representation of a floating-point number.
1006
1007
1008
1009
1010
1011       === General output functions ===
1012
1013
1014       type open_flag =
1015        | Open_rdonly  (* open for reading. *)
1016        | Open_wronly  (* open for writing. *)
1017        | Open_append  (* open for appending: always write at end of file. *)
1018        | Open_creat  (* create the file if it does not exist. *)
1019        | Open_trunc  (* empty the file if it already exists. *)
1020        | Open_excl  (* fail if Open_creat and the file already exists. *)
1021        | Open_binary  (* open in binary mode (no conversion). *)
1022        | Open_text  (* open in text mode (may perform conversions). *)
1023        | Open_nonblock  (* open in non-blocking mode. *)
1024
1025
1026       Opening modes for Pervasives.open_out_gen and Pervasives.open_in_gen .
1027
1028
1029
1030
1031       val open_out : string -> out_channel
1032
1033       Open  the  named  file  for writing, and return a new output channel on
1034       that file, positionned at the beginning of the file. The file is  trun‐
1035       cated to zero length if it already exists. It is created if it does not
1036       already exists.  Raise Sys_error if the file could not be opened.
1037
1038
1039
1040
1041       val open_out_bin : string -> out_channel
1042
1043       Same as Pervasives.open_out , but the file is opened in binary mode, so
1044       that  no  translation  takes  place during writes. On operating systems
1045       that do not distinguish between text mode and binary mode,  this  func‐
1046       tion behaves like Pervasives.open_out .
1047
1048
1049
1050
1051       val open_out_gen : open_flag list -> int -> string -> out_channel
1052
1053
1054       open_out_gen  mode  perm  filename opens the named file for writing, as
1055       described above. The extra argument mode specify the opening mode.  The
1056       extra  argument  perm  specifies the file permissions, in case the file
1057       must be created.  Pervasives.open_out and  Pervasives.open_out_bin  are
1058       special cases of this function.
1059
1060
1061
1062
1063       val flush : out_channel -> unit
1064
1065       Flush  the  buffer associated with the given output channel, performing
1066       all pending writes on that channel.  Interactive programs must be care‐
1067       ful  about  flushing  standard  output  and standard error at the right
1068       time.
1069
1070
1071
1072
1073       val flush_all : unit -> unit
1074
1075       Flush all open output channels; ignore errors.
1076
1077
1078
1079
1080       val output_char : out_channel -> char -> unit
1081
1082       Write the character on the given output channel.
1083
1084
1085
1086
1087       val output_string : out_channel -> string -> unit
1088
1089       Write the string on the given output channel.
1090
1091
1092
1093
1094       val output : out_channel -> string -> int -> int -> unit
1095
1096
1097       output oc buf pos len writes len characters from string buf ,  starting
1098       at  offset  pos , to the given output channel oc .  Raise Invalid_argu‐
1099       ment output if pos and len do not designate a valid substring of buf .
1100
1101
1102
1103
1104       val output_byte : out_channel -> int -> unit
1105
1106       Write one 8-bit integer (as the single character with that code) on the
1107       given output channel. The given integer is taken modulo 256.
1108
1109
1110
1111
1112       val output_binary_int : out_channel -> int -> unit
1113
1114       Write  one  integer in binary format (4 bytes, big-endian) on the given
1115       output channel.  The given integer is taken  modulo  2^{32.   The  only
1116       reliable way to read it back is through the Pervasives.input_binary_int
1117       function. The format is compatible across all machines for a given ver‐
1118       sion of Objective Caml.
1119
1120
1121
1122
1123       val output_value : out_channel -> 'a -> unit
1124
1125       Write  the  representation of a structured value of any type to a chan‐
1126       nel. Circularities and sharing inside the value are detected  and  pre‐
1127       served.   The   object  can  be  read  back,  by  the  function  Perva‐
1128       sives.input_value . See the description  of  module  Marshal  for  more
1129       information.  Pervasives.output_value is equivalent to Marshal.to_chan‐
1130       nel with an empty list of flags.
1131
1132
1133
1134
1135       val seek_out : out_channel -> int -> unit
1136
1137
1138       seek_out chan pos sets the current writing position to pos for  channel
1139       chan . This works only for regular files. On files of other kinds (such
1140       as terminals, pipes and sockets), the behavior is unspecified.
1141
1142
1143
1144
1145       val pos_out : out_channel -> int
1146
1147       Return the current writing position for the given  channel.   Does  not
1148       work  on channels opened with the Open_append flag (returns unspecified
1149       results).
1150
1151
1152
1153
1154       val out_channel_length : out_channel -> int
1155
1156       Return the size (number of characters) of the regular file on which the
1157       given  channel  is  opened.  If the channel is opened on a file that is
1158       not a regular file, the result is meaningless.
1159
1160
1161
1162
1163       val close_out : out_channel -> unit
1164
1165       Close the given channel, flushing all buffered write operations.   Out‐
1166       put  functions  raise  a Sys_error exception when they are applied to a
1167       closed output channel, except close_out and flush ,  which  do  nothing
1168       when  applied  to  an  already closed channel.  Note that close_out may
1169       raise Sys_error if the operating system signals an error when  flushing
1170       or closing.
1171
1172
1173
1174
1175       val close_out_noerr : out_channel -> unit
1176
1177       Same as close_out , but ignore all errors.
1178
1179
1180
1181
1182       val set_binary_mode_out : out_channel -> bool -> unit
1183
1184
1185       set_binary_mode_out  oc  true  sets  the  channel oc to binary mode: no
1186       translations take place during output.   set_binary_mode_out  oc  false
1187       sets  the  channel  oc to text mode: depending on the operating system,
1188       some translations may take place during output.   For  instance,  under
1189       Windows,  end-of-lines will be translated from \n to \r\n .  This func‐
1190       tion has no effect under operating  systems  that  do  not  distinguish
1191       between text mode and binary mode.
1192
1193
1194
1195
1196
1197       === General input functions ===
1198
1199
1200       val open_in : string -> in_channel
1201
1202       Open the named file for reading, and return a new input channel on that
1203       file, positionned at the beginning of the file.  Raise Sys_error if the
1204       file could not be opened.
1205
1206
1207
1208
1209       val open_in_bin : string -> in_channel
1210
1211       Same  as Pervasives.open_in , but the file is opened in binary mode, so
1212       that no translation takes place during reads. On operating systems that
1213       do  not  distinguish  between  text mode and binary mode, this function
1214       behaves like Pervasives.open_in .
1215
1216
1217
1218
1219       val open_in_gen : open_flag list -> int -> string -> in_channel
1220
1221
1222       open_in_gen mode perm filename opens the named  file  for  reading,  as
1223       described  above. The extra arguments mode and perm specify the opening
1224       mode   and   file   permissions.    Pervasives.open_in    and    Perva‐
1225       sives.open_in_bin are special cases of this function.
1226
1227
1228
1229
1230       val input_char : in_channel -> char
1231
1232       Read  one character from the given input channel.  Raise End_of_file if
1233       there are no more characters to read.
1234
1235
1236
1237
1238       val input_line : in_channel -> string
1239
1240       Read characters from the given input channel, until a newline character
1241       is  encountered.  Return the string of all characters read, without the
1242       newline character at the end.  Raise End_of_file if the end of the file
1243       is reached at the beginning of line.
1244
1245
1246
1247
1248       val input : in_channel -> string -> int -> int -> int
1249
1250
1251       input  ic buf pos len reads up to len characters from the given channel
1252       ic , storing them in string buf , starting at character  number  pos  .
1253       It  returns  the  actual  number  of characters read, between 0 and len
1254       (inclusive).  A return value of 0  means  that  the  end  of  file  was
1255       reached.  A return value between 0 and len exclusive means that not all
1256       requested len characters were read, either because no  more  characters
1257       were  available  at  that  time, or because the implementation found it
1258       convenient to do a partial read; input must be called again to read the
1259       remaining  characters,  if  desired.  (See also Pervasives.really_input
1260       for reading exactly len characters.)  Exception Invalid_argument  input
1261       is raised if pos and len do not designate a valid substring of buf .
1262
1263
1264
1265
1266       val really_input : in_channel -> string -> int -> int -> unit
1267
1268
1269       really_input  ic  buf  pos  len  reads len characters from channel ic ,
1270       storing them in string buf , starting at character number pos .   Raise
1271       End_of_file  if  the  end of file is reached before len characters have
1272       been read.  Raise Invalid_argument really_input if pos and len  do  not
1273       designate a valid substring of buf .
1274
1275
1276
1277
1278       val input_byte : in_channel -> int
1279
1280       Same as Pervasives.input_char , but return the 8-bit integer represent‐
1281       ing the character.  Raise End_of_file if an end of file was reached.
1282
1283
1284
1285
1286       val input_binary_int : in_channel -> int
1287
1288       Read an integer encoded in binary format (4 bytes, big-endian) from the
1289       given   input   channel.   See  Pervasives.output_binary_int  .   Raise
1290       End_of_file if an end of file was reached while reading the integer.
1291
1292
1293
1294
1295       val input_value : in_channel -> 'a
1296
1297       Read the representation of a structured value, as  produced  by  Perva‐
1298       sives.output_value , and return the corresponding value.  This function
1299       is identical to Marshal.from_channel ; see the  description  of  module
1300       Marshal for more information, in particular concerning the lack of type
1301       safety.
1302
1303
1304
1305
1306       val seek_in : in_channel -> int -> unit
1307
1308
1309       seek_in chan pos sets the current reading position to pos  for  channel
1310       chan  . This works only for regular files. On files of other kinds, the
1311       behavior is unspecified.
1312
1313
1314
1315
1316       val pos_in : in_channel -> int
1317
1318       Return the current reading position for the given channel.
1319
1320
1321
1322
1323       val in_channel_length : in_channel -> int
1324
1325       Return the size (number of characters) of the regular file on which the
1326       given  channel  is  opened.  If the channel is opened on a file that is
1327       not a regular file, the result is meaningless.  The returned size  does
1328       not  take  into  account  the end-of-line translations that can be per‐
1329       formed when reading from a channel opened in text mode.
1330
1331
1332
1333
1334       val close_in : in_channel -> unit
1335
1336       Close the given channel.  Input functions raise a  Sys_error  exception
1337       when  they  are  applied  to  a closed input channel, except close_in ,
1338       which does nothing when applied to an  already  closed  channel.   Note
1339       that  close_in  may  raise Sys_error if the operating system signals an
1340       error.
1341
1342
1343
1344
1345       val close_in_noerr : in_channel -> unit
1346
1347       Same as close_in , but ignore all errors.
1348
1349
1350
1351
1352       val set_binary_mode_in : in_channel -> bool -> unit
1353
1354
1355       set_binary_mode_in ic true sets the  channel  ic  to  binary  mode:  no
1356       translations  take  place  during  input.  set_binary_mode_out ic false
1357       sets the channel ic to text mode: depending on  the  operating  system,
1358       some  translations  may  take  place during input.  For instance, under
1359       Windows, end-of-lines will be translated from \r\n to \n .  This  func‐
1360       tion  has  no  effect  under  operating systems that do not distinguish
1361       between text mode and binary mode.
1362
1363
1364
1365
1366
1367       === Operations on large files ===
1368
1369
1370       module LargeFile : sig end
1371
1372
1373       Operations on large files.  This sub-module provides 64-bit variants of
1374       the  channel  functions  that manipulate file positions and file sizes.
1375       By representing positions and sizes by 64-bit integers  (type  int64  )
1376       instead  of  regular  integers  (type  int ), these alternate functions
1377       allow operating on files whose sizes are greater than max_int .
1378
1379
1380
1381
1382
1383       === References ===
1384
1385
1386       type 'a ref = {
1387
1388       mutable contents : 'a ;
1389        }
1390
1391
1392       The type of references (mutable indirection cells) containing  a  value
1393       of type 'a .
1394
1395
1396
1397
1398       val ref : 'a -> 'a ref
1399
1400       Return a fresh reference containing the given value.
1401
1402
1403
1404
1405       val (!)  : 'a ref -> 'a
1406
1407
1408       !r  returns  the current contents of reference r .  Equivalent to fun r
1409       -> r.contents .
1410
1411
1412
1413
1414       val (:=) : 'a ref -> 'a -> unit
1415
1416
1417       r := a stores the value of a in reference r .  Equivalent to fun r v ->
1418       r.contents <- v .
1419
1420
1421
1422
1423       val incr : int ref -> unit
1424
1425       Increment  the integer contained in the given reference.  Equivalent to
1426       fun r -> r := succ !r .
1427
1428
1429
1430
1431       val decr : int ref -> unit
1432
1433       Decrement the integer contained in the given reference.  Equivalent  to
1434       fun r -> r := pred !r .
1435
1436
1437
1438
1439
1440       === Operations on format strings ===
1441
1442
1443       ===  Format  strings  are  used  to read and print data using formatted
1444       input functions in module Scanf and formatted output in modules  Printf
1445       and Format. ===
1446
1447
1448       type ('a, 'b, 'c, 'd) format4 = ('a, 'b, 'c, 'c, 'c, 'd) format6
1449
1450
1451       Format  strings have a general and highly polymorphic type ('a, 'b, 'c,
1452       'd, 'e, 'f) format6 . Type format6 is built  in.   The  two  simplified
1453       types, format and format4 below are included for backward compatibility
1454       with earlier releases of Objective Caml.  'a is the type of the parame‐
1455       ters  of the format, 'c is the result type for the "printf"-style func‐
1456       tion, and 'b is the type of the first  argument  given  to  %a  and  %t
1457       printing functions.
1458
1459
1460
1461       type ('a, 'b, 'c) format = ('a, 'b, 'c, 'c) format4
1462
1463
1464
1465
1466
1467       val string_of_format : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> string
1468
1469       Converts a format string into a string.
1470
1471
1472
1473
1474       val format_of_string : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> ('a, 'b, 'c,
1475       'd, 'e, 'f) format6
1476
1477
1478       format_of_string s returns a format string read from the string literal
1479       s .
1480
1481
1482
1483
1484       val (^^) : ('a, 'b, 'c, 'd, 'e, 'f) format6 -> ('f, 'b, 'c, 'e, 'g, 'h)
1485       format6 -> ('a, 'b, 'c, 'd, 'g, 'h) format6
1486
1487
1488       f1 ^^ f2 catenates formats f1 and f2 .  The result  is  a  format  that
1489       accepts arguments from f1 , then arguments from f2 .
1490
1491
1492
1493
1494
1495       === Program termination ===
1496
1497
1498       val exit : int -> 'a
1499
1500       Terminate the process, returning the given status code to the operating
1501       system: usually 0 to indicate no errors, and a small  positive  integer
1502       to  indicate  failure.   All  open  output  channels  are  flushed with
1503       flush_all.  An implicit exit 0 is performed each time a program  termi‐
1504       nates  normally.  An implicit exit 2 is performed if the program termi‐
1505       nates early because of an uncaught exception.
1506
1507
1508
1509
1510       val at_exit : (unit -> unit) -> unit
1511
1512       Register the given function to be called at program  termination  time.
1513       The  functions  registered with at_exit will be called when the program
1514       executes Pervasives.exit , or terminates, either normally or because of
1515       an  uncaught  exception.   The functions are called in ``last in, first
1516       out'' order: the function most recently added with  at_exit  is  called
1517       first.
1518
1519
1520
1521
1522
1523
1524OCamldoc                          2010-01-29                     Pervasives(3)
Impressum