package checked_oint

checked_oint

checked_oint is an OCaml library for checked integer arithmetic. We support the full set of signed and unsigned integers of bitnesses 8, 16, 32, 64, and 128. In some applications, the exact types of integers may be unknown at compile-time; we thus also provide a proper escape hatch based on existential types.

Installation

$ opam install checked_oint

Usage

open Checked_oint

let () =
  let x = U8.of_int_exn 50 in
  let y = U8.of_int_exn 70 in
  assert (U8.equal (U8.add_exn x y) (U8.of_int_exn 120));
  assert (Option.is_none (U8.mul x y))

You can find the API documentation here.

Polymorphic comparison

Polymorphic comparison operators (Stdlib.( = ), Stdlib.compare, etc.) can compute wrong results on checked integers, because they compare internal representations instead of the semantic values. To protect against accidental misuse, every integer carries a special "guard" value that makes polymorphic comparisons raise Invalid_argument. We recommend always using the monomorphic operations such as S.equal and S.compare, because they are both safe and fast.

The guard costs one allocation of a pair and a guard value per integer. To avoid this overhead, link your project against the checked_oint.guard-off library:

(executable
 ; ...
 (libraries checked_oint checked_oint.guard-off))

Libraries should only depend on checked_oint, leaving the choice of the guard implementation to final executables.

With this guard off, integers are represented with zero overhead, but polymorphic comparison operators silently succeed, possibly returning meaningless results.

Implementation

• u8, u16, i8, and i16 are represented as int internally.
• u32 and i32 (resp. u64 and i64) are represented as int32 (resp. int64) internally.
• u128 and i128 are represented as { high : int64; low : int64 } internally.
• Operations on integers of 8, 16, 32, and 64 bits are implemented primarily in OCaml, save a small amount of C stub functions.

• Operations on 128-bit integers are implemented solely in C.

  • We heavily rely on the __int128 extension by GCC and Clang.

Release procedure

1. Update the version field in dune-project.
2. Type dune build to generate checked_oint.opam.
3. Update CHANGELOG.md.

4. Release the project in GitHub Releases.

   1. Generate a source code archive and include it in the release:
      git archive HEAD -o checked_oint-<major>.<minor>.<patch>.tar.gz

5. Type git pull && opam publish.

   1. Specify the correct archive URL and checksums (by running md5sum and sha512sum on the archive).