# 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`
5. `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