The OCaml Standard library.

This module is automatically opened at the beginning of each compilation. All components of this module can therefore be referred by their short name, without prefixing them byStdlib.

In particular, it provides the basic operations over the built-in types (numbers, booleans, byte sequences, strings, exceptions, references, lists, arrays, input-output channels, ...) and thestandard library modules.

Raise the given exception value

A faster versionraise which does not record the backtrace.

Raise exceptionInvalid_argument with the given string.

Raise exceptionFailure with the given string.

TheExit exception is not raised by any library function. It is provided for use in your programs.

Exception raised when none of the cases of a pattern-matching apply. The arguments are the location of the match keyword in the source code (file name, line number, column number).

Exception raised when an assertion fails. The arguments are the location of the assert keyword in the source code (file name, line number, column number).

Exception raised by library functions to signal that the given arguments do not make sense. The string gives some information to the programmer. As a general rule, this exception should not be caught, it denotes a programming error and the code should be modified not to trigger it.

Exception raised by library functions to signal that they are undefined on the given arguments. The string is meant to give some information to the programmer; you must not pattern match on the string literal because it may change in future versions (use Failure _ instead).

Exception raised by search functions when the desired object could not be found.

Exception raised by the garbage collector when there is insufficient memory to complete the computation. (Not reliable for allocations on the minor heap.)

Exception raised by the bytecode interpreter when the evaluation stack reaches its maximal size. This often indicates infinite or excessively deep recursion in the user's program.

Before 4.10, it was not fully implemented by the native-code compiler.

Exception raised by the input/output functions to report an operating system error. The string is meant to give some information to the programmer; you must not pattern match on the string literal because it may change in future versions (use Sys_error _ instead).

Exception raised by input functions to signal that the end of file has been reached.

Exception raised by integer division and remainder operations when their second argument is zero.

A special case of Sys_error raised when no I/O is possible on a non-blocking I/O channel.

Exception raised when an ill-founded recursive module definition is evaluated. The arguments are the location of the definition in the source code (file name, line number, column number).

e1 = e2 tests for structural equality ofe1 ande2. Mutable structures (e.g. references and arrays) are equal if and only if their current contents are structurally equal, even if the two mutable objects are not the same physical object. Equality between functional values raisesInvalid_argument. Equality between cyclic data structures may not terminate. Left-associative operator, seeOcaml_operators for more information.

Negation of(=). Left-associative operator, seeOcaml_operators for more information.

See(>=). Left-associative operator, seeOcaml_operators for more information.

See(>=). Left-associative operator, seeOcaml_operators for more information.

See(>=). Left-associative operator, seeOcaml_operators for more information.

Structural ordering functions. These functions coincide with the usual orderings over integers, characters, strings, byte sequences and floating-point numbers, and extend them to a total ordering over all types. The ordering is compatible with( = ). As in the case of( = ), mutable structures are compared by contents. Comparison between functional values raisesInvalid_argument. Comparison between cyclic structures may not terminate. Left-associative operator, seeOcaml_operators for more information.

compare x y returns0 ifx is equal toy, a negative integer ifx is less thany, and a positive integer ifx is greater thany. The ordering implemented bycompare is compatible with the comparison predicates=,< and> defined above, with one difference on the treatment of the float valuenan. Namely, the comparison predicates treatnan as different from any other float value, including itself; whilecompare treatsnan as equal to itself and less than any other float value. This treatment ofnan ensures thatcompare defines a total ordering relation.

compare applied to functional values may raiseInvalid_argument.compare applied to cyclic structures may not terminate.

Thecompare function can be used as the comparison function required by theSet.Make andMap.Make functors, as well as theList.sort andArray.sort functions.

Return the smaller of the two arguments. The result is unspecified if one of the arguments contains the float valuenan.

Return the greater of the two arguments. The result is unspecified if one of the arguments contains the float valuenan.

