hannesm/usane

Unsigned integers for OCaml

Usane - unsigned integers for OCaml

%%VERSION%% The behaviour of numbers (int, int32, int64) in OCaml is to be signed, and wrap around on over/underflow. This library gives explicit access to the carry bit by using compiler builtins. Other fine integer libraries, such as integers library and stdint) mirror the OCaml standard library behaviour.

This library defines 8, 16, 32, and 64 bit unsigned integers which interoperates well with the builtin types (int32, int64) by reusing their representation. Arithmetic operations return the carry bit explicitly.

Some motivating examples are:

# succ max_int
- : int = -4611686018427387904

# pred min_int
- : int = 4611686018427387903

# abs min_int
- : int = -4611686018427387904

Usane comes with a extensive test suite to show the behaviour.

Currently this library is not released, I first want to a) use ocb-stubblr (to get it to run on MirageOS) and b) test on 32bit.

Documentation

API Documentation is available online.

usane's Issues

exception-free result wrappers

It would be very nice to have an interface along the lines of:

module Usane : sig
  module Usane32 : sig
    val of_int_e : 'error -> int -> (t, 'error) result
  end
end

Interoperability with the integers package

For easy interoperability it would be helpful to have the following type equalities in the interface:

module Usane :
sig
  module Uint8 : 
  sig
    type t = Unsigned.UInt8.t
    (* ... *)
  end

  module Uint16 : 
  sig
    type t = Unsigned.UInt16.t
    (* ... *)
  end

  module Uint32 : 
  sig
    type t = Unsigned.UInt32.t
    (* ... *)
  end

  module Uint64 : 
  sig
    type t = Unsigned.UInt64.t
    (* ... *)
  end
end

rather than the current situation:

module Usane :
sig
  module Uint8 : 
  sig
    type t = int
    (* ... *)
  end

  module Uint16 : 
  sig
    type t = int
    (* ... *)
  end

  module Uint32 : 
  sig
    type t = int32
    (* ... *)
  end

  module Uint64 : 
  sig
    type t = int64
    (* ... *)
  end
end

Besides interoperability, there'd be an added bonus: polymorphic comparison (Pervasives.compare, Pervasives.(<)) would work as expected on Uint32.t and Uint64.t. At present, large positive numbers of those types are represented as negative numbers, and so comparison behaves unexpectedly.

Previous discussion: yallop/ocaml-integers#2