Permalink
Browse files

Merge pull request #184 from toton/doc-exceptions

Documentation of raised exceptions and tool to check for these in future
  • Loading branch information...
2 parents c674c2a + 477cdc5 commit bb65d57f327091f9ef25a345d25d05ca2e4929ce @thelema thelema committed Dec 9, 2011
Showing with 820 additions and 734 deletions.
  1. +79 −0 check_raise
  2. +2 −2 src/batArg.mli
  3. +2 −2 src/batBase64.mli
  4. +5 −5 src/batBig_int.mli
  5. +3 −3 src/batBitSet.mli
  6. +3 −3 src/batBool.mli
  7. +5 −5 src/batBuffer.mli
  8. +2 −2 src/batCache.mli
  9. +5 −5 src/batChar.mli
  10. +3 −3 src/batCharParser.mli
  11. +24 −24 src/batComplex.mli
  12. +6 −6 src/batConcurrent.mli
  13. +1 −2 src/batDeque.ml
  14. +2 −2 src/batDigest.mli
  15. +11 −11 src/batDllist.mli
  16. +2 −2 src/batDynArray.mli
  17. +1 −1 src/batEnum.mli
  18. +12 −11 src/batFile.mli
  19. +53 −53 src/batFloat.mli
  20. +1 −1 src/batFormat.mli
  21. +2 −2 src/batGc.mli
  22. +3 −3 src/batGenlex.mli
  23. +6 −6 src/batGlobal.mli
  24. +2 −1 src/batHashcons.mli
  25. +33 −33 src/batHashtbl.ml
  26. +32 −32 src/batHashtbl.mli
  27. +2 −2 src/batHeap.mli
  28. +2 −1 src/batHistogram.mli
  29. +3 −3 src/batIMap.mli
  30. +42 −42 src/batIO.mli
  31. +5 −3 src/batISet.mli
  32. +45 −45 src/batInnerIO.mli
  33. +12 −12 src/batInt.mli
  34. +37 −37 src/batInt32.mli
  35. +7 −7 src/batInt64.mli
  36. +66 −66 src/batLazyList.mli
  37. +3 −3 src/batLexing.mli
  38. +37 −37 src/batList.mli
  39. +5 −5 src/batLog.mli
  40. +27 −26 src/batMap.mli
  41. +4 −4 src/batMarshal.mli
  42. +4 −4 src/batMultiPMap.mli
  43. +1 −1 src/batMutex.mli
  44. +9 −9 src/batNativeint.mli
  45. +19 −17 src/batNum.mli
  46. +6 −6 src/batNumber.mli
  47. +17 −17 src/batOo.mli
  48. +1 −1 src/batOptParse.mli
  49. +8 −8 src/batOption.mli
  50. +4 −4 src/batParserCo.mli
  51. +1 −1 src/batPathGen.ml
  52. +1 −1 src/batPathGen.mli
  53. +1 −1 src/batPervasives.mli
  54. +11 −11 src/batPrint.mli
  55. +3 −3 src/batPrintexc.mli
  56. +21 −21 src/batPrintf.mli
  57. +6 −6 src/batQueue.mli
  58. +1 −1 src/batRMutex.mli
  59. +5 −5 src/batRandom.mli
  60. +6 −6 src/batRef.mli
  61. +1 −1 src/batResult.mli
  62. +5 −5 src/batReturn.mli
  63. +2 −2 src/batScanf.mli
  64. +2 −2 src/batSeq.mli
  65. +2 −2 src/batStack.ml
  66. +6 −6 src/batStack.mli
  67. +2 −2 src/batStr.mli
  68. +5 −5 src/batStream.mli
  69. +2 −2 src/batString.mli
  70. +14 −14 src/batSubstring.mli
  71. +6 −6 src/batTuple.mli
  72. +3 −3 src/batUnit.ml
  73. +5 −5 src/batUnit.mli
  74. +22 −22 src/batUnix.mli
  75. +4 −4 src/batUref.ml
  76. +14 −14 src/batVect.mli
  77. +1 −1 src/batteriesConfig.mlp
  78. +2 −2 src/batteriesHelp.mli
