regina::NLargeInteger Class Reference
[Mathematical Support]

Represents an arbitrary precision integer. More...

#include <nlargeinteger.h>

List of all members.

Public Member Functions

 NLargeInteger ()
 Initialises this integer to zero.
 NLargeInteger (long value)
 Initialises this integer to the given value.
 NLargeInteger (const NLargeInteger &value)
 Initialises this integer to the given value.
 NLargeInteger (const char *value, int base=10, bool *valid=0)
 Initialises this integer to the given value which is represented as a string of digits in a given base.
 NLargeInteger (const std::string &value, int base=10, bool *valid=0)
 Initialises this integer to the given value which is represented as a string of digits in a given base.
virtual ~NLargeInteger ()
 Destroys this integer.
bool isInfinite () const
 Determines if this large integer is infinity.
long longValue () const
 Returns the value of this integer as a long.
std::string stringValue (int base=10) const
 Returns the value of this integer as a string in the given base.
NLargeIntegeroperator= (const NLargeInteger &value)
 Sets this integer to the given value.
NLargeIntegeroperator= (long value)
 Sets this integer to the given value.
NLargeIntegeroperator= (const char *value)
 Sets this integer to the given value which is represented as a string of digits in base 10.
NLargeIntegeroperator= (const std::string &value)
 Sets this integer to the given value which is represented as a string of digits in base 10.
void swap (NLargeInteger &other)
 Swaps the values of this and the given integer.
bool operator== (const NLargeInteger &compareTo) const
 Determines if this is equal to the given integer.
bool operator== (long compareTo) const
 Determines if this is equal to the given integer.
bool operator!= (const NLargeInteger &compareTo) const
 Determines if this is not equal to the given integer.
bool operator!= (long compareTo) const
 Determines if this is not equal to the given integer.
bool operator< (const NLargeInteger &compareTo) const
 Determines if this is less than the given integer.
bool operator< (long compareTo) const
 Determines if this is less than the given integer.
bool operator> (const NLargeInteger &compareTo) const
 Determines if this is greater than the given integer.
bool operator> (long compareTo) const
 Determines if this is greater than the given integer.
bool operator<= (const NLargeInteger &compareTo) const
 Determines if this is less than or equal to the given integer.
bool operator<= (long compareTo) const
 Determines if this is less than or equal to the given integer.
bool operator>= (const NLargeInteger &compareTo) const
 Determines if this is greater than or equal to the given integer.
bool operator>= (long compareTo) const
 Determines if this is greater than or equal to the given integer.
NLargeInteger operator+ (const NLargeInteger &other) const
 Adds this to the given integer and returns the result.
NLargeInteger operator- (const NLargeInteger &other) const
 Subtracts the given integer from this and returns the result.
NLargeInteger operator* (const NLargeInteger &other) const
 Multiplies this by the given integer and returns the result.
NLargeInteger operator/ (const NLargeInteger &other) const
 Divides this by the given integer and returns the result.
NLargeInteger divExact (const NLargeInteger &other) const
 Divides this by the given integer and returns the result.
NLargeInteger operator% (const NLargeInteger &other) const
 Determines the remainder when this integer is divided by the given integer.
NLargeInteger divisionAlg (const NLargeInteger &divisor, NLargeInteger &remainder) const
 Uses the division algorithm to obtain a quotient and remainder when dividing by the given integer.
NLargeInteger operator- () const
 Determines the negative of this integer.
NLargeIntegeroperator+= (const NLargeInteger &other)
 Adds the given integer to this.
NLargeIntegeroperator+= (long other)
 Adds the given integer to this.
NLargeIntegeroperator-= (const NLargeInteger &other)
 Subtracts the given integer from this.
NLargeIntegeroperator-= (long other)
 Subtracts the given integer from this.
NLargeIntegeroperator*= (const NLargeInteger &other)
 Multiplies the given integer by this.
NLargeIntegeroperator/= (const NLargeInteger &other)
 Divides this by the given integer.
NLargeIntegerdivByExact (const NLargeInteger &other)
 Divides this by the given integer.
NLargeIntegeroperator%= (const NLargeInteger &other)
 Reduces this integer modulo the given integer.
void negate ()
 Negates this integer.
void raiseToPower (unsigned long exp)
 Raises this integer to the power of the given exponent.
NLargeInteger abs () const
 Determines the absolute value of this integer.
NLargeInteger gcd (const NLargeInteger &other) const
 Determines the greatest common divisor of this and the given integer.
