From 6f633fe37edcc442df38809ce654717daf40ec6a Mon Sep 17 00:00:00 2001
From: Anthony Scemama <scemama@irsamc.ups-tlse.fr>
Date: Sat, 3 Mar 2018 21:19:50 +0100
Subject: [PATCH] Zkey.mli

---
 Utils/Zkey.ml  | 36 ++++++++++--------------------------
 Utils/Zkey.mli | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 26 deletions(-)
 create mode 100644 Utils/Zkey.mli

diff --git a/Utils/Zkey.ml b/Utils/Zkey.ml
index 987a011..8c01eca 100644
--- a/Utils/Zkey.ml
+++ b/Utils/Zkey.ml
@@ -8,18 +8,22 @@ type t =
   }
 
 
-let of_int kind right =
+(** Creates a Zkey. *)
+let make ~kind right =
   { left = 0 ; right ; kind }
 
+(** Move [right] to [left] and set [right = x] *)
 let (<|) z x = 
   z.left  <- z.right;
   z.right <- x;
   z
 
+(** Shift left [right] by 10 bits, and add [x]. *)
 let (<<) z x =  
   z.right <- (z.right lsl 10) lor x ;
   z
 
+(** Shift left [right] by 10 bits, and add [x]. *)
 let (<+) z x =  
   z.right <- (z.right lsl 15) lor x ;
   z
@@ -31,19 +35,19 @@ type kind =
   | Nine   of (Powers.t * Powers.t * Powers.t)
   | Twelve of (Powers.t * Powers.t * Powers.t * Powers.t)
 
-let of_powers_three { x=a ; y=b ; z=c ; _ } = of_int 3 a <+ b <+ c
+let of_powers_three { x=a ; y=b ; z=c ; _ } = make 3 a <+ b <+ c
 
 let of_powers_six   { x=a ; y=b ; z=c ; _ } { x=d ; y=e ; z=f ; _ } =
-      of_int 6 a << b << c << d << e << f 
+      make 6 a << b << c << d << e << f 
 
 let of_powers_twelve { x=a ; y=b ; z=c ; _ } { x=d ; y=e ; z=f ; _ }
   { x=g ; y=h ; z=i ; _ } { x=j ; y=k ; z=l ; _ }  = 
-      of_int 12 a << b << c << d << e << f
+      make 12 a << b << c << d << e << f
           <| g << h << i << j << k << l
 
 let of_powers_nine { x=a ; y=b ; z=c ; _ } { x=d ; y=e ; z=f ; _ }
   { x=g ; y=h ; z=i ; _ } = 
-      of_int 9 a << b << c << d << e << f
+      make 9 a << b << c << d << e << f
           <| g << h << i 
 
 
@@ -168,7 +172,7 @@ let equal
   { right = r2 ; left = l2 ; kind = k2 } =
   r1 = r2 && l1 = l2 && k1 = k2
 
-let cmp 
+let compare
   { right = r1 ; left = l1 ; kind = k1 }
   { right = r2 ; left = l2 ; kind = k2 } =
   if k1 <> k2 then invalid_arg (__FILE__^": cmp");
@@ -186,23 +190,3 @@ let to_string { left ; right ; kind } =
   |> String.concat ", "
   ) ^ " >"
 
-(*
-let debug () = 
-  and k3  = of_int_array Kind_3  [| 1 ; 2 ; 3 |]
-  and k6  = of_int_array Kind_6  [| 1 ; 2 ; 3; 4 ; 5; 6|]
-  and k12 = of_int_array Kind_12 [| 1 ; 2 ; 3; 4 ; 5; 6 ; 7 ; 8 ; 9 ; 10 ; 11; 12|]
-  in
-  print_endline @@ to_string Kind_3 k3 ;
-  print_endline @@ to_string Kind_6 k6 ;
-  print_endline @@ to_string Kind_12 k12
-  
-  (*
-< 65538 | 1, 2 >
-< 1050627 | 1, 2, 3 >
-< 281483566841860 | 1, 2, 3, 4 >
-< 1128102155523078 | 1, 2, 3, 4, 5, 6 >
-< 20809811751934310026571282435288076 | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 >
-*)  
-
-let () = debug ()
-*)
diff --git a/Utils/Zkey.mli b/Utils/Zkey.mli
new file mode 100644
index 0000000..a73aaad
--- /dev/null
+++ b/Utils/Zkey.mli
@@ -0,0 +1,46 @@
+(** Encodes the powers of x, y, z in a compact form, suitable for being
+  used in a hash table.
+  *)
+
+type t 
+
+val to_string : t -> string
+(** Pretty printing *)
+
+val of_powers_three  : Powers.t -> t
+(** Create from a {!Powers.t}. *)
+
+val of_powers_six    : Powers.t -> Powers.t -> t
+(** Create from two {!Powers.t}. *)
+
+val of_powers_nine   : Powers.t -> Powers.t -> Powers.t -> t
+(** Create from three {!Powers.t}. *)
+
+val of_powers_twelve : Powers.t -> Powers.t -> Powers.t -> Powers.t -> t
+(** Create from four {!Powers.t}. *)
+
+type kind =
+  | Three  of  Powers.t
+  | Six    of (Powers.t * Powers.t)
+  | Nine   of (Powers.t * Powers.t * Powers.t)
+  | Twelve of (Powers.t * Powers.t * Powers.t * Powers.t)
+
+val of_powers : kind -> t
+(** Create using the [kind] type *)
+
+val to_int_array : t -> int array
+(** Convert to an int array. *)
+
+val to_powers : t -> kind
+
+(** {1 Functions for hash tables} *)
+
+val hash : t -> int
+(** Associates a nonnegative integer to any Zkey. *)
+
+val equal : t -> t -> bool
+(** The equal function. True if two Zkeys are equal. *)
+
+val compare : t -> t -> int
+(** Comparison function, used for sorting. *)
+