e1 == e2 tests for physical equality ofe1 ande2. On mutable types such as references, arrays, byte sequences, records with mutable fields and objects with mutable instance variables,e1 == e2 is true if and only if physical modification ofe1 also affectse2. On non-mutable types, the behavior of( == ) is implementation-dependent; however, it is guaranteed thate1 == e2 impliescompare e1 e2 = 0. Left-associative operator, seeOcaml_operators for more information.

Negation of(==). Left-associative operator, seeOcaml_operators for more information.

The boolean negation.

The boolean 'and'. Evaluation is sequential, left-to-right: ine1 && e2,e1 is evaluated first, and if it returnsfalse,e2 is not evaluated at all. Right-associative operator, seeOcaml_operators for more information.

The boolean 'or'. Evaluation is sequential, left-to-right: ine1 || e2,e1 is evaluated first, and if it returnstrue,e2 is not evaluated at all. Right-associative operator, seeOcaml_operators for more information.

__LOC__ returns the location at which this expression appears in the file currently being parsed by the compiler, with the standard error format of OCaml: "File %S, line %d, characters %d-%d".

__FILE__ returns the name of the file currently being parsed by the compiler.

__LINE__ returns the line number at which this expression appears in the file currently being parsed by the compiler.

__MODULE__ returns the module name of the file being parsed by the compiler.

__POS__ returns a tuple(file,lnum,cnum,enum), corresponding to the location at which this expression appears in the file currently being parsed by the compiler.file is the current filename,lnum the line number,cnum the character position in the line andenum the last character position in the line.

__FUNCTION__ returns the name of the current function or method, including any enclosing modules or classes.

__LOC_OF__ expr returns a pair(loc, expr) whereloc is the location ofexpr in the file currently being parsed by the compiler, with the standard error format of OCaml: "File %S, line %d, characters %d-%d".

__LINE_OF__ expr returns a pair(line, expr), whereline is the line number at which the expressionexpr appears in the file currently being parsed by the compiler.

__POS_OF__ expr returns a pair(loc,expr), whereloc is a tuple(file,lnum,cnum,enum) corresponding to the location at which the expressionexpr appears in the file currently being parsed by the compiler.file is the current filename,lnum the line number,cnum the character position in the line andenum the last character position in the line.

Reverse-application operator:x |> f |> g is exactly equivalent tog (f (x)). Left-associative operator, seeOcaml_operators for more information.

Application operator:g @@ f @@ x is exactly equivalent tog (f (x)). Right-associative operator, seeOcaml_operators for more information.

Unary negation. You can also write- e instead of~- e. Unary operator, seeOcaml_operators for more information.

Unary addition. You can also write+ e instead of~+ e. Unary operator, seeOcaml_operators for more information.

succ x isx + 1.

pred x isx - 1.

Integer addition. Left-associative operator, seeOcaml_operators for more information.

Integer subtraction. Left-associative operator, , seeOcaml_operators for more information.

Integer multiplication. Left-associative operator, seeOcaml_operators for more information.

Integer division. Integer division rounds the real quotient of its arguments towards zero. More precisely, ifx >= 0 andy > 0,x / y is the greatest integer less than or equal to the real quotient ofx byy. Moreover,(- x) / y = x / (- y) = - (x / y). Left-associative operator, seeOcaml_operators for more information.

Integer remainder. Ify is not zero, the result ofx mod y satisfies the following properties:x = (x / y) * y + x mod y andabs(x mod y) <= abs(y) - 1. Ify = 0,x mod y raisesDivision_by_zero. Note thatx mod y is negative only ifx < 0. Left-associative operator, seeOcaml_operators for more information.

abs x is the absolute value ofx. Onmin_int this ismin_int itself and thus remains negative.

The greatest representable integer.

The smallest representable integer.

Bitwise logical and. Left-associative operator, seeOcaml_operators for more information.

Bitwise logical or. Left-associative operator, seeOcaml_operators for more information.

Bitwise logical exclusive or. Left-associative operator, seeOcaml_operators for more information.

Bitwise logical negation.

