regina::Rational Class Reference
Mathematical Support

Represents an arbitrary precision rational number. More...

`#include <maths/rational.h>`

## Public Member Functions

| Rational ()
| Initialises to 0/1. More...
| Rational (const Rational &value)
| Initialises to the given rational value. More...
template<bool supportInfinity>
| Rational (const IntegerBase< supportInfinity > &value)
| Initialises to the given integer value. More...
| Rational (long value)
| Initialises to the given integer value. More...
template<bool supportInfinity>
| Rational (const IntegerBase< supportInfinity > &newNum, const IntegerBase< supportInfinity > &newDen)
| Initialises to newNum/newDen. More...
| Rational (long newNum, unsigned long newDen)
| Initialises to newNum/newDen. More...
| ~Rational ()
| Destroys this rational. More...
Rational & | operator= (const Rational &value)
| Sets this rational to the given rational value. More...
template<bool supportInfinity>
Rational & | operator= (const IntegerBase< supportInfinity > &value)
| Sets this rational to the given integer value. More...
Rational & | operator= (long value)
| Sets this rational to the given integer value. More...
void | swap (Rational &other)
| Swaps the values of this and the given rational. More...
Integer | numerator () const
| Returns the numerator of this rational. More...
Integer | denominator () const
| Returns the denominator of this rational. More...
Rational | operator* (const Rational &r) const
| Calculates the product of two rationals. More...
Rational | operator/ (const Rational &r) const
| Calculates the ratio of two rationals. More...
Rational | operator+ (const Rational &r) const
| Calculates the sum of two rationals. More...
Rational | operator- (const Rational &r) const
| Calculates the difference of two rationals. More...
Rational | operator- () const
| Determines the negative of this rational. More...
Rational | inverse () const
| Calculates the inverse of this rational. More...
Rational | abs () const
| Determines the absolute value of this rational. More...
Rational & | operator+= (const Rational &other)
| Adds the given rational to this. More...
Rational & | operator-= (const Rational &other)
| Subtracts the given rational from this. More...
Rational & | operator*= (const Rational &other)
| Multiplies the given rational by this. More...
Rational & | operator/= (const Rational &other)
| Divides this by the given rational. More...
void | negate ()
| Negates this rational. More...
void | invert ()
| Inverts this rational. More...
bool | operator== (const Rational &compare) const
| Determines if this is equal to the given rational. More...
bool | operator!= (const Rational &compare) const
| Determines if this is not equal to the given rational. More...
bool | operator< (const Rational &compare) const
| Determines if this is less than the given rational. More...
bool | operator> (const Rational &compare) const
| Determines if this is greater than the given rational. More...
bool | operator<= (const Rational &compare) const
| Determines if this is less than or equal to the given rational. More...
bool | operator>= (const Rational &compare) const
| Determines if this is greater than or equal to the given rational. More...
double | doubleApprox (bool *inRange=0) const
| Attempts to convert this rational to a real number. More...
std::string | TeX () const
| Returns this rational as written using TeX formatting. More...
std::ostream & | writeTeX (std::ostream &out) const
| Writes this rational in TeX format to the given output stream. More...

## Static Public Attributes

static const Rational | zero
| Globally available zero. More...
static const Rational | one
| Globally available one. More...
static const Rational | infinity
| Globally available infinity. More...
static const Rational | undefined
| Globally available undefined. More...

## Friends

std::ostream & | operator<< (std::ostream &out, const Rational &rat)
| Writes the given rational to the given output stream. More...

## Detailed Description

Represents an arbitrary precision rational number.

Calculations with Rational objects will be exact.

Infinity (1/0) and undefined (0/0) are catered for. (-1/0) is considered the same as (1/0), and is represented as (1/0). Any operation involving (0/0) will return (0/0).

Since infinity is the same as negative infinity, both infinity plus infinity and infinity minus infinity will return infinity. Infinity divided by infinity returns undefined, as does infinity times zero.

For the purposes of ordering, undefined is the smallest rational and infinity is the largest. Undefined is always equal to itself, and infinity is always equal to itself.

When performing computations on rationals, the results will always be stored in lowest terms (i.e., with relatively prime numerator and denominator), and with a non-negative denominator. However, when constructing a rational number from scratch (e.g., by supplying the numerator and denominator separately), it is your responsibility to ensure that the rational is in lowest terms.

## Constructor & Destructor Documentation

## Rational() [1/6]

regina::Rational::Rational | ( |  | ) |

inline

Initialises to 0/1.

## Rational() [2/6]

regina::Rational::Rational | ( | const Rational & | value | ) |

inline

Initialises to the given rational value.

Parameters

  value | the new rational value of this rational.

## Rational() [3/6]

template<bool supportInfinity>

regina::Rational::Rational | ( | const IntegerBase< supportInfinity > & | value | ) |

inline

Initialises to the given integer value.

The given integer may be infinite.

