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 [open Int63.Operators] in your code
  55     so that you get the operators [+^], [-^] .. and the type [int63]
  56     directly, and can still use the less frequent functions
  57     as [Int63.logand] etc.
  58 *)
  59
  60 module Operators : sig
  61   type int63 = t
  62
  63   val ( +^ ) : t -> t -> t
  64   val ( -^ ) : t -> t -> t
  65   val ( *^ ) : t -> t -> t
  66   val ( /^ ) : t -> t -> t
  67     (** Arithmetic operators. *)
  68
  69   val ( <<^ ) : t -> int -> t
  70   val ( >>^ ) : t -> int -> t
  71     (** Shift left and logical shift right. *)
  72
  73   val ( ~^ ) : int -> t
  74     (** Constant, eg. [~^0] is the constant zero. *)
  75   val ( ~^~ ) : int -> t
  76     (** Negative constant, eg. [~^~1] is the constant minus one. *)
  77 end
  78
  79 (** {2 Functions}
  80
  81     These functions are analogous to the similarly named
  82     functions available in the standard library [Int32] and
  83     [Int64] modules. *)
  84
  85 val zero : t
  86 val one : t
  87 val minus_one : t
  88   (** Some constants. *)
  89
  90 val neg : t -> t
  91   (** Negate. *)
  92
  93 val add : t -> t -> t
  94 val sub : t -> t -> t
  95 val mul : t -> t -> t
  96 val div : t -> t -> t
  97 val rem : t -> t -> t
  98   (** Arithmetic. *)
  99
 100 val succ : t -> t
 101   (** Successor. *)
 102 val pred : t -> t
 103   (** Predecessor. *)
 104
 105 val abs : t -> t
 106   (** Absolute value. *)
 107
 108 val max_int : t
 109   (** The constant [2{^62}-1]. *)
 110 val min_int : t
 111   (** The constant [-2{^62}]. *)
 112
 113 val logand : t -> t -> t
 114 val logor : t -> t -> t
 115 val logxor : t -> t -> t
 116 val lognot : t -> t
 117   (** Bitwise logical and, or, xor and not. *)
 118
 119 val shift_left : t -> int -> t
 120   (** Shift the number left by the integer number of bits. *)
 121 val shift_right : t -> int -> t
 122   (** Arithmetic shift the number right by the integer number of bits.
 123       The sign bit is replicated into the vacated bits. *)
 124 val shift_right_logical : t -> int -> t
 125   (** Logical shift the number right by the integer number of bits.
 126       The vacated bits are filled with bit [0] regardless of sign. *)
 127
 128 val of_int : int -> t
 129 val to_int : t -> int
 130 val of_float : float -> t
 131 val to_float : t -> float
 132 val of_int32 : int32 -> t
 133 val to_int32 : t -> int32
 134 val of_int64 : int64 -> t
 135 val to_int64 : t -> int64
 136 val of_nativeint : nativeint -> t
 137 val to_nativeint : t -> nativeint
 138   (** Convert between t and various standard types. *)
 139
 140 val of_string : string -> t
 141 val to_string : t -> string
 142   (** Convert between string. *)
 143
 144 val compare : t -> t -> int
 145   (** Compare two numbers. *)