Regina Calculation Engine
Public Member Functions | Static Public Attributes | Friends | List of all members
regina::NRational Class Reference

Represents an arbitrary precision rational number. More...

#include <maths/nrational.h>

Public Member Functions

 NRational ()
 Initialises to 0/1. More...
 
 NRational (const NRational &value)
 Initialises to the given rational value. More...
 
template<bool supportInfinity>
 NRational (const NIntegerBase< supportInfinity > &value)
 Initialises to the given integer value. More...
 
 NRational (long value)
 Initialises to the given integer value. More...
 
template<bool supportInfinity>
 NRational (const NIntegerBase< supportInfinity > &newNum, const NIntegerBase< supportInfinity > &newDen)
 Initialises to newNum/newDen. More...
 
 NRational (long newNum, unsigned long newDen)
 Initialises to newNum/newDen. More...
 
virtual ~NRational ()
 Destroys this rational. More...
 
NRationaloperator= (const NRational &value)
 Sets this rational to the given rational value. More...
 
template<bool supportInfinity>
NRationaloperator= (const NIntegerBase< supportInfinity > &value)
 Sets this rational to the given integer value. More...
 
NRationaloperator= (long value)
 Sets this rational to the given integer value. More...
 
void swap (NRational &other)
 Swaps the values of this and the given rational. More...
 
NInteger getNumerator () const
 Returns the numerator of this rational. More...
 
NInteger getDenominator () const
 Returns the denominator of this rational. More...
 
NRational operator* (const NRational &r) const
 Calculates the product of two rationals. More...
 
NRational operator/ (const NRational &r) const
 Calculates the ratio of two rationals. More...
 
NRational operator+ (const NRational &r) const
 Calculates the sum of two rationals. More...
 
NRational operator- (const NRational &r) const
 Calculates the difference of two rationals. More...
 
NRational operator- () const
 Determines the negative of this rational. More...
 
NRational inverse () const
 Calculates the inverse of this rational. More...
 
NRational abs () const
 Determines the absolute value of this rational. More...
 
NRationaloperator+= (const NRational &other)
 Adds the given rational to this. More...
 
NRationaloperator-= (const NRational &other)
 Subtracts the given rational from this. More...
 
NRationaloperator*= (const NRational &other)
 Multiplies the given rational by this. More...
 
NRationaloperator/= (const NRational &other)
 Divides this by the given rational. More...
 
void negate ()
 Negates this rational. More...
 
void invert ()
 Inverts this rational. More...
 
bool operator== (const NRational &compare) const
 Determines if this is equal to the given rational. More...
 
bool operator!= (const NRational &compare) const
 Determines if this is not equal to the given rational. More...
 
bool operator< (const NRational &compare) const
 Determines if this is less than the given rational. More...
 
bool operator> (const NRational &compare) const
 Determines if this is greater than the given rational. More...
 
bool operator<= (const NRational &compare) const
 Determines if this is less than or equal to the given rational. More...
 