Parameters

  value | the new integer value of this rational.

## Rational() [4/6]

regina::Rational::Rational | ( | long | value | ) |

inline

Initialises to the given integer value.

Parameters

  value | the new integer value of this rational.

## Rational() [5/6]

template<bool supportInfinity>

regina::Rational::Rational | ( | const IntegerBase< supportInfinity > & | newNum,
|  | const IntegerBase< supportInfinity > & | newDen
| ) |  |

Initialises to newNum/newDen.

Precondition
  gcd(newNum, newDen) = 1 or newDen = 0.
  newDen is non-negative.

Warning
  Failing to meet the preconditions above can result in misleading or even undefined behaviour. As an example, Rational(4,4) (which breaks the gcd requirement) is considered different from Rational(1,1) (a valid rational), which is different again from Rational(-1,-1) (which breaks the non-negativity requirement).

Precondition
  Neither of the given integers is infinite.

Parameters

  newNum | the new numerator.
  newDen | the new denominator.

## Rational() [6/6]

regina::Rational::Rational | ( | long | newNum,
|  | unsigned long | newDen
| ) |  |

Initialises to newNum/newDen.

Precondition
  gcd(newNum, newDen) = 1 or newDen = 0.
  newDen is non-negative.

Warning
  Failing to meet the preconditions above can result in misleading or even undefined behaviour. As an example, Rational(4,4) (which breaks the gcd requirement) is considered different from Rational(1,1) (a valid rational), which is different again from Rational(-1,-1) (which breaks the non-negativity requirement).

Parameters

  newNum | the new numerator.
  newDen | the new denominator.

## ~Rational()

regina::Rational::~Rational | ( |  | ) |

inline

Destroys this rational.

## Member Function Documentation

## abs()

Rational regina::Rational::abs | ( |  | ) | const

Determines the absolute value of this rational.

This rational is not changed.

Returns
  the absolute value of this rational.

## denominator()

Integer regina::Rational::denominator | ( |  | ) | const

Returns the denominator of this rational.

Note that rationals are always stored in lowest terms with non-negative denominator. Infinity will be stored as 1/0.

Returns
  the denominator.

## doubleApprox()

double regina::Rational::doubleApprox | ( | bool * | inRange = `0` | ) | const

Attempts to convert this rational to a real number.

