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 as {!Int63.logand} 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. *)