Adds an introductory example as another test

README.md

@@ -82,10 +82,11 @@ option to `ocamlc` / `ocamlopt`, or the `-package zarith` option to `ocamlfind`.
   make doc
 ```
 
-## ONLINE DOCUMENTATION
+## DOCUMENTATION
 
 The documentation for the latest release is hosted on [GitHub Pages](https://antoinemine.github.io/Zarith/doc/latest/index.html).
 
+The tests/ directory contains examples, regression tests, and benchmarks.
 
 ## LICENSE
 
@@ -126,4 +127,4 @@ Source files        | Description
   projet.mak        | builds Z, Q and the tests
   zarith.opam       | package description for opam
   z_mlgmpidl.ml[i]  | conversion between Zarith and MLGMPIDL
-  tests/            | simple regression tests and benchmarks
+  tests/            | examples, simple regression tests and benchmarks

tests/Makefile

@@ -18,6 +18,10 @@ test:: zq.byt
 	@echo "Testing zq (bytecode)..."
 	@if ocamlrun -I .. ./zq.byt | cmp -s zq.output$(WORDSIZE) - ; then echo "zq: passed"; else echo "zq: FAILED"; exit 2; fi
 
+test:: introduction.exe
+	@echo "Testing introduction..."
+	@if ./introduction.exe integers | cmp -s introduction.output - ; then echo "introduction: passed"; else echo "introduction: FAILED"; exit 2; fi
+
 ifeq ($(HAS_NUM),true)
 test:: bi.exe
 	@echo "Testing bi..."

tests/introduction.ml

@@ -0,0 +1,51 @@
+let integers () =
+  (* Build something bigger than an OCaml int can hold. *)
+  let z = Z.of_int max_int in
+  let bigz = Z.mul z z in
+    print_endline (Z.to_string bigz);
+  (* Go even bigger *)
+  let biggerz = Z.shift_left z 100 in
+    print_endline (Z.to_string biggerz);
+    Printf.printf "This has %i significant bits, of which %i are set\n" (Z.numbits biggerz) (Z.popcount biggerz);
+    Printf.printf "Does it fit in an Int64.t? %b\n" (Z.fits_int64 biggerz);
+    (* Logarithm (as an int, because it is small) *)
+    Printf.printf "Logarithm, base two: %i\n" (Z.log2 biggerz);
+    (* Prime just larger than this (probably) *)
+    Printf.printf "Next prime... %s\n" (Z.to_string (Z.nextprime biggerz));
+    (* There are alternative printers: *)
+    print_endline "Decimal:";
+    print_endline (Z.format "%i" biggerz);
+    print_endline "Octal:";
+    print_endline (Z.format "%o" biggerz);
+    print_endline "Binary:";
+    print_endline (Z.format "%b" biggerz);
+    print_endline "Hexadecimal:";
+    print_endline (Z.format "%0#X" biggerz)
+
+let rationals () =
+  (* 1 / 100 *)
+  let q = Q.make (Z.of_int 1) (Z.of_int 100) in
+  (* Or, more easily 1 / 1000 *)
+  let q2 = Q.of_ints 1 1000 in
+  (* Or, even more easily 1 / 10000 *)
+  let open Q in
+  let q3 = 1 // 10000 in
+  (* Or, from a string *)
+  let q4 = Q.of_string "1/10000" in
+    (* Show parts *)
+    Printf.printf "Parts of q3: %s, %s\n" (Z.to_string q3.num) (Z.to_string q3.den);
+    (* Printing *)
+    Q.print q3;
+    print_newline ();
+    (* Arithmetic *)
+    let q5 = Q.mul q3 q4 in
+      print_endline "Multiplied:";
+      Q.print q5;
+      print_newline ();
+      Printf.printf "As a float: %f\n" (Q.to_float q4)
+
+let () =
+  match Sys.argv with
+  | [|_; "integers"|] -> integers ()
+  | [|_; "rationals"|] -> rationals ()
+  | _ -> Printf.eprintf "introduction: unknown command line. Try 'integers' or 'rationals'.\n"

tests/introduction.output

@@ -0,0 +1,14 @@
+21267647932558653957237540927630737409
+5846006549323611671547088730636902677127026966528
+This has 162 significant bits, of which 62 are set
+Does it fit in an Int64.t? false
+Logarithm, base two: 161
+Next prime... 5846006549323611671547088730636902677127026966581
+Decimal:
+5846006549323611671547088730636902677127026966528
+Octal:
+777777777777777777776000000000000000000000000000000000
+Binary:
+111111111111111111111111111111111111111111111111111111111111110000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+Hexadecimal:
+0X3FFFFFFFFFFFFFFF0000000000000000000000000