Documentation fix.
[virt-df.git] / lib / int63.mli
1 (** 63 bit signed integer type *)
2 (* (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
3
4    This program is free software; you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation; either version 2 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program; if not, write to the Free Software
16    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17  *)
18
19 (** This module deals with creating an efficient 63 bit signed integer
20     type.
21
22     In OCaml, the basic [int] type is fast because it is unboxed, but
23     it has a different size on 32 and 64 bit platforms (31 and 63 bits
24     respectively).  If we want a large integer type we can use the
25     OCaml [int64] type, but that is boxed and hence operations are
26     slow, even on 64 bit platforms.
27
28     This type gives us a large integer (up to 63 bits, therefore fine
29     for things involving eg. large disk file sizes), but retains
30     efficiency.  On 64 bit platforms it degenerates into just a normal
31     [int], hence unboxed and fast.  On 32 bit platforms it degenerates
32     to a kind of [int64], which is boxed and slow but hey 32 bit
33     platforms are going the way of all things anyway.
34
35     The implementation of this type is in the files [int63_on_32.ml]
36     or [int63_on_64.ml] for 32 bit and 64 bit platforms respectively.
37     The appropriate implementation is copied by the Makefile to
38     [int63.ml].
39 *)
40
41 (** {2 Type Int63.t}
42
43     OCaml cross-module inlining means that the compiler gets to
44     inline [int] operations directly and efficiently on 64 bit
45     platforms.  However we still need to hide the actual type
46     to prevent people from writing code that accidentally depends
47     on 32/64-bit platform differences.
48 *)
49
50 type t
51
52 (** {2 Operators}
53
54     It is recommended to do:
55
56 {[
57 open Int63.Operators
58 ]}
59
60     in your code so that you get the operators [+^], [-^] .. and the
61     type [int63] directly, and can still use the less frequent
62     functions such as {!Int63.abs} etc.
63 *)
64
65 module Operators : sig
66   type int63 = t
67
68   (* For the gory details of the rules of operators, see:
69    * http://caml.inria.fr/pub/docs/manual-ocaml/lex.html
70    *)
71
72   val ( +^ ) : t -> t -> t
73   val ( -^ ) : t -> t -> t
74   val ( *^ ) : t -> t -> t
75   val ( /^ ) : t -> t -> t
76   val ( %^ ) : t -> t -> t
77     (** Infix arithmetic operators. eg. [a +^ b -^ c] *)
78
79   val ( <^< ) : t -> int -> t
80   val ( >^> ) : t -> int -> t
81     (** Infix shift left and logical shift right.
82         eg. [~^1 <^< 62]
83
84         NB: We cannot use two less-than signs or two greater-than signs
85         in a row because that clashes with the symbols used for
86         camlp4 quotations. *)
87
88   val ( &&^ ) : t -> t -> t
89   val ( ||^ ) : t -> t -> t
90   val ( ^^^ ) : t -> t -> t
91     (** Infix logical and, or and xor operators.
92         eg. [bits &&^ mask] *)
93
94   val ( ~^ ) : int -> t
95     (** Small integer constants,
96         eg. [~^0] is the constant zero and [~^1] is the constant one. *)
97   val ( ~^~ ) : int -> t
98     (** Small negative integer constants,
99         eg. [~^~1] is the constant minus one. *)
100 end
101
102 (** {2 Functions}
103
104     These functions are analogous to the similarly named
105     functions available in the standard library [Int32] and
106     [Int64] modules. *)
107
108 val zero : t
109 val one : t
110 val minus_one : t
111   (** Some constants. *)
112
113 val neg : t -> t
114   (** Negate. *)
115
116 val add : t -> t -> t
117 val sub : t -> t -> t
118 val mul : t -> t -> t
119 val div : t -> t -> t
120 val rem : t -> t -> t
121   (** Arithmetic. *)
122
123 val succ : t -> t
124   (** Successor. *)
125 val pred : t -> t
126   (** Predecessor. *)
127
128 val abs : t -> t
129   (** Absolute value. *)
130
131 val max_int : t
132   (** The constant 2{^62}-1. *)
133 val min_int : t
134   (** The constant -2{^62}. *)
135
136 val logand : t -> t -> t
137 val logor : t -> t -> t
138 val logxor : t -> t -> t
139 val lognot : t -> t
140   (** Bitwise logical and, or, xor and not. *)
141
142 val shift_left : t -> int -> t
143   (** Shift the number left by the integer number of bits. *)
144 val shift_right : t -> int -> t
145   (** Arithmetic shift the number right by the integer number of bits.
146       The sign bit is replicated into the vacated bits. *)
147 val shift_right_logical : t -> int -> t
148   (** Logical shift the number right by the integer number of bits.
149       The vacated bits are filled with bit [0] regardless of sign. *)
150
151 val of_int : int -> t
152 val to_int : t -> int
153 val of_float : float -> t
154 val to_float : t -> float
155 val of_int32 : int32 -> t
156 val to_int32 : t -> int32
157 val of_int64 : int64 -> t
158 val to_int64 : t -> int64
159 val of_nativeint : nativeint -> t
160 val to_nativeint : t -> nativeint
161   (** Convert between t and various standard types. *)
162
163 val of_string : string -> t
164 val to_string : t -> string
165   (** Convert between string. *)
166
167 val compare : t -> t -> int
168   (** Compare two numbers. *)