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