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...

	Rational (Rational &&src) noexcept
	Moves the given rational into this new rational. 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...

Rational &	operator= (Rational &&src) noexcept
	Moves the given rational into this rational. More...

void	swap (Rational &other) noexcept
	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 () 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::string	TeX () const
	Deprecated routine that 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.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Constructor & Destructor Documentation

◆ Rational() [1/7]

regina::Rational::Rational ( )

inline

Initialises to 0/1.

◆ Rational() [2/7]

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

inline

Initialises to the given rational value.

Parameters

value the new rational value of this rational.

◆ Rational() [3/7]

regina::Rational::Rational ( Rational && src )

inlinenoexcept

Moves the given rational into this new rational.

This is a fast (constant time) operation.

The rational that is passed (src) will no longer be usable.

Parameters

src	the rational to move.

◆ Rational() [4/7]

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() [5/7]

regina::Rational::Rational ( long value )

inline

Initialises to the given integer value.

Parameters

value the new integer value of this rational.

◆ Rational() [6/7]

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() [7/7]

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 ( ) 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 this routine will throw an exception.

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).

Exceptions

UnsolvedCase This rational lies outside double's allowable range.

Python: The old python-only routine doubleApproxCheck() is now deprecated. Just call this routine inside a try/catch block.

Returns: the double approximation to this rational.

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

Determines the negative of this rational.

This rational is not changed.

Returns: the negative of this rational.

◆ operator-() [2/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-=()

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/4]

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=() [2/4]

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=() [3/4]

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=() [4/4]

Rational & regina::Rational::operator= ( Rational && src )

inlinenoexcept

Moves the given rational into this rational.

This is a fast (constant time) operation.

The rational that is passed (src) will no longer be usable.

Parameters

src	the rational to move.

Returns: a reference to this rational.

◆ 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 )

inlinenoexcept

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

◆ TeX()

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

inline

Deprecated routine that returns this rational as written using TeX formatting.

Deprecated:: This routine has been renamed to tex().

Returns: this rational as written using TeX formatting.

◆ 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: Not present; instead use the variant tex() that takes no arguments and returns a string.

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

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Rational() [1/7]

◆ Rational() [2/7]

◆ Rational() [3/7]

◆ Rational() [4/7]

◆ Rational() [5/7]

◆ Rational() [6/7]

◆ Rational() [7/7]

◆ ~Rational()

Member Function Documentation

◆ abs()

◆ denominator()

◆ doubleApprox()

◆ inverse()

◆ invert()

◆ negate()

◆ numerator()

◆ operator!=()

◆ operator*()

◆ operator*=()

◆ operator+()

◆ operator+=()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator-=()

◆ operator/()

◆ operator/=()

◆ operator<()

◆ operator<=()

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ operator==()

◆ operator>()

◆ operator>=()

◆ swap()

◆ tex()

◆ TeX()

◆ writeTeX()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ infinity

◆ one

◆ undefined

◆ zero