NLargeInteger lcm (const NLargeInteger &other) const
 Determines the lowest common multiple of this and the given integer.
NLargeInteger gcdWithCoeffs (const NLargeInteger &other, NLargeInteger &u, NLargeInteger &v) const
 Determines the greatest common divisor of this and the given integer and finds the smallest coefficients with which these integers combine to give their gcd.
int legendre (const NLargeInteger &p) const
 Returns the Legendre symbol (a/p), where a is this integer and p is an odd prime.

Static Public Attributes

static const NLargeInteger zero
 Globally available zero.
static const NLargeInteger one
 Globally available one.
static const NLargeInteger infinity
 Globally available infinity.

Friends

class NPrimes
 Allow access to private members.
class NRational
 Allow access to private members.
std::ostream & operator<< (std::ostream &out, const NLargeInteger &large)
 Writes the given integer to the given output stream.


Detailed Description

Represents an arbitrary precision integer.

Calculations will be exact no matter how large the integers become. Current algorithms and representations use the GNU multiple precision arithmetic library.

Infinity is catered for. For comparison operations, infinity is considered larger than any other integer but equal to itself.

Test:
Tested in the test suite, though not exhaustively.

Constructor & Destructor Documentation

regina::NLargeInteger::NLargeInteger (  )  [inline]

Initialises this integer to zero.

regina::NLargeInteger::NLargeInteger ( long  value  )  [inline]

Initialises this integer to the given value.

Parameters:
value the new value of this integer.

regina::NLargeInteger::NLargeInteger ( const NLargeInteger value  )  [inline]

Initialises this integer to the given value.

Parameters:
value the new value of this integer.

regina::NLargeInteger::NLargeInteger ( const char *  value,
int  base = 10,
bool *  valid = 0 
) [inline]

Initialises this integer to the given value which is represented as a string of digits in a given base.

If not specified, the base defaults to 10. If the given base is zero, the base will be automatically determined. If the given string begins with 0x or 0X, the base will be assumed to be 16. Otherwise, if the string begins with 0, the base will be assumed to be 8. Otherwise it will be taken as base 10.

Whitespace may be present in the given string and will simply be ignored.

Error detection is possible by passing a non-null boolean pointer as the third parameter to this constructor.

Precondition:
The given base is zero, or is between 2 and 36 inclusive.

The given string represents a finite integer in the given base, with optional whitespace added.

Python:
The final parameter valid is not present.
Parameters:
value the new value of this integer, represented as a string of digits in base base.
base the base in which value is given.
valid if this pointer is not null, the boolean referenced will be set to true if the entire given string was a valid large integer representation and false otherwise.

regina::NLargeInteger::NLargeInteger ( const std::string &  value,
int  base = 10,
bool *  valid = 0 
) [inline]

Initialises this integer to the given value which is represented as a string of digits in a given base.

If not specified, the base defaults to 10. If the given base is zero, the base will be automatically determined. If the given string begins with 0x or 0X, the base will be assumed to be 16. Otherwise, if the string begins with 0, the base will be assumed to be 8. Otherwise it will be taken as base 10.

Whitespace may be present in the given string and will simply be ignored.

Error detection is possible by passing a non-null boolean pointer as the third parameter to this constructor.

Precondition:
The given base is zero, or is between 2 and 36 inclusive.

The given string represents a finite integer in the given base, with optional whitespace added.

Python:
The final parameter valid is not present.
Parameters:
value the new value of this integer, represented as a string of digits in base base.
base the base in which value is given.
valid if this pointer is not null, the boolean referenced will be set to true if the entire given string was a valid large integer representation and false otherwise.

regina::NLargeInteger::~NLargeInteger (  )  [inline, virtual]

Destroys this integer.


Member Function Documentation

NLargeInteger regina::NLargeInteger::abs (  )  const [inline]

Determines the absolute value of this integer.

This integer is not changed.

Returns:
the absolute value of this integer.

NLargeInteger & regina::NLargeInteger::divByExact ( const NLargeInteger other  )  [inline]

Divides this by the given integer.

This can only be used when the given integer divides into this exactly, and is much faster than ordinary division. This integer is changed to reflect the result.

Precondition:
The given integer divides exactly into this integer, i.e. this divided by other is an integer.

other is not zero.

Neither this nor other is infinite.

Parameters:
other the integer to divide this by.
Returns:
a reference to this integer with its new value.

NLargeInteger regina::NLargeInteger::divExact ( const NLargeInteger other  )  const [inline]