bool operator>= (const NRational &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 getTeX () 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 NRational zero
 Globally available zero. More...
 
static const NRational one
 Globally available one. More...
 
static const NRational infinity
 Globally available infinity. More...
 
static const NRational undefined
 Globally available undefined. More...
 

Friends

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

Detailed Description

Represents an arbitrary precision rational number.

Calculations with NRational 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.

Rationals will always be stored in lowest terms (i.e., with relatively prime numerator and denominator), and with a non-negative denominator.

Constructor & Destructor Documentation

regina::NRational::NRational ( )
inline

Initialises to 0/1.

regina::NRational::NRational ( const NRational value)
inline

Initialises to the given rational value.

Parameters
valuethe new rational value of this rational.
template<bool supportInfinity>
regina::NRational::NRational ( const NIntegerBase< supportInfinity > &  value)
inline

Initialises to the given integer value.

The given integer may be infinite.

Parameters
valuethe new integer value of this rational.
regina::NRational::NRational ( long  value)
inline

Initialises to the given integer value.

Parameters
valuethe new integer value of this rational.
template<bool supportInfinity>
regina::NRational::NRational ( const NIntegerBase< supportInfinity > &  newNum,
const NIntegerBase< 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, NRational(4,4) (which breaks the gcd requirement) is considered different from NRational(1,1) (a valid rational), which is different again from NRational(-1,-1) (which breaks the non-negativity requirement).
Precondition
Neither of the given integers is infinite.
Parameters
newNumthe new numerator.
newDenthe new denominator.
regina::NRational::NRational ( 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, NRational(4,4) (which breaks the gcd requirement) is considered different from NRational(1,1) (a valid rational), which is different again from NRational(-1,-1) (which breaks the non-negativity requirement).
Parameters
newNumthe new numerator.
newDenthe new denominator.
regina::NRational::~NRational ( )
inlinevirtual

Destroys this rational.

Member Function Documentation

NRational regina::NRational::abs ( ) const

Determines the absolute value of this rational.

This rational is not changed.

Returns
the absolute value of this rational.
double regina::NRational::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
inRangereturns 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.
NInteger regina::NRational::getDenominator ( ) 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.
NInteger regina::NRational::getNumerator ( ) 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.
std::string regina::NRational::getTeX ( ) 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
NRational regina::NRational::inverse ( ) const

Calculates the inverse of this rational.

This rational is not changed.

Returns
the inverse 1 / this.
void regina::NRational::invert ( )

Inverts this rational.

This rational is changed to reflect the result.

void regina::NRational::negate ( )
inline

Negates this rational.

This rational is changed to reflect the result.

bool regina::NRational::operator!= ( const NRational compare) const
inline

Determines if this is not equal to the given rational.

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is not equal to compare.
NRational regina::NRational::operator* ( const NRational r) const

Calculates the product of two rationals.

This rational is not changed.

Parameters
rthe rational with which to multiply this.
Returns
the product this * r.
NRational& regina::NRational::operator*= ( const NRational other)

Multiplies the given rational by this.

This rational is changed to reflect the result.

Parameters
otherthe rational to multiply by this.
Returns
a reference to this rational with its new value.
NRational regina::NRational::operator+ ( const NRational r) const

Calculates the sum of two rationals.

This rational is not changed.

Parameters
rthe rational to add to this.
Returns
the sum this + r.
NRational& regina::NRational::operator+= ( const NRational other)

Adds the given rational to this.

This rational is changed to reflect the result.

Parameters
otherthe rational to add to this.
Returns
a reference to this rational with its new value.
NRational regina::NRational::operator- ( const NRational r) const

Calculates the difference of two rationals.

This rational is not changed.

Parameters
rthe rational to subtract from this.
Returns
the difference this - r.
NRational regina::NRational::operator- ( ) const

Determines the negative of this rational.

This rational is not changed.

Returns
the negative of this rational.
NRational& regina::NRational::operator-= ( const NRational other)

Subtracts the given rational from this.

This rational is changed to reflect the result.

Parameters
otherthe rational to subtract from this.
Returns
a reference to this rational with its new value.
NRational regina::NRational::operator/ ( const NRational r) const

Calculates the ratio of two rationals.

This rational is not changed.

Parameters
rthe rational to divide this by.
Returns
the ratio this / r.
NRational& regina::NRational::operator/= ( const NRational other)

Divides this by the given rational.

This rational is changed to reflect the result.

Parameters
otherthe rational to divide this by.
Returns
a reference to this rational with its new value.
bool regina::NRational::operator< ( const NRational compare) const

Determines if this is less than the given rational.

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is less than compare.
bool regina::NRational::operator<= ( const NRational compare) const
inline

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

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is less than or equal to compare.
NRational & regina::NRational::operator= ( const NRational value)
inline

Sets this rational to the given rational value.

Parameters
valuethe new value of this rational.
Returns
a reference to this rational with its new value.
template<bool supportInfinity>
NRational & regina::NRational::operator= ( const NIntegerBase< supportInfinity > &  value)
inline

Sets this rational to the given integer value.

The given integer may be infinite.

Parameters
valuethe new value of this rational.
Returns
a reference to this rational with its new value.
NRational & regina::NRational::operator= ( long  value)
inline

Sets this rational to the given integer value.

Parameters
valuethe new value of this rational.
Returns
a reference to this rational with its new value.
bool regina::NRational::operator== ( const NRational compare) const

Determines if this is equal to the given rational.

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is equal to compare.
bool regina::NRational::operator> ( const NRational compare) const

Determines if this is greater than the given rational.

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is greater than compare.
bool regina::NRational::operator>= ( const NRational compare) const
inline

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

Parameters
comparethe rational with which this will be compared.
Returns
true if and only if this rational is greater than or equal to compare.
void regina::NRational::swap ( NRational other)
inline

Swaps the values of this and the given rational.

Parameters
otherthe rational whose value will be swapped with this.
std::ostream& regina::NRational::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 be used.
Parameters
outthe output stream to which to write.
Returns
a reference to the given output stream.
Author
Ryan Budney

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  out,
const NRational 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
outthe output stream to which to write.
ratthe rational to write.
Returns
a reference to out.

Member Data Documentation

const NRational regina::NRational::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.

const NRational regina::NRational::one
static

Globally available one.

const NRational regina::NRational::undefined
static

Globally available undefined.

This is represented as 0/0.

const NRational regina::NRational::zero
static

Globally available zero.


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

Copyright © 1999-2014, 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@debian.org).