n lsl m shiftsn to the left bym bits. The result is unspecified ifm < 0 orm > Sys.int_size. Right-associative operator, seeOcaml_operators for more information.

n lsr m shiftsn to the right bym bits. This is a logical shift: zeroes are inserted regardless of the sign ofn. The result is unspecified ifm < 0 orm > Sys.int_size. Right-associative operator, seeOcaml_operators for more information.

n asr m shiftsn to the right bym bits. This is an arithmetic shift: the sign bit ofn is replicated. The result is unspecified ifm < 0 orm > Sys.int_size. Right-associative operator, seeOcaml_operators for more information.

Unary negation. You can also write-. e instead of~-. e. Unary operator, seeOcaml_operators for more information.

Unary addition. You can also write+. e instead of~+. e. Unary operator, seeOcaml_operators for more information.

Floating-point addition. Left-associative operator, seeOcaml_operators for more information.

Floating-point subtraction. Left-associative operator, seeOcaml_operators for more information.

Floating-point multiplication. Left-associative operator, seeOcaml_operators for more information.

Floating-point division. Left-associative operator, seeOcaml_operators for more information.

Exponentiation. Right-associative operator, seeOcaml_operators for more information.

Square root.

Exponential.

Natural logarithm.

Base 10 logarithm.

expm1 x computesexp x -. 1.0, giving numerically-accurate results even ifx is close to0.0.

log1p x computeslog(1.0 +. x) (natural logarithm), giving numerically-accurate results even ifx is close to0.0.

Cosine. Argument is in radians.

Sine. Argument is in radians.

Tangent. Argument is in radians.

Arc cosine. The argument must fall within the range[-1.0, 1.0]. Result is in radians and is between0.0 andpi.

Arc sine. The argument must fall within the range[-1.0, 1.0]. Result is in radians and is between-pi/2 andpi/2.

Arc tangent. Result is in radians and is between-pi/2 andpi/2.

atan2 y x returns the arc tangent ofy /. x. The signs ofx andy are used to determine the quadrant of the result. Result is in radians and is between-pi andpi.

hypot x y returnssqrt(x *. x + y *. y), that is, the length of the hypotenuse of a right-angled triangle with sides of lengthx andy, or, equivalently, the distance of the point(x,y) to origin. If one ofx ory is infinite, returnsinfinity even if the other isnan.

Hyperbolic cosine. Argument is in radians.

Hyperbolic sine. Argument is in radians.

Hyperbolic tangent. Argument is in radians.

Hyperbolic arc cosine. The argument must fall within the range[1.0, inf]. Result is in radians and is between0.0 andinf.

Hyperbolic arc sine. The argument and result range over the entire real line. Result is in radians.

Hyperbolic arc tangent. The argument must fall within the range[-1.0, 1.0]. Result is in radians and ranges over the entire real line.

Round above to an integer value.ceil f returns the least integer value greater than or equal tof. The result is returned as a float.

Round below to an integer value.floor f returns the greatest integer value less than or equal tof. The result is returned as a float.

abs_float f returns the absolute value off.

copysign x y returns a float whose absolute value is that ofx and whose sign is that ofy. Ifx isnan, returnsnan. Ify isnan, returns eitherx or-. x, but it is not specified which.

mod_float a b returns the remainder ofa with respect tob. The returned value isa -. n *. b, wheren is the quotienta /. b rounded towards zero to an integer.

frexp f returns the pair of the significant and the exponent off. Whenf is zero, the significantx and the exponentn off are equal to zero. Whenf is non-zero, they are defined byf = x *. 2 ** n and0.5 <= x < 1.0.

ldexp x n returnsx *. 2 ** n.

modf f returns the pair of the fractional and integral part off.

Same asfloat_of_int.

Convert an integer to floating-point.

Same asint_of_float.

Truncate the given floating-point number to an integer. The result is unspecified if the argument isnan or falls outside the range of representable integers.

Positive infinity.

Negative infinity.

