(***********************************************************************)
(* *)
(* Objective Caml *)
(* *)
(* Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
(* *)
(* Copyright 1996 Institut National de Recherche en Informatique et *)
(* en Automatique. All rights reserved. This file is distributed *)
(* under the terms of the GNU Library General Public License, with *)
(* the special exception on linking described in file ../LICENSE. *)
(* *)
(***********************************************************************)
(* $Id: pervasives.mli,v 1.108 2007/02/21 14:15:19 xleroy Exp $ *)
(** The initially opened module.
This module provides the basic operations over the built-in types
(numbers, booleans, strings, exceptions, references, lists, arrays,
input-output channels, ...)
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 by [Pervasives].
*)
(** {6 Exceptions} *)
external raise : exn -> 'a = "%raise"
(** Raise the given exception value *)
val invalid_arg : string -> 'a
(** Raise exception [Invalid_argument] with the given string. *)
val failwith : string -> 'a
(** Raise exception [Failure] with the given string. *)
exception Exit
(** The [Exit] exception is not raised by any library function. It is
provided for use in your programs.*)
(** {6 Comparisons} *)
external ( = ) : 'a -> 'a -> bool = "%equal"
(** [e1 = e2] tests for structural equality of [e1] and [e2].
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 raises [Invalid_argument].
Equality between cyclic data structures does not terminate. *)
external ( <> ) : 'a -> 'a -> bool = "%notequal"
(** Negation of {!Pervasives.(=)}. *)
external ( < ) : 'a -> 'a -> bool = "%lessthan"
(** See {!Pervasives.(>=)}. *)
external ( > ) : 'a -> 'a -> bool = "%greaterthan"
(** See {!Pervasives.(>=)}. *)
external ( <= ) : 'a -> 'a -> bool = "%lessequal"
(** See {!Pervasives.(>=)}. *)
external ( >= ) : 'a -> 'a -> bool = "%greaterequal"
(** Structural ordering functions. These functions coincide with
the usual orderings over integers, characters, strings
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 raises [Invalid_argument].
Comparison between cyclic structures does not terminate. *)
external compare : 'a -> 'a -> int = "%compare"
(** [compare x y] returns [0] if [x] is equal to [y],
a negative integer if [x] is less than [y], and a positive integer
if [x] is greater than [y]. The ordering implemented by [compare]
is compatible with the comparison predicates [=], [<] and [>]
defined above, with one difference on the treatment of the float value
{!Pervasives.nan}. Namely, the comparison predicates treat [nan]
as different from any other float value, including itself;
while [compare] treats [nan] as equal to itself and less than any
other float value. This treatment of [nan] ensures that [compare]
defines a total ordering relation.
[compare] applied to functional values may raise [Invalid_argument].
[compare] applied to cyclic structures may not terminate.
The [compare] function can be used as the comparison function
required by the {!Set.Make} and {!Map.Make} functors, as well as
the {!List.sort} and {!Array.sort} functions. *)
val min : 'a -> 'a -> 'a
(** Return the smaller of the two arguments. *)
val max : 'a -> 'a -> 'a
(** Return the greater of the two arguments. *)
external ( == ) : 'a -> 'a -> bool = "%eq"
(** [e1 == e2] tests for physical equality of [e1] and [e2].
On integers and characters, physical equality is identical to structural
equality. On mutable structures, [e1 == e2] is true if and only if
physical modification of [e1] also affects [e2].
On non-mutable structures, the behavior of [(==)] is
implementation-dependent; however, it is guaranteed that
[e1 == e2] implies [compare e1 e2 = 0]. *)
external ( != ) : 'a -> 'a -> bool = "%noteq"
(** Negation of {!Pervasives.(==)}. *)
(** {6 Boolean operations} *)
external not : bool -> bool = "%boolnot"
(** The boolean negation. *)
external ( && ) : bool -> bool -> bool = "%sequand"
(** The boolean ``and''. Evaluation is sequential, left-to-right:
in [e1 && e2], [e1] is evaluated first, and if it returns [false],
[e2] is not evaluated at all. *)
external ( & ) : bool -> bool -> bool = "%sequand"
(** @deprecated {!Pervasives.(&&)} should be used instead. *)
external ( || ) : bool -> bool -> bool = "%sequor"
(** The boolean ``or''. Evaluation is sequential, left-to-right:
in [e1 || e2], [e1] is evaluated first, and if it returns [true],
[e2] is not evaluated at all. *)
external ( or ) : bool -> bool -> bool = "%sequor"
(** @deprecated {!Pervasives.(||)} should be used instead.*)
(** {6 Integer arithmetic} *)
(** Integers are 31 bits wide (or 63 bits on 64-bit processors).
All operations are taken modulo 2{^31} (or 2{^63}).
They do not fail on overflow. *)
external ( ~- ) : int -> int = "%negint"
(** Unary negation. You can also write [-e] instead of [~-e]. *)
external succ : int -> int = "%succint"
(** [succ x] is [x+1]. *)
external pred : int -> int = "%predint"
(** [pred x] is [x-1]. *)
external ( + ) : int -> int -> int = "%addint"
(** Integer addition. *)
external ( - ) : int -> int -> int = "%subint"
(** Integer subtraction. *)
external ( * ) : int -> int -> int = "%mulint"
(** Integer multiplication. *)
external ( / ) : int -> int -> int = "%divint"
(** Integer division.
Raise [Division_by_zero] if the second argument is 0.
Integer division rounds the real quotient of its arguments towards zero.
More precisely, if [x >= 0] and [y > 0], [x / y] is the greatest integer
less than or equal to the real quotient of [x] by [y]. Moreover,
[(-x) / y = x / (-y) = -(x / y)]. *)
external ( mod ) : int -> int -> int = "%modint"
(** Integer remainder. If [y] is not zero, the result
of [x mod y] satisfies the following properties:
[x = (x / y) * y + x mod y] and
[abs(x mod y) <= abs(y)-1].
If [y = 0], [x mod y] raises [Division_by_zero].
Notice that [x mod y] is nonpositive if and only if [x < 0].
Raise [Division_by_zero] if [y] is zero. *)
val abs : int -> int
(** Return the absolute value of the argument. Note that this may be
negative if the argument is [min_int]. *)
val max_int : int
(** The greatest representable integer. *)
val min_int : int
(** The smallest representable integer. *)
(** {7 Bitwise operations} *)
external ( land ) : int -> int -> int = "%andint"
(** Bitwise logical and. *)
external ( lor ) : int -> int -> int = "%orint"
(** Bitwise logical or. *)
external ( lxor ) : int -> int -> int = "%xorint"
(** Bitwise logical exclusive or. *)
val lnot : int -> int
(** Bitwise logical negation. *)
external ( lsl ) : int -> int -> int = "%lslint"
(** [n lsl m] shifts [n] to the left by [m] bits.
The result is unspecified if [m < 0] or [m >= bitsize],
where [bitsize] is [32] on a 32-bit platform and
[64] on a 64-bit platform. *)
external ( lsr ) : int -> int -> int = "%lsrint"
(** [n lsr m] shifts [n] to the right by [m] bits.
This is a logical shift: zeroes are inserted regardless of
the sign of [n].
The result is unspecified if [m < 0] or [m >= bitsize]. *)
external ( asr ) : int -> int -> int = "%asrint"
(** [n asr m] shifts [n] to the right by [m] bits.
This is an arithmetic shift: the sign bit of [n] is replicated.
The result is unspecified if [m < 0] or [m >= bitsize]. *)
(** {6 Floating-point arithmetic}
Caml's floating-point numbers follow the
IEEE 754 standard, using double precision (64 bits) numbers.
Floating-point operations never raise an exception on overflow,
underflow, division by zero, etc. Instead, special IEEE numbers
are returned as appropriate, such as [infinity] for [1.0 /
