Int_builtinsSourceIn the following, the _untagged variant takes an untagged (i.e., C) int, whereas the normal variant takes an OCaml int. Which one to choose depends on the context: if you were previously doing integer operations, the compiler probably already compiled the untagged int, so using the _untagged version might be slightly faster (though probably barely noticeable). If you are reading from an argument or a field in a datastructure, your integer is tagged, so you should use the normal version.
Warning: for some corner arguments, the normal and untagged version may have different behaviours. In that case, we suffix the unsafe variant with _unsafe.
If in doubt, just use the normal version.
For non-zero numbers, log2 x is the position of the highest bit set, i.e. such that x lsr (log x) = 1. Numbers are interpreted as unsigned (e.g. (log2 -1) = 62 on 64-bit plateforms, as ints are 63-bit in OCaml.
In this version, log2 0 = -1.
Warning: log2_untagged_unsafe 0 = 1, which is probably not what you want. Furthermore, log2_untagged_unsafe x = 1 + log2 x when x is negative. log2_untagged_unsafe is thus safe only on strictly positive integer values.
highest_bit x is the value y where the only bit set is the most significant bit of x, i.e.
x land y = yx land (lnot y) land (lnot y - 1) = 0. Furthermore, highest_bit 0 = 0.Like highest_bit, but highest_bit_untagged_unsafe 0 and highest_bit_untagged_unsafe x when x < 0 are undefined.
See ffs.
popcount returns the number of bit set in the machine representation of the integer.
See popcount.