Integers, floats and arithmetic

max_int + 1 in OCaml 5.5.1 gives -4611686018427387904 without any error, and -7 mod 2 gives -1, not 1. The same program prints a max_int of 2147483647 once it is compiled to JavaScript.

You will keep integers and floats apart with their own operators, predict overflow, division and mod on negative numbers, read infinity, nan and rounding correctly, parse numbers from text without exceptions, and choose a bigger integer type when 63 bits are not enough.

int and float are separate types with separate operators

OCaml never converts a number from one type to another by itself. Integers use +, -, *, / and mod; floats use their own operators with a dot, +., -., *. and /., and a float literal always has a dot or an exponent, 2.0 or 2.. Mixing them is a type error, so a conversion has to be written: float_of_int (also Float.of_int) from int to float, and truncate, int_of_float or Float.round the other way.

Text needs a conversion as well. int_of_string raises the exception Failure "int_of_string" on bad input, which stops a program unless it is caught, while int_of_string_opt returns None instead. Both read 0x, 0o and 0b prefixes and _ separators:

from session import toplevel

# int and float never mix without a conversion. Converting text to numbers: int_of_string raises on bad input, the _opt versions return None instead and accept
# 0x, 0o and 0b prefixes and _ separators. OCaml 5.5 adds bit counting such as Int.popcount.
toplevel("""
3 + 2.0;;
3 +. 2.0;;
float_of_int 3 +. 2.0;;
int_of_string "42";;
int_of_string "12a";;
int_of_string_opt "12a";;
int_of_string_opt "0x1F";;
int_of_string_opt "1_000_000";;
float_of_string_opt "2.5e3";;
Int.popcount 255;;
""")

$ ocaml
OCaml version 5.5.1
Enter #help;; for help.

# 3 + 2.0;;
Line 1, characters 4-7:
1 | 3 + 2.0;;
        ^^^
Error: The constant 2.0 has type float but an expression was expected of type
         int
# 3 +. 2.0;;
Line 1, characters 0-1:
1 | 3 +. 2.0;;
    ^
Error: The constant 3 has type int but an expression was expected of type
         float
Hint: Did you mean 3.?
# float_of_int 3 +. 2.0;;
- : float = 5.
# int_of_string "42";;
- : int = 42
# int_of_string "12a";;
Exception: Failure "int_of_string".
# int_of_string_opt "12a";;
- : int option = None
# int_of_string_opt "0x1F";;
- : int option = Some 31
# int_of_string_opt "1_000_000";;
- : int option = Some 1000000
# float_of_string_opt "2.5e3";;
- : float option = Some 2500.
# Int.popcount 255;;
- : int = 8

3 + 2.0 failed because 2.0 is a float where + wants an int, and 3 +. 2.0 failed the other way, with the hint “Did you mean 3.?”. int_of_string_opt "0x1F" gave Some 31 and "1_000_000" gave Some 1000000. The last line uses a function new in OCaml 5.5: Int.popcount 255 counts the bits that are set, 8.

A native int has 63 bits and wraps without warning

The manual’s chapter on values promises only the range −2³⁰ to 2³⁰ − 1, and adds that on 64-bit platforms the current implementation supports −2⁶² to 2⁶² − 1: one bit of each machine word goes to the runtime, which uses it to tell numbers from pointers. So max_int is 2⁶² − 1, and arithmetic past it wraps round silentlyinteger overflow: A result beyond max_int or min_int. OCaml's int arithmetic wraps around silently, so max_int + 1 gives min_int and no error is raised.:

from session import toplevel

# int has 63 bits on a 64-bit machine, so max_int is 2^62 - 1, and one more wraps round to min_int without any
# error. Int64 has the full 64 bits.
toplevel("""
max_int;;
min_int;;
max_int + 1;;
max_int + 1 = min_int;;
Sys.int_size;;
Int64.max_int;;
Int64.add Int64.max_int 1L;;
""")

$ ocaml
OCaml version 5.5.1
Enter #help;; for help.