Divides this by the given integer and returns the result.

This can only be used when the given integer divides into this exactly, and is much faster than ordinary division. This integer is not changed.

Precondition:
The given integer divides exactly into this integer, i.e. this divided by other is an integer.

other is not zero.

Neither this nor other is infinite.

Parameters:
other the integer to divide this by.
Returns:
the quotient this divided by other.

NLargeInteger regina::NLargeInteger::divisionAlg ( const NLargeInteger divisor,
NLargeInteger remainder 
) const

Uses the division algorithm to obtain a quotient and remainder when dividing by the given integer.

Suppose this integer is n and we pass the divisor d. The division algorithm describes the result of dividing n by d; in particular, it expresses n = qd + r, where q is the quotient and r is the remainder.

The division algorithm is precise about which values of q and r are chosen; in particular it chooses the unique r in the range 0 <= r < |d|.

Note that this differs from other division routines in this class, in that it always rounds to give a non-negative remainder. Thus NLargeInteger(-7).divisionAlg(3) gives quotient -3 and remainder 2, whereas (-7)/3 gives quotient -2 and (-7)%3 gives remainder -1.

The two results are passed back to the caller as follows: The quotient q is passed back as the return value of the function, and the remainder r is stored in the reference argument r.

In the special case where the given divisor is 0 (not allowed by the usual division algorithm), this routine selects quotient 0 and remainder n.

Precondition:
Neither this nor the divisor are infinite.
Python:
The argument r is missing; instead both the quotient and remainder are passed back through the return value of the function. Specifically, this function returns a (q, r) pair.
Parameters:
divisor the divisor d.
remainder used to store the remainder r when the functon returns. The initial value of this argument is ignored.
Returns:
the quotient q.
Author:
Ryan Budney, B.B.

NLargeInteger regina::NLargeInteger::gcd ( const NLargeInteger other  )  const [inline]

Determines the greatest common divisor of this and the given integer.

This integer is not changed.

Note that the result might possibly be negative. As a special case, gcd(0,0) is considered to be zero.

Precondition:
Neither this integer nor other is infinite.
Parameters:
other the integer whose greatest common divisor with this will be found.
Returns:
the greatest common divisor of this and the given integer.

NLargeInteger regina::NLargeInteger::gcdWithCoeffs ( const NLargeInteger other,
NLargeInteger u,
NLargeInteger v 
) const

Determines the greatest common divisor of this and the given integer and finds the smallest coefficients with which these integers combine to give their gcd.

Note that the given integers need not be non-negative. However, the gcd returned is guaranteed to be non-negative.

If d is the gcd of this and other, the values placed into u and v will be those for which u*this + v*other = d, -abs(this)/d < v*sign(other) <= 0 and 1 <= u*sign(this) <= abs(other)/d. These equations are not satisfied when either of this or other are zero, but in this case u and v are both 0, 1 or -1, using as many zeros as possible.

Precondition:
Neither this integer nor other is infinite.
Parameters:
other the integer whose greatest common divisor with this will be found.
u a variable into which the final coefficient of this will be placed.
v a variable into which the final coefficient of other will be placed.
Returns:
the greatest common divisor of this and other.

bool regina::NLargeInteger::isInfinite (  )  const [inline]

Determines if this large integer is infinity.

Returns:
true if and only if this large integer is infinity.

NLargeInteger regina::NLargeInteger::lcm ( const NLargeInteger other  )  const [inline]

Determines the lowest common multiple of this and the given integer.

This integer is not changed.

Note that the result might possibly be negative.

Precondition:
Neither this integer nor other is infinite.
Parameters:
other the integer whose lowest common multiple with this will be found.
Returns:
the lowest common multiple of this and the given integer.

int regina::NLargeInteger::legendre ( const NLargeInteger p  )  const [inline]

Returns the Legendre symbol (a/p), where a is this integer and p is an odd prime.

The Legendre symbol is equal to 0 if this integer is divisible by p, 1 if this integer is congruent to a square mod p (but not divisible by p), and -1 otherwise.

Precondition:
The given integer p is an odd positive prime.
Parameters:
p the given odd prime.
Returns:
The Legendre symbol (0, 1 or -1) as described above.
Author:
Ryan Budney

long regina::NLargeInteger::longValue (  )  const [inline]

Returns the value of this integer as a long.

If this integer is outside the range of a long, the result is unpredictable.

Precondition:
This integer is not infinity.
Returns:
the value of this integer.

