Up
# module Z

: sig
# Toplevel

# Types

# Construction

# Basic arithmetic operations

# Bit-level operations

# Conversions

# Printing

# Ordering

# Elementary number theory

# Powers

# Representation

# Prefix and infix operators

# Miscellaneous

Integers.

This modules provides arbitrary-precision integers.
Small integers internally use a regular OCaml `int`

.
When numbers grow too large, we switch transparently to GMP numbers
(`mpn`

numbers fully allocated on the OCaml heap).

This interface is rather similar to that of `Int32`

and `Int64`

,
with some additional functions provided natively by GMP
(GCD, square root, pop-count, etc.).

This file is part of the Zarith library http://forge.ocamlcore.org/projects/zarith . It is distributed under LGPL 2 licensing, with static linking exception. See the LICENSE file included in the distribution.

Copyright (c) 2010-2011 Antoine Miné, Abstraction project. Abstraction is part of the LIENS (Laboratoire d'Informatique de l'ENS), a joint laboratory by: CNRS (Centre national de la recherche scientifique, France), ENS (École normale supérieure, Paris, France), INRIA Rocquencourt (Institut national de recherche en informatique, France).

For an optimal experience with the `ocaml`

interactive toplevel,
the magic commands are:

```
#load "zarith.cma";;
#install_printer Z.pp_print;;
```

#

type t

Type of integers of arbitrary length.

#

exception Overflow

Raised by conversion functions when the value cannot be represented in the destination type.

#

external of_float : float -> t
= "ml_z_of_float"

Converts from a floating-point value.
The value is truncated.
Raises `Overflow`

on infinity and NaN arguments.

#

val of_string : string -> t

Converts a string to an integer.
An optional `-`

prefix indicates a negative number, while a `+`

prefix is ignored.
An optional prefix `0x`

, `0o`

, or `0b`

(following the optional `-`

or `+`

prefix) indicates that the number is,
represented, in hexadecimal, octal, or binary, respectively.
Otherwise, base 10 is assumed.
(Unlike C, a lone `0`

prefix does not denote octal.)

#

external of_string_base : int -> string -> t
= "ml_z_of_string_base"

Parses a number represented as a string in the specified base,
with optional `-`

or `+`

prefix.
The base must be between 2 and 16.

For all bit-level operations, negative numbers are considered in 2's complement representation, starting with a virtual infinite number of 1s.

#

external popcount : t -> int
= "ml_z_popcount"

Counts the number of bits set.
Raises `Overflow`

for negative arguments, as those have an infinite
number of bits set.

Note that, when converting to an integer type that cannot represent the
converted value, an `Overflow`

exception is raised.

#

external to_int32 : t -> int32
= "ml_z_to_int32"

Converts to a 32-bit integer. May raise an `Overflow`

.

#

external to_nativeint : t -> nativeint
= "ml_z_to_nativeint"

Converts to a native integer. May raise an `Overflow`

.

#

external to_float : t -> float
= "ml_z_to_float"

Converts to a floating-point value. This function is designed explicitly for the case where the FPU rounds towards +oo, in which case the resulting float always over-approximates the argument. It is not guaranteed to be the least over-approximation though. In the (default) case where the FPU does not round towards +oo, it is only guaranteed that the result approximates the argument (but it may not be the nearest float).

#

external format : string -> t -> string
= "ml_z_format"

Gives a string representation of the argument in the specified printf-like format. The general specification has the following form:

`% [flags] [width] type`

Where the type actually indicates the base:

`i`

,`d`

,`u`

: decimal`b`

: binary`o`

: octal`x`

: lowercase hexadecimal`X`

: uppercase hexadecimal

Supported flags are:

`+`

: prefix positive numbers with a`+`

sign- space: prefix positive numbers with a space
`-`

: left-justify (default is right justification)`0`

: pad with zeroes (instead of spaces)`#`

: alternate formatting (actually, simply output a literal-like prefix:`0x`

,`0b`

,`0o`

)

Unlike the classic `printf`

, all numbers are signed (even hexadecimal ones),
there is no precision field, and characters that are not part of the format
are simply ignored (and not copied in the output).

#

external fits_int : t -> bool
= "ml_z_fits_int" "noalloc"

Whether the argument fits in a regular `int`

.

#

external fits_int32 : t -> bool
= "ml_z_fits_int32" "noalloc"

Whether the argument fits in an `int32`

.

#

external fits_int64 : t -> bool
= "ml_z_fits_int64" "noalloc"

Whether the argument fits in an `int64`

.

#

external fits_nativeint : t -> bool
= "ml_z_fits_nativeint" "noalloc"

Whether the argument fits in a `nativeint`

.

#

val output : Pervasives.out_channel -> t -> unit

Prints the argument on the specified channel.
Also intended to be used as `%a`

format printer in `Printf.printf`

.

#

external sign : t -> int
= "ml_z_sign" "noalloc"

Returns -1, 0, or 1 when the argument is respectively negative, null, or positive.

#

val hash : t -> int

Hashes a number.
This functions gives the same result as OCaml's polymorphic hashing
function.
The result is consistent with equality: if `a`

= `b`

, then `hash a`

=
`hash b`

.

#

external probab_prime : t -> int -> int
= "ml_z_probab_prime"

`probab_prime x r`

returns 0 if `x`

is definitely composite,
1 if `x`

is probably prime, and 2 if `x`

is definitely prime.
The `r`

argument controls how many Miller-Rabin probabilistic
primality tests are performed (5 to 10 is a reasonable value).

#

external perfect_power : t -> bool
= "ml_z_perfect_power"

True if the argument has the form `a^b`

, with `b>1`

#

external size : t -> int
= "ml_z_size" "noalloc"

Returns the number of machine words used to represent the number.

#

val signed_extract : t -> int -> int -> t

`signed_extract a off len`

extracts bits `off`

to `off`

+`len`

-1 of `b`

,
as `extract`

does, then sign-extends bit `len-1`

of the result
(that is, bit `off + len - 1`

of `a`

). The result is between
`- 2{^[len]-1}`

(included) and `2{^[len]-1}`

excluded,
and equal to `extract a off len`

modulo `2{^len}`

.

#

external to_bits : t -> string
= "ml_z_to_bits"

Returns a binary representation of the argument. The string result should be interpreted as a sequence of bytes, corresponding to the binary representation of the absolute value of the argument in little endian ordering. The sign is not stored in the string.

#

external of_bits : string -> t
= "ml_z_of_bits"

Constructs a number from a binary string representation.
The string is interpreted as a sequence of bytes in little endian order,
and the result is always positive.
We have the identity: `of_bits (to_bits x) = abs x`

.
However, we can have `to_bits (of_bits s) <> s`

due to the presence of
trailing zeros in s.

Classic (and less classic) prefix and infix `int`

operators are
redefined on `t`

.

This makes it easy to typeset expressions.
Using OCaml 3.12's local open, you can simply write
`Z.(~$2 + ~$5 * ~$10)`

.

#

val version : string

Library version (this file refers to version `"1.3"`

).

end