# max_int;;
- : int = 4611686018427387903
# min_int;;
- : int = -4611686018427387904
# max_int + 1;;
- : int = -4611686018427387904
# max_int + 1 = min_int;;
- : bool = true
# Sys.int_size;;
- : int = 63
# Int64.max_int;;
- : int64 = 9223372036854775807L
# Int64.add Int64.max_int 1L;;
- : int64 = -9223372036854775808L

max_int + 1 gave exactly min_int, and Sys.int_size reported 63. Int64 has all 64 bits, up to 9223372036854775807, but it wraps the same way, as Int64.add Int64.max_int 1L showed. The size of int also depends on where the program runs:

from session import files, run

# One program, three targets: native code, JavaScript through js_of_ocaml and WebAssembly through wasm_of_ocaml,
# each run and printing its own int size.
files("ints.ml")
run("""
ocamlfind ocamlopt -package unix ints.ml -o ints_native && ./ints_native
ocamlfind ocamlc -package js_of_ocaml -linkpkg ints.ml -o ints.byte
js_of_ocaml ints.byte -o ints.js && node ints.js
wasm_of_ocaml ints.byte -o ints_wasm.js && node ints_wasm.js
""")

$ ocamlfind ocamlopt -package unix ints.ml -o ints_native && ./ints_native
int_size 63, max_int 4611686018427387903
$ ocamlfind ocamlc -package js_of_ocaml -linkpkg ints.ml -o ints.byte
$ js_of_ocaml ints.byte -o ints.js && node ints.js
int_size 32, max_int 2147483647
$ wasm_of_ocaml ints.byte -o ints_wasm.js && node ints_wasm.js
int_size 31, max_int 1073741823

Native code printed 63 bits, the JavaScript build from js_of_ocaml 32 bits and the WebAssembly build from wasm_of_ocaml 31 bits, with a max_int of 1073741823. A program meant for the browser must not assume 63 bits. Answer three questions about your own numbers and see which type fits:

For counts, indexes and money in paise, int is right on a server. When values have no known limit, an arbitrary-precision library such as Zarith keeps every digit, at a cost in speed.

Division truncates towards zero, and mod takes the dividend’s sign

Integer division rounds towards zero, and mod takes the sign of the number being divided, so a = (a / b) * b + (a mod b) always holds. The Int module of OCaml 5.5 adds three more ways to divide, each with its own rounding:

from session import toplevel

# Integer division truncates towards zero and mod takes the sign of the dividend; OCaml 5.5's Int.fdiv, cdiv, ediv
# and erem round down, round up or keep the remainder non-negative; erem keeps a step back from day 0 of a week
# inside 0 to 6. Dividing an int by zero raises an exception.
toplevel("""
-7 / 2;;
-7 mod 2;;
Int.fdiv (-7) 2;;
Int.cdiv (-7) 2;;
Int.ediv (-7) 2;;
Int.erem (-7) 2;;
(-1) mod 7;;
Int.erem (-1) 7;;
1 / 0;;
""")

$ ocaml
OCaml version 5.5.1
Enter #help;; for help.

# -7 / 2;;
- : int = -3
# -7 mod 2;;
- : int = -1
# Int.fdiv (-7) 2;;
- : int = -4
# Int.cdiv (-7) 2;;
- : int = -3
# Int.ediv (-7) 2;;
- : int = -4
# Int.erem (-7) 2;;
- : int = 1
# (-1) mod 7;;
- : int = -1
# Int.erem (-1) 7;;
- : int = 6
# 1 / 0;;
Exception: Division_by_zero.

The table matters when a negative number meets mod. Testing “is n odd?” with n mod 2 = 1 fails for -7, whose mod 2 is -1; n mod 2 <> 0 or Int.erem n 2 = 1 works for both signs. Indexes that wrap around need the same care. Counting the days of a week from 0, one step back from day 0 is (-1) mod 7, which gave -1, not a day at all, while Int.erem (-1) 7 gave 6, the last day of the week. And 1 / 0 raised Division_by_zero, an exception, while the next section shows that floats behave quite differently.

Floats follow IEEE 754: infinity, nan and binary rounding

