Rational tutorial#

rational is a class that builds upon integer to provide an implementation of rational numbers represented as a numerator-denominator integer pairs.

Like integer, rational is parametrised over an integral value SSize which represents the number of limbs that will be stored directly within both the numerator and the denominator before resorting to dynamic memory allocation (see the integer tutorial for a detailed explanation of the meaning of the SSize parameter).

The rational class adopts the usual canonical representation of rational numbers:

numerator and denominator are coprime,
the denominator is always strictly positive.

This representation is usually enforced automatically by the rational API (however, a couple of low-level functions are available to access and mutate directly the numerator and the denominator in performance-critical scenarios).

In addition to the features common to all mp++ classes, the rational API provides a few additional capabilities:

it is possible to construct a rational from an integral pair of arguments representing the numerator and the denominator:

rat_t q1{3, 4};                // Construction from int numerator and denominator.

rat_t q2{long(-6), short(-8)}; // Construction from mixed numerator and denominator types.

assert(q1 == q2);              // Construction canonicalises the rational.

it is possible to get const and mutable references to the integer objects representing the numerator and the denominator via the mppp::rational::get_num(), mppp::rational::get_den(), mppp::rational::_get_num() and mppp::rational::_get_den() member functions. These accessors allow to use any function from the integer API on the numerator and on the denominator:
```
rat_t q1{2, 5};
assert(q1.get_num() == 2); // Const access to numerator and denominator.
assert(q1.get_den() == 5);

q1._get_num() = 1;         // Mutable access to numerator and denominator.
q1._get_den() = 3;
assert(q1 == rat_t{1, 3});
```

the mppp::rational::canonicalise() member function (and its free function counterpart) can be used to canonicalise a rational. This is normally not necessary, unless the numerator or the denominator have been changed manually via the mutable getters:

rat_t q1{1, 6};
q1._get_num() = 9;         // Change the numerator using the mutable getter.
                           // WARNING: q1 = 9/6, not in canonical form any more!

q1.canonicalise();         // Canonicalise q1.
assert(q1 == rat_t{3, 2});

a few additional arithmetic and comparison functions are available;
a few exponentiation and number-theoretic functions are available;
like integer, rational also provides a specialisation of std::hash for use in the standard unordered containers.

Many of these features, which are documented in detail in the rational reference, are available in multiple overloads, often both as free and member functions.

Interacting with the GMP API#

Like integer, rational provides facilities for interfacing with the GMP library. Currently, the interoperability is limited to rational objects being able to be constructed and assigned from both mpz_t and mpq_t objects:

mpz_t m;
mpz_init_set_si(m, -4);      // Init an mpz_t with the value -4.

rat_t q1{m};                 // Init a rat_t from the mpz_t.
assert(q1 == -4);            // Verify that the value is correct.

mpq_t q;
mpq_init(q);
mpq_set_si(q, 3, 4);         // Init an mpq_t with the value 3/4.

rat_t q2{q};                 // Init a rat_t from the mpq_t.
assert((q2 == rat_t{3, 4})); // Verify that the value is correct.

rat_t q3;
q3 = m;                      // Assign the mpz_t to another rat_t.
assert(q3 == -4);            // Verify that the value is correct.

rat_t q4;
q4 = q;                      // Assign the mpq_t to another rat_t.
assert((q4 == rat_t{3, 4})); // Verify that the value is correct.

mpz_clear(m);                // Clear the mpz_t.
mpq_clear(q);                // Clear the mpq_t.

User-defined literals#

Added in version 0.19.

User-defined literals are available to construct mppp::rational instances with 1, 2 and 3 limbs of static storage. The literals are defined within the inline namespace mppp::literals, and they support binary, octal, decimal and hexadecimal representations:

using namespace mppp::literals;

auto q1 = 123_q1;      // q1 has 1 limb of static storage,
                       // and it contains the value 123.

auto q2 = -0b10011_q2; // q2 has 2 limbs of static storage,
                       // and it contains the value -19
                       // (-10011 in base 2).

auto q3 = 0146_q1;     // q3 has 1 limb of static storage,
                       // and it contains the value 102
                       // (146 in base 8).

auto q4 = 0xfe45_q3;   // q4 has 3 limbs of static storage,
                       // and it contains the value 65093
                       // (fe45 in base 16).

Note that, due to language limitations, only values with unitary denominator can be constructed via these literals.

Rational tutorial

Contents

Rational tutorial#

Interacting with the GMP API#

User-defined literals#