Ekdohibs
/
ocaml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Modification emplacement et syntaxe commentaires pour OCamldoc 

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@3926 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02
master
Maxence Guesdon 2001-10-26 22:38:48 +00:00
parent 7c6c78a292
commit b95796f461
17 changed files with 1659 additions and 1216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
stdlib/int32.mli
View File

@ -12,9 +12,9 @@
(* $Id$ *)
(* Module [Int32]: 32-bit integers *)
(** 32-bit integers.
(* This module provides operations on the type [int32]
This module provides operations on the type [int32]
of signed 32-bit integers. Unlike the built-in [int] type,
the type [int32] is guaranteed to be exactly 32-bit wide on all
platforms. All arithmetic operations over [int32] are taken
@ -25,94 +25,118 @@
[int32] are generally slower than those on [int]. Use [int32]
only when the application requires exact 32-bit arithmetic. *)
(** The 32-bit integer 0. *)
val zero : int32
(** The 32-bit integer 1. *)
val one : int32
(** The 32-bit integer -1. *)
val minus_one : int32
(* The 32-bit integers 0, 1, -1. *)
(** Unary negation. *)
external neg : int32 -> int32 = "%int32_neg"
(* Unary negation. *)
(** Addition. *)
external add : int32 -> int32 -> int32 = "%int32_add"
(* Addition. *)
(** Subtraction. *)
external sub : int32 -> int32 -> int32 = "%int32_sub"
(* Subtraction. *)
(** Multiplication. *)
external mul : int32 -> int32 -> int32 = "%int32_mul"
(* Multiplication. *)
(** Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
external div : int32 -> int32 -> int32 = "%int32_div"
(* Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
(** Integer remainder. If [x >= 0] and [y > 0], the result
of [Int32.rem x y] satisfies the following properties:
[0 <= Int32.rem x y < y] and
[x = Int32.add (Int32.mul (Int32.div x y) y) (Int32.rem x y)].
If [y = 0], [Int32.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Int32.rem x y] is
not specified and depends on the platform. *)
external rem : int32 -> int32 -> int32 = "%int32_mod"
(* Integer remainder. If [x >= 0] and [y > 0], the result
of [Int32.rem x y] satisfies the following properties:
[0 <= Int32.rem x y < y] and
[x = Int32.add (Int32.mul (Int32.div x y) y) (Int32.rem x y)].
If [y = 0], [Int32.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Int32.rem x y] is
not specified and depends on the platform. *)
(** Successor. [Int32.succ x] is [Int32.add x Int32.one]. *)
val succ : int32 -> int32
(* Successor. [Int32.succ x] is [Int32.add x Int32.one]. *)
(** Predecessor. [Int32.pred x] is [Int32.sub x Int32.one]. *)
val pred : int32 -> int32
(* Predecessor. [Int32.pred x] is [Int32.sub x Int32.one]. *)
(** Return the absolute value of its argument. *)
val abs : int32 -> int32
(* Return the absolute value of its argument. *)
(** The greatest representable 32-bit integer, $2^{31} - 1$. *)
val max_int : int32
(* The greatest representable 32-bit integer, $2^{31} - 1$. *)
(** The smallest representable 32-bit integer, $-2^{31}$. *)
val min_int : int32
(* The smallest representable 32-bit integer, $-2^{31}$. *)
(** Bitwise logical and. *)
external logand : int32 -> int32 -> int32 = "%int32_and"
(* Bitwise logical and. *)
(** Bitwise logical or. *)
external logor : int32 -> int32 -> int32 = "%int32_or"
(* Bitwise logical or. *)
(** Bitwise logical exclusive or. *)
external logxor : int32 -> int32 -> int32 = "%int32_xor"
(* Bitwise logical exclusive or. *)
(** Bitwise logical negation *)
val lognot : int32 -> int32
(* Bitwise logical negation *)
(** [Int32.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= 32]. *)
external shift_left : int32 -> int -> int32 = "%int32_lsl"
(* [Int32.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= 32]. *)
(** [Int32.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= 32]. *)
external shift_right : int32 -> int -> int32 = "%int32_asr"
(* [Int32.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= 32]. *)
(** [Int32.shift_right_logical x y] shifts [x] to the right by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= 32]. *)
external shift_right_logical : int32 -> int -> int32 = "%int32_lsr"
(* [Int32.shift_right_logical x y] shifts [x] to the right by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= 32]. *)
(** Convert the given integer (type [int]) to a 32-bit integer (type [int32]). *)
external of_int : int -> int32 = "%int32_of_int"
(* Convert the given integer (type [int]) to a 32-bit integer
(type [int32]). *)
(** Convert the given 32-bit integer (type [int32]) to an
integer (type [int]). On 32-bit platforms, the 32-bit integer
is taken modulo $2^{31}$, i.e. the high-order bit is lost
during the conversion. On 64-bit platforms, the conversion
is exact. *)
external to_int : int32 -> int = "%int32_to_int"
(* Convert the given 32-bit integer (type [int32]) to an
integer (type [int]). On 32-bit platforms, the 32-bit integer
is taken modulo $2^{31}$, i.e. the high-order bit is lost
during the conversion. On 64-bit platforms, the conversion
is exact. *)
(** Convert the given floating-point number to a 32-bit integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range \[{!Int32.min_int}, {!Int32.max_int}\]. *)
external of_float : float -> int32 = "int32_of_float"
(* Convert the given floating-point number to a 32-bit integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range [Int32.min_int, Int32.max_int]. *)
external to_float : int32 -> float = "int32_to_float"
(* Convert the given 32-bit integer to a floating-point number. *)
(** Convert the given 32-bit integer to a floating-point number. *)
external to_float : int32 -> float = "int32_to_float"
(** Convert the given string to a 32-bit integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
external of_string : string -> int32 = "int32_of_string"
(* Convert the given string to a 32-bit integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
(** Return the string representation of its argument, in signed decimal. *)
val to_string : int32 -> string
(* Return the string representation of its argument,
in signed decimal. *)
(** [Int32.format fmt n] return the string representation of the
32-bit integer [n] in the format specified by [fmt].
[fmt] is a [Printf]-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the [Printf] module for more information, *)
external format : string -> int32 -> string = "int32_format"
(* [Int32.format fmt n] return the string representation of the
32-bit integer [n] in the format specified by [fmt].
[fmt] is a [Printf]-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the [Printf] module for more information, *)

195
stdlib/int64.mli
View File

@ -12,9 +12,9 @@
(* $Id$ *)
(* Module [Int64]: 64-bit integers *)
(** Module [Int64]: 64-bit integers *)
(* This module provides operations on the type [int64] of
(** This module provides operations on the type [int64] of
signed 64-bit integers. Unlike the built-in [int] type,
the type [int64] is guaranteed to be exactly 64-bit wide on all
platforms. All arithmetic operations over [int64] are taken
@ -28,125 +28,154 @@
Performance notice: values of type [int64] occupy more memory
space than values of type [int], and arithmetic operations on
[int64] are generally slower than those on [int]. Use [int64]
only when the application requires exact 64-bit arithmetic. *)
only when the application requires exact 64-bit arithmetic.
*)
(** The 64-bit integer 0. *)
val zero : int64
(** The 64-bit integer 1. *)
val one : int64
(** The 64-bit integer -1. *)
val minus_one : int64
(* The 64-bit integers 0, 1, -1. *)
(** Unary negation. *)
external neg : int64 -> int64 = "%int64_neg"
(* Unary negation. *)
(** Addition. *)
external add : int64 -> int64 -> int64 = "%int64_add"
(* Addition. *)
(** Subtraction. *)
external sub : int64 -> int64 -> int64 = "%int64_sub"
(* Subtraction. *)
(** Multiplication. *)
external mul : int64 -> int64 -> int64 = "%int64_mul"
(* Multiplication. *)
(** Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
external div : int64 -> int64 -> int64 = "%int64_div"
(* Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
(** Integer remainder. If [x >= 0] and [y > 0], the result
of [Int64.rem x y] satisfies the following properties:
[0 <= Int64.rem x y < y] and
[x = Int64.add (Int64.mul (Int64.div x y) y) (Int64.rem x y)].
If [y = 0], [Int64.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Int64.rem x y] is
not specified and depends on the platform. *)
external rem : int64 -> int64 -> int64 = "%int64_mod"
(* Integer remainder. If [x >= 0] and [y > 0], the result
of [Int64.rem x y] satisfies the following properties:
[0 <= Int64.rem x y < y] and
[x = Int64.add (Int64.mul (Int64.div x y) y) (Int64.rem x y)].
If [y = 0], [Int64.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Int64.rem x y] is
not specified and depends on the platform. *)
(** Successor. [Int64.succ x] is [Int64.add x Int64.one]. *)
val succ : int64 -> int64
(* Successor. [Int64.succ x] is [Int64.add x Int64.one]. *)
(** Predecessor. [Int64.pred x] is [Int64.sub x Int64.one]. *)
val pred : int64 -> int64
(* Predecessor. [Int64.pred x] is [Int64.sub x Int64.one]. *)
(** Return the absolute value of its argument. *)
val abs : int64 -> int64
(* Return the absolute value of its argument. *)
(** The greatest representable 64-bit integer, $2^{63} - 1$. *)
val max_int : int64
(* The greatest representable 64-bit integer, $2^{63} - 1$. *)
(** The smallest representable 64-bit integer, $-2^{63}$. *)
val min_int : int64
(* The smallest representable 64-bit integer, $-2^{63}$. *)
(** Bitwise logical and. *)
external logand : int64 -> int64 -> int64 = "%int64_and"
(* Bitwise logical and. *)
(** Bitwise logical or. *)
external logor : int64 -> int64 -> int64 = "%int64_or"
(* Bitwise logical or. *)
(** Bitwise logical exclusive or. *)
external logxor : int64 -> int64 -> int64 = "%int64_xor"
(* Bitwise logical exclusive or. *)
(** Bitwise logical negation *)
val lognot : int64 -> int64
(* Bitwise logical negation *)
(** [Int64.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= 64]. *)
external shift_left : int64 -> int -> int64 = "%int64_lsl"
(* [Int64.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= 64]. *)
(** [Int64.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= 64]. *)
external shift_right : int64 -> int -> int64 = "%int64_asr"
(* [Int64.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= 64]. *)
(** [Int64.shift_right_logical x y] shifts [x] to the right by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= 64]. *)
external shift_right_logical : int64 -> int -> int64 = "%int64_lsr"
(* [Int64.shift_right_logical x y] shifts [x] to the right by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= 64]. *)
(** Convert the given integer (type [int]) to a 64-bit integer (type [int64]). *)
external of_int : int -> int64 = "%int64_of_int"
(* Convert the given integer (type [int]) to a 64-bit integer
(type [int64]). *)
(** Convert the given 64-bit integer (type [int64]) to an
integer (type [int]). On 64-bit platforms, the 64-bit integer
is taken modulo $2^{63}$, i.e. the high-order bit is lost
during the conversion. On 32-bit platforms, the 64-bit integer
is taken modulo $2^{31}$, i.e. the top 33 bits are lost
during the conversion. *)
external to_int : int64 -> int = "%int64_to_int"
(* Convert the given 64-bit integer (type [int64]) to an
integer (type [int]). On 64-bit platforms, the 64-bit integer
is taken modulo $2^{63}$, i.e. the high-order bit is lost
during the conversion. On 32-bit platforms, the 64-bit integer
is taken modulo $2^{31}$, i.e. the top 33 bits are lost
during the conversion. *)
(** Convert the given floating-point number to a 64-bit integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range \[{![Int64.min_int}, {!Int64.max_int]\]. *)
external of_float : float -> int64 = "int64_of_float"
(* Convert the given floating-point number to a 64-bit integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range [Int64.min_int, Int64.max_int]. *)
(** Convert the given 64-bit integer to a floating-point number. *)
external to_float : int64 -> float = "int64_to_float"
(* Convert the given 64-bit integer to a floating-point number. *)
(** Convert the given 32-bit integer (type [int32])
to a 64-bit integer (type [int64]). *)
external of_int32 : int32 -> int64 = "%int64_of_int32"
(* Convert the given 32-bit integer (type [int32])
to a 64-bit integer (type [int64]). *)
(** Convert the given 64-bit integer (type [int64]) to a
32-bit integer (type [int32]). The 64-bit integer
is taken modulo $2^{32}$, i.e. the top 32 bits are lost
during the conversion. *)
external to_int32 : int64 -> int32 = "%int64_to_int32"
(* Convert the given 64-bit integer (type [int64]) to a
32-bit integer (type [int32]). The 64-bit integer
is taken modulo $2^{32}$, i.e. the top 32 bits are lost
during the conversion. *)
(** Convert the given native integer (type [nativeint])
to a 64-bit integer (type [int64]). *)
external of_nativeint : nativeint -> int64 = "%int64_of_nativeint"
(* Convert the given native integer (type [nativeint])
to a 64-bit integer (type [int64]). *)
(** Convert the given 64-bit integer (type [int64]) to a
native integer. On 32-bit platforms, the 64-bit integer
is taken modulo $2^{32}$. On 64-bit platforms,
the conversion is exact. *)
external to_nativeint : int64 -> nativeint = "%int64_to_nativeint"
(* Convert the given 64-bit integer (type [int64]) to a
native integer. On 32-bit platforms, the 64-bit integer
is taken modulo $2^{32}$. On 64-bit platforms,
the conversion is exact. *)
(** Convert the given string to a 64-bit integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
external of_string : string -> int64 = "int64_of_string"
(* Convert the given string to a 64-bit integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
val to_string : int64 -> string
(* Return the string representation of its argument, in decimal. *)
external format : string -> int64 -> string = "int64_format"
(* [Int64.format fmt n] return the string representation of the
64-bit integer [n] in the format specified by [fmt].
[fmt] is a [Printf]-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the [Printf] module for more information, *)
(** Return the string representation of its argument, in decimal. *)
val to_string : int64 -> string
(** [Int64.format fmt n] return the string representation of the
64-bit integer [n] in the format specified by [fmt].
[fmt] is a {!Printf}-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the {!Printf} module for more information, *)
external format : string -> int64 -> string = "int64_format"
(** Return the internal representation of the given float according
to the IEEE 754 floating-point ``double format'' bit layout.
Bit 63 of the result represents the sign of the float;
bits 62 to 52 represent the (biased) exponent; bits 51 to 0
represent the mantissa. *)
external bits_of_float : float -> int64 = "int64_bits_of_float"
(* Return the internal representation of the given float according
to the IEEE 754 floating-point ``double format'' bit layout.
Bit 63 of the result represents the sign of the float;
bits 62 to 52 represent the (biased) exponent; bits 51 to 0
represent the mantissa. *)
(** Return the floating-point number whose internal representation,
according to the IEEE 754 floating-point ``double format'' bit layout,
is the given [int64]. *)
external float_of_bits : int64 -> float = "int64_float_of_bits"
(* Return the floating-point number whose internal representation,
according to the IEEE 754 floating-point ``double format'' bit layout,
is the given [int64]. *)

15
stdlib/lazy.mli
View File

@ -12,7 +12,7 @@
(* $Id$ *)
(* Module [Lazy]: deferred computations. *)
(** Deferred computations. *)
type 'a status =
| Delayed of (unit -> 'a)
@ -20,19 +20,20 @@ type 'a status =
| Exception of exn
;;
type 'a t = 'a status ref;;
(* A value of type ['a Lazy.t] is a deferred computation (also called a
(** A value of type ['a Lazy.t] is a deferred computation (also called a
suspension) that computes a result of type ['a]. The expression
[lazy (expr)] returns a suspension that computes [expr].
*)
[lazy (expr)] returns a suspension that computes [expr]. **)
type 'a t = 'a status ref;;
exception Undefined;;
val force: 'a t -> 'a;;
(* [Lazy.force x] computes the suspension [x] and returns its result.
(** [Lazy.force x] computes the suspension [x] and returns its result.
If the suspension was already computed, [Lazy.force x] returns the
same value again. If it raised an exception, the same exception is
raised again.
Raise [Undefined] if the evaluation of the suspension requires its
own result.
*)
val force: 'a t -> 'a;;

91
stdlib/lexing.mli
View File

@ -12,10 +12,15 @@
(* $Id$ *)
(* Module [Lexing]: the run-time library for lexers generated by [ocamllex] *)
(** The run-time library for lexers generated by [ocamllex]. *)
(*** Lexer buffers *)
(** {2 Lexer buffers} *)
(** The type of lexer buffers. A lexer buffer is the argument passed
to the scanning functions defined by the generated scanners.
The lexer buffer holds the current state of the scanner, plus
a function to refill the buffer from the input. *)
type lexbuf =
{ refill_buff : lexbuf -> unit;
mutable lex_buffer : string;
@ -25,58 +30,64 @@ type lexbuf =
mutable lex_curr_pos : int;
mutable lex_last_pos : int;
mutable lex_last_action : int;
mutable lex_eof_reached : bool }
(* The type of lexer buffers. A lexer buffer is the argument passed
to the scanning functions defined by the generated scanners.
The lexer buffer holds the current state of the scanner, plus
a function to refill the buffer from the input. *)
mutable lex_eof_reached : bool;
}
(** Create a lexer buffer on the given input channel.
[Lexing.from_channel inchan] returns a lexer buffer which reads
from the input channel [inchan], at the current reading position. *)
val from_channel : in_channel -> lexbuf
(* Create a lexer buffer on the given input channel.
[Lexing.from_channel inchan] returns a lexer buffer which reads
from the input channel [inchan], at the current reading position. *)
(** Create a lexer buffer which reads from
the given string. Reading starts from the first character in
the string. An end-of-input condition is generated when the
end of the string is reached. *)
val from_string : string -> lexbuf
(* Create a lexer buffer which reads from
the given string. Reading starts from the first character in
the string. An end-of-input condition is generated when the
end of the string is reached. *)
(** Create a lexer buffer with the given function as its reading method.
When the scanner needs more characters, it will call the given
function, giving it a character string [s] and a character
count [n]. The function should put [n] characters or less in [s],
starting at character number 0, and return the number of characters
provided. A return value of 0 means end of input. *)
val from_function : (string -> int -> int) -> lexbuf
(* Create a lexer buffer with the given function as its reading method.
When the scanner needs more characters, it will call the given
function, giving it a character string [s] and a character
count [n]. The function should put [n] characters or less in [s],
starting at character number 0, and return the number of characters
provided. A return value of 0 means end of input. *)
(*** Functions for lexer semantic actions *)
(* The following functions can be called from the semantic actions
of lexer definitions (the ML code enclosed in braces that
computes the value returned by lexing functions). They give
access to the character string matched by the regular expression
associated with the semantic action. These functions must be
applied to the argument [lexbuf], which, in the code generated by
[ocamllex], is bound to the lexer buffer passed to the parsing
function. *)
(** {2 Functions for lexer semantic actions} *)
val lexeme : lexbuf -> string
(* [Lexing.lexeme lexbuf] returns the string matched by
(** The following functions can be called from the semantic actions
of lexer definitions (the ML code enclosed in braces that
computes the value returned by lexing functions). They give
access to the character string matched by the regular expression
associated with the semantic action. These functions must be
applied to the argument [lexbuf], which, in the code generated by
[ocamllex], is bound to the lexer buffer passed to the parsing
function. *)
(** [Lexing.lexeme lexbuf] returns the string matched by
the regular expression. *)
val lexeme : lexbuf -> string
(** [Lexing.lexeme_char lexbuf i] returns character number [i] in
the matched string. *)
val lexeme_char : lexbuf -> int -> char
(* [Lexing.lexeme_char lexbuf i] returns character number [i] in
the matched string. *)
(** [Lexing.lexeme_start lexbuf] returns the position in the
input stream of the first character of the matched string.
The first character of the stream has position 0. *)
val lexeme_start : lexbuf -> int
(* [Lexing.lexeme_start lexbuf] returns the position in the
input stream of the first character of the matched string.
The first character of the stream has position 0. *)
(** [Lexing.lexeme_end lexbuf] returns the position in the input stream
of the character following the last character of the matched
string. The first character of the stream has position 0. *)
val lexeme_end : lexbuf -> int
(* [Lexing.lexeme_end lexbuf] returns the position in the input stream
of the character following the last character of the matched
string. The first character of the stream has position 0. *)
(*--*)
(* The following definitions are used by the generated scanners only.
(** {2 } *)
(** The following definitions are used by the generated scanners only.
They are not intended to be used by user programs. *)
type lex_tables =

299
stdlib/list.mli
View File

@ -12,9 +12,9 @@
(* $Id$ *)
(* Module [List]: list operations *)
(** List operations.
(* Some functions are flagged as not tail-recursive. A tail-recursive
Some functions are flagged as not tail-recursive. A tail-recursive
function uses constant stack space, while a non-tail-recursive function
uses stack space proportional to the length of its list argument, which
can be a problem with very long lists. When the function takes several
@ -25,188 +25,235 @@
longer than about 10000 elements.
*)
(** Return the length (number of elements) of the given list. *)
val length : 'a list -> int
(* Return the length (number of elements) of the given list. *)
(** Return the first element of the given list. Raise
[Failure "hd"] if the list is empty. *)
val hd : 'a list -> 'a
(* Return the first element of the given list. Raise
[Failure "hd"] if the list is empty. *)
(** Return the given list without its first element. Raise
[Failure "tl"] if the list is empty. *)
val tl : 'a list -> 'a list
(* Return the given list without its first element. Raise
[Failure "tl"] if the list is empty. *)
(** Return the n-th element of the given list.
The first element (head of the list) is at position 0.
Raise [Failure "nth"] if the list is too short. *)
val nth : 'a list -> int -> 'a
(* Return the n-th element of the given list.
The first element (head of the list) is at position 0.
Raise [Failure "nth"] if the list is too short. *)
(** List reversal. *)
val rev : 'a list -> 'a list
(* List reversal. *)
(** Catenate two lists. Same function as the infix operator [@].
Not tail-recursive (length of the first argument). The [@]
operator is not tail-recursive either. *)
val append : 'a list -> 'a list -> 'a list
(* Catenate two lists. Same function as the infix operator [@].
Not tail-recursive (length of the first argument). The [@]
operator is not tail-recursive either. *)
(** [List.rev_append l1 l2] reverses [l1] and catenates it to [l2].
This is equivalent to {!List.rev}[ l1 @ l2], but [rev_append] is
tail-recursive and more efficient. *)
val rev_append : 'a list -> 'a list -> 'a list
(* [List.rev_append l1 l2] reverses [l1] and catenates it to [l2].
This is equivalent to [List.rev l1 @ l2], but [rev_append] is
tail-recursive and more efficient. *)
(** Concatenate a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
val concat : 'a list list -> 'a list
(** Flatten a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
val flatten : 'a list list -> 'a list
(* Catenate (flatten) a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
(** Iterators *)
(** {2 Iterators} *)
(** [List.iter f [a1; ...; an]] applies function [f] in turn to
[a1; ...; an]. It is equivalent to
[begin f a1; f a2; ...; f an; () end]. *)
val iter : ('a -> unit) -> 'a list -> unit
(* [List.iter f [a1; ...; an]] applies function [f] in turn to
[a1; ...; an]. It is equivalent to
[begin f a1; f a2; ...; f an; () end]. *)
(** [List.map f [a1; ...; an]] applies function [f] to [a1, ..., an],
and builds the list [[f a1; ...; f an]]
with the results returned by [f]. Not tail-recursive. *)
val map : ('a -> 'b) -> 'a list -> 'b list
(* [List.map f [a1; ...; an]] applies function [f] to [a1, ..., an],
and builds the list [[f a1; ...; f an]]
with the results returned by [f]. Not tail-recursive. *)
(** [List.rev_map f l] gives the same result as
{!List.rev}[ (]{!List.map}[ f l)], but is tail-recursive and
more efficient. *)
val rev_map : ('a -> 'b) -> 'a list -> 'b list
(* [List.rev_map f l] gives the same result as
[List.rev (List.map f l)], but is tail-recursive and
more efficient. *)
(** [List.fold_left f a [b1; ...; bn]] is
[f (... (f (f a b1) b2) ...) bn]. *)
val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a
(* [List.fold_left f a [b1; ...; bn]] is
[f (... (f (f a b1) b2) ...) bn]. *)
(** [List.fold_right f [a1; ...; an] b] is
[f a1 (f a2 (... (f an b) ...))]. Not tail-recursive. *)
val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
(* [List.fold_right f [a1; ...; an] b] is
[f a1 (f a2 (... (f an b) ...))]. Not tail-recursive. *)
(** Iterators on two lists *)
(** {2 Iterators on two lists} *)
(** [List.iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
[f a1 b1; ...; f an bn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
(* [List.iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
[f a1 b1; ...; f an bn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [List.map2 f [a1; ...; an] [b1; ...; bn]] is
[[f a1 b1; ...; f an bn]].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
(* [List.map2 f [a1; ...; an] [b1; ...; bn]] is
[[f a1 b1; ...; f an bn]].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
(** [List.rev_map2 f l] gives the same result as
{!List.rev}[ (]{!List.map2}[ f l)], but is tail-recursive and
more efficient. *)
val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
(* [List.rev_map2 f l] gives the same result as
[List.rev (List.map2 f l)], but is tail-recursive and
more efficient. *)
(** [List.fold_left2 f a [b1; ...; bn] [c1; ...; cn]] is
[f (... (f (f a b1 c1) b2 c2) ...) bn cn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
val fold_left2 :
('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list -> 'a
(* [List.fold_left2 f a [b1; ...; bn] [c1; ...; cn]] is
[f (... (f (f a b1 c1) b2 c2) ...) bn cn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [List.fold_right2 f [a1; ...; an] [b1; ...; bn] c] is
[f a1 b1 (f a2 b2 (... (f an bn c) ...))].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
val fold_right2 :
('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c -> 'c
(* [List.fold_right2 f [a1; ...; an] [b1; ...; bn] c] is
[f a1 b1 (f a2 b2 (... (f an bn c) ...))].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
(** List scanning *)
(** {2 List scanning} *)
(** [for_all p [a1; ...; an]] checks if all elements of the list
satisfy the predicate [p]. That is, it returns
[(p a1) && (p a2) && ... && (p an)]. *)
val for_all : ('a -> bool) -> 'a list -> bool
(* [for_all p [a1; ...; an]] checks if all elements of the list
satisfy the predicate [p]. That is, it returns
[(p a1) && (p a2) && ... && (p an)]. *)
(** [exists p [a1; ...; an]] checks if at least one element of
the list satisfies the predicate [p]. That is, it returns
[(p a1) || (p a2) || ... || (p an)]. *)
val exists : ('a -> bool) -> 'a list -> bool
(* [exists p [a1; ...; an]] checks if at least one element of
the list satisfies the predicate [p]. That is, it returns
[(p a1) || (p a2) || ... || (p an)]. *)
(** Same as {!List.for_all}, but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
(** Same as {!List.exists}, but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
(* Same as [for_all] and [exists], but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [mem a l] is true if and only if [a] is equal
to an element of [l]. *)
val mem : 'a -> 'a list -> bool
(* [mem a l] is true if and only if [a] is equal
to an element of [l]. *)
(** Same as {!List.mem}, but uses physical equality instead of structural
equality to compare list elements. *)
val memq : 'a -> 'a list -> bool
(* Same as [mem], but uses physical equality instead of structural
equality to compare list elements. *)
(** List searching *)
(** {2 List searching} *)
(** [find p l] returns the first element of the list [l]
that satisfies the predicate [p].
Raise [Not_found] if there is no value that satisfies [p] in the
list [l]. *)
val find : ('a -> bool) -> 'a list -> 'a
(* [find p l] returns the first element of the list [l]
that satisfies the predicate [p].
Raise [Not_found] if there is no value that satisfies [p] in the
list [l]. *)
(** [filter p l] returns all the elements of the list [l]
that satisfy the predicate [p]. The order of the elements
in the input list is preserved. *)
val filter : ('a -> bool) -> 'a list -> 'a list
(** [find_all] is another name for {!List.filter}. *)
val find_all : ('a -> bool) -> 'a list -> 'a list
(* [filter p l] returns all the elements of the list [l]
that satisfy the predicate [p]. The order of the elements
in the input list is preserved. [find_all] is another name
for [filter]. *)
(** [partition p l] returns a pair of lists [(l1, l2)], where
[l1] is the list of all the elements of [l] that
satisfy the predicate [p], and [l2] is the list of all the
elements of [l] that do not satisfy [p].
The order of the elements in the input list is preserved. *)
val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
(* [partition p l] returns a pair of lists [(l1, l2)], where
[l1] is the list of all the elements of [l] that
satisfy the predicate [p], and [l2] is the list of all the
elements of [l] that do not satisfy [p].
The order of the elements in the input list is preserved. *)
(** Association lists *)
(** {2 Association lists} *)
(** [assoc a l] returns the value associated with key [a] in the list of
pairs [l]. That is,
[assoc a [ ...; (a,b); ...] = b]
if [(a,b)] is the leftmost binding of [a] in list [l].
Raise [Not_found] if there is no value associated with [a] in the
list [l]. *)
val assoc : 'a -> ('a * 'b) list -> 'b
(* [assoc a l] returns the value associated with key [a] in the list of
pairs [l]. That is,
[assoc a [ ...; (a,b); ...] = b]
if [(a,b)] is the leftmost binding of [a] in list [l].
Raise [Not_found] if there is no value associated with [a] in the
list [l]. *)
(** Same as {!List.assoc}, but uses physical equality instead of structural
equality to compare keys. *)
val assq : 'a -> ('a * 'b) list -> 'b
(* Same as [assoc], but uses physical equality instead of structural
equality to compare keys. *)
(** Same as {!List.assoc}, but simply return true if a binding exists,
and false if no bindings exist for the given key. *)
val mem_assoc : 'a -> ('a * 'b) list -> bool
(* Same as [assoc], but simply return true if a binding exists,
and false if no bindings exist for the given key. *)
(** Same as {!List.mem_assoc}, but uses physical equality instead of
structural equality to compare keys. *)
val mem_assq : 'a -> ('a * 'b) list -> bool
(* Same as [mem_assoc], but uses physical equality instead of
structural equality to compare keys. *)
(** [remove_assoc a l] returns the list of
pairs [l] without the first pair with key [a], if any.
Not tail-recursive. *)
val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
(* [remove_assoc a l] returns the list of
pairs [l] without the first pair with key [a], if any.
Not tail-recursive. *)
(** Same as {!List.remove_assq}, but uses physical equality instead
of structural equality to compare keys. Not tail-recursive. *)
val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
(* Same as [remove_assq], but uses physical equality instead
of structural equality to compare keys. Not tail-recursive. *)
(** Lists of pairs *)
(** {2 Lists of pairs} *)
(** Transform a list of pairs into a pair of lists:
[split [(a1,b1); ...; (an,bn)]] is [([a1; ...; an], [b1; ...; bn])].
Not tail-recursive.
*)
val split : ('a * 'b) list -> 'a list * 'b list
(* Transform a list of pairs into a pair of lists:
[split [(a1,b1); ...; (an,bn)]] is [([a1; ...; an], [b1; ...; bn])].
Not tail-recursive.
*)
(** Transform a pair of lists into a list of pairs:
[combine [a1; ...; an] [b1; ...; bn]] is
[[(a1,b1); ...; (an,bn)]].
Raise [Invalid_argument] if the two lists
have different lengths. Not tail-recursive. *)
val combine : 'a list -> 'b list -> ('a * 'b) list
(* Transform a pair of lists into a list of pairs:
[combine [a1; ...; an] [b1; ...; bn]] is
[[(a1,b1); ...; (an,bn)]].
Raise [Invalid_argument] if the two lists
have different lengths. Not tail-recursive. *)
(** Sorting *)
(** {2 Sorting} *)
(** Sort a list in increasing order according to a comparison
function. The comparison function must return 0 if it arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller. For example,
the [compare] function is a suitable comparison function.
The resulting list is sorted in increasing order.
[List.sort] is guaranteed to run in constant heap space
(in addition to the size of the result list) and logarithmic
stack space.
The current implementation uses Merge Sort and is the same as
{!List.stable_sort}.
*)
val sort : ('a -> 'a -> int) -> 'a list -> 'a list;;
(* Sort a list in increasing order according to a comparison
function. The comparison function must return 0 if it arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller. For example,
the [compare] function is a suitable comparison function.
The resulting list is sorted in increasing order.
[List.sort] is guaranteed to run in constant heap space
(in addition to the size of the result list) and logarithmic
stack space.
The current implementation uses Merge Sort and is the same as
[List.stable_sort].
*)
(** Same as {!List.sort}, but the sorting algorithm is stable.
The current implementation is Merge Sort. It runs in constant
heap space and logarithmic stack space.
*)
val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list;;
(* Same as [List.sort], but the sorting algorithm is stable.
The current implementation is Merge Sort. It runs in constant
heap space and logarithmic stack space.
*)

309
stdlib/listLabels.mli
View File

@ -12,9 +12,10 @@
(* $Id$ *)
(* Module [List]: list operations *)
(* Some functions are flagged as not tail-recursive. A tail-recursive
(** List operations.
Some functions are flagged as not tail-recursive. A tail-recursive
function uses constant stack space, while a non-tail-recursive function
uses stack space proportional to the length of its list argument, which
can be a problem with very long lists. When the function takes several
@ -25,188 +26,244 @@
longer than about 10000 elements.
*)
(** Return the length (number of elements) of the given list. *)
val length : 'a list -> int
(* Return the length (number of elements) of the given list. *)
(** Return the first element of the given list. Raise
[Failure "hd"] if the list is empty. *)
val hd : 'a list -> 'a
(* Return the first element of the given list. Raise
[Failure "hd"] if the list is empty. *)
(** Return the given list without its first element. Raise
[Failure "tl"] if the list is empty. *)
val tl : 'a list -> 'a list
(* Return the given list without its first element. Raise
[Failure "tl"] if the list is empty. *)
(** Return the n-th element of the given list.
The first element (head of the list) is at position 0.
Raise [Failure "nth"] if the list is too short. *)
val nth : 'a list -> int -> 'a
(* Return the n-th element of the given list.
The first element (head of the list) is at position 0.
Raise [Failure "nth"] if the list is too short. *)
(** List reversal. *)
val rev : 'a list -> 'a list
(* List reversal. *)
(** Catenate two lists. Same function as the infix operator [@].
Not tail-recursive (length of the first argument). The [@]
operator is not tail-recursive either. *)
val append : 'a list -> 'a list -> 'a list
(* Catenate two lists. Same function as the infix operator [@].
Not tail-recursive (length of the first argument). The [@]
operator is not tail-recursive either. *)
(** [List.rev_append l1 l2] reverses [l1] and catenates it to [l2].
This is equivalent to {!ListLabels.rev}[ l1 @ l2], but [rev_append] is
tail-recursive and more efficient. *)
val rev_append : 'a list -> 'a list -> 'a list
(* [List.rev_append l1 l2] reverses [l1] and catenates it to [l2].
This is equivalent to [List.rev l1 @ l2], but [rev_append] is
tail-recursive and more efficient. *)
(** Concatenate a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
val concat : 'a list list -> 'a list
(** Flatten a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
val flatten : 'a list list -> 'a list
(* Catenate (flatten) a list of lists. Not tail-recursive
(length of the argument + length of the longest sub-list). *)
(** Iterators *)
(** {2 Iterators} *)
(** [List.iter f [a1; ...; an]] applies function [f] in turn to
[a1; ...; an]. It is equivalent to
[begin f a1; f a2; ...; f an; () end]. *)
val iter : f:('a -> unit) -> 'a list -> unit
(* [List.iter f [a1; ...; an]] applies function [f] in turn to
[a1; ...; an]. It is equivalent to
[begin f a1; f a2; ...; f an; () end]. *)
(** [List.map f [a1; ...; an]] applies function [f] to [a1, ..., an],
and builds the list [[f a1; ...; f an]]
with the results returned by [f]. Not tail-recursive. *)
val map : f:('a -> 'b) -> 'a list -> 'b list
(* [List.map f [a1; ...; an]] applies function [f] to [a1, ..., an],
and builds the list [[f a1; ...; f an]]
with the results returned by [f]. Not tail-recursive. *)
(** [List.rev_map f l] gives the same result as
{!ListLabels.rev}[ (]{!ListLabels.map}[ f l)], but is tail-recursive and
more efficient. *)
val rev_map : f:('a -> 'b) -> 'a list -> 'b list
(* [List.rev_map f l] gives the same result as
[List.rev (List.map f l)], but is tail-recursive and
more efficient. *)
(** [List.fold_left f a [b1; ...; bn]] is
[f (... (f (f a b1) b2) ...) bn]. *)
val fold_left : f:('a -> 'b -> 'a) -> init:'a -> 'b list -> 'a
(* [List.fold_left f a [b1; ...; bn]] is
[f (... (f (f a b1) b2) ...) bn]. *)
(** [List.fold_right f [a1; ...; an] b] is
[f a1 (f a2 (... (f an b) ...))]. Not tail-recursive. *)
val fold_right : f:('a -> 'b -> 'b) -> 'a list -> init:'b -> 'b
(* [List.fold_right f [a1; ...; an] b] is
[f a1 (f a2 (... (f an b) ...))]. Not tail-recursive. *)
(** Iterators on two lists *)
(** {2 Iterators on two lists} *)
(** [List.iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
[f a1 b1; ...; f an bn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
val iter2 : f:('a -> 'b -> unit) -> 'a list -> 'b list -> unit
(* [List.iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
[f a1 b1; ...; f an bn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [List.map2 f [a1; ...; an] [b1; ...; bn]] is
[[f a1 b1; ...; f an bn]].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
val map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
(* [List.map2 f [a1; ...; an] [b1; ...; bn]] is
[[f a1 b1; ...; f an bn]].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
(** [List.rev_map2 f l] gives the same result as
{!ListLabels.rev}[ (]{!ListLabels.map2}[ f l)], but is tail-recursive and
more efficient. *)
val rev_map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
(* [List.rev_map2 f l] gives the same result as
[List.rev (List.map2 f l)], but is tail-recursive and
more efficient. *)
(** [List.fold_left2 f a [b1; ...; bn] [c1; ...; cn]] is
[f (... (f (f a b1 c1) b2 c2) ...) bn cn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
val fold_left2 :
f:('a -> 'b -> 'c -> 'a) -> init:'a -> 'b list -> 'c list -> 'a
(* [List.fold_left2 f a [b1; ...; bn] [c1; ...; cn]] is
[f (... (f (f a b1 c1) b2 c2) ...) bn cn].
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [List.fold_right2 f [a1; ...; an] [b1; ...; bn] c] is
[f a1 b1 (f a2 b2 (... (f an bn c) ...))].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
val fold_right2 :
f:('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> init:'c -> 'c
(* [List.fold_right2 f [a1; ...; an] [b1; ...; bn] c] is
[f a1 b1 (f a2 b2 (... (f an bn c) ...))].
Raise [Invalid_argument] if the two lists have
different lengths. Not tail-recursive. *)
(** List scanning *)
(** {2 List scanning} *)
(** [for_all p [a1; ...; an]] checks if all elements of the list
satisfy the predicate [p]. That is, it returns
[(p a1) && (p a2) && ... && (p an)]. *)
val for_all : f:('a -> bool) -> 'a list -> bool
(* [for_all p [a1; ...; an]] checks if all elements of the list
satisfy the predicate [p]. That is, it returns
[(p a1) && (p a2) && ... && (p an)]. *)
(** [exists p [a1; ...; an]] checks if at least one element of
the list satisfies the predicate [p]. That is, it returns
[(p a1) || (p a2) || ... || (p an)]. *)
val exists : f:('a -> bool) -> 'a list -> bool
(* [exists p [a1; ...; an]] checks if at least one element of
the list satisfies the predicate [p]. That is, it returns
[(p a1) || (p a2) || ... || (p an)]. *)
(** Same as {!ListLabels.for_all}, but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
val for_all2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
(** Same as {!ListLabels.exists}, but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
val exists2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
(* Same as [for_all] and [exists], but for a two-argument predicate.
Raise [Invalid_argument] if the two lists have
different lengths. *)
(** [mem a l] is true if and only if [a] is equal
to an element of [l]. *)
val mem : 'a -> set:'a list -> bool
(* [mem a l] is true if and only if [a] is equal
to an element of [l]. *)
(** Same as {!ListLabels.mem}, but uses physical equality instead of structural
equality to compare list elements. *)
val memq : 'a -> set:'a list -> bool
(* Same as [mem], but uses physical equality instead of structural
equality to compare list elements. *)
(** List searching *)
(** {2 List searching} *)
(** [find p l] returns the first element of the list [l]
that satisfies the predicate [p].
Raise [Not_found] if there is no value that satisfies [p] in the
list [l]. *)
val find : f:('a -> bool) -> 'a list -> 'a
(* [find p l] returns the first element of the list [l]
that satisfies the predicate [p].
Raise [Not_found] if there is no value that satisfies [p] in the
list [l]. *)
(** [filter p l] returns all the elements of the list [l]
that satisfy the predicate [p]. The order of the elements
in the input list is preserved. *)
val filter : f:('a -> bool) -> 'a list -> 'a list
(** [find_all] is another name for {!ListLabels.filter}. *)
val find_all : f:('a -> bool) -> 'a list -> 'a list
(* [filter p l] returns all the elements of the list [l]
that satisfy the predicate [p]. The order of the elements
in the input list is preserved. [find_all] is another name
for [filter]. *)
(** [partition p l] returns a pair of lists [(l1, l2)], where
[l1] is the list of all the elements of [l] that
satisfy the predicate [p], and [l2] is the list of all the
elements of [l] that do not satisfy [p].
The order of the elements in the input list is preserved. *)
val partition : f:('a -> bool) -> 'a list -> 'a list * 'a list
(* [partition p l] returns a pair of lists [(l1, l2)], where
[l1] is the list of all the elements of [l] that
satisfy the predicate [p], and [l2] is the list of all the
elements of [l] that do not satisfy [p].
The order of the elements in the input list is preserved. *)
(** Association lists *)
(** {2 Association lists} *)
(** [assoc a l] returns the value associated with key [a] in the list of
pairs [l]. That is,
[assoc a [ ...; (a,b); ...] = b]
if [(a,b)] is the leftmost binding of [a] in list [l].
Raise [Not_found] if there is no value associated with [a] in the
list [l]. *)
val assoc : 'a -> ('a * 'b) list -> 'b
(* [assoc a l] returns the value associated with key [a] in the list of
pairs [l]. That is,
[assoc a [ ...; (a,b); ...] = b]
if [(a,b)] is the leftmost binding of [a] in list [l].
Raise [Not_found] if there is no value associated with [a] in the
list [l]. *)
(** Same as {!ListLabels.assoc}, but uses physical equality instead of structural
equality to compare keys. *)
val assq : 'a -> ('a * 'b) list -> 'b
(* Same as [assoc], but uses physical equality instead of structural
equality to compare keys. *)
(** Same as {!ListLabels.assoc}, but simply return true if a binding exists,
and false if no bindings exist for the given key. *)
val mem_assoc : 'a -> map:('a * 'b) list -> bool
(* Same as [assoc], but simply return true if a binding exists,
and false if no bindings exist for the given key. *)
(** Same as {!ListLabels.mem_assoc}, but uses physical equality instead of
structural equality to compare keys. *)
val mem_assq : 'a -> map:('a * 'b) list -> bool
(* Same as [mem_assoc], but uses physical equality instead of
structural equality to compare keys. *)
(** [remove_assoc a l] returns the list of
pairs [l] without the first pair with key [a], if any.
Not tail-recursive. *)
val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
(* [remove_assoc a l] returns the list of
pairs [l] without the first pair with key [a], if any.
Not tail-recursive. *)
(** Same as {!ListLabels.remove_assq}, but uses physical equality instead
of structural equality to compare keys. Not tail-recursive. *)
val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
(* Same as [remove_assq], but uses physical equality instead
of structural equality to compare keys. Not tail-recursive. *)
(** Lists of pairs *)
(** {2 Lists of pairs} *)
(** Transform a list of pairs into a pair of lists:
[split [(a1,b1); ...; (an,bn)]] is [([a1; ...; an], [b1; ...; bn])].
Not tail-recursive.
*)
val split : ('a * 'b) list -> 'a list * 'b list
(* Transform a list of pairs into a pair of lists:
[split [(a1,b1); ...; (an,bn)]] is [([a1; ...; an], [b1; ...; bn])].
Not tail-recursive.
*)
(** Transform a pair of lists into a list of pairs:
[combine [a1; ...; an] [b1; ...; bn]] is
[[(a1,b1); ...; (an,bn)]].
Raise [Invalid_argument] if the two lists
have different lengths. Not tail-recursive. *)
val combine : 'a list -> 'b list -> ('a * 'b) list
(* Transform a pair of lists into a list of pairs:
[combine ([a1; ...; an], [b1; ...; bn])] is
[[(a1,b1); ...; (an,bn)]].
Raise [Invalid_argument] if the two lists
have different lengths. Not tail-recursive. *)
(** Sorting *)
(** {2 Sorting} *)
(** Sort a list in increasing order according to a comparison
function. The comparison function must return 0 if it arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller. For example,
the [compare] function is a suitable comparison function.
The resulting list is sorted in increasing order.
[List.sort] is guaranteed to run in constant heap space
(in addition to the size of the result list) and logarithmic
stack space.
The current implementation uses Merge Sort and is the same as
{!ListLabels.stable_sort}.
*)
val sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list;;
(* Sort a list in increasing order according to a comparison
function. The comparison function must return 0 if it arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller. For example,
the [compare] function is a suitable comparison function.
The resulting list is sorted in increasing order.
[List.sort] is guaranteed to run in constant heap space
(in addition to the size of the result list) and logarithmic
stack space.
The current implementation uses Merge Sort and is the same as
[List.stable_sort].
*)
(** Same as {!ListLabels.sort}, but the sorting algorithm is stable.
The current implementation is Merge Sort. It runs in constant
heap space and logarithmic stack space.
*)
val stable_sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list;;
(* Same as [List.sort], but the sorting algorithm is stable.
The current implementation is Merge Sort. It runs in constant
heap space and logarithmic stack space.
*)

101
stdlib/map.mli
View File

@ -12,74 +12,87 @@
(* $Id$ *)
(* Module [Map]: association tables over ordered types *)
(** Association tables over ordered types.
(* This module implements applicative association tables, also known as
This module implements applicative association tables, also known as
finite maps or dictionaries, given a total ordering function
over the keys.
All operations over maps are purely applicative (no side-effects).
The implementation uses balanced binary trees, and therefore searching
and insertion take time logarithmic in the size of the map. *)
and insertion take time logarithmic in the size of the map.
*)
(** The input signature of the functor [Map.Make].
[t] is the type of the map keys.
{!Pervasives.compare} is a total ordering function over the keys.
This is a two-argument function [f] such that
[f e1 e2] is zero if the keys [e1] and [e2] are equal,
[f e1 e2] is strictly negative if [e1] is smaller than [e2],
and [f e1 e2] is strictly positive if [e1] is greater than [e2].
Example: a suitable ordering function is
the generic structural comparison function {!Pervasives.compare}. *)
module type OrderedType =
sig
type t
val compare: t -> t -> int
end
(* The input signature of the functor [Map.Make].
[t] is the type of the map keys.
[compare] is a total ordering function over the keys.
This is a two-argument function [f] such that
[f e1 e2] is zero if the keys [e1] and [e2] are equal,
[f e1 e2] is strictly negative if [e1] is smaller than [e2],
and [f e1 e2] is strictly positive if [e1] is greater than [e2].
Example: a suitable ordering function is
the generic structural comparison function [compare]. *)
module type S =
sig
(** The type of the map keys. *)
type key
(* The type of the map keys. *)
(** The type of maps from type [key] to type ['a]. *)
type (+'a) t
(* The type of maps from type [key] to type ['a]. *)
(** The empty map. *)
val empty: 'a t
(* The empty map. *)
(** [add x y m] returns a map containing the same bindings as
[m], plus a binding of [x] to [y]. If [x] was already bound
in [m], its previous binding disappears. *)
val add: key -> 'a -> 'a t -> 'a t
(* [add x y m] returns a map containing the same bindings as
[m], plus a binding of [x] to [y]. If [x] was already bound
in [m], its previous binding disappears. *)
(** [find x m] returns the current binding of [x] in [m],
or raises [Not_found] if no such binding exists. *)
val find: key -> 'a t -> 'a
(* [find x m] returns the current binding of [x] in [m],
or raises [Not_found] if no such binding exists. *)
(** [remove x m] returns a map containing the same bindings as
[m], except for [x] which is unbound in the returned map. *)
val remove: key -> 'a t -> 'a t
(* [remove x m] returns a map containing the same bindings as
[m], except for [x] which is unbound in the returned map. *)
(** [mem x m] returns [true] if [m] contains a binding for [x],
and [false] otherwise. *)
val mem: key -> 'a t -> bool
(* [mem x m] returns [true] if [m] contains a binding for [x],
and [false] otherwise. *)
(** [iter f m] applies [f] to all bindings in map [m].
[f] receives the key as first argument, and the associated value
as second argument. The order in which the bindings are passed to
[f] is unspecified. Only current bindings are presented to [f]:
bindings hidden by more recent bindings are not passed to [f]. *)
val iter: (key -> 'a -> unit) -> 'a t -> unit
(* [iter f m] applies [f] to all bindings in map [m].
[f] receives the key as first argument, and the associated value
as second argument. The order in which the bindings are passed to
[f] is unspecified. Only current bindings are presented to [f]:
bindings hidden by more recent bindings are not passed to [f]. *)
(** [map f m] returns a map with same domain as [m], where the
associated value [a] of all bindings of [m] has been
replaced by the result of the application of [f] to [a].
The order in which the associated values are passed to [f]
is unspecified. *)
val map: ('a -> 'b) -> 'a t -> 'b t
(* [map f m] returns a map with same domain as [m], where the
associated value [a] of all bindings of [m] has been
replaced by the result of the application of [f] to [a].
The order in which the associated values are passed to [f]
is unspecified. *)
(** Same as {!Map.S.map}, but the function receives as arguments both the
key and the associated value for each binding of the map. *)
val mapi: (key -> 'a -> 'b) -> 'a t -> 'b t
(* Same as [map], but the function receives as arguments both the
key and the associated value for each binding of the map. *)
(** [fold f m a] computes [(f kN dN ... (f k1 d1 a)...)],
where [k1 ... kN] are the keys of all bindings in [m],
and [d1 ... dN] are the associated data.
The order in which the bindings are presented to [f] is
unspecified. *)
val fold: (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
(* [fold f m a] computes [(f kN dN ... (f k1 d1 a)...)],
where [k1 ... kN] are the keys of all bindings in [m],
and [d1 ... dN] are the associated data.
The order in which the bindings are presented to [f] is
unspecified. *)
end
module Make(Ord: OrderedType): (S with type key = Ord.t)
(* Functor building an implementation of the map structure
given a totally ordered type. *)
(** Functor building an implementation of the map structure
given a totally ordered type. *)
module Make (Ord : OrderedType): (S with type key = Ord.t)

152
stdlib/marshal.mli
View File

@ -12,9 +12,9 @@
(* $Id$ *)
(* Module [Marshal]: marshaling of data structures *)
(** Marshaling of data structures.
(* This module provides functions to encode arbitrary data structures
This module provides functions to encode arbitrary data structures
as sequences of bytes, which can then be written on a file or
sent over a pipe or network connection. The bytes can then
be read back later, possibly in another process, and decoded back
@ -30,7 +30,7 @@
for all ['a]; it has one, unique type which cannot be determined
at compile-type. The programmer should explicitly give the expected
type of the returned value, using the following syntax:
[(Marshal.from_channel chan : type)].
- [(Marshal.from_channel chan : type)].
Anything can happen at run-time if the object in the file does not
belong to the given type.
@ -40,92 +40,98 @@
and [Marshal.from_channel] must be opened in binary mode, using e.g.
[open_out_bin] or [open_in_bin]; channels opened in text mode will
cause unmarshaling errors on platforms where text channels behave
differently than binary channels, e.g. Windows. *)
differently than binary channels, e.g. Windows.
*)
(** The flags to the [Marshal.to_*] functions below. *)
type extern_flags =
No_sharing (* Don't preserve sharing *)
| Closures (* Send function closures *)
(* The flags to the [Marshal.to_*] functions below. *)
No_sharing (** Don't preserve sharing *)
| Closures (** Send function closures *)
(** [Marshal.to_channel chan v flags] writes the representation
of [v] on channel [chan]. The [flags] argument is a
possibly empty list of flags that governs the marshaling
behavior with respect to sharing and functional values.
If [flags] does not contain [Marshal.No_sharing], circularities
and sharing inside the value [v] are detected and preserved
in the sequence of bytes produced. In particular, this
guarantees that marshaling always terminates. Sharing
between values marshaled by successive calls to
[Marshal.to_channel] is not detected, though.
If [flags] contains [Marshal.No_sharing], sharing is ignored.
This results in faster marshaling if [v] contains no shared
substructures, but may cause slower marshaling and larger
byte representations if [v] actually contains sharing,
or even non-termination if [v] contains cycles.
If [flags] does not contain [Marshal.Closures],
marshaling fails when it encounters a functional value
inside [v]: only ``pure'' data structures, containing neither
functions nor objects, can safely be transmitted between
different programs. If [flags] contains [Marshal.Closures],
functional values will be marshaled as a position in the code
of the program. In this case, the output of marshaling can
only be read back in processes that run exactly the same program,
with exactly the same compiled code. (This is checked
at un-marshaling time, using an MD5 digest of the code
transmitted along with the code position.) *)
val to_channel: out_channel -> 'a -> extern_flags list -> unit
(* [Marshal.to_channel chan v flags] writes the representation
of [v] on channel [chan]. The [flags] argument is a
possibly empty list of flags that governs the marshaling
behavior with respect to sharing and functional values.
If [flags] does not contain [Marshal.No_sharing], circularities
and sharing inside the value [v] are detected and preserved
in the sequence of bytes produced. In particular, this
guarantees that marshaling always terminates. Sharing
between values marshaled by successive calls to
[Marshal.to_channel] is not detected, though.
If [flags] contains [Marshal.No_sharing], sharing is ignored.
This results in faster marshaling if [v] contains no shared
substructures, but may cause slower marshaling and larger
byte representations if [v] actually contains sharing,
or even non-termination if [v] contains cycles.
If [flags] does not contain [Marshal.Closures],
marshaling fails when it encounters a functional value
inside [v]: only ``pure'' data structures, containing neither
functions nor objects, can safely be transmitted between
different programs. If [flags] contains [Marshal.Closures],
functional values will be marshaled as a position in the code
of the program. In this case, the output of marshaling can
only be read back in processes that run exactly the same program,
with exactly the same compiled code. (This is checked
at un-marshaling time, using an MD5 digest of the code
transmitted along with the code position.) *)
(** [Marshal.to_string v flags] returns a string containing
the representation of [v] as a sequence of bytes.
The [flags] argument has the same meaning as for
{!Marshal.to_channel}. *)
external to_string: 'a -> extern_flags list -> string
= "output_value_to_string"
(* [Marshal.to_string v flags] returns a string containing
the representation of [v] as a sequence of bytes.
The [flags] argument has the same meaning as for
[Marshal.to_channel]. *)
(** [Marshal.to_buffer buff ofs len v flags] marshals the value [v],
storing its byte representation in the string [buff],
starting at character number [ofs], and writing at most
[len] characters. It returns the number of characters
actually written to the string. If the byte representation
of [v] does not fit in [len] characters, the exception [Failure]
is raised. *)
val to_buffer: string -> int -> int -> 'a -> extern_flags list -> int
(* [Marshal.to_buffer buff ofs len v flags] marshals the value [v],
storing its byte representation in the string [buff],
starting at character number [ofs], and writing at most
[len] characters. It returns the number of characters
actually written to the string. If the byte representation
of [v] does not fit in [len] characters, the exception [Failure]
is raised. *)
(** [Marshal.from_channel chan] reads from channel [chan] the
byte representation of a structured value, as produced by
one of the [Marshal.to_*] functions, and reconstructs and
returns the corresponding value.*)
val from_channel: in_channel -> 'a
(* [Marshal.from_channel chan] reads from channel [chan] the
byte representation of a structured value, as produced by
one of the [Marshal.to_*] functions, and reconstructs and
returns the corresponding value.*)
(** [Marshal.from_string buff ofs] unmarshals a structured value
like {!Marshal.from_channel} does, except that the byte
representation is not read from a channel, but taken from
the string [buff], starting at position [ofs]. *)
val from_string: string -> int -> 'a
(* [Marshal.from_string buff ofs] unmarshals a structured value
like [Marshal.from_channel] does, except that the byte
representation is not read from a channel, but taken from
the string [buff], starting at position [ofs]. *)
(** The bytes representing a marshaled value are composed of
a fixed-size header and a variable-sized data part,
whose size can be determined from the header.
{!Marshal.header_size} is the size, in characters, of the header.
{!Marshal.data_size}[ buff ofs] is the size, in characters,
of the data part, assuming a valid header is stored in
[buff] starting at position [ofs].
Finally, {!Marshal.total_size}[ buff ofs] is the total size,
in characters, of the marshaled value.
Both {!Marshal.data_size} and {!Marshal.total_size} raise [Failure]
if [buff], [ofs] does not contain a valid header.
To read the byte representation of a marshaled value into
a string buffer, the program needs to read first
{!Marshal.header_size} characters into the buffer,
then determine the length of the remainder of the
representation using {!Marshal.data_size},
make sure the buffer is large enough to hold the remaining
data, then read it, and finally call {!Marshal.from_string}
to unmarshal the value. *)
val header_size : int
(** See {!Marshal.header_size}.*)
val data_size : string -> int -> int
(** See {!Marshal.header_size}.*)
val total_size : string -> int -> int
(* The bytes representing a marshaled value are composed of
a fixed-size header and a variable-sized data part,
whose size can be determined from the header.
[Marshal.header_size] is the size, in characters, of the header.
[Marshal.data_size buff ofs] is the size, in characters,
of the data part, assuming a valid header is stored in
[buff] starting at position [ofs].
Finally, [Marshal.total_size buff ofs] is the total size,
in characters, of the marshaled value.
Both [Marshal.data_size] and [Marshal.total_size] raise [Failure]
if [buff], [ofs] does not contain a valid header.
To read the byte representation of a marshaled value into
a string buffer, the program needs to read first
[Marshal.header_size] characters into the buffer,
then determine the length of the remainder of the
representation using [Marshal.data_size],
make sure the buffer is large enough to hold the remaining
data, then read it, and finally call [Marshal.from_string]
to unmarshal the value. *)

187
stdlib/nativeint.mli
View File

@ -12,9 +12,9 @@
(* $Id$ *)
(* Module [Nativeint]: processor-native integers *)
(** Processor-native integers.
(* This module provides operations on the type [nativeint] of
This module provides operations on the type [nativeint] of
signed 32-bit integers (on 32-bit platforms) or
signed 64-bit integers (on 64-bit platforms).
This integer type has exactly the same width as that of a [long]
@ -26,117 +26,146 @@
space than values of type [int], and arithmetic operations on
[nativeint] are generally slower than those on [int]. Use [nativeint]
only when the application requires the extra bit of precision
over the [int] type. *)
over the [int] type.
*)
(** The native integer 0.*)
val zero: nativeint
(** The native integer 1.*)
val one: nativeint
(** The native integer -1.*)
val minus_one: nativeint
(* The native integers 0, 1, -1. *)
(** Unary negation. *)
external neg: nativeint -> nativeint = "%nativeint_neg"
(* Unary negation. *)
(** Addition. *)
external add: nativeint -> nativeint -> nativeint = "%nativeint_add"
(* Addition. *)
(** Subtraction. *)
external sub: nativeint -> nativeint -> nativeint = "%nativeint_sub"
(* Subtraction. *)
(** Multiplication. *)
external mul: nativeint -> nativeint -> nativeint = "%nativeint_mul"
(* Multiplication. *)
(** Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
external div: nativeint -> nativeint -> nativeint = "%nativeint_div"
(* Integer division. Raise [Division_by_zero] if the second
argument is zero. *)
(** Integer remainder. If [x >= 0] and [y > 0], the result
of [Nativeint.rem x y] satisfies the following properties:
[0 <= Nativeint.rem x y < y] and
[x = Nativeint.add (Nativeint.mul (Nativeint.div x y) y) (Nativeint.rem x y)].
If [y = 0], [Nativeint.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Nativeint.rem x y] is
not specified and depends on the platform. *)
external rem: nativeint -> nativeint -> nativeint = "%nativeint_mod"
(* Integer remainder. If [x >= 0] and [y > 0], the result
of [Nativeint.rem x y] satisfies the following properties:
[0 <= Nativeint.rem x y < y] and
[x = Nativeint.add (Nativeint.mul (Nativeint.div x y) y) (Nativeint.rem x y)].
If [y = 0], [Nativeint.rem x y] raises [Division_by_zero].
If [x < 0] or [y < 0], the result of [Nativeint.rem x y] is
not specified and depends on the platform. *)
(** Successor.
[Nativeint.succ x] is [Nativeint.add x Nativeint.one]. *)
val succ: nativeint -> nativeint
(* Successor.
[Nativeint.succ x] is [Nativeint.add x Nativeint.one]. *)
(** Predecessor.
[Nativeint.pred x] is [Nativeint.sub x Nativeint.one]. *)
val pred: nativeint -> nativeint
(* Predecessor.
[Nativeint.pred x] is [Nativeint.sub x Nativeint.one]. *)
(** Return the absolute value of its argument. *)
val abs: nativeint -> nativeint
(* Return the absolute value of its argument. *)
(** The size in bits of a native integer. This is equal to [32]
on a 32-bit platform and to [64] on a 64-bit platform. *)
val size: int
(* The size in bits of a native integer. This is equal to [32]
on a 32-bit platform and to [64] on a 64-bit platform. *)
(** The greatest representable native integer,
either $2^{31} - 1$ on a 32-bit platform,
or $2^{63} - 1$ on a 64-bit platform. *)
val max_int: nativeint
(* The greatest representable native integer,
either $2^{31} - 1$ on a 32-bit platform,
or $2^{63} - 1$ on a 64-bit platform. *)
(** The greatest representable native integer,
either $-2^{31}$ on a 32-bit platform,
or $-2^{63}$ on a 64-bit platform. *)
val min_int: nativeint
(* The greatest representable native integer,
either $-2^{31}$ on a 32-bit platform,
or $-2^{63}$ on a 64-bit platform. *)
(** Bitwise logical and. *)
external logand: nativeint -> nativeint -> nativeint = "%nativeint_and"
(* Bitwise logical and. *)
(** Bitwise logical or. *)
external logor: nativeint -> nativeint -> nativeint = "%nativeint_or"
(* Bitwise logical or. *)
(** Bitwise logical exclusive or. *)
external logxor: nativeint -> nativeint -> nativeint = "%nativeint_xor"
(* Bitwise logical exclusive or. *)
(** Bitwise logical negation *)
val lognot: nativeint -> nativeint
(* Bitwise logical negation *)
(** [Nativeint.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= bitsize],
where [bitsize] is [32] on a 32-bit platform and
[64] on a 64-bit platform. *)
external shift_left: nativeint -> int -> nativeint = "%nativeint_lsl"
(* [Nativeint.shift_left x y] shifts [x] to the left by [y] bits.
The result is unspecified if [y < 0] or [y >= bitsize],
where [bitsize] is [32] on a 32-bit platform and
[64] on a 64-bit platform. *)
(** [Nativeint.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= bitsize]. *)
external shift_right: nativeint -> int -> nativeint = "%nativeint_asr"
(* [Nativeint.shift_right x y] shifts [x] to the right by [y] bits.
This is an arithmetic shift: the sign bit of [x] is replicated
and inserted in the vacated bits.
The result is unspecified if [y < 0] or [y >= bitsize]. *)
(** [Nativeint.shift_right_logical x y] shifts [x] to the right
by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= bitsize]. *)
external shift_right_logical: nativeint -> int -> nativeint = "%nativeint_lsr"
(* [Nativeint.shift_right_logical x y] shifts [x] to the right
by [y] bits.
This is a logical shift: zeroes are inserted in the vacated bits
regardless of the sign of [x].
The result is unspecified if [y < 0] or [y >= bitsize]. *)
(** Convert the given integer (type [int]) to a native integer
(type [nativeint]). *)
external of_int: int -> nativeint = "%nativeint_of_int"
(* Convert the given integer (type [int]) to a native integer
(type [nativeint]). *)
(** Convert the given native integer (type [nativeint]) to an
integer (type [int]). The high-order bit is lost during
the conversion. *)
external to_int: nativeint -> int = "%nativeint_to_int"
(* Convert the given native integer (type [nativeint]) to an
integer (type [int]). The high-order bit is lost during
the conversion. *)
(** Convert the given floating-point number to a native integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range
\[{!Nativeint.min_int}, {!Nativeint.max_int}\]. *)
external of_float : float -> nativeint = "nativeint_of_float"
(* Convert the given floating-point number to a native integer,
discarding the fractional part (truncate towards 0).
The result of the conversion is undefined if, after truncation,
the number is outside the range
[Nativeint.min_int, Nativeint.max_int]. *)
(** Convert the given native integer to a floating-point number. *)
external to_float : nativeint -> float = "nativeint_to_float"
(* Convert the given native integer to a floating-point number. *)
(** Convert the given 32-bit integer (type [int32])
to a native integer. *)
external of_int32: int32 -> nativeint = "%nativeint_of_int32"
(* Convert the given 32-bit integer (type [int32])
to a native integer. *)
(** Convert the given native integer to a
32-bit integer (type [int32]). On 64-bit platforms,
the 64-bit native integer is taken modulo $2^{32}$,
i.e. the top 32 bits are lost. On 32-bit platforms,
the conversion is exact. *)
external to_int32: nativeint -> int32 = "%nativeint_to_int32"
(* Convert the given native integer to a
32-bit integer (type [int32]). On 64-bit platforms,
the 64-bit native integer is taken modulo $2^{32}$,
i.e. the top 32 bits are lost. On 32-bit platforms,
the conversion is exact. *)
(** Convert the given string to a native integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
external of_string: string -> nativeint = "nativeint_of_string"
(* Convert the given string to a native integer.
The string is read in decimal (by default) or in hexadecimal,
octal or binary if the string begins with [0x], [0o] or [0b]
respectively.
Raise [Failure "int_of_string"] if the given string is not
a valid representation of an integer. *)
val to_string: nativeint -> string
(* Return the string representation of its argument, in decimal. *)
external format : string -> nativeint -> string = "nativeint_format"
(* [Nativeint.format fmt n] return the string representation of the
native integer [n] in the format specified by [fmt].
[fmt] is a [Printf]-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the [Printf] module for more information, *)
(** Return the string representation of its argument, in decimal. *)
val to_string: nativeint -> string
(** [Nativeint.format fmt n] return the string representation of the
native integer [n] in the format specified by [fmt].
[fmt] is a [Printf]-style format containing exactly
one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
See the documentation of the [Printf] module for more information, *)
external format : string -> nativeint -> string = "nativeint_format"

8
stdlib/obj.mli
View File

@ -12,9 +12,10 @@
(* $Id$ *)
(* Module [Obj]: operations on internal representations of values *)
(** Operations on internal representations of values.
(* Not for the casual user. *)
Not for the casual user.
*)
type t
@ -41,8 +42,7 @@ val double_tag : int
val double_array_tag : int
val final_tag : int
(* The following two functions are deprecated. Use module [Marshal]
instead. *)
(** The following two functions are deprecated. Use module {!Marshal} instead. *)
val marshal : t -> string
val unmarshal : string -> int -> t * int

24
stdlib/oo.mli
View File

@ -12,21 +12,24 @@
(* $Id$ *)
(* Module [Oo]: object-oriented extension *)
(** Object-oriented extension *)
(** [Oo.copy o] returns a copy of object [o], that is a fresh
object with the same methods and instance variables as [o] *)
val copy : (< .. > as 'a) -> 'a
(* [Oo.copy o] returns a copy of object [o], that is a fresh
object with the same methods and instance variables as [o] *)
(*--*)
(*** For system use only, not for the casual user *)
(** {2 For system use only, not for the casual user} *)
(** {2 Methods} *)
(* Methods *)
type label
val new_method: string -> label
(* Classes *)
(** {2 Classes} *)
type table
type meth
type t
@ -42,12 +45,14 @@ val add_initializer: table -> (obj -> unit) -> unit
val create_table: string list -> table
val init_class: table -> unit
(* Objects *)
(** {2 Objects} *)
val create_object: table -> obj
val run_initializers: obj -> table -> unit
val send: obj -> label -> t
(* Parameters *)
(** {2 Parameters} *)
type params = {
mutable compact_table : bool;
mutable copy_parent : bool;
@ -58,7 +63,8 @@ type params = {
val params : params
(* Statistics *)
(** {2 Statistics} *)
type stats =
{ classes: int; labels: int; methods: int; inst_vars: int; buckets: int;
distrib : int array; small_bucket_count: int; small_bucket_max: int }

57
stdlib/parsing.mli
View File

@ -12,37 +12,46 @@
(* $Id$ *)
(* Module [Parsing]: the run-time library for parsers generated by [ocamlyacc]*)
(** The run-time library for parsers generated by [ocamlyacc]. *)
(** [symbol_start] and {!Parsing.symbol_end} are to be called in the action part
of a grammar rule only. They return the position of the string that
matches the left-hand side of the rule: [symbol_start()] returns
the position of the first character; [symbol_end()] returns the
position of the last character, plus one. The first character
in a file is at position 0. *)
val symbol_start : unit -> int
val symbol_end : unit -> int
(* [symbol_start] and [symbol_end] are to be called in the action part
of a grammar rule only. They return the position of the string that
matches the left-hand side of the rule: [symbol_start()] returns
the position of the first character; [symbol_end()] returns the
position of the last character, plus one. The first character
in a file is at position 0. *)
val rhs_start: int -> int
val rhs_end: int -> int
(* Same as [symbol_start] and [symbol_end], but return the
position of the string matching the [n]th item on the
right-hand side of the rule, where [n] is the integer parameter
to [lhs_start] and [lhs_end]. [n] is 1 for the leftmost item. *)
val clear_parser : unit -> unit
(* Empty the parser stack. Call it just after a parsing function
has returned, to remove all pointers from the parser stack
to structures that were built by semantic actions during parsing.
This is optional, but lowers the memory requirements of the
programs. *)
(** See {!Parsing.symbol_start}. *)
val symbol_end : unit -> int
(** Same as {!Parsing.symbol_start} and {!Parsing.symbol_end}, but return the
position of the string matching the [n]th item on the
right-hand side of the rule, where [n] is the integer parameter
to [lhs_start] and [lhs_end]. [n] is 1 for the leftmost item. *)
val rhs_start: int -> int
(** See {!Parsing.rhs_start}. *)
val rhs_end: int -> int
(** Empty the parser stack. Call it just after a parsing function
has returned, to remove all pointers from the parser stack
to structures that were built by semantic actions during parsing.
This is optional, but lowers the memory requirements of the
programs. *)
val clear_parser : unit -> unit
(** Raised when a parser encounters a syntax error.
Can also be raised from the action part of a grammar rule,
to initiate error recovery. *)
exception Parse_error
(* Raised when a parser encounters a syntax error.
Can also be raised from the action part of a grammar rule,
to initiate error recovery. *)
(*--*)
(* The following definitions are used by the generated parsers only.
(** {2 } *)
(** The following definitions are used by the generated parsers only.
They are not intended to be used by user programs. *)
type parser_env

1049
stdlib/pervasives.mli
View File

File diff suppressed because it is too large Load Diff

35
stdlib/printexc.mli
View File

@ -12,26 +12,27 @@
(* $Id$ *)
(* Module [Printexc]: facilities for printing exceptions *)
(** Facilities for printing exceptions. *)
(** [Printexc.to_string e] returns a string representation of
the exception [e]. *)
val to_string : exn -> string
(* [Printexc.to_string e] returns a string representation of
the exception [e]. *)
(** [Printexc.print fn x] applies [fn] to [x] and returns the result.
If the evaluation of [fn x] raises any exception, the
name of the exception is printed on standard error output,
and the exception is raised again.
The typical use is to catch and report exceptions that
escape a function application. *)
val print: ('a -> 'b) -> 'a -> 'b
(* [Printexc.print fn x] applies [fn] to [x] and returns the result.
If the evaluation of [fn x] raises any exception, the
name of the exception is printed on standard error output,
and the exception is raised again.
The typical use is to catch and report exceptions that
escape a function application. *)
(** [Printexc.catch fn x] is similar to {!Printexc.print}, but
aborts the program with exit code 2 after printing the
uncaught exception. This function is deprecated: the runtime
system is now able to print uncaught exceptions as precisely
as [Printexc.catch] does. Moreover, calling [Printexc.catch]
makes it harder to track the location of the exception
using the debugger or the stack backtrace facility.
So, do not use [Printexc.catch] in new code. *)
val catch: ('a -> 'b) -> 'a -> 'b
(* [Printexc.catch fn x] is similar to [Printexc.print], but
aborts the program with exit code 2 after printing the
uncaught exception. This function is deprecated: the runtime
system is now able to print uncaught exceptions as precisely
as [Printexc.catch] does. Moreover, calling [Printexc.catch]
makes it harder to track the location of the exception
using the debugger or the stack backtrace facility.
So, do not use [Printexc.catch] in new code. *)

116
stdlib/printf.mli
View File

@ -12,72 +12,72 @@
(* $Id$ *)
(* Module [Printf]: formatting printing functions *)
(** Formatting printing functions. *)
(** [fprintf outchan format arg1 ... argN] formats the arguments
[arg1] to [argN] according to the format string [format],
and outputs the resulting string on the channel [outchan].
The format is a character string which contains two types of
objects: plain characters, which are simply copied to the
output channel, and conversion specifications, each of which
causes conversion and printing of one argument.
Conversion specifications consist in the [%] character, followed
by optional flags and field widths, followed by one conversion
character. The conversion characters and their meanings are:
- [d] or [i]: convert an integer argument to signed decimal
- [u]: convert an integer argument to unsigned decimal
- [x]: convert an integer argument to unsigned hexadecimal,
using lowercase letters.
- [X]: convert an integer argument to unsigned hexadecimal,
using uppercase letters.
- [o]: convert an integer argument to unsigned octal.
- [s]: insert a string argument
- [c]: insert a character argument
- [f]: convert a floating-point argument to decimal notation,
in the style [dddd.ddd]
- [e] or [E]: convert a floating-point argument to decimal notation,
in the style [d.ddd e+-dd] (mantissa and exponent)
- [g] or [G]: convert a floating-point argument to decimal notation,
in style [f] or [e], [E] (whichever is more compact)
- [b]: convert a boolean argument to the string [true] or [false]
- [a]: user-defined printer. Takes two arguments and apply the first
one to [outchan] (the current output channel) and to the second
argument. The first argument must therefore have type
[out_channel -> 'b -> unit] and the second ['b].
The output produced by the function is therefore inserted
in the output of [fprintf] at the current point.
- [t]: same as [%a], but takes only one argument (with type
[out_channel -> unit]) and apply it to [outchan].
- [%]: take no argument and output one [%] character.
- Refer to the C library [printf] function for the meaning of
flags and field width specifiers.
Warning: if too few arguments are provided,
for instance because the [printf] function is partially
applied, the format is immediately printed up to
the conversion of the first missing argument; printing
will then resume when the missing arguments are provided.
For example, [List.iter (printf "x=%d y=%d " 1) [2;3]]
prints [x=1 y=2 3] instead of the expected
[x=1 y=2 x=1 y=3]. To get the expected behavior, do
[List.iter (fun y -> printf "x=%d y=%d " 1 y) [2;3]]. *)
val fprintf: out_channel -> ('a, out_channel, unit) format -> 'a
(* [fprintf outchan format arg1 ... argN] formats the arguments
[arg1] to [argN] according to the format string [format],
and outputs the resulting string on the channel [outchan].
The format is a character string which contains two types of
objects: plain characters, which are simply copied to the
output channel, and conversion specifications, each of which
causes conversion and printing of one argument.
Conversion specifications consist in the [%] character, followed
by optional flags and field widths, followed by one conversion
character. The conversion characters and their meanings are:
- [d] or [i]: convert an integer argument to signed decimal
- [u]: convert an integer argument to unsigned decimal
- [x]: convert an integer argument to unsigned hexadecimal,
using lowercase letters.
- [X]: convert an integer argument to unsigned hexadecimal,
using uppercase letters.
- [o]: convert an integer argument to unsigned octal.
- [s]: insert a string argument
- [c]: insert a character argument
- [f]: convert a floating-point argument to decimal notation,
in the style [dddd.ddd]
- [e] or [E]: convert a floating-point argument to decimal notation,
in the style [d.ddd e+-dd] (mantissa and exponent)
- [g] or [G]: convert a floating-point argument to decimal notation,
in style [f] or [e], [E] (whichever is more compact)
- [b]: convert a boolean argument to the string [true] or [false]
- [a]: user-defined printer. Takes two arguments and apply the first
one to [outchan] (the current output channel) and to the second
argument. The first argument must therefore have type
[out_channel -> 'b -> unit] and the second ['b].
The output produced by the function is therefore inserted
in the output of [fprintf] at the current point.
- [t]: same as [%a], but takes only one argument (with type
[out_channel -> unit]) and apply it to [outchan].
- [%]: take no argument and output one [%] character.
- Refer to the C library [printf] function for the meaning of
flags and field width specifiers.
Warning: if too few arguments are provided,
for instance because the [printf] function is partially
applied, the format is immediately printed up to
the conversion of the first missing argument; printing
will then resume when the missing arguments are provided.
For example, [List.iter (printf "x=%d y=%d " 1) [2;3]]
prints [x=1 y=2 3] instead of the expected
[x=1 y=2 x=1 y=3]. To get the expected behavior, do
[List.iter (fun y -> printf "x=%d y=%d " 1 y) [2;3]]. *)
(** Same as {!Printf.fprintf}, but output on [stdout]. *)
val printf: ('a, out_channel, unit) format -> 'a
(* Same as [fprintf], but output on [stdout]. *)
(** Same as {!Printf.fprintf}, but output on [stderr]. *)
val eprintf: ('a, out_channel, unit) format -> 'a
(* Same as [fprintf], but output on [stderr]. *)
(** Same as {!Printf.fprintf}, but instead of printing on an output channel,
return a string containing the result of formatting
the arguments. *)
val sprintf: ('a, unit, string) format -> 'a
(* Same as [fprintf], but instead of printing on an output channel,
return a string containing the result of formatting
the arguments. *)
(** Same as {!Printf.fprintf}, but instead of printing on an output channel,
append the formatted arguments to the given extensible buffer
(see module {!Buffer}). *)
val bprintf: Buffer.t -> ('a, Buffer.t, unit) format -> 'a
(* Same as [fprintf], but instead of printing on an output channel,
append the formatted arguments to the given extensible buffer
(see module [Buffer]). *)

40
stdlib/queue.mli
View File

@ -12,31 +12,41 @@
(* $Id$ *)
(* Module [Queue]: first-in first-out queues *)
(** First-in first-out queues.
(* This module implements queues (FIFOs), with in-place modification. *)
This module implements queues (FIFOs), with in-place modification.
*)
(** The type of queues containing elements of type ['a]. *)
type 'a t
(* The type of queues containing elements of type ['a]. *)
(** Raised when {!Queue.take} or {!Queue.peek} is applied to an empty queue. *)
exception Empty
(* Raised when [take] is applied to an empty queue. *)
(** Return a new queue, initially empty. *)
val create: unit -> 'a t
(* Return a new queue, initially empty. *)
(** [add x q] adds the element [x] at the end of the queue [q]. *)
val add: 'a -> 'a t -> unit
(* [add x q] adds the element [x] at the end of the queue [q]. *)
(** [take q] removes and returns the first element in queue [q],
or raises [Empty] if the queue is empty. *)
val take: 'a t -> 'a
(* [take q] removes and returns the first element in queue [q],
or raises [Empty] if the queue is empty. *)
(** [peek q] returns the first element in queue [q], without removing
it from the queue, or raises [Empty] if the queue is empty. *)
val peek: 'a t -> 'a
(* [peek q] returns the first element in queue [q], without removing
it from the queue, or raises [Empty] if the queue is empty. *)
(** Discard all elements from a queue. *)
val clear: 'a t -> unit
(* Discard all elements from a queue. *)
(** Return the number of elements in a queue. *)
val length: 'a t -> int
(* Return the number of elements in a queue. *)
(** [iter f q] applies [f] in turn to all elements of [q],
from the least recently entered to the most recently entered.
The queue itself is unchanged. *)
val iter: ('a -> unit) -> 'a t -> unit
(* [iter f q] applies [f] in turn to all elements of [q],
from the least recently entered to the most recently entered.
The queue itself is unchanged. *)

51
stdlib/random.mli
View File

@ -12,35 +12,42 @@
(* $Id$ *)
(* Module [Random]: pseudo-random number generator (PRNG) *)
(** Pseudo-random number generator (PRNG). *)
val init : int -> unit
(* Initialize the generator, using the argument as a seed.
(** Initialize the generator, using the argument as a seed.
The same seed will always yield the same sequence of numbers. *)
val full_init : int array -> unit
(* Same as [init] but takes more data as seed. *)
val self_init : unit -> unit
(* Initialize the generator with a more-or-less random seed chosen
in a system-dependent way. *)
val init : int -> unit
(** Same as {!Random.init} but takes more data as seed. *)
val full_init : int array -> unit
(** Initialize the generator with a more-or-less random seed chosen
in a system-dependent way. *)
val self_init : unit -> unit
(** Return 30 random bits in a nonnegative integer. *)
val bits : unit -> int
(* Return 30 random bits in a nonnegative integer. *)
val int : int -> int
(* [Random.int bound] returns a random integer between 0 (inclusive)
(** [Random.int bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] must be more than 0 and less
than $2^{30}$. *)
val float : float -> float
(* [Random.float bound] returns a random floating-point number
between 0 (inclusive) and [bound] (exclusive). If [bound] is
negative, the result is negative. If [bound] is 0, the result
is 0. *)
val int : int -> int
(** [Random.float bound] returns a random floating-point number
between 0 (inclusive) and [bound] (exclusive). If [bound] is
negative, the result is negative. If [bound] is 0, the result
is 0. *)
val float : float -> float
(** Values of this type are used to store the current state of the
generator. *)
type state;;
(* Values of this type are used to store the current state of the
generator. *)
(** Returns the current state of the generator. This is useful for
checkpointing computations that use the PRNG. *)
val get_state : unit -> state;;
(* Returns the current state of the generator. This is useful for
checkpointing computations that use the PRNG. *)
(** Resets the state of the generator to some previous state returned by
{!Random.get_state}. *)
val set_state : state -> unit;;
(* Resets the state of the generator to some previous state returned by
[get_state]. *)