Floats are 64-bit binary numbers, as the Float module’s documentation describes, so division by zero does not raise: it gives infinity, or nan, “not a number”, for 0. /. 0.. Comparing nan is where programs go wrong:

from session import toplevel

# Floats follow IEEE 754: dividing by zero gives infinity or nan, and nan is not equal to itself under =, though
# compare and Float.equal treat it as equal. Converting to int truncates; printing shows the binary value.
toplevel("""
1. /. 0.;;
0. /. 0.;;
nan = nan;;
compare nan nan;;
Float.equal nan nan;;
truncate 2.9;;
Float.round 2.5;;
string_of_float (0.1 +. 0.2);;
0.1 +. 0.2 = 0.3;;
Float.abs (0.1 +. 0.2 -. 0.3) < 1e-9;;
Printf.printf "%.17g %h %F\\n" (0.1 +. 0.2) 0.1 1.0;;
""")

$ ocaml
OCaml version 5.5.1
Enter #help;; for help.

# 1. /. 0.;;
- : float = infinity
# 0. /. 0.;;
- : float = nan
# nan = nan;;
- : bool = false
# compare nan nan;;
- : int = 0
# Float.equal nan nan;;
- : bool = true
# truncate 2.9;;
- : int = 2
# Float.round 2.5;;
- : float = 3.
# string_of_float (0.1 +. 0.2);;
- : string = "0.3"
# 0.1 +. 0.2 = 0.3;;
- : bool = false
# Float.abs (0.1 +. 0.2 -. 0.3) < 1e-9;;
- : bool = true
# Printf.printf "%.17g %h %F\n" (0.1 +. 0.2) 0.1 1.0;;
0.30000000000000004 0x1.999999999999ap-4 1.
- : unit = ()

nan = nan was false, because IEEE 754 makes nan unequal to everything, itself included, while compare nan nan gave 0 and Float.equal nan nan gave true, so sorting and tables treat it consistently. truncate 2.9 dropped the fraction to 2, and Float.round 2.5 rounded half away from zero, to 3. Finally, printing: string_of_float showed 0.3, while %.17g printed the stored value 0.30000000000000004, and %h gave the exact binary value of 0.1 in hexadecimal.

That stored value is why 0.1 +. 0.2 = 0.3 answered false. Neither 0.1 nor 0.2 has an exact binary form, and their rounded sum lands one step away from the rounded 0.3. Results of float arithmetic are compared within a tolerance chosen for the problem: Float.abs (0.1 +. 0.2 -. 0.3) < 1e-9 gave true. Amounts that must add up exactly, such as money, belong in integers of the smallest unit instead.

Practise: numbers that surprise

The questions give expressions with negative numbers, overflow, mixed types and nan, and ask what OCaml 5.5.1 answers. Each answer is in one of the sessions above:

Interview questions

Warm-up (fresher to 2–5 years): why does 3 + 2.0 not compile in OCaml?

OCaml has no implicit conversions between numeric types, and its operators are typed: + takes two ints and +. takes two floats. In 3 + 2.0, 2.0 is a float where + expects an int, so the type checker rejects the expression. You write the conversion yourself, float_of_int 3 +. 2.0, which gives 5., or 3 + int_of_float 2.0 if you want an int. The design costs a few characters but removes a class of bugs where a value is silently rounded or widened, and it is also why the compiler can keep ints unboxed and fast.

Two harder questions follow, about a sum that turns negative and about averaging prices. Settle your answer before you open each first step:

Key takeaways

• int and float are separate types with separate operators, such as + and +., and every conversion between them, or from text, is written out.
• A native int has 63 bits and wraps silently past max_int, and the same program has 32-bit or 31-bit ints in JavaScript or WebAssembly, so larger or fixed sizes need Int64, Int32 or an arbitrary-precision library.
• Integer division truncates towards zero and mod takes the dividend’s sign, while OCaml 5.5’s Int.fdiv, Int.cdiv, Int.ediv and Int.erem round down, up or keep the remainder non-negative.
• Floats follow IEEE 754, so division by zero gives infinity or nan, nan = nan is false, and %.17g shows the binary value behind a short printed float.