GNU Free Documentation License, Version 1.2

- Examples
- User documentation
- Maintainer Documentation
- Bugs, Shortcomings and other ideas
- Main changes

**IMPORTANT NOTE:**

**see**`BigRatOps`

for basic operations on values of type`BigRat`

**see**`NumTheory`

for more advanced operations

The class `BigRat`

is intended to represent (exact) rational numbers
of practically unlimited range; it is currently based on the
implementation in the GMP *multiple precision* library. This code forms
the interface between CoCoALib and the big integer/rational library
upon which it relies. It seems most unlikely that GMP will be
displaced from its position as the foremost library of this type; as a
consequence the class `BigRat`

may eventually be replaced by GMP's
own C++ interface.

It is important not to confuse values of type `BigRat`

with values of type
`RingElem`

which happen to belong to the ring `RingQQ`

. The distinction
is analogous to that between values of type `BigInt`

and value of type
`RingElem`

which happen to belong to the ring `RingZZ`

. In summary, the
operations available for `RingElem`

are those applicable to elements of
any ordered commutative ring, whereas the range of operations on `BigRat`

values is wider (since we have explicit knowledge of the type).

A value of type `BigRat`

may be created from:

`BigRat()`

default ctor, the value is zero`BigRat(n)`

where`n`

is an integer:**warning: do not write**`BigRat(2/3)`

, it compiles but works unexpectedly!`BigRat(q)`

where`q`

is another value of type`BigRat`

(its value is copied)`BigRat(n,d)`

where`n`

and`d`

are both integers (machine integers or`BigInt`

s) specifying numerator and denominator in that order`BigRat(BigRat::OneOverZero)`

create the "infinity" rational`1/0`

(will trigger an error if you try to perform arithmetic with it, but you can access`num`

and`den`

)`BigRatFromString(str)`

where`str`

is a string of the form`N`

or`N/D`

where`N`

is the decimal representation of the numerator and`D`

that of the denominator (leading and trailing whitespace is permitted)`BigRatFromMPQ(mpq_value)`

copy a GMP rational (of type`mpq_t`

) into a`BigRat`

; helps interfacing between CoCoALib and code using GMP directly.

The ctors `BigRat(n,d)`

and `BigRatFromString(str)`

accept an optional final
arg `BigRat::AlreadyReduced`

which asserts that the value is already reduced
(*i.e.* positive denominator, and numerator and denominator are coprime).
Use this feature only if you are **absolutely certain** that there is no
common factor between the given numerator and denominator.

See **Bugs** section for why there is no ctor from a single integer.

- Functions violating encapsulation
`mpqref(n)`

-- this gives a (const) reference to the`mpq_t`

value inside a`BigRat`

object. You should use this accessor very sparingly!

Nothing very clever. Conversion from a string was a bit tedious.

I have replaced the bodies of the `BigRat`

ctors which take two integers
as arguments by a call to the common body `BigRat::myAssign`

. This does
mean that some wasteful temporaries are created when either of the
arguments is a machine integer. Time will tell whether this waste is
intolerable.

The reason for having "strange" ctors from`std::string`

and `mpq_t`

was to avoid problems with `BigRat(0)`

. Note that expressions such
as `BigInt(2/3)`

are equivalent to `BigInt(0)`

but should be forbidden
at compile time; however, at the moment `mpq_t`

is a pointer type, so
`BigRat(2/3)`

is seen as `BigRat(0)`

, and `0`

can be interpreted as
a null-pointer... so `BigRat(mpq_t)`

would be an almost perfect match!

This code is probably not *exception safe*; I do not know what the `mpq_*`

functions do when there is insufficient memory to proceed. Making the
code *exception safe* could well be non-trivial: I suspect a sort of
`auto_ptr`

to an `mpq_t`

value might be needed.

Removed `BigRat`

ctors from a single (machine) integer because too often
I made the mistake of writing something like `BigRat(1/2)`

instead of
`BigRat(1,2)`

.

Should the `BigRatFromString`

pseudo-ctor also accept numbers with decimal points?
*e.g.* `BigRat("3.14159")`

? We'll wait and see whether there is demand for this
before implementing; note that GMP does **not** offer this capability.

**2018**

- June (v0.99570): split off
`BigRatOps`

- April (v0.99570):
Removed ctors from
`string`

and`mpq_t`

; replaced them by pseudo-ctors. This means that`BigRat(0)`

and`BigRat(1/2)`

etc. now give compile-time errors.

**2011**

- August (v0.9950):
class
`QQ`

renamed into`BigRat`

: to avoid confusion with`RingQQ`

and its name in CoCoA system