A special floating-point value denoting the result of an undefined operation such as0.0 /. 0.0. Stands for 'not a number'. Any floating-point operation withnan as argument returnsnan as result, unless otherwise specified in IEEE 754 standard. As for floating-point comparisons,=,<,<=,> and>= returnfalse and<> returnstrue if one or both of their arguments isnan.

nan is a quiet NaN since 5.1; it was a signaling NaN before.

The largest positive finite value of typefloat.

The smallest positive, non-zero, non-denormalized value of typefloat.

The difference between1.0 and the smallest exactly representable floating-point number greater than1.0.

The five classes of floating-point numbers, as determined by theclassify_float function.

Return the class of the given floating-point number: normal, subnormal, zero, infinite, or not a number.

String concatenation. Right-associative operator, seeOcaml_operators for more information.

Return the ASCII code of the argument.

Return the character with the given ASCII code.

Discard the value of its argument and return(). For instance,ignore(f x) discards the result of the side-effecting functionf. It is equivalent tof x; (), except that the latter may generate a compiler warning; writingignore(f x) instead avoids the warning.

Return the string representation of a boolean. As the returned values may be shared, the user should not modify them directly.

Convert the given string to a boolean.

ReturnNone if the string is not"true" or"false".

Same asbool_of_string_opt, but raiseInvalid_argument "bool_of_string" instead of returningNone.

Return the string representation of an integer, in decimal.

Convert the given string to an integer. The string is read in decimal (by default, or if the string begins with0u), in hexadecimal (if it begins with0x or0X), in octal (if it begins with0o or0O), or in binary (if it begins with0b or0B).

The0u prefix reads the input as an unsigned integer in the range[0, 2*max_int+1]. If the input exceedsmax_int it is converted to the signed integermin_int + input - max_int - 1.

The_ (underscore) character can appear anywhere in the string and is ignored.

ReturnNone if the given string is not a valid representation of an integer, or if the integer represented exceeds the range of integers representable in typeint.

Same asint_of_string_opt, but raiseFailure "int_of_string" instead of returningNone.

Return a string representation of a floating-point number.

This conversion can involve a loss of precision. For greater control over the manner in which the number is printed, seePrintf.

Convert the given string to a float. The string is read in decimal (by default) or in hexadecimal (marked by0x or0X).

The format of decimal floating-point numbers is [-] dd.ddd (e|E) [+|-] dd , whered stands for a decimal digit.

The format of hexadecimal floating-point numbers is [-] 0(x|X) hh.hhh (p|P) [+|-] dd , whereh stands for an hexadecimal digit andd for a decimal digit.

In both cases, at least one of the integer and fractional parts must be given; the exponent part is optional.

The_ (underscore) character can appear anywhere in the string and is ignored.

Depending on the execution platforms, other representations of floating-point numbers can be accepted, but should not be relied upon.

ReturnNone if the given string is not a valid representation of a float.

Same asfloat_of_string_opt, but raiseFailure "float_of_string" instead of returningNone.

Return the first component of a pair.

Return the second component of a pair.

l0 @ l1 appendsl1 tol0. Same function asList.append. Right-associative operator, seeOcaml_operators for more information.

The type of input channel.

The type of output channel.

The standard input for the process.

The standard output for the process.

The standard error output for the process.

Print a character on standard output.

Print a string on standard output.

Print a byte sequence on standard output.

Print an integer, in decimal, on standard output.

Print a floating-point number, in decimal, on standard output.

The conversion of the number to a string usesstring_of_float and can involve a loss of precision.

Print a string, followed by a newline character, on standard output and flush standard output.

Print a newline character on standard output, and flush standard output. This can be used to simulate line buffering of standard output.

Print a character on standard error.

Print a string on standard error.

Print a byte sequence on standard error.

Print an integer, in decimal, on standard error.

Print a floating-point number, in decimal, on standard error.

The conversion of the number to a string usesstring_of_float and can involve a loss of precision.

Print a string, followed by a newline character on standard error and flush standard error.