void regina::NLargeInteger::negate (  )  [inline]

Negates this integer.

This integer is changed to reflect the result.

Negating infinity will result in infinity.

bool regina::NLargeInteger::operator!= ( long  compareTo  )  const [inline]

Determines if this is not equal to the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this and the given integer are not equal.

bool regina::NLargeInteger::operator!= ( const NLargeInteger compareTo  )  const [inline]

Determines if this is not equal to the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this and the given integer are not equal.

NLargeInteger regina::NLargeInteger::operator% ( const NLargeInteger other  )  const [inline]

Determines the remainder when this integer is divided by the given integer.

If non-zero, the result will have the same sign as this integer. This integer is not changed.

For a division routine that always returns a non-negative remainder, see divisionAlg().

Precondition:
other is not zero.

Neither this nor other is infinite.

Parameters:
other the integer to divide this by.
Returns:
the remainder this modulo other.

NLargeInteger & regina::NLargeInteger::operator%= ( const NLargeInteger other  )  [inline]

Reduces this integer modulo the given integer.

If non-zero, the result will have the same sign as the original value of this integer. This integer is changed to reflect the result.

For a mod routine that always returns a non-negative remainder, see divisionAlg().

Precondition:
other is not zero.

Neither this nor other is infinite.

Parameters:
other the integer modulo which this integer will be reduced.
Returns:
a reference to this integer with its new value.

NLargeInteger regina::NLargeInteger::operator* ( const NLargeInteger other  )  const [inline]

Multiplies this by the given integer and returns the result.

This integer is not changed.

If either factor of the product is infinite, the result will be infinity.

Parameters:
other the integer to multiply by this integer.
Returns:
the product this times other.

NLargeInteger & regina::NLargeInteger::operator*= ( const NLargeInteger other  )  [inline]

Multiplies the given integer by this.

This integer is changed to reflect the result.

If either factor of the product is infinite, the result will be infinity.

Parameters:
other the integer to multiply with this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger regina::NLargeInteger::operator+ ( const NLargeInteger other  )  const [inline]

Adds this to the given integer and returns the result.

This integer is not changed.

If either term of the sum is infinite, the result will be infinity.

Parameters:
other the integer to add to this integer.
Returns:
the sum this plus other.

NLargeInteger & regina::NLargeInteger::operator+= ( long  other  )  [inline]

Adds the given integer to this.

This integer is changed to reflect the result.

If either term of the sum is infinite, the result will be infinity.

Parameters:
other the integer to add to this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger & regina::NLargeInteger::operator+= ( const NLargeInteger other  )  [inline]

Adds the given integer to this.

This integer is changed to reflect the result.

If either term of the sum is infinite, the result will be infinity.

Parameters:
other the integer to add to this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger regina::NLargeInteger::operator- (  )  const [inline]

Determines the negative of this integer.

This integer is not changed.

Negating infinity will return infinity.

Returns:
the negative of this integer.

NLargeInteger regina::NLargeInteger::operator- ( const NLargeInteger other  )  const [inline]

Subtracts the given integer from this and returns the result.

This integer is not changed.

If either term of the difference is infinite, the result will be infinity.

Parameters:
other the integer to subtract from this integer.
Returns:
the difference this minus other.

NLargeInteger & regina::NLargeInteger::operator-= ( long  other  )  [inline]

Subtracts the given integer from this.

This integer is changed to reflect the result.

If either term of the difference is infinite, the result will be infinity.

Parameters:
other the integer to subtract from this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger & regina::NLargeInteger::operator-= ( const NLargeInteger other  )  [inline]

Subtracts the given integer from this.

This integer is changed to reflect the result.

If either term of the difference is infinite, the result will be infinity.

Parameters:
other the integer to subtract from this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger regina::NLargeInteger::operator/ ( const NLargeInteger other  )  const [inline]

Divides this by the given integer and returns the result.

The result will be truncated to an integer, i.e. rounded towards zero. This integer is not changed.

If other is known to divide this integer exactly, divExact() should be used instead.

Infinity divided by anything will return infinity; anything finite divided by infinity will return zero; anything finite divided by zero will return infinity.

For a division routine that always rounds down, see divisionAlg().

Parameters:
other the integer to divide this by.
Returns:
the quotient this divided by other.

NLargeInteger & regina::NLargeInteger::operator/= ( const NLargeInteger other  )  [inline]

Divides this by the given integer.

The result will be truncated to an integer, i.e. rounded towards zero. This integer is changed to reflect the result.

