# BigRatOps

© 2018 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 rational values; see also the more advanced functions in NumTheory.

The usual arithmetic operations are available with standard C++ syntax. The type BigRat is provided for convenience of representing rational values rather than for rapid computation; the native GMP operations may be noticeably faster.

There is an important exception to the natural syntax: ^ does not denote exponentiation; you must use the function power instead. We have chosen not to define operator^ to perform exponentiation 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.

Arithmetic may also be performed between a BigRat and a machine integer or a BigInt. The result is always of type BigRat (even if the value turns out to be an integer). Do remember, though, that operations between two machine integers are handled directly by C++, and problems of overflow can occur.

#### Infix operators

NOTE: similar to operations on BigInt -- see BigIntOps

1. normal arithmetic (potentially inefficient because of temporaries)
• + the sum
• - the difference
• * the product
• / quotient
• = assignment

2. arithmetic and assignment
• +=, -=, *=, /= -- definitions as expected; LHS must be of type BigRat

3. arithmetic ordering
• ==, !=
• <, <=, >, >= -- comparison (using the normal arithmetic ordering) -- see also the cmp function below.

4. increment/decrement
• ++, -- (prefix, e.g. ++a) use these if you can
• ++, -- (postfix, e.g. a++) avoid these if you can, as they create temporaries

#### More functions

1. query functions (all take 1 argument)
• IsZero(q) -- true iff q is zero
• IsOne(q) -- true iff q is 1
• IsMinusOne(q) -- true iff q is -1
• IsOneNum(q) -- true iff num(q) is 1
• IsOneDen(q) -- true iff den(q) is 1
• sign(q) -- gives -1 (machine integer) to mean q is negative, 0 (machine integer) to mean q is zero, +1 (machine integer) to mean q is positive.

2. Exponentiation
• power(a, b) -- returns a to the power b (result is always a BigRat)

3. The cmp function (three way comparison)
• cmp(a,b) -- returns an int which is < 0 if a < b, or == 0 if a == b, or > 0 if a > b.
• CmpAbs(a,b) -- equivalent to cmp(abs(a),abs(b))

4. Other functions
• abs(q) -- gives the absolute value of q
• floor(q) -- returns a BigInt for the greatest integer <= q
• ceil(q) -- returns a BigInt for the least integer >= q
• round(q) -- returns a BigInt which is the nearest to q (halves round the same way as in RoundDiv, see BigIntOps)
• num(q) -- returns a BigInt which is the numerator of q
• den(q) -- returns a positive BigInt which is the denominator of q
• log(q) -- returns a double whose value is (approx) the natural logarithm of q
• FloorLog2(q) -- same as ``FloorLogBase(q,2)
• FloorLog10(q) -- same as ``FloorLogBase(q,10)
• FloorLogBase(q,base) -- returns largest integer k such that power(base,k) <= abs(q)
• mantissa(q) -- returns a double between 0.5 and 1 (excluded)
• exponent(q) --

#### Conversion functions

Only for BigInt

• mantissa(N) -- N represented as a floating-point number. If N is zero, produces 0.0. If N>0, produces a value between 0.5 and 0.999...; otherwise (when N<0) a value between -0.5 and -0.999... The bits of the floating point result are the topmost bits of the binary representation of N.
• exponent(N) -- result is a long whose value is the least integer e such that 2^e > abs(n). If N is zero, result is zero.

#### Miscellany

Only for BigInt

• SizeInBase(N, b) -- (returns long) the number of digits N has when written in base b. Very fast! WARNING the result may sometimes to be too large by 1; use 1+FloorLogBase(N) to get the exact result.

## Maintainer Documentation

Most impls are very simple (since GMP does all the real work).

## Bugs, shortcomings and other ideas

Impl of FloorLogBase is ugly!

There are some NYI functions!

2018