If this rational can be approximated by a double (specifically, if it lies within double's allowable range) then a such an approximation is returned. Otherwise zero is returned instead.

The optional inRange argument allows the result of range checking to be returned explicitly as a boolean (`*inRange` will be set to `true` if a double approximation is possible and `false` otherwise).

It is safe to pass inRange as `null`, in which case this boolean is not returned. Range checking is still performed internally however, i.e., zero is still returned if the rational is out of range.

Note that "lies with double's allowable range" is machine-dependent, and may vary between different installations. Infinity and undefined are always considered out of range. Otherwise a rational is out of range if its absolute value is finite but too large (e.g., 10^10000) or non-zero but too small (e.g., 10^-10000).

Parameters

  inRange | returns the result of range checking as described above; this pointer may be passed as `null` if the caller does not care about this result.

Returns
  the double approximation to this rational, or zero if this rational lies outside double's allowable range.

Python:
  The inRange argument is not present. Instead there are two versions of this routine. The first is doubleApprox(), which returns a single real number. The second is doubleApproxCheck(), which returns a (real, bool) pair containing the converted real number followed by the result of range checking.

Author
  Ryan Budney, B.B.

## inverse()

Rational regina::Rational::inverse | ( |  | ) | const

Calculates the inverse of this rational.

This rational is not changed.

Returns
  the inverse 1 / this.

## invert()

void regina::Rational::invert | ( |  | ) |

Inverts this rational.

This rational is changed to reflect the result.

## negate()

void regina::Rational::negate | ( |  | ) |

inline

Negates this rational.

This rational is changed to reflect the result.

## numerator()

Integer regina::Rational::numerator | ( |  | ) | const

Returns the numerator of this rational.

Note that rationals are always stored in lowest terms with non-negative denominator. Infinity will be stored as 1/0.

Returns
  the numerator.

## operator!=()

bool regina::Rational::operator!= | ( | const Rational & | compare | ) | const

inline

Determines if this is not equal to the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is not equal to compare.

## operator*()

Rational regina::Rational::operator* | ( | const Rational & | r | ) | const

Calculates the product of two rationals.

This rational is not changed.

Parameters

  r | the rational with which to multiply this.

Returns
  the product this * r.

## operator*=()

Rational& regina::Rational::operator*= | ( | const Rational & | other | ) |

Multiplies the given rational by this.

This rational is changed to reflect the result.

Parameters

  other | the rational to multiply by this.

Returns
  a reference to this rational with its new value.

## operator+()

Rational regina::Rational::operator+ | ( | const Rational & | r | ) | const

Calculates the sum of two rationals.

This rational is not changed.

Parameters

  r | the rational to add to this.

Returns
  the sum this + r.

## operator+=()

Rational& regina::Rational::operator+= | ( | const Rational & | other | ) |

Adds the given rational to this.

This rational is changed to reflect the result.

Parameters

  other | the rational to add to this.

Returns
  a reference to this rational with its new value.

## operator-() [1/2]

Rational regina::Rational::operator- | ( | const Rational & | r | ) | const

Calculates the difference of two rationals.

This rational is not changed.

Parameters

  r | the rational to subtract from this.

Returns
  the difference this - r.

## operator-() [2/2]

Rational regina::Rational::operator- | ( |  | ) | const

Determines the negative of this rational.

This rational is not changed.

Returns
  the negative of this rational.

## operator-=()

Rational& regina::Rational::operator-= | ( | const Rational & | other | ) |

Subtracts the given rational from this.

This rational is changed to reflect the result.

Parameters

  other | the rational to subtract from this.

Returns
  a reference to this rational with its new value.

## operator/()

Rational regina::Rational::operator/ | ( | const Rational & | r | ) | const

Calculates the ratio of two rationals.

This rational is not changed.

Parameters

  r | the rational to divide this by.

Returns
  the ratio this / r.

## operator/=()

Rational& regina::Rational::operator/= | ( | const Rational & | other | ) |

Divides this by the given rational.

This rational is changed to reflect the result.

Parameters

  other | the rational to divide this by.

Returns
  a reference to this rational with its new value.

## operator<()

bool regina::Rational::operator< | ( | const Rational & | compare | ) | const

Determines if this is less than the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is less than compare.

## operator<=()

bool regina::Rational::operator<= | ( | const Rational & | compare | ) | const

inline

Determines if this is less than or equal to the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is less than or equal to compare.

## operator=() [1/3]

Rational & regina::Rational::operator= | ( | const Rational & | value | ) |

inline

Sets this rational to the given rational value.

Parameters

  value | the new value of this rational.

Returns
  a reference to this rational with its new value.

## operator=() [2/3]

template<bool supportInfinity>

Rational & regina::Rational::operator= | ( | const IntegerBase< supportInfinity > & | value | ) |

inline

Sets this rational to the given integer value.

The given integer may be infinite.

Parameters

  value | the new value of this rational.

Returns
  a reference to this rational with its new value.

## operator=() [3/3]

Rational & regina::Rational::operator= | ( | long | value | ) |

inline

Sets this rational to the given integer value.

Parameters

  value | the new value of this rational.

Returns
  a reference to this rational with its new value.

## operator==()

bool regina::Rational::operator== | ( | const Rational & | compare | ) | const

Determines if this is equal to the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is equal to compare.

## operator>()

bool regina::Rational::operator> | ( | const Rational & | compare | ) | const

Determines if this is greater than the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is greater than compare.

## operator>=()

bool regina::Rational::operator>= | ( | const Rational & | compare | ) | const

inline

Determines if this is greater than or equal to the given rational.

Parameters

  compare | the rational with which this will be compared.

Returns
  `true` if and only if this rational is greater than or equal to compare.

## swap()

void regina::Rational::swap | ( | Rational & | other | ) |

inline

Swaps the values of this and the given rational.

Parameters

  other | the rational whose value will be swapped with this.

## TeX()

std::string regina::Rational::TeX | ( |  | ) | const

Returns this rational as written using TeX formatting.

No leading or trailing dollar signs will be included.

Returns
  this rational as written using TeX formatting.

Author
  Ryan Budney

## writeTeX()

std::ostream& regina::Rational::writeTeX | ( | std::ostream & | out | ) | const

Writes this rational in TeX format to the given output stream.

No leading or trailing dollar signs will be included.

Python:
  The parameter out does not exist; instead standard output will always be used. Moreover, this routine returns `None`.

Parameters

  out | the output stream to which to write.

Returns
  a reference to the given output stream.

Author
  Ryan Budney

## Friends And Related Function Documentation

## operator<<

std::ostream& operator<< | ( | std::ostream & | out,
|  | const Rational & | rat
| ) |  |

friend

Writes the given rational to the given output stream.

Infinity will be written as `Inf`. Undefined will be written as `Undef`. A rational with denominator one will be written as a single integer. All other rationals will be written in the form `r/s`.

Parameters

  out | the output stream to which to write.
  rat | the rational to write.

Returns
  a reference to out.

## Member Data Documentation

## infinity

const Rational regina::Rational::infinity

static

Globally available infinity.

Note that both 1/0 and -1/0 evaluate to this same rational. When queried, the representation 1/0 will be returned.

## one

const Rational regina::Rational::one

static

Globally available one.

## undefined

const Rational regina::Rational::undefined

static

Globally available undefined.

This is represented as 0/0.

## zero

const Rational regina::Rational::zero

static

Globally available zero.

The documentation for this class was generated from the following file:

- maths/rational.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).