If other is known to divide this integer exactly, divByExact() should be used instead.

Infinity divided by anything will return infinity; anything finite divided by infinity will return zero; anything finite divided by zero will return infinity.

For a division routine that always rounds down, see divisionAlg().

Parameters:
other the integer to divide this by.
Returns:
a reference to this integer with its new value.

bool regina::NLargeInteger::operator< ( long  compareTo  )  const [inline]

Determines if this is less than the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is less than the given integer.

bool regina::NLargeInteger::operator< ( const NLargeInteger compareTo  )  const [inline]

Determines if this is less than the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is less than the given integer.

bool regina::NLargeInteger::operator<= ( long  compareTo  )  const [inline]

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

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is less than or equal to the given integer.

bool regina::NLargeInteger::operator<= ( const NLargeInteger compareTo  )  const [inline]

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

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is less than or equal to the given integer.

NLargeInteger & regina::NLargeInteger::operator= ( const std::string &  value  )  [inline]

Sets this integer to the given value which is represented as a string of digits in base 10.

Whitespace may be present in the given string and will simply be ignored.

Precondition:
The given string represents an integer in base 10, with optional whitespace added.
Parameters:
value the new value of this integer, represented as a string of digits in base 10.
Returns:
a reference to this integer with its new value.

NLargeInteger & regina::NLargeInteger::operator= ( const char *  value  )  [inline]

Sets this integer to the given value which is represented as a string of digits in base 10.

Whitespace may be present in the given string and will simply be ignored.

Precondition:
The given string represents an integer in base 10, with optional whitespace added.
Parameters:
value the new value of this integer, represented as a string of digits in base 10.
Returns:
a reference to this integer with its new value.

NLargeInteger & regina::NLargeInteger::operator= ( long  value  )  [inline]

Sets this integer to the given value.

Parameters:
value the new value of this integer.
Returns:
a reference to this integer with its new value.

NLargeInteger & regina::NLargeInteger::operator= ( const NLargeInteger value  )  [inline]

Sets this integer to the given value.

Parameters:
value the new value of this integer.
Returns:
a reference to this integer with its new value.

bool regina::NLargeInteger::operator== ( long  compareTo  )  const [inline]

Determines if this is equal to the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this and the given integer are equal.

bool regina::NLargeInteger::operator== ( const NLargeInteger compareTo  )  const [inline]

Determines if this is equal to the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this and the given integer are equal.

bool regina::NLargeInteger::operator> ( long  compareTo  )  const [inline]

Determines if this is greater than the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is greater than the given integer.

bool regina::NLargeInteger::operator> ( const NLargeInteger compareTo  )  const [inline]

Determines if this is greater than the given integer.

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is greater than the given integer.

bool regina::NLargeInteger::operator>= ( long  compareTo  )  const [inline]

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

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is greater than or equal to the given integer.

bool regina::NLargeInteger::operator>= ( const NLargeInteger compareTo  )  const [inline]

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

Parameters:
compareTo the integer with which this will be compared.
Returns:
true if and only if this is greater than or equal to the given integer.

void regina::NLargeInteger::raiseToPower ( unsigned long  exp  )  [inline]

Raises this integer to the power of the given exponent.

This integer is changed to reflect the result.

Note that 0 to the power of 0 will be 1, infinity to the power of 0 will be 1, and infinity to the power of anything else will be infinity.

Precondition:
The given exponent is non-negative.
Parameters:
exp the power to which this integer will be raised.

std::string regina::NLargeInteger::stringValue ( int  base = 10  )  const

Returns the value of this integer as a string in the given base.

If not specified, the base defaults to 10.

If this integer is infinity, the string returned will be inf.

Precondition:
The given base is between 2 and 36 inclusive.
Returns:
the value of this integer as a newly allocated string.

void regina::NLargeInteger::swap ( NLargeInteger other  )  [inline]

Swaps the values of this and the given integer.

Parameters:
other the integer whose value will be swapped with this.


Friends And Related Function Documentation

friend class NPrimes [friend]

Allow access to private members.

friend class NRational [friend]

Allow access to private members.

std::ostream& operator<< ( std::ostream &  out,
const NLargeInteger large 
) [friend]

Writes the given integer to the given output stream.

Parameters:
out the output stream to which to write.
large the integer to write.
Returns:
a reference to out.


Member Data Documentation

Globally available infinity.

Globally available one.

Globally available zero.


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

Copyright © 1999-2009, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).