View
79 check_raise
@@ -0,0 +1,79 @@
+#!/bin/bash
+# Simple sanity checking of documentation of exceptions.
+# Usage: go to src/ and run ../check_raise
+
+header() {
+ info=$1
+ shift
+ result=$(mktemp)
+ $* >$result
+ cw=$(wc -w $result | cut -f1 -d\ )
+ if [ "$cw" -ne "0" ]
+ then
+ echo $info
+ cat $result
+ echo
+ fi
+}
+
+setminus() {
+ diff --new-line-format= --unchanged-line-format= $1 $2
+}
+
+# Capitalized Raise should be rare
+header "Interesting places:" \
+ grep -n Raise *
+
+#header "Needs source style:" \
+# grep -n "Invalid_argument[[:space:]]\"" *.mli
+
+# Modules known to have documentation of exceptions OK
+already_ok=$(mktemp)
+echo "
+batteriesHelp
+batStack
+batSplay
+batReturn
+batRef
+batRandom
+batQueue
+batDeque
+batConcurrent
+batCharParser
+" | sort >$already_ok
+
+use_raise=$(mktemp)
+doc_raise=$(mktemp)
+poor_doc_raise=$(mktemp)
+to_be_verified=$(mktemp)
+
+# Crude check for presence of exceptions in implementations and interfaces
+grep -n "\(raise\|invalid_arg\|failwith\)" *.ml | cut -f1 -d. | uniq | sort >$use_raise
+grep -n @raise *.mli | cut -f1 -d. | uniq | sort >$doc_raise
+grep -ni raise *.mli | cut -f1 -d. | uniq | sort >$poor_doc_raise
+
+setminus $use_raise $already_ok >$to_be_verified
+
+suspicious=$(mktemp)
+setminus $to_be_verified $doc_raise >$suspicious
+
+need_doc=$(mktemp)
+setminus $suspicious $poor_doc_raise >$need_doc
+
+header "Documentation of the following modules mentions exceptions and awaits formal @raise clauses:" \
+ setminus $suspicious $need_doc
+
+header "The following modules need raised exceptions to be documented (quite likely):" \
+ cat $need_doc
+
+# Look for mistakes
+
+header "@raises instead of @raise:" \
+ grep -n @raises *
+
+header Typos: \
+ grep -n "Invalid_arg[[:space:]]" `find . -not -name batDynArray\*`
+
+header Typos: \
+ grep -n Invald_argument *
+
View
4 src/batArg.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtArg - Additional operations on arguments
* Copyright (C) 1996 Damien Doligez
* 2009 David Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
View
4 src/batBase64.mli
@@ -1,7 +1,7 @@
(*
* Base64 - Base64 codec
* Copyright (C) 2003 Nicolas Cannasse
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -22,7 +22,7 @@
8-bit characters are encoded into 6-bit ones using ASCII lookup tables.
Default tables maps 0..63 values on characters A-Z, a-z, 0-9, '+' and '/'
- (in that order).
+ (in that order).
@documents Base64
View
10 src/batBig_int.mli
@@ -21,13 +21,13 @@
(** Operations on arbitrary-precision integers.
-
+
Big integers (type {!big_int} or equivalently {!Big_int.t}) are
signed integers of arbitrary size. This module lets you compute
with huge numbers, whose size is limited only by the amount of
memory given to OCaml. The downside is speed, as big integers
are much slower than any other type of integer known to OCaml.
-
+
This module extends Stdlib's
{{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Big_int.html}Big_int}
module, go there for documentation on the rest of the functions
@@ -37,10 +37,10 @@
@author Gabriel Scherer
@author David Teller
*)
-
+
open Nat
open Big_int
-
+
type t = big_int
val zero : big_int
@@ -167,7 +167,7 @@ val float_of_big_int : big_int -> float
module Infix : BatNumber.Infix with type bat__infix_t = t
module Compare : BatNumber.Compare with type bat__compare_t = t
-
+
(**/**)
(** {6 For internal use} *)
View
6 src/batBitSet.mli
@@ -20,11 +20,11 @@
*)
(** Efficient bit sets.
-
+
A bitset is an array of boolean values that can be accessed with indexes
like an array but provides a better memory usage (divided by 8) for a
- very small speed trade-off.
-
+ very small speed trade-off.
+
@author Nicolas Cannasse
@author David Teller (Boilerplate code)
*)
View
6 src/batBool.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtBool - Extended booleans
* Copyright (C) 2007 Bluestorm <bluestorm dot dylc on-the-server gmail dot com>
* 2008 David Teller
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -20,7 +20,7 @@
*)
(**Operations on booleans
-
+
@author Gabriel Scherer
@author David Teller
*)
View
10 src/batBuffer.mli
@@ -1,9 +1,9 @@
-(*
+(*
* ExtBuffer - Additional buffer operations
* Copyright (C) 1999 Pierre Weis, Xavier Leroy
* 2009 David Teller, LIFO, Universite d'Orleans
* 2009 Dawid Toton
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -28,7 +28,7 @@
in quasi-linear time (instead of quadratic time when strings are
concatenated pairwise).
-
+
This module extends Stdlib's
{{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Buffer.html}Buffer}
module, go there for documentation on the rest of the functions
@@ -43,7 +43,7 @@ open Buffer
val enum : t -> char BatEnum.t
- (** Returns an enumeration of the characters of a buffer.
+ (** Returns an enumeration of the characters of a buffer.
Contents of the enumeration is unspecified if the buffer is modified after
the enumeration is returned.*)
@@ -56,7 +56,7 @@ val blit : t -> int -> string -> int -> int -> unit
(** [Buffer.blit b srcoff dst dstoff len] copies [len] characters from
the current contents of the buffer [b] starting at offset [off],
starting at character number [srcoff], to string [dst], starting at
- character number [dstoff].
+ character number [dstoff].
@raise Invalid_argument if [srcoff] and [len] do not designate a
valid substring of the buffer, or if [dstoff] and [len] do not
View
4 src/batCache.mli
@@ -20,8 +20,8 @@
type ('a,'b) manual_cache = {
- get : 'a -> 'b;
- del : 'a -> unit;
+ get : 'a -> 'b;
+ del : 'a -> unit;
enum: unit -> ('a * 'b) BatEnum.t
}
View
10 src/batChar.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtChar - Additional character operations
* Copyright (C) 1996 Xavier Leroy
* 2008 David Teller
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -19,13 +19,13 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
-(** Operations on characters.
+(** Operations on characters.
Characters range upon Latin-1 encoding, i.e. languages used in
Western Europe and North America. For international characters,
another, richer, module is provided: {!UChar}.
-
+
This module extends Stdlib's
{{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Char.html}Char}
module, go there for documentation on the rest of the functions
@@ -37,7 +37,7 @@
val is_whitespace : char -> bool
(** Determine if a character is a whitespace.
- Whitespace characters are defined as
+ Whitespace characters are defined as
[' '], ['\010'], ['\013'], ['\009'], ['\026']
and ['\012']. *)
View
6 src/batCharParser.mli
@@ -1,4 +1,4 @@
-(*
+(*
* CharParser - Parsing character strings
* Copyright (C) 2008 David Teller
*
@@ -18,7 +18,7 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
-(** Parsing character strings.
+(** Parsing character strings.
This module defines common functions for parsing character strings,
encoded in Latin-1. These functions are meant to be used in conjunction
@@ -40,7 +40,7 @@ type position =
}
val advance : char -> position -> position
-(**Advance by one char.
+(**Advance by one char.
[advance c p] returns a new position advanced by one char. If [c] is '\r' or '\n',
the result is [{offset = 0; line = p.line + 1}]. Other wise, the result is
View
48 src/batComplex.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtComplex - Extended Complex
* Copyright (C) 2007 Bluestorm <bluestorm dot dylc on-the-server gmail dot com>
* 2008 David Teller
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -22,80 +22,80 @@
(** Additional and modified functions for complex numbers.*)
(** Complex numbers.
-
+
This module provides arithmetic operations on complex numbers.
Complex numbers are represented by their real and imaginary parts
(cartesian representation). Each part is represented by a
- double-precision floating-point number (type {!float}).
-
+ double-precision floating-point number (type {!float}).
+
@author Xavier Leroy (base module)
@author Gabriel Scherer
@author David Teller
*)
type t = Complex.t
-
+
val zero: t
(** The complex number [0]. *)
-
+
val one: t
(** The complex number [1]. *)
-
+
val i: t
(** The complex number [i]. *)
-
+
val neg: t -> t
(** Unary negation. *)
-
+
val conj: t -> t
(** Conjugate: given the complex [x + i.y], returns [x - i.y]. *)
-
+
val add: t -> t -> t
(** Addition *)
-
+
val sub: t -> t -> t
(** Subtraction *)
-
+
val mul: t -> t -> t
(** Multiplication *)
-
+
val inv: t -> t
(** Multiplicative inverse ([1/z]). *)
-
+
val div: t -> t -> t
(** Division *)
-
+
val sqrt: t -> t
(** Square root. The result [x + i.y] is such that [x > 0] or
[x = 0] and [y >= 0].
This function has a discontinuity along the negative real axis. *)
-
+
val norm2: t -> float
(** Norm squared: given [x + i.y], returns [x^2 + y^2]. *)
-
+
val norm: t -> float
(** Norm: given [x + i.y], returns [sqrt(x^2 + y^2)]. *)
-
+
val arg: t -> float
(** Argument. The argument of a complex number is the angle
in the complex plane between the positive real axis and a line
passing through zero and the number. This angle ranges from
[-pi] to [pi]. This function has a discontinuity along the
negative real axis. *)
-
+
val polar: float -> float -> t
(** [polar norm arg] returns the complex having norm [norm]
and argument [arg]. *)
-
+
val exp: t -> t
(** Exponentiation. [exp z] returns [e] to the [z] power. *)
-
+
val log: t -> t
(** Natural logarithm (in base [e]). *)
-
+
val pow: t -> t -> t
(** Power function. [pow z1 z2] returns [z1] to the [z2] power. *)
-
+
val operations : t BatNumber.numeric
val inv : t -> t
View
12 src/batConcurrent.mli
@@ -1,7 +1,7 @@
-(*
+(*
* Concurrent - Generic interface for concurrent operations
* Copyright (C) 2008 David Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -40,7 +40,7 @@ val create: enter:(unit -> unit) -> leave:(unit -> unit) -> lock
@param enter Enter critical section.
@param leave Leave critical section.
.*)
-
+
val nolock : lock
(** A lock which does nothing.*)
@@ -50,7 +50,7 @@ val synchronize: (unit -> lock) -> ('a -> 'b) -> 'a -> 'b
[f] but whose executions are protected by one lock obtained from
[locker]. The same lock will be reused for all subsequent uses of
[f'].
-
+
For instance,
[synchronize Mutex.make f] is a new function whose executions
will by synchronized by a new lock. Conversely,
@@ -76,7 +76,7 @@ val compose : lock -> lock -> lock
module type BaseLock =
sig
type t(**The type of a lock.*)
-
+
val create:unit -> t
val lock : t -> unit
val unlock:t -> unit
@@ -87,7 +87,7 @@ end
module type Lock =
sig
type t(**The type of a lock.*)
-
+
val create: unit -> t
val lock : t -> unit
val unlock: t -> unit
View
3 src/batDeque.ml
@@ -146,8 +146,7 @@ let rec at ?(backwards=false) q n =
match front q with
| Some (x, q) ->
if n = 0 then Some x else git q (n - 1)
- | None ->
- failwith "Deque.at: internal error"
+ | None -> assert false
in
git q n
View
4 src/batDigest.mli
@@ -2,7 +2,7 @@
* ExtDigest - Additional functions for MD5 message digests
* Copyright (C) 1996 Xavier Leroy, INRIA Rocquencourt
* Copyright (C) 2009 David Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -43,7 +43,7 @@ val channel : input -> int -> Digest.t
[End_of_file] if end-of-file is reached before [len] characters
are read. If [len] is negative, [Digest.channel ic len] reads
all characters from [ic] until end-of-file is reached and return
- their digest.
+ their digest.
{b Note} This version of [channel] is currently very inefficient
if [len] < 0 and requires copying the whole input to a temporary
View
22 src/batDllist.mli
@@ -33,7 +33,7 @@
*)
-type 'a node_t (* abstract *)
+type 'a node_t (* abstract *)
type 'a t = 'a node_t (*For uniformity*)
(**
The type of a non-empty doubly-linked list.
@@ -104,7 +104,7 @@ val rev_drop : 'a node_t -> 'a node_t
separate the nodes between [n1] and [n2] from the rest of the list. In this
case, those nodes become a discrete list by themselves. This is an O(1)
operation.
-*)
+*)
val splice : 'a node_t -> 'a node_t -> unit
(** Given a node, get the data associated with that node. This is an
@@ -117,17 +117,17 @@ val get : 'a node_t -> 'a
*)
val set : 'a node_t -> 'a -> unit
-(** Given a node, get the next element in the list after the node.
+(** Given a node, get the next element in the list after the node.
- The list is circular, so the last node of the list returns the first
+ The list is circular, so the last node of the list returns the first
node of the list as it's next node.
-
+
This is an O(1) operation.
*)
val next : 'a node_t -> 'a node_t
(** Given a node, get the previous element in the list before the node.
-
+
The list is circular, so the first node of the list returns the
last element of the list as it's previous node.
@@ -146,7 +146,7 @@ val skip : 'a node_t -> int -> 'a node_t
*)
val iter : ('a -> unit) -> 'a node_t -> unit
-(** Accumulate a value over the entire list.
+(** Accumulate a value over the entire list.
This works like List.fold_left. This is an O(N) operation.
*)
val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b node_t -> 'a
@@ -160,7 +160,7 @@ val fold_right : ('a -> 'b -> 'b) -> 'a node_t -> 'b -> 'b
val find : ('a -> bool) -> 'a node_t -> 'a node_t
(** [find p l] returns the first element, [l] or after, for which [p]
- returns true.
+ returns true.
@raise Not_found if no such element exists
@added 1.4.0
@@ -169,7 +169,7 @@ val find : ('a -> bool) -> 'a node_t -> 'a node_t
val for_all : ('a -> bool) -> 'a node_t -> bool
(** Test whether a given predicate returns true for all members of the
given list. O(N) *)
-
+
val exists : ('a -> bool) -> 'a node_t -> bool
(** Test whether there exists an element of the given list for which
the predicate returns true. O(N) *)
@@ -185,15 +185,15 @@ val filter : ('a -> bool) -> 'a node_t -> 'a node_t
(** [filter p l] returns a new list, with entirely new nodes, whose
values are all the elements of the list [l] that satisfy the
predicate [p]. The order of the elements in the input list is
- preserved.
+ preserved.
@raise Empty if the resulting list is empty.*)
val filter_map : ('a -> 'b option) -> 'a node_t -> 'b node_t
(** [filter_map f l] calls [(f a0) (f a1) ... (f an)] where [a0,a1...an]
are the elements of [l]. It returns a new list of elements [bi]
such as [f ai = Some bi] (when [f] returns [None], the
- corresponding element of [l] is discarded).
+ corresponding element of [l] is discarded).
@raise Empty if the resulting list is empty.*)
View
4 src/batDynArray.mli
@@ -189,14 +189,14 @@ val keep : ('a -> bool) -> 'a t -> unit
val filter : ('a -> bool) -> 'a t -> 'a t
(** [filter p a] returns all the elements of the array [a]
that satisfy the predicate [p]. The order of the elements
- in the input array is preserved.
+ in the input array is preserved.
{b Note} This function replaces another function called [filter],
available in previous versions of the library. As the old function
was incompatible with comprehension of dynamic arrays, its name
was changed to {!keep}.
*)
-
+
val filter_map : ('a -> 'b option) -> 'a t -> 'b t
(** [filter_map f e] returns an array consisting in all elements
[x] such that [f y] returns [Some x] , where [y] is an element
View
2 src/batEnum.mli
@@ -565,7 +565,7 @@ val arg_max : ('a -> 'b) -> 'a t -> 'a
Example: [List.enum ["cat"; "canary"; "dog"; "dodo"; "ant"; "cow"] |> arg_max String.length = "canary"]
@added v1.4.0
- @raises [Invalid_argument] if the input enum is empty
+ @raise Invalid_argument if the input enum is empty
*)
(** {6 Trampolining} *)
View
23 src/batFile.mli
@@ -1,4 +1,4 @@
-(*
+(*
* File - File manipulation
* Copyright (C) 2008 David Teller
*
@@ -20,7 +20,7 @@
(**
File manipulation.
-
+
@author David Teller
*)
@@ -36,7 +36,7 @@ val lines_of : string -> string BatEnum.t
val write_lines: string -> string BatEnum.t -> unit
(** [write_lines name lines] writes strings given by [lines] to file [name] with newline character appended to each line. *)
-
+
val size_of: string -> int
(** [size_of name] returns the size of file [name] in bytes.*)
@@ -46,7 +46,7 @@ val size_of_big: string -> Int64.t
This function is provided as the size of a file larger than 1 Gb cannot
be represented with an [int] on a 32-bit machine.*)
-(** {6 File permissions}
+(** {6 File permissions}
File permissions are used when creating a file to allow controlling which users
may read, write or open that file. To use a permission, create a value of type
@@ -84,15 +84,15 @@ val group_exec: permission
containing the user. Ignored under Windows.*)
val other_read: permission
-(**Give the permission to read the file to the rest
+(**Give the permission to read the file to the rest
of the world. Ignored under Windows.*)
val other_write: permission
-(**Give the permission to modify the file to the rest
+(**Give the permission to modify the file to the rest
of the world. Ignored under Windows.*)
val other_exec: permission
-(**Give the permission to execute the file to the rest
+(**Give the permission to execute the file to the rest
of the world. Ignored under Windows.*)
val perm : permission list -> permission
@@ -101,7 +101,8 @@ val perm : permission list -> permission
val unix_perm : int -> permission
(**Create a permission from a Unix-style octal integer.
See your favorite Unix documentation on [chmod]
- for more details.*)
+ for more details.
+ @raise Invalid_argument if given number outside the [[0, 0o777]] range *)
val set_permissions: string -> permission -> unit
(** Set the permissions on a file.*)
@@ -131,7 +132,7 @@ val open_in : ?mode:(open_in_flag list) -> ?perm:permission -> string -> input
val with_file_in : ?mode:(open_in_flag list) -> ?perm:permission -> string -> (input -> 'a) -> 'a
(** [with_file_in file_name f] opens the file named [file_name] for reading,
- invokes [f] to process the contents of that file then, once [f] has returned
+ invokes [f] to process the contents of that file then, once [f] has returned
or triggered an exception, closes the file before proceeding. *)
(** {6 Opening a file for writing} *)
@@ -161,7 +162,7 @@ val open_out : ?mode:(open_out_flag list) -> ?perm:permission -> string -> unit
val with_file_out: ?mode:(open_out_flag list) -> ?perm:permission -> string -> (unit output -> 'a) -> 'a
(** [with_file_out file_name f] opens the file named [file_name] for writing,
- invokes [f] to write onto that file then, once [f] has returned or triggered
+ invokes [f] to write onto that file then, once [f] has returned or triggered
an exception, closes the file before proceeding. *)
(** {6 Opening a temporary file for writing} *)
@@ -170,7 +171,7 @@ type open_temporary_out_flag =
[ open_out_flag
| `delete_on_exit (**Should the file be deleted when program ends?*) ]
-val open_temporary_out: ?mode:(open_temporary_out_flag list) -> ?prefix:string -> ?suffix:string -> unit ->
+val open_temporary_out: ?mode:(open_temporary_out_flag list) -> ?prefix:string -> ?suffix:string -> unit ->
(unit output * string)
(** [open_temporary_out ()] opens a new temporary file for writing.
View
106 src/batFloat.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtFloat - Extended floats
* Copyright (C) 2007 Bluestorm <bluestorm dot dylc on-the-server gmail dot com>
* 2009 David Rajchenbach-Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -36,11 +36,11 @@
For more precision, see
{{:http://en.wikipedia.org/wiki/IEEE_754}The Wikipedia entry on
standard IEEE 754}.
-
+
@author Gabriel Scherer
@author David Teller
@author Edgar Friendly
-
+
@documents Float
*)
@@ -111,46 +111,46 @@
external exp : float -> float = "caml_exp_float" "exp" "float"
(** Exponential. *)
-
+
external log : float -> float = "caml_log_float" "log" "float"
(** Natural logarithm. *)
-
+
external log10 : float -> float = "caml_log10_float" "log10" "float"
(** Base 10 logarithm. *)
-
+
external cos : float -> float = "caml_cos_float" "cos" "float"
(** See {!atan2}. *)
-
+
external sin : float -> float = "caml_sin_float" "sin" "float"
(** See {!atan2}. *)
-
+
external tan : float -> float = "caml_tan_float" "tan" "float"
(** See {!atan2}. *)
-
+
external acos : float -> float = "caml_acos_float" "acos" "float"
(** See {!atan2}. *)
-
+
external asin : float -> float = "caml_asin_float" "asin" "float"
(** See {!atan2}. *)
-
+
external atan : float -> float = "caml_atan_float" "atan" "float"
(** See {!atan2}. *)
-
+
external atan2 : float -> float -> float = "caml_atan2_float" "atan2" "float"
(** The usual trigonometric functions. *)
-
+
external cosh : float -> float = "caml_cosh_float" "cosh" "float"
(** See {!tanh}. *)
external sinh : float -> float = "caml_sinh_float" "sinh" "float"
(** See {!tanh}. *)
-
+
external tanh : float -> float = "caml_tanh_float" "tanh" "float"
(** The usual hyperbolic trigonometric functions. *)
-
+
external ceil : float -> float = "caml_ceil_float" "ceil" "float"
(** See {!floor}. *)
-
+
external floor : float -> float = "caml_floor_float" "floor" "float"
(** Round the given float to an integer value.
[floor f] returns the greatest integer value less than or
@@ -170,31 +170,31 @@
val infinity : float
(** Positive infinity. *)
-
+
val neg_infinity : float
(** Negative infinity. *)
-
+
val nan : float
(** A special floating-point value denoting the result of an
undefined operation such as [0.0 /. 0.0]. Stands for
``not a number''. Any floating-point operation with [nan] as
argument returns [nan] as result. As for floating-point comparisons,
[=], [<], [<=], [>] and [>=] return [false] and [<>] returns [true]
if one or both of their arguments is [nan]. *)
-
+
val is_nan : float -> bool
(** [is_nan f] returns [true] if [f] is [nan], [false] otherwise.*)
val is_special : float -> bool
(** [is_special f] returns [true] if [f] is [nan] or [+/- infinity],
[false] otherwise. *)
-
+
val epsilon : float
(** The smallest positive float [x] such that [1.0 +. x <> 1.0]. *)
-
+
val pi : float
(** The constant pi (3.14159...) *)
-
+
(** {6 Operations on the internal representation of floating-point numbers}*)
external frexp : float -> float * int = "caml_frexp_float"
@@ -203,24 +203,24 @@
significant [x] and the exponent [n] of [f] are equal to
zero. When [f] is non-zero, they are defined by
[f = x *. 2 ** n] and [0.5 <= x < 1.0]. *)
-
+
external ldexp : float -> int -> float = "caml_ldexp_float"
(** [ldexp x n] returns [x *. 2 ** n]. *)
-
+
external modf : float -> float * float = "caml_modf_float"
(** [modf f] returns the pair of the fractional and integral
part of [f]. *)
(** Classes of floating point numbers*)
- type fpkind = Pervasives.fpclass =
+ type fpkind = Pervasives.fpclass =
FP_normal (** Normal number, none of the below *)
| FP_subnormal (** Number very close to 0.0, has reduced precision *)
| FP_zero (** Number is 0.0 or -0.0 *)
| FP_infinite (** Number is positive or negative infinity *)
| FP_nan (** Not a number: result of an undefined operation *)
(** The five classes of floating-point numbers, as determined by
the {!classify} function. *)
-
+
external classify : float -> fpkind = "caml_classify_float"
(** Return the class of the given floating-point number:
normal, subnormal, zero, infinite, or not a number. *)
@@ -249,7 +249,7 @@
(**Operations on floating-point numbers, with exceptions raised in
- case of error.
+ case of error.
The operations implemented in this module are the same as the operations
implemented in module {!Float}, with the exception that no operation returns
@@ -270,9 +270,9 @@
For more precision, see
{{:http://en.wikipedia.org/wiki/IEEE_754}The Wikipedia entry on
standard IEEE 754}.
-
+
@author David Teller
-
+
@documents Safe_float
*)
module Safe_float :
@@ -344,46 +344,46 @@ module Safe_float :
val exp : float -> float
(** Exponential. *)
-
+
val log : float -> float
(** Natural logarithm. *)
-
+
val log10 : float -> float
(** Base 10 logarithm. *)
-
+
val cos : float -> float
(** See {!atan2}. *)
-
+
val sin : float -> float
(** See {!atan2}. *)
-
+
val tan : float -> float
(** See {!atan2}. *)
-
+
val acos : float -> float
(** See {!atan2}. *)
-
+
val asin : float -> float
(** See {!atan2}. *)
-
+
val atan : float -> float
(** See {!atan2}. *)
-
+
val atan2 : float -> float -> float
(** The usual trigonometric functions. *)
-
+
val cosh : float -> float
(** See {!tanh}. *)
val sinh : float -> float
(** See {!tanh}. *)
-
+
val tanh : float -> float
(** The usual hyperbolic trigonometric functions. *)
-
+
val ceil : float -> float
(** See {!floor}. *)
-
+
val floor : float -> float
(** Round the given float to an integer value.
[floor f] returns the greatest integer value less than or
@@ -393,27 +393,27 @@ module Safe_float :
val infinity : float
(** Positive infinity. *)
-
+
val neg_infinity : float
(** Negative infinity. *)
-
+
val nan : float
(** A special floating-point value denoting the result of an
undefined operation such as [0.0 /. 0.0]. Stands for
``not a number''. Any floating-point operation with [nan] as
argument returns [nan] as result. As for floating-point comparisons,
[=], [<], [<=], [>] and [>=] return [false] and [<>] returns [true]
if one or both of their arguments is [nan]. *)
-
+
val is_nan : float -> bool
(** [is_nan f] returns [true] if [f] is [nan], [false] otherwise.*)
-
+
val epsilon : float
(** The smallest positive float [x] such that [1.0 +. x <> 1.0]. *)
-
+
val pi : float
(** The constant pi (3.14159...) *)
-
+
(** {6 Operations on the internal representation of floating-point numbers}*)
val frexp : float -> float * int
@@ -422,24 +422,24 @@ module Safe_float :
significant [x] and the exponent [n] of [f] are equal to
zero. When [f] is non-zero, they are defined by
[f = x *. 2 ** n] and [0.5 <= x < 1.0]. *)
-
+
val ldexp : float -> int -> float
(** [ldexp x n] returns [x *. 2 ** n]. *)
-
+
val modf : float -> float * float
(** [modf f] returns the pair of the fractional and integral
part of [f]. *)
(** Classes of floating point numbers*)
- type fpkind = Pervasives.fpclass =
+ type fpkind = Pervasives.fpclass =
FP_normal (** Normal number, none of the below *)
| FP_subnormal (** Number very close to 0.0, has reduced precision *)
| FP_zero (** Number is 0.0 or -0.0 *)
| FP_infinite (** Number is positive or negative infinity *)
| FP_nan (** Not a number: result of an undefined operation *)
(** The five classes of floating-point numbers, as determined by
the {!classify} function. *)
-
+
external classify : float -> fpkind = "caml_classify_float"
(** Return the class of the given floating-point number:
normal, subnormal, zero, infinite, or not a number. *)
View
2 src/batFormat.mli
@@ -1,4 +1,4 @@
-(*
+(*
* ExtFormat - Extended Format module
* Copyright (C) 1996 Pierre Weis
* 2009 David Teller, LIFO, Universite d'Orleans
View
4 src/batGc.mli
@@ -1,4 +1,4 @@
-(*
+(*
* ExtGC - Extended GC operations
* Copyright (C) 1996 Damien Doligez
* 2008 David Teller, LIFO, Universite d'Orleans
@@ -20,7 +20,7 @@
*)
-(** Memory management control and statistics; finalised values.
+(** Memory management control and statistics; finalised values.
This module extends Stdlib's
{{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html}Gc}
View
6 src/batGenlex.mli
@@ -2,7 +2,7 @@
* Genlex - Generic lexer
* Copyright (C) 2002 Jacques Garrigue
* 2008 David Teller (Contributor)
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -57,7 +57,7 @@ val to_lazy_list_filter: t -> char BatLazyList.t -> token BatLazyList.t
open BatCharParser
module Languages :
sig
-module type Definition =
+module type Definition =
sig
val comment_delimiters : (string * string) option
val line_comment_start : string option
@@ -150,6 +150,6 @@ sig
to ignore following comments.*)
end
-
+
end
View
12 src/batGlobal.mli
@@ -2,7 +2,7 @@
* Global - Mutable global variable
* Copyright (C) 2003 Nicolas Cannasse
* Copyright (C) 2008 David Teller
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -20,8 +20,8 @@
*)
(** Mutable global variable.
-
- Often in OCaml you want to have a global variable, which is mutable
+
+ Often in OCaml you want to have a global variable, which is mutable
and uninitialized when declared. You can use a ['a option ref] but
this is not very convenient. The Global module provides functions
to easily create and manipulate such variables.
@@ -51,13 +51,13 @@ val get : 'a t -> 'a
(** Get the global value contents - raise Global_not_initialized if not
defined. *)
-val undef : 'a t -> unit
+val undef : 'a t -> unit
(** Reset the global value contents to undefined. *)
-val isdef : 'a t -> bool
+val isdef : 'a t -> bool
(** Return [true] if the global value has been set. *)
-val opt : 'a t -> 'a option
+val opt : 'a t -> 'a option
(** Return [None] if the global is undefined, else [Some v] where v is the
current global value contents. *)
View
3 src/batHashcons.mli
@@ -51,7 +51,8 @@ module type Table = sig
val hashcons : t -> key -> key hobj
(** [hashcons tab k] returns either [k], adding it to the table
[tab] as a side effect, or if [k] is already in the table then
- it returns the hashed object corresponding to that entry. *)
+ it returns the hashed object corresponding to that entry.
+ @raise Failure if number of objects with the same hash reaches system limit of array size *)
val iter : (key hobj -> unit) -> t -> unit
(** [iter f tab] applied [f] to every live hashed object in the
View
66 src/batHashtbl.ml
@@ -1,10 +1,10 @@
-(*
+(*
* ExtHashtbl, extra functions over hashtables.
* Copyright (C) 1996 Xavier Leroy
* 2003 Nicolas Cannasse
* 2005 Damien Doligez
* 2009 David Rajchenbach-Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -20,7 +20,7 @@
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
-
+
(** {6 Import the contents of {!Hashtbl}}
@@ -45,7 +45,7 @@
type ('a, 'b) h_bucketlist =
| Empty
| Cons of 'a * 'b * ('a, 'b) h_bucketlist
-
+
type ('a, 'b) h_t = {
mutable size: int;
mutable data: ('a, 'b) h_bucketlist array
@@ -71,7 +71,7 @@
done;
tbl.data <- ndata;
end
-
+
let enum h =
let rec make ipos ibuck idata icount =
let pos = ref ipos in
@@ -88,7 +88,7 @@
let rec next() =
force();
match !buck with
- | Empty ->
+ | Empty ->
if !hcount = 0 then raise BatEnum.No_more_elements;
incr pos;
buck := Array.unsafe_get !hdata !pos;
@@ -106,23 +106,23 @@
make !pos !buck !hdata !hcount
in
BatEnum.make ~next ~count ~clone
- in
+ in
make (-1) Empty (Obj.magic()) (-1)
-
+
let keys h =
BatEnum.map (fun (k,_) -> k) (enum h)
-
+
let values h =
BatEnum.map (fun (_,v) -> v) (enum h)
-
+
let map f h =
let rec loop = function
| Empty -> Empty
| Cons (k,v,next) -> Cons (k,f k v,loop next)
in
h_make {
size = (h_conv h).size;
- data = Array.map loop (h_conv h).data;
+ data = Array.map loop (h_conv h).data;
}
let remove_all h key =
@@ -138,7 +138,7 @@
in
let pos = (hash key) mod (Array.length hc.data) in
Array.unsafe_set hc.data pos (loop (Array.unsafe_get hc.data pos))
-
+
let find_default h key defval =
let rec loop = function
| Empty -> defval
@@ -147,7 +147,7 @@
in
let pos = (hash key) mod (Array.length (h_conv h).data) in
loop (Array.unsafe_get (h_conv h).data pos)
-
+
let find_option h key =
let rec loop = function
| Empty -> None
@@ -156,15 +156,15 @@
in
let pos = (hash key) mod (Array.length (h_conv h).data) in
loop (Array.unsafe_get (h_conv h).data pos)
-
+
let of_enum e =
let h = create (if BatEnum.fast_count e then BatEnum.count e else 0) in
BatEnum.iter (fun (k,v) -> add h k v) e;
h
-
+
let length h =
(h_conv h).size
-
+
let is_empty h = length h = 0
let print ?(first="{\n") ?(last="\n}") ?(sep=",\n") print_k print_v out t =
@@ -241,17 +241,17 @@
val values : 'a t -> 'a BatEnum.t
val enum : 'a t -> (key * 'a) BatEnum.t
val of_enum : (key * 'a) BatEnum.t -> 'a t
- val print : ?first:string -> ?last:string -> ?sep:string ->
- ('a BatInnerIO.output -> key -> unit) ->
- ('a BatInnerIO.output -> 'b -> unit) ->
+ val print : ?first:string -> ?last:string -> ?sep:string ->
+ ('a BatInnerIO.output -> key -> unit) ->
+ ('a BatInnerIO.output -> 'b -> unit) ->
'a BatInnerIO.output -> 'b t -> unit
(** Operations on {!Hashtbl} without exceptions.*)
module Exceptionless :
sig
val find : 'a t -> key -> 'a option
end
-
+
(** Infix operators over a {!BatHashtbl} *)
module Infix :
sig
@@ -270,7 +270,7 @@
end
(** Operations on {!Hashtbl} with labels.
-
+
This module overrides a number of functions of {!Hashtbl} by
functions in which some arguments require labels. These labels are
there to improve readability and safety and to let you change the
@@ -292,7 +292,7 @@
end
end
-
+
module Make(H: HashedType): (S with type key = H.t) =
struct
@@ -306,19 +306,19 @@
let create = create
let clear = clear
let copy = copy
-
+
let safehash key = (H.hash key) land max_int
-
+
let add h key info =
let h = h_conv h in
let i = (safehash key) mod (Array.length h.data) in
let bucket = Cons(key, info, h.data.(i)) in
h.data.(i) <- bucket;
h.size <- succ h.size;
if h.size > Array.length h.data lsl 1 then resize safehash h
-
+
let remove h key =
- let h = h_conv h in
+ let h = h_conv h in
let rec remove_bucket = function
Empty ->
Empty
@@ -328,13 +328,13 @@
else Cons(k, i, remove_bucket next) in
let i = (safehash key) mod (Array.length h.data) in
h.data.(i) <- remove_bucket h.data.(i)
-
+
let rec find_rec key = function
Empty ->
raise Not_found
| Cons(k, d, rest) ->
if H.equal key k then d else find_rec key rest
-
+
let find h key =
let h = h_conv h in
match h.data.((safehash key) mod (Array.length h.data)) with
@@ -349,7 +349,7 @@
Empty -> raise Not_found
| Cons(k3, d3, rest3) ->
if H.equal key k3 then d3 else find_rec key rest3
-
+
let find_all h key =
let rec find_in_bucket = function
Empty ->
@@ -359,7 +359,7 @@
then d :: find_in_bucket rest
else find_in_bucket rest in
find_in_bucket h.data.((safehash key) mod (Array.length h.data))
-
+
let replace h key info =
let rec replace_bucket = function
Empty ->
@@ -384,7 +384,7 @@
| Cons(k, d, rest) ->
H.equal k key || mem_in_bucket rest in
mem_in_bucket h.data.((safehash key) mod (Array.length h.data))*)
-
+
let iter = iter
let fold = fold
let length = length
@@ -435,7 +435,7 @@
result
let filter f t = filteri (fun k a -> f a) t
-
+
let filter_map f t =
let result = create 16 in
iter (fun k a -> match f k a with
@@ -471,7 +471,7 @@
module Cap =
struct
type ('a, 'b, 'c) t = ('a, 'b) Hashtbl.t constraint 'c = [< `Read | `Write ]
-
+
let create = create
external of_table : ('a, 'b) Hashtbl.t -> ('a, 'b, _ ) t = "%identity"
external to_table : ('a, 'b, [`Read | `Write]) t -> ('a, 'b) Hashtbl.t = "%identity"
View
64 src/batHashtbl.mli
@@ -1,8 +1,8 @@
-(*
+(*
* ExtHashtbl - extra functions over hashtables.
* Copyright (C) 2003 Nicolas Cannasse
* 2009 David Teller, LIFO, Universite d'Orleans
- *
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -18,12 +18,12 @@
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
-
+
(** Extra functions over hashtables. *)
-(** Operations over hashtables.
-
+(** Operations over hashtables.
+
This module replaces Stdlib's
{{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Hashtbl.html}Hashtbl}
module. All functions and types are provided here.
@@ -140,7 +140,7 @@ val mem : ('a, 'b) t -> 'a -> bool
choice between using the more general functions of {!BatEnum}, with
{!keys}, {!values}, {!enum} and {!of_enum}, or the more optimized
functions of this section.
-
+
If you are new to OCaml or unsure about data structure, using the
functions of {!BatEnum} is a safe bet. Should you wish to improve
performance at the cost of generality, you will always be able to
@@ -219,8 +219,8 @@ external hash_param : int -> int -> 'a -> int = "caml_hash_univ_param" "noalloc"
(** {7 Printing}*)
-val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) ->
- ('a BatInnerIO.output -> 'c -> unit) ->
+val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) ->
+ ('a BatInnerIO.output -> 'c -> unit) ->
'a BatInnerIO.output -> ('b, 'c) t -> unit
(** {6 Override modules}*)
@@ -230,7 +230,7 @@ val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.outp
behaving slightly differently but having the same name. This is by design:
the functions meant to override the corresponding functions of {!Hashtbl}.
*)
-
+
(** Operations on {!Hashtbl} without exceptions.
@documents Hashtbl.Exceptionless
@@ -258,7 +258,7 @@ sig
end
(** Operations on {!Hashtbl} with labels.
-
+
This module overrides a number of functions of {!Hashtbl} by
functions in which some arguments require labels. These labels are
there to improve readability and safety and to let you change the
@@ -333,27 +333,27 @@ module type S =
val values : 'a t -> 'a BatEnum.t
val enum : 'a t -> (key * 'a) BatEnum.t
val of_enum : (key * 'a) BatEnum.t -> 'a t
- val print : ?first:string -> ?last:string -> ?sep:string ->
- ('a BatInnerIO.output -> key -> unit) ->
- ('a BatInnerIO.output -> 'b -> unit) ->
+ val print : ?first:string -> ?last:string -> ?sep:string ->
+ ('a BatInnerIO.output -> key -> unit) ->
+ ('a BatInnerIO.output -> 'b -> unit) ->
'a BatInnerIO.output -> 'b t -> unit
-
+
(** {6 Override modules}*)
-
+
(**
The following modules replace functions defined in {!Hashtbl} with functions
behaving slightly differently but having the same name. This is by design:
the functions meant to override the corresponding functions of {!Hashtbl}.
*)
-
+
(** Operations on {!Hashtbl} without exceptions.
@documents Hashtbl.S.Exceptionless*)
module Exceptionless :
sig
val find : 'a t -> key -> 'a option
end
-
+
(** Infix operators over a {!BatHashtbl} *)
module Infix :
sig
@@ -372,7 +372,7 @@ module type S =
end
(** Operations on {!Hashtbl} with labels.
-
+
This module overrides a number of functions of {!Hashtbl} by
functions in which some arguments require labels. These labels are
there to improve readability and safety and to let you change the
@@ -397,7 +397,7 @@ module type S =
end
(** The output signature of the functor {!Hashtbl.Make}. *)
-
+
module Make (H : HashedType) : S with type key = H.t
(** Functor building an implementation of the hashtable structure.
The functor [Hashtbl.Make] returns a structure containing
@@ -408,7 +408,7 @@ module Make (H : HashedType) : S with type key = H.t
specified in the functor argument [H] instead of generic
equality and hashing. *)
-(** Capabilities for hashtables.
+(** Capabilities for hashtables.
@documents Hashtbl.Cap
*)
@@ -417,35 +417,35 @@ sig
type ('a, 'b, 'c) t constraint 'c = [< `Read | `Write ]
(** The type of a hashtable. *)
-
+
(**{6 Constructors}*)
val create : int -> ('a, 'b, _) t
external of_table : ('a, 'b) Hashtbl.t -> ('a, 'b, _ ) t = "%identity"
(** Adopt a regular hashtable as a capability hashtble, allowing
to decrease capabilities if necessary.
-
+
This operation involves no copying. In other words, in
[let cap = of_table a in ...], any modification in [a]
will also have effect on [cap] and reciprocally.*)
-
+
external to_table : ('a, 'b, [`Read | `Write]) t -> ('a, 'b) Hashtbl.t = "%identity"
(** Return a capability hashtable as a regular hashtable.
-
+
This operation requires both read and write permissions
on the capability table and involves no copying. In other
words, in [let a = of_table cap in ...], any modification
in [a] will also have effect on [cap] and reciprocally.*)
-
+
external read_only : ('a, 'b, [>`Read]) t -> ('a, 'b, [`Read]) t = "%identity"
(** Drop to read-only permissions.
-
+
This operation involves no copying.*)
-
+
external write_only : ('a, 'b, [>`Write]) t -> ('a, 'b, [`Write]) t = "%identity"
(** Drop to write-only permissions.
-
+
This operation involves no copying.*)
(**{6 Base operations}*)
@@ -509,20 +509,20 @@ val of_enum : ('a * 'b) BatEnum.t -> ('a, 'b, _) t
(** {7 Printing}*)
-val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) ->
- ('a BatInnerIO.output -> 'c -> unit) ->
+val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) ->
+ ('a BatInnerIO.output -> 'c -> unit) ->
'a BatInnerIO.output -> ('b, 'c, [>`Read]) t -> unit
(** {6 Override modules}*)
-
+
(** Operations on {!BatHashtbl.Cap} without exceptions.*)
module Exceptionless :
sig
val find : ('a, 'b, [>`Read]) t -> 'a -> 'b option
end
-
+
(** Operations on {!BatHashtbl.Cap} with labels.*)
module Labels :
sig
View
4 src/batHeap.mli
@@ -50,11 +50,11 @@ val merge : 'a t -> 'a t -> 'a t
val find_min : 'a t -> 'a
(** Find the minimal element of the heap. O(1)
- @raises [Invalid_argument "find_min"] if the heap is empty *)
+ @raise Invalid_argument ["find_min"] if the heap is empty *)
val del_min : 'a t -> 'a t
(** Delete the minimal element of the heap. O(log n)
- @raises [Invalid_argument "del_min"] if the heap is empty *)
+ @raise Invalid_argument ["del_min"] if the heap is empty *)
(** {6 Transformation} *)
View
3 src/batHistogram.mli
@@ -79,5 +79,6 @@ val values : t -> float BatEnum.t
(** Given a list of values between 0.0 and 100.0 (excluding
endpoints), return the percentile measurement from added values
- corresponding to each value*)
+ corresponding to each value
+ @raise Invalid_argument if some of the given values is outside the open inteval (0, 100) *)
val percentile : t -> float list -> float list
View
6 src/batIMap.mli
@@ -11,7 +11,7 @@ type key = int
val empty : 'a t
val is_empty : 'a t -> bool
-
+
val add : ?eq:('a -> 'a -> bool) -> int -> 'a -> 'a t -> 'a t
val add_range : ?eq:('a -> 'a -> bool) -> int -> int -> 'a -> 'a t -> 'a t
@@ -39,7 +39,7 @@ val iter_range : (int -> int -> 'a -> unit) -> 'a t -> unit
val map : ?eq:('b -> 'b -> bool) -> ('a -> 'b) -> 'a t -> 'b t
val mapi : ?eq:('b -> 'b -> bool) -> (int -> 'a -> 'b) -> 'a t -> 'b t
-
+
val map_range : ?eq:('b -> 'b -> bool) -> (int -> int -> 'a -> 'b) -> 'a t -> 'b t
val fold : (int -> 'b -> 'a -> 'a) -> 'b t -> 'a -> 'a
@@ -71,7 +71,7 @@ module Infix : sig
(** [map<--(key, value)] returns a map containing the same bindings as
[map], plus a binding of [key] to [value]. If [key] was already bound
in [map], its previous binding disappears. Equivalent to [add key value map]
-
+
{b Important warning}: {!BatIMap.add} takes an optional argument, [eq] that
is missing in this operator [<--]. As a consequence, using [<--] implies the
use of {{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Pervasives.html#VAL(==)}Pervasives.(==)}
View
84 src/batIO.mli
@@ -1,4 +1,4 @@
-(*
+(*
* BatIO - Abstract input/output
* Copyright (C) 2003 Nicolas Cannasse
* 2008 David Teller (contributor)
@@ -22,7 +22,7 @@
*)
(** High-order abstract I/O.
-
+
This module deals with {!type: input}s and {!type:
output}s. Inputs are manners of getting information from the
outside world and into your program (for instance, reading from
@@ -63,7 +63,7 @@
may wish to force all waiting operations to take place {e now}.
For this purpose, you may either function {!flush} or function
I {!flush_out}.
-
+
Once you have finished using your {!type: input} or your {!type:
output}, chances are that you will want to close it. This is not a
strict necessity, as OCaml will eventually close it for you when
@@ -139,7 +139,7 @@ val stdout: unit output
val stderr: unit output
(** Standard error output, as per Unix/Windows conventions.
-
+
Use this output to display warnings and error messages.
Example: [
@@ -298,7 +298,7 @@ val close_all : unit -> unit
*)
(**/**)
-(** {6 Creation of BatIO Inputs/Outputs}
+(** {6 Creation of BatIO Inputs/Outputs}
To open a file for reading/writing, see {!File.open_file_in}
and {!File.open_file_out}*)
@@ -323,13 +323,13 @@ val output_buffer : Buffer.t -> string output
(** Create an output that will append its results at the end of a buffer
in an efficient way. Closing returns the whole contents of the buffer
-- the buffer remains usable.*)
-
+
val input_enum : char BatEnum.t -> input
(** Create an input that will read from an [enum]. *)
val output_enum : unit -> char BatEnum.t output
-(** Create an output that will write into an [enum]. The
+(** Create an output that will write into an [enum]. The
final enum is returned when the output is closed. *)
val combine : ('a output * 'b output) -> ('a * 'b) output
@@ -349,7 +349,7 @@ val tab_out : ?tab:char -> int -> 'a output -> unit output
*)
(*val repeat: int -> 'a output -> unit output
-(** [repeat n out] create an output in which every character or string is repeated
+(** [repeat n out] create an output in which every character or string is repeated
[n] times to [out].*)*)
(** {6 Utilities} *)
@@ -362,7 +362,7 @@ val read_uall : input -> Ulib.Text.t
val pipe : unit -> input * unit output
(** Create a pipe between an input and an ouput. Data written from
- the output can be read from the input.
+ the output can be read from the input.
*)
val copy : ?buffer:int -> input -> _ output -> unit
@@ -376,7 +376,7 @@ val pos_in : input -> input * (unit -> int)
(** Create an input that provide a count function of the number of bytes
read from it. *)
-val progress_in : input -> (unit -> unit) -> input
+val progress_in : input -> (unit -> unit) -> input
(** [progress_in inp f] create an input that calls [f ()]
whenever some content is succesfully read from it.*)
@@ -389,7 +389,7 @@ val progress_out : 'a output -> (unit -> unit) -> unit output
whenever some content is succesfully written to it.*)
external cast_output : 'a output -> unit output = "%identity"
-(** You can safely transform any output to an unit output in a safe way
+(** You can safely transform any output to an unit output in a safe way
by using this function. *)
@@ -460,7 +460,7 @@ val write_i16 : 'a output -> int -> unit
(** Write a signed 16-bit word. *)
val write_i32 : 'a output -> int -> unit
-(** Write a signed 32-bit integer. *)
+(** Write a signed 32-bit integer. *)
val write_real_i32 : 'a output -> int32 -> unit
(** Write an OCaml int32. *)
@@ -485,7 +485,7 @@ val write_text : _ output -> Ulib.Text.t -> unit
val write_line : 'a output -> string -> unit
(** Write a line and append a line end.
-
+
This adds the correct line end for your operating system. That
is, if you are writing to a file and your system imposes that
files should end lines with character LF (or ['\n']), as Unix,
@@ -505,7 +505,7 @@ sig
Generally, to use this module you will wish to either open both
{!BatIO} and {!BigEndian}, so as to import a big-endian version of
{!BatIO}, as per
- [open System.BatIO, BigEndian in ...],
+ [open System.BatIO, BigEndian in ...],
or to redefine locally {!BatIO} to use big-endian encodings
[module BatIO = System.BatIO include BigEndian]
@@ -541,7 +541,7 @@ sig
(** Write a signed 16-bit word. *)
val write_i32 : 'a output -> int -> unit
- (** Write a signed 32-bit integer. *)
+ (** Write a signed 32-bit integer. *)
val write_real_i32 : 'a output -> int32 -> unit
(** Write an OCaml int32. *)
@@ -584,7 +584,7 @@ sig
(** Write an enumeration of signed 16-bit words. *)
val write_i32s : 'a output -> int BatEnum.t -> unit
- (** Write an enumeration of signed 32-bit integers. *)
+ (** Write an enumeration of signed 32-bit integers. *)
val write_real_i32s : 'a output -> int32 BatEnum.t -> unit
(** Write an enumeration of OCaml int32s. *)
@@ -636,9 +636,9 @@ val drop_bits : in_bits -> unit
val create_in :
read:(unit -> char) ->
- input:(string -> int -> int -> int) ->
+ input:(string -> int -> int -> int) ->
close:(unit -> unit) -> input
-(** Fully create an input by giving all the needed functions.
+(** Fully create an input by giving all the needed functions.
{b Note} Do {e not} use this function for creating an input
which reads from one or more underlying inputs. Rather, use
@@ -647,26 +647,26 @@ val create_in :
val wrap_in :
read:(unit -> char) ->
- input:(string -> int -> int -> int) ->
- close:(unit -> unit) ->
+ input:(string -> int -> int -> int) ->
+ close:(unit -> unit) ->
underlying:(input list) ->
input
-(** Fully create an input reading from other inputs by giving all
- the needed functions.
+(** Fully create an input reading from other inputs by giving all
+ the needed functions.
This function is a more general version of {!create_in}
which also handles dependency management between inputs.
{b Note} When you create an input which reads from another
- input, function [close] should {e not} close the inputs of
+ input, function [close] should {e not} close the inputs of
[underlying]. Doing so is a common error, which could result
in inadvertently closing {!stdin} or a network socket, etc.
*)
val inherit_in:
?read:(unit -> char) ->
- ?input:(string -> int -> int -> int) ->
- ?close:(unit -> unit) ->
+ ?input:(string -> int -> int -> int) ->
+ ?close:(unit -> unit) ->
input -> input
(** Simplified and optimized version of {!wrap_in} which may be used
whenever only one input appears as dependency.
@@ -681,11 +681,11 @@ val inherit_in:
val create_out :
write:(char -> unit) ->