lib/int63_on_32.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 type t
  44
  45 (** {2 Operators}
  46
  47     It is recommended to do:
  48
  49 {[
  50 open Int63.Operators
  51 ]}
  52
  53     in your code so that you get the operators [+^], [-^] .. and the
  54     type [int63] directly, and can still use the less frequent
  55     functions such as {!Int63.abs} etc.
  56 *)
  57
  58 module Operators : sig
  59   type int63 = t
  60
  61   (* For the gory details of the rules of operators, see:
  62    * http://caml.inria.fr/pub/docs/manual-ocaml/lex.html
  63    *)
  64
  65   val ( +^ ) : t -> t -> t
  66   val ( -^ ) : t -> t -> t
  67   val ( *^ ) : t -> t -> t
  68   val ( /^ ) : t -> t -> t
  69   val ( %^ ) : t -> t -> t
  70     (** Infix arithmetic operators. eg. [a +^ b -^ c] *)
  71
  72   val ( <^< ) : t -> int -> t
  73   val ( >^> ) : t -> int -> t
  74     (** Infix shift left and logical shift right.
  75         eg. [~^1 <^< 62]
  76
  77         NB: We cannot use two less-than signs or two greater-than signs
  78         in a row because that clashes with the symbols used for
  79         camlp4 quotations. *)
  80
  81   val ( &^ ) : t -> t -> t
  82   val ( |^ ) : t -> t -> t
  83   val ( ^^ ) : t -> t -> t
  84     (** Infix logical and, or and xor operators.
  85         eg. [bits &^ mask] *)
  86
  87   val ( ~^ ) : int -> t
  88     (** Small integer constants,
  89         eg. [~^0] is the constant zero and [~^1] is the constant one. *)
  90   val ( ~^~ ) : int -> t
  91     (** Small negative integer constants,
  92         eg. [~^~1] is the constant minus one. *)
  93 end
  94
  95 (** {2 Functions}
  96
  97     These functions are analogous to the similarly named
  98     functions available in the standard library [Int32] and
  99     [Int64] modules. *)
 100
 101 val zero : t
 102 val one : t
 103 val minus_one : t
 104   (** Some constants. *)
 105
 106 val neg : t -> t
 107   (** Negate. *)
 108
 109 val add : t -> t -> t
 110 val sub : t -> t -> t
 111 val mul : t -> t -> t
 112 val div : t -> t -> t
 113 val rem : t -> t -> t
 114   (** Arithmetic. *)
 115
 116 val succ : t -> t
 117   (** Successor. *)
 118 val pred : t -> t
 119   (** Predecessor. *)
 120
 121 val abs : t -> t
 122   (** Absolute value. *)
 123
 124 val max_int : t
 125   (** The constant 2{^62}-1. *)
 126 val min_int : t
 127   (** The constant -2{^62}. *)
 128
 129 val logand : t -> t -> t
 130 val logor : t -> t -> t
 131 val logxor : t -> t -> t
 132 val lognot : t -> t
 133   (** Bitwise logical and, or, xor and not. *)
 134
 135 val shift_left : t -> int -> t
 136   (** Shift the number left by the integer number of bits. *)
 137 val shift_right : t -> int -> t
 138   (** Arithmetic shift the number right by the integer number of bits.
 139       The sign bit is replicated into the vacated bits. *)
 140 val shift_right_logical : t -> int -> t
 141   (** Logical shift the number right by the integer number of bits.
 142       The vacated bits are filled with bit [0] regardless of sign. *)
 143
 144 val of_int : int -> t
 145 val to_int : t -> int
 146 val of_float : float -> t
 147 val to_float : t -> float
 148 val of_int32 : int32 -> t
 149 val to_int32 : t -> int32
 150 val of_int64 : int64 -> t
 151 val to_int64 : t -> int64
 152 val of_nativeint : nativeint -> t
 153 val to_nativeint : t -> nativeint
 154   (** Convert between t and various standard types. *)
 155
 156 val of_string : string -> t
 157 val to_string : t -> string
 158   (** Convert between string. *)
 159
 160 val compare : t -> t -> int
 161   (** Compare two numbers. *)