Print a newline character on standard error, and flush standard error.

Flush standard output, then read characters from standard input until a newline character is encountered.

Return the string of all characters read, without the newline character at the end.

Flush standard output, then read one line from standard input and convert it to an integer.

ReturnNone if the line read is not a valid representation of an integer.

Same asread_int_opt, but raiseFailure "int_of_string" instead of returningNone.

Flush standard output, then read one line from standard input and convert it to a floating-point number.

ReturnNone if the line read is not a valid representation of a floating-point number.

Same asread_float_opt, but raiseFailure "float_of_string" instead of returningNone.

Opening modes foropen_out_gen andopen_in_gen.

Open the named file for writing, and return a new output channel on that file, positioned at the beginning of the file. The file is truncated to zero length if it already exists. It is created if it does not already exists.

Same asopen_out, but the file is opened in binary mode, so that no translation takes place during writes. On operating systems that do not distinguish between text mode and binary mode, this function behaves likeopen_out.

open_out_gen mode perm filename opens the named file for writing, as described above. The extra argumentmode specifies the opening mode. The extra argumentperm specifies the file permissions, in case the file must be created.open_out andopen_out_bin are special cases of this function.

Flush the buffer associated with the given output channel, performing all pending writes on that channel. Interactive programs must be careful about flushing standard output and standard error at the right time.

Flush all open output channels; ignore errors.

Write the character on the given output channel.

Write the string on the given output channel.

Write the byte sequence on the given output channel.

output oc buf pos len writeslen characters from byte sequencebuf, starting at offsetpos, to the given output channeloc.

Same asoutput but take a string as argument instead of a byte sequence.

Write one 8-bit integer (as the single character with that code) on the given output channel. The given integer is taken modulo 256.

Write one integer in binary format (4 bytes, big-endian) on the given output channel. The given integer is taken modulo 2³². The only reliable way to read it back is through theinput_binary_int function. The format is compatible across all machines for a given version of OCaml.

Write the representation of a structured value of any type to a channel. Circularities and sharing inside the value are detected and preserved. The object can be read back, by the functioninput_value. See the description of moduleMarshal for more information.output_value is equivalent toMarshal.to_channel with an empty list of flags.

seek_out chan pos sets the current writing position topos for channelchan. This works only for regular files. On files of other kinds (such as terminals, pipes and sockets), the behavior is unspecified.

Return the current writing position for the given channel. Does not work on channels opened with theOpen_append flag (returns unspecified results). For files opened in text mode under Windows, the returned position is approximate (owing to end-of-line conversion); in particular, saving the current position withpos_out, then going back to this position usingseek_out will not work. For this programming idiom to work reliably and portably, the file must be opened in binary mode.

Return the size (number of characters) of the regular file on which the given channel is opened. If the channel is opened on a file that is not a regular file, the result is meaningless.

Close the given channel, flushing all buffered write operations. Output functions raise aSys_error exception when they are applied to a closed output channel, exceptclose_out andflush, which do nothing when applied to an already closed channel. Note thatclose_out may raiseSys_error if the operating system signals an error when flushing or closing.

Same asclose_out, but ignore all errors.

set_binary_mode_out oc true sets the channeloc to binary mode: no translations take place during output.set_binary_mode_out oc false sets the channeloc to text mode: depending on the operating system, some translations may take place during output. For instance, under Windows, end-of-lines will be translated from\n to\r\n. This function has no effect under operating systems that do not distinguish between text mode and binary mode.

Open the named file for reading, and return a new input channel on that file, positioned at the beginning of the file.

Same asopen_in, but the file is opened in binary mode, so that no translation takes place during reads. On operating systems that do not distinguish between text mode and binary mode, this function behaves likeopen_in.

open_in_gen mode perm filename opens the named file for reading, as described above. The extra argumentsmode andperm specify the opening mode and file permissions.open_in andopen_in_bin are special cases of this function.

Read one character from the given input channel.

Read characters from the given input channel, until a newline character is encountered. Return the string of all characters read, without the newline character at the end.

input ic buf pos len reads up tolen characters from the given channelic, storing them in byte sequencebuf, starting at character numberpos. It returns the actual number of characters read, between 0 andlen (inclusive). A return value of 0 means that the end of file was reached. A return value between 0 andlen exclusive means that not all requestedlen characters were read, either because no more characters were available at that time, or because the implementation found it convenient to do a partial read;input must be called again to read the remaining characters, if desired. (See alsoreally_input for reading exactlylen characters.) ExceptionInvalid_argument "input" is raised ifpos andlen do not designate a valid range ofbuf.

really_input ic buf pos len readslen characters from channelic, storing them in byte sequencebuf, starting at character numberpos.

really_input_string ic len readslen characters from channelic and returns them in a new string.

Same asinput_char, but return the 8-bit integer representing the character.

Read an integer encoded in binary format (4 bytes, big-endian) from the given input channel. Seeoutput_binary_int.

Read the representation of a structured value, as produced byoutput_value, and return the corresponding value. This function is identical toMarshal.from_channel; see the description of moduleMarshal for more information, in particular concerning the lack of type safety.

seek_in chan pos sets the current reading position topos for channelchan. This works only for regular files. On files of other kinds, the behavior is unspecified.

Return the current reading position for the given channel. For files opened in text mode under Windows, the returned position is approximate (owing to end-of-line conversion); in particular, saving the current position withpos_in, then going back to this position usingseek_in will not work. For this programming idiom to work reliably and portably, the file must be opened in binary mode.

Return the size (number of characters) of the regular file on which the given channel is opened. If the channel is opened on a file that is not a regular file, the result is meaningless. The returned size does not take into account the end-of-line translations that can be performed when reading from a channel opened in text mode.

Close the given channel. Input functions raise aSys_error exception when they are applied to a closed input channel, exceptclose_in, which does nothing when applied to an already closed channel.

Same asclose_in, but ignore all errors.

set_binary_mode_in ic true sets the channelic to binary mode: no translations take place during input.set_binary_mode_out ic false sets the channelic to text mode: depending on the operating system, some translations may take place during input. For instance, under Windows, end-of-lines will be translated from\r\n to\n. This function has no effect under operating systems that do not distinguish between text mode and binary mode.

The type of references (mutable indirection cells) containing a value of type'a.

Return a fresh reference containing the given value.

!r returns the current contents of referencer. Equivalent tofun r -> r.contents. Unary operator, seeOcaml_operators for more information.

r := a stores the value ofa in referencer. Equivalent tofun r v -> r.contents <- v. Right-associative operator, seeOcaml_operators for more information.

Increment the integer contained in the given reference. Equivalent tofun r -> r := succ !r.

Decrement the integer contained in the given reference. Equivalent tofun r -> r := pred !r.

Converts a format string into a string.

format_of_string s returns a format string read from the string literals. Note:format_of_string can not convert a string argument that is not a literal. If you need this functionality, use the more generalScanf.format_from_string function.

f1 ^^ f2 catenates format stringsf1 andf2. The result is a format string that behaves as the concatenation of format stringsf1 andf2: in case of formatted output, it accepts arguments fromf1, then arguments fromf2; in case of formatted input, it returns results fromf1, then results fromf2. Right-associative operator, seeOcaml_operators for more information.

Terminate the process, returning the given status code to the operating system: usually 0 to indicate no errors, and a small positive integer to indicate failure. All open output channels are flushed withflush_all. The callbacks registered withDomain.at_exit are called followed by those registered withat_exit.

An implicitexit 0 is performed each time a program terminates normally. An implicitexit 2 is performed if the program terminates early because of an uncaught exception.

Register the given function to be called at program termination time. The functions registered withat_exit will be called when the program does any of the following:

• executesexit
• terminates, either normally or because of an uncaught exception
• executes the C functioncaml_shutdown. The functions are called in 'last in, first out' order: the function most recently added withat_exit is called first.