Updated deps for i386.
[virt-df.git] / lib / int63_on_64.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     For reasons not fully understood, we need to declare this
44     type explicitly in order to get properly optimized operations.
45     This means the user of a 64 bit platform must be careful not to
46     accidentally write code which depends on [t] being an [int],
47     but should treat this as an opaque type.
48 *)
49
50 type t = int
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. *)