© 2012,2014,2017 John Abbott and Anna M. Bigatti
GNU Free Documentation License, Version 1.2

CoCoALib Documentation Index


User documentation

Here is a collection of basic operations available for integer values; see also the more advanced functions in NumTheory.

CoCoALib functions which expect integer values will accept either machine integer values or BigInt values -- they may be mixed. The return type is usually BigInt; the few cases where the return type is long are clearly indicated. Remember that basic arithmetic operations between two machine integers are handled directly by C++ (with its rules and restrictions e.g. overflow).

If you want to write new functions which accept machine integers as arguments, take a look at the class MachineInt which is designed for this purpose (handling both signed and unsigned machine integers safely).


Only for BigInt


Infix operators

  1. normal arithmetic (potentially inefficient because of temporaries)

NOTE: you cannot use ^ for exponentiation; you must use the function power instead. We decided this because it is too easy to write misleading code: for instance, a*b^2 is interpreted by the compiler as (a*b)^2. There is no way to make the C++ compiler use the expected interpretation.

  1. arithmetic and assignment
  2. arithmetic ordering
  3. increment/decrement


(three way comparison)

Sundry standard functions


The arguments of the functions below may be either a machine integer or a BigInt.

These functions always return BigInt

Conversion functions

Only for BigInt


Only for BigInt

Procedures for arithmetic

These procedures are ugly but may give a slight gain in speed. Use them only if you really must; it is probably better to use GMP directly if speed is so very important.

We expect these procedures (except quorem) to become obsolete when CoCoALib upgrades to the C++11 standard.

Assignment is always to leftmost argument(s) a, a BigInt. Second and/or third argument of type BigInt.

Error Conditions and Exceptions

Error conditions are signalled by exceptions. Examples of error conditions are impossible arithmetic operations such as division by zero, overly large arguments (e.g. second argument to binomial must fit into a machine long), and exhaustion of resources.

Currently the exception structure is very simplistic:

ERR::ArgTooBig value supplied is too large for the answer to be computed
ERR::BadArg unsuitable arg(s) supplied (or input number too large)
ERR::BadNumBase the base must be between 2 and 36
ERR::BadPwrZero attempt to raise 0 to negative power
ERR::DivByZero division by zero
ERR::ExpTooBig exponent is too large
ERR::IntDivByNeg inexact integer division by a negative divisor
ERR::NegExp negative exponent
ERR::ZeroModulus the modulus specified is zero

Maintainer Documentation

The implementation of cmp is more convoluted than I'd like; it must avoid internal overflow.

The implementation of RoundDiv was more difficult than I had expected. Part of the problem was making sure that needless overflow would never occur: this was especially relevant in the auxiliary functions uround_half_up and uround_half_down. It would be nice if a neater implementation could be achieved -- it seems strange that the C/C++ standard libraries do not already offer such a function. The standard C functions lround almost achieves what is needed here, but there are two significant shortcomings: rounding is always away from zero (rather than towards +infinity), and there could be loss of accuracy if the quotient exceeds 1/epsilon. There is also a standard function ldiv which computes quotient and remainder, but it seems to be faster to compute the two values explicitly.

NOTE: if you change rounding of halves, you must change TWO fns (RoundDiv for machine ints and RoundDiv for big ints).

Bugs, shortcomings and other ideas

The power functions could allow high powers of -1,0,1 (without complaining about the exponent being too big). But is it worth it?

Only partial access to all the various division functions offered by the C interface to GMP. Many other GMP functions are not directly accessible.

IsExactFloorRoot has rather a lot of signatures.

Main changes