Represents an arbitrary precision integer. More...

#include <maths/integer.h>

Inheritance diagram for regina::IntegerBase< supportInfinity >:

Public Member Functions
	IntegerBase ()
	Initialises this integer to zero. More...

	IntegerBase (int value)
	Initialises this integer to the given value. More...

	IntegerBase (unsigned value)
	Initialises this integer to the given value. More...

	IntegerBase (long value)
	Initialises this integer to the given value. More...

	IntegerBase (unsigned long value)
	Initialises this integer to the given value. More...

	IntegerBase (long long value)
	Initialises this integer to the given value. More...

	IntegerBase (unsigned long long value)
	Initialises this integer to the given value. More...

	IntegerBase (const IntegerBase< supportInfinity > &value)
	Initialises this integer to the given value. More...

	IntegerBase (const IntegerBase<! supportInfinity > &value)
	Initialises this integer to the given value. More...

	IntegerBase (IntegerBase< supportInfinity > &&src) noexcept
	Moves the given integer into this new integer. More...

	IntegerBase (IntegerBase<! supportInfinity > &&src) noexcept
	Moves the given integer into this new integer. More...

template<int bytes>
	IntegerBase (const NativeInteger< bytes > &value)
	Initialises this integer to the given value. More...

	IntegerBase (python_int value)
	Initialises this to the given native Python integer. More...

	IntegerBase (double value)
	Initialises this integer to the truncation of the given real number. More...

	IntegerBase (const char *value, int base=10)
	Initialises this integer to the given value which is represented as a string of digits in a given base. More...

	IntegerBase (const std::string &value, int base=10)
	Initialises this integer to the given value which is represented as a string of digits in a given base. More...

	~IntegerBase ()
	Destroys this integer. More...

bool	isNative () const
	Returns whether we are currently working with a native C/C++ long, or whether we have switched to GMP large integer arithmetic for this integer. More...

bool	isZero () const
	Returns whether or not this integer is zero. More...

int	sign () const
	Returns the sign of this integer. More...

bool	isInfinite () const
	Returns whether this integer is infinity. More...

void	makeInfinite ()
	Sets this integer to be infinity. More...

long	longValue () const
	Returns the value of this integer as a long. More...

long	safeLongValue () const
	Returns the value of this integer as a long, or throws an exception if this is not possible. More...

template<int bytes>
IntOfSize< bytes >::type	nativeValue () const
	Returns the value of this integer as a native integer of some fixed byte length. More...

std::string	stringValue (int base=10) const
	Returns the value of this integer as a string in the given base. More...

python_int	pythonValue () const
	Returns the value of this integer as a native Python integer. More...

IntegerBase &	operator= (const IntegerBase &value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (const IntegerBase<! supportInfinity > &value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (IntegerBase &&src) noexcept
	Moves the given integer into this integer. More...

IntegerBase &	operator= (IntegerBase<! supportInfinity > &&src) noexcept
	Moves the given integer into this integer. More...

IntegerBase &	operator= (int value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (unsigned value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (long value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (unsigned long value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (long long value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (unsigned long long value)
	Sets this integer to the given value. More...

IntegerBase &	operator= (const char *value)
	Sets this integer to the given value which is represented as a string of digits in base 10. More...

IntegerBase &	operator= (const std::string &value)
	Sets this integer to the given value which is represented as a string of digits in base 10. More...

void	swap (IntegerBase &other) noexcept
	Swaps the values of this and the given integer. More...

bool	operator== (const IntegerBase &rhs) const
	Determines if this is equal to the given integer. More...

bool	operator== (const IntegerBase<! supportInfinity > &rhs) const
	Determines if this is equal to the given integer. More...

bool	operator== (long rhs) const
	Determines if this is equal to the given integer. More...

bool	operator!= (const IntegerBase &rhs) const
	Determines if this is not equal to the given integer. More...

bool	operator!= (const IntegerBase<! supportInfinity > &rhs) const
	Determines if this is not equal to the given integer. More...

bool	operator!= (long rhs) const
	Determines if this is not equal to the given integer. More...

bool	operator< (const IntegerBase &rhs) const
	Determines if this is less than the given integer. More...

bool	operator< (long rhs) const
	Determines if this is less than the given integer. More...

bool	operator> (const IntegerBase &rhs) const
	Determines if this is greater than the given integer. More...

bool	operator> (long rhs) const
	Determines if this is greater than the given integer. More...

bool	operator<= (const IntegerBase &rhs) const
	Determines if this is less than or equal to the given integer. More...

bool	operator<= (long rhs) const
	Determines if this is less than or equal to the given integer. More...

bool	operator>= (const IntegerBase &rhs) const
	Determines if this is greater than or equal to the given integer. More...

bool	operator>= (long rhs) const
	Determines if this is greater than or equal to the given integer. More...

IntegerBase &	operator++ ()
	The preincrement operator. More...

IntegerBase	operator++ (int)
	The postincrement operator. More...

IntegerBase &	operator-- ()
	The predecrement operator. More...

IntegerBase	operator-- (int)
	The postdecrement operator. More...

IntegerBase	operator+ (const IntegerBase &other) const
	Adds this to the given integer and returns the result. More...

IntegerBase	operator+ (long other) const
	Adds this to the given integer and returns the result. More...

IntegerBase	operator- (const IntegerBase &other) const
	Subtracts the given integer from this and returns the result. More...

IntegerBase	operator- (long other) const
	Subtracts the given integer from this and returns the result. More...

IntegerBase	operator* (const IntegerBase &other) const
	Multiplies this by the given integer and returns the result. More...

IntegerBase	operator* (long other) const
	Multiplies this by the given integer and returns the result. More...

IntegerBase	operator/ (const IntegerBase &other) const
	Divides this by the given integer and returns the result. More...

IntegerBase	operator/ (long other) const
	Divides this by the given integer and returns the result. More...

IntegerBase	divExact (const IntegerBase &other) const
	Divides this by the given integer and returns the result. More...

IntegerBase	divExact (long other) const
	Divides this by the given integer and returns the result. More...

IntegerBase	operator% (const IntegerBase &other) const
	Determines the remainder when this integer is divided by the given integer. More...

IntegerBase	operator% (long other) const
	Determines the remainder when this integer is divided by the given integer. More...

std::pair< IntegerBase, IntegerBase >	divisionAlg (const IntegerBase &divisor) const
	Uses the division algorithm to obtain a quotient and remainder when dividing by the given integer. More...

IntegerBase	operator- () const
	Determines the negative of this integer. More...

IntegerBase &	operator+= (const IntegerBase &other)
	Adds the given integer to this. More...

IntegerBase &	operator+= (long other)
	Adds the given integer to this. More...

IntegerBase &	operator-= (const IntegerBase &other)
	Subtracts the given integer from this. More...

IntegerBase &	operator-= (long other)
	Subtracts the given integer from this. More...

IntegerBase &	operator*= (const IntegerBase &other)
	Multiplies the given integer by this. More...

IntegerBase &	operator*= (long other)
	Multiplies the given integer by this. More...

IntegerBase &	operator/= (const IntegerBase &other)
	Divides this by the given integer. More...

IntegerBase &	operator/= (long other)
	Divides this by the given integer. More...

IntegerBase &	divByExact (const IntegerBase &other)
	Divides this by the given integer. More...

IntegerBase &	divByExact (long other)
	Divides this by the given integer. More...

IntegerBase &	operator%= (const IntegerBase &other)
	Reduces this integer modulo the given integer. More...

IntegerBase &	operator%= (long other)
	Reduces this integer modulo the given integer. More...

void	negate ()
	Negates this integer. More...

void	raiseToPower (unsigned long exp)
	Raises this integer to the power of the given exponent. More...

IntegerBase	abs () const
	Determines the absolute value of this integer. More...

void	gcdWith (const IntegerBase &other)
	Sets this integer to be the greatest common divisor of this and the given integer. More...

IntegerBase	gcd (const IntegerBase &other) const
	Determines the greatest common divisor of this and the given integer. More...

void	lcmWith (const IntegerBase &other)
	Sets this integer to be the lowest common multiple of this and the given integer. More...

IntegerBase	lcm (const IntegerBase &other) const
	Determines the lowest common multiple of this and the given integer. More...

std::tuple< IntegerBase, IntegerBase, IntegerBase >	gcdWithCoeffs (const IntegerBase< supportInfinity > &other) 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. More...

IntegerBase< supportInfinity >	gcdWithCoeffs (const IntegerBase< supportInfinity > &other, IntegerBase< supportInfinity > &u, IntegerBase< supportInfinity > &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. More...

int	legendre (const IntegerBase< supportInfinity > &p) const
	Returns the Legendre symbol (a/p), where a is this integer and p is an odd prime. More...

IntegerBase< supportInfinity >	randomBoundedByThis () const
	Generate a pseudo-random integer that is uniformly distributed in the interval [0,*this). More...

void	setRaw (mpz_srcptr fromData)
	Set this to a copy of the given raw GMP integer. More...

mpz_srcptr	rawData () const
	Returns the raw GMP data that describes this integer. More...

mpz_ptr	rawData ()
	Returns the raw GMP data that describes this integer. More...

void	makeLarge ()
	Converts this integer to use a GMP large integer representation, regardless of whether this is actually necessary. More...

void	tryReduce ()
	Converts this integer to use a native C/C++ long representation, if this is possible. More...

void	tightEncode (std::ostream &out) const
	Writes the tight encoding of this integer to the given output stream. More...

std::string	tightEncoding () const
	Returns the tight encoding of this integer. More...

Static Public Member Functions
static IntegerBase< supportInfinity >	randomBinary (unsigned long n)
	Generate a pseudo-random integer that is uniformly distributed in the interval [0,2^n). More...

static IntegerBase< supportInfinity >	randomCornerBinary (unsigned long n)
	Generate a pseudo-random integer that is distributed in the interval [0,2^n), with a tendency to have long strings of 0s and 1s in its binary expansion. More...

static IntegerBase	tightDecoding (const std::string &enc)
	Reconstructs an integer from its given tight encoding. More...

static IntegerBase	tightDecode (std::istream &input)
	Reconstructs an integer from its given tight encoding. More...

Static Public Attributes
static const IntegerBase< supportInfinity >	zero
	Globally available zero. More...

static const IntegerBase< supportInfinity >	one = 1
	Globally available one. More...

static const IntegerBase< supportInfinity >	infinity
	Globally available infinity. More...

Friends
template<int bytes>
class	NativeInteger

template<bool supportInfinity_>
std::ostream &	operator<< (std::ostream &out, const IntegerBase< supportInfinity_ > &large)

Detailed Description

template<bool supportInfinity = false>
class regina::IntegerBase< supportInfinity >

Represents an arbitrary precision integer.

Calculations are always guaranteed to be exact, regardless of how large the integers become.

The current implementation uses fast native integer arithmetic wherever possible, whilst always testing for potential overflow. If a potential overflow is detected, this class switches to using the GNU multiple precision arithmetic library (libgmp) instead.

This class takes a single boolean argument supportInfinity. If this is true, then this class will support infinity as an allowed value. If this is false (the default), then infinity is not supported, and any attempt to work with infinity will lead to undefined behaviour. Supporting infinity is more flexible, but also comes with a slight performance cost (very roughly estimated at around 10%-20%).

For the purposes of comparison, infinity is considered larger than any other integer but equal to itself.

All routines in this class, including random number generation, are thread-safe.

The opportunistic use of native arithmetic where possible was inspired by the (much more complex and powerful) lazy exact arithmetic in CGAL. Thanks to Menelaos Karavelas for encouraging me to take another look at these ideas.

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.

Headers: Parts of this template class are implemented in a C++ source file that is not available through the headers. However, this should not affect users since the calculation engine includes explicit instantiations for all possible template parameters.

Python: Both variants of this template are available through Python. For supportInfinity = false, use the name Integer. For supportInfinity = true, use the name LargeInteger.

Constructor & Destructor Documentation

◆ IntegerBase() [1/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase

inline

Initialises this integer to zero.

◆ IntegerBase() [2/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( int value )

inline

Initialises this integer to the given value.

Python: Not present. In Python, the only native-integer constructor is IntegerBase(long).

Parameters

value the new value of this integer.

◆ IntegerBase() [3/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( unsigned value )

inline

Initialises this integer to the given value.

Python: Not present. In Python, the only native-integer constructor is IntegerBase(long).

Parameters

value the new value of this integer.

◆ IntegerBase() [4/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( long value )

inline

Initialises this integer to the given value.

Python: In Python, this is the only native-integer constructor available.

Parameters

value the new value of this integer.

◆ IntegerBase() [5/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( unsigned long value )

inline

Initialises this integer to the given value.

Python: Not present. In Python, the only native-integer constructor is IntegerBase(long).

Parameters

value the new value of this integer.

◆ IntegerBase() [6/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( long long value )

inline

Initialises this integer to the given value.

Python: Not present. In Python, the only native-integer constructor is IntegerBase(long).

Parameters

value the new value of this integer.

◆ IntegerBase() [7/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( unsigned long long value )

inline

Initialises this integer to the given value.

Python: Not present. In Python, the only native-integer constructor is IntegerBase(long).

Parameters

value the new value of this integer.

◆ IntegerBase() [8/16]

template<bool supportInfinity>

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

inline

Initialises this integer to the given value.

Parameters

value the new value of this integer.

◆ IntegerBase() [9/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( const IntegerBase<! supportInfinity > & value )

inline

Initialises this integer to the given value.

Precondition: The given integer is not infinite.

Parameters

value the new value of this integer.

◆ IntegerBase() [10/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( IntegerBase< supportInfinity > && src )

inlinenoexcept

Moves the given integer into this new integer.

This is a fast (constant time) operation.

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

Parameters

src	the integer to move.

◆ IntegerBase() [11/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( IntegerBase<! supportInfinity > && src )

inlinenoexcept

Moves the given integer into this new integer.

This is a fast (constant time) operation.

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

Precondition: The given integer is not infinite.

Parameters

src	the integer to move.

◆ IntegerBase() [12/16]

template<bool supportInfinity>

template<int bytes>

regina::IntegerBase< supportInfinity >::IntegerBase ( const NativeInteger< bytes > & value )

inline

Initialises this integer to the given value.

Precondition: If bytes is larger than sizeof(long), then bytes is a strict multiple of sizeof(long). For instance, if longs are 8 bytes then you can use bytes=16 but not bytes=12. This restriction is enforced through a compile-time assertion, but may be lifted in future versions of Regina.

Python: Not present. This is because the NativeInteger classes are not available to Python users.

Parameters

value the new value of this integer.

◆ IntegerBase() [13/16]

template<bool supportInfinity = false>

regina::IntegerBase< supportInfinity >::IntegerBase ( python_int value )

Initialises this to the given native Python integer.

The argument is of the Python int type, which Python uses to store integers of arbitrary magnitude (much like Regina does with its Integer and LargeInteger classes).

C++: Not present.

Parameters

value the new value of this integer.

◆ IntegerBase() [14/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase ( double value )

inline

Initialises this integer to the truncation of the given real number.

Parameters

value the real number to be truncated.

◆ IntegerBase() [15/16]

template<bool supportInfinity = false>

regina::IntegerBase< supportInfinity >::IntegerBase	(	const char *	value,
		int	base = `10`
	)

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.

If the template argument supportInfinity is true, then any string beginning with "inf" (after any initial whitesapce) will be interpreted as infinity.

Whitespace may be present at the beginning or the end of the given string, and will simply be ignored.

For finer details on how the string parsing works, see strtol() from the standard C library (on which this method is based).

Precondition: The given base is zero, or is between 2 and 36 inclusive.; The given string represents an integer in the given base, with optional whitespace beforehand.

Exceptions

InvalidArgument The given string was not a valid large integer representation.

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.

◆ IntegerBase() [16/16]

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::IntegerBase	(	const std::string &	value,
		int	base = `10`
	)

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.

If the template argument supportInfinity is true, then any string beginning with "inf" (after any initial whitesapce) will be interpreted as infinity.

Whitespace may be present at the beginning or the end of the given string, and will simply be ignored.

For finer details on how the string parsing works, see strtol() from the standard C library (on which this method is based).

Precondition: The given base is zero, or is between 2 and 36 inclusive.; The given string represents an integer in the given base, with optional whitespace beforehand.

Exceptions

InvalidArgument The given string was not a valid large integer representation.

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.

◆ ~IntegerBase()

template<bool supportInfinity>

regina::IntegerBase< supportInfinity >::~IntegerBase

inline

Destroys this integer.

Member Function Documentation

◆ abs()

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::abs

inline

Determines the absolute value of this integer.

This integer is not changed.

Returns: the absolute value of this integer.

◆ divByExact() [1/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::divByExact ( const IntegerBase< supportInfinity > & other )

Divides this by the given integer.

This can only be used when the given integer divides into this exactly, and for large integers this 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.

◆ divByExact() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::divByExact ( long other )

Divides this by the given integer.

This can only be used when the given integer divides into this exactly, and for large integers this 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.; This integer is not infinite.

Parameters

other the integer to divide this by.

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

◆ divExact() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::divExact ( const IntegerBase< supportInfinity > & 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 for large integers can be 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.

◆ divExact() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::divExact ( long 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 for large integers can be 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.; This integer is not infinite.

Parameters

other the integer to divide this by.

Returns: the quotient this divided by other.

◆ divisionAlg()

template<bool supportInfinity = false>

std::pair< IntegerBase, IntegerBase > regina::IntegerBase< supportInfinity >::divisionAlg ( const IntegerBase< supportInfinity > & divisor ) 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 (-7).divisionAlg(3) gives quotient -3 and remainder 2, whereas (-7)/3 gives quotient -2 and (-7)%3 gives remainder -1.

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.

Parameters

divisor the divisor d.

Returns: the pair (q, r), where q is the quotient and r is the remainder, as described above.

◆ gcd()

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::gcd ( const IntegerBase< supportInfinity > & other ) const

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

This integer is not changed.

The result is guaranteed to be non-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.

◆ gcdWith()

template<bool supportInfinity = false>

void regina::IntegerBase< supportInfinity >::gcdWith ( const IntegerBase< supportInfinity > & other )

Sets this integer to be the greatest common divisor of this and the given integer.

The result is guaranteed to be non-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.

◆ gcdWithCoeffs() [1/2]

template<bool supportInfinity>

std::tuple< IntegerBase< supportInfinity >, IntegerBase< supportInfinity >, IntegerBase< supportInfinity > > regina::IntegerBase< supportInfinity >::gcdWithCoeffs ( const IntegerBase< supportInfinity > & other ) const

inline

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, then this routine returns the tuple (d, u, v), where u and v are coefficients 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 will both be 0, 1 or -1, using as many zeros as possible.

Precondition: Neither this integer nor other is infinite.

Note: There are two variants of this routine: one returns the coefficients u and v as part of a tuple, and one returns them via reference arguments. For now both versions remain supported, but there is a long-term plan to eventually phase out the reference argument variant (i.e., not this variant).

Parameters

other the integer whose greatest common divisor with this will be found.

Returns: a tuple containing: the greatest common divisor of this and other; the final coefficient of this; and the final coefficient of other.

◆ gcdWithCoeffs() [2/2]

template<bool supportInfinity = false>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::gcdWithCoeffs	(	const IntegerBase< supportInfinity > &	other,
		IntegerBase< supportInfinity > &	u,
		IntegerBase< supportInfinity > &	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 coefficients 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 will both be 0, 1 or -1, using as many zeros as possible.

Precondition: Neither this integer nor other is infinite.

Note: There are two variants of this routine: one returns the coefficients u and v as part of a tuple, and one returns them via reference arguments. For now both versions remain supported, but there is a long-term plan to eventually phase out the reference argument variant (i.e., this variant).

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. Any existing contents of u will be overwritten.
v	a variable into which the final coefficient of other will be placed. Any existing contents of v will be overwritten.

Returns: the greatest common divisor of this and other.

◆ isInfinite()

template<bool supportInfinity = false>

bool regina::IntegerBase< supportInfinity >::isInfinite ( ) const

Returns whether this integer is infinity.

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

◆ isNative()

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::isNative

inline

Returns whether we are currently working with a native C/C++ long, or whether we have switched to GMP large integer arithmetic for this integer.

If this integer is infinite, this routine will return false.

Returns: true if and only if we are still using a native C/C++ long.

◆ isZero()

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::isZero

inline

Returns whether or not this integer is zero.

This is micro-optimised to be faster than simply testing whether (*this) == 0.

Returns: true if and only if this integer is zero.

◆ lcm()

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::lcm ( const IntegerBase< supportInfinity > & other ) const

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.

◆ lcmWith()

template<bool supportInfinity = false>

void regina::IntegerBase< supportInfinity >::lcmWith ( const IntegerBase< supportInfinity > & other )

Sets this integer to be the lowest common multiple of this and the given integer.

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.

◆ legendre()

template<bool supportInfinity = false>

int regina::IntegerBase< supportInfinity >::legendre ( const IntegerBase< supportInfinity > & p ) const

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.; This integer is not infinite.

Parameters

p	the given odd prime.

Returns: The Legendre symbol (0, 1 or -1) as described above.

Author: Ryan Budney

◆ longValue()

template<bool supportInfinity>

long regina::IntegerBase< supportInfinity >::longValue

inline

Returns the value of this integer as a long.

It is the programmer's reponsibility to ensure that this integer is within the required range. If this integer is too large or small to fit into a long, then the result will be undefined.

Note that, assuming the value is within the required range, this routine will give correct results regardless of whether the underlying representation is a native or large integer.

Precondition: This integer is not infinity.

Returns: the value of this integer.

◆ makeInfinite()

template<bool supportInfinity = false>

void regina::IntegerBase< supportInfinity >::makeInfinite ( )

inline

Sets this integer to be infinity.

If the template parameter supportInfinity is false, this routine safely does nothing.

◆ makeLarge()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::makeLarge

inline

Converts this integer to use a GMP large integer representation, regardless of whether this is actually necessary.

The contents of this integer will be preserved.

It does not matter which kind of representation this integer is currently using.

Precondition: This integer is not infinite.

◆ nativeValue()

template<bool supportInfinity>

template<int bytes>

IntOfSize< bytes >::type regina::IntegerBase< supportInfinity >::nativeValue

Returns the value of this integer as a native integer of some fixed byte length.

It is the programmer's reponsibility to ensure that this integer is within the required range. If this integer is too large or small to fit into the return type, then the result will be undefined.

Note that, assuming the value is within the required range, this routine will give correct results regardless of whether the underlying representation is a native or large integer.

Precondition: If bytes is larger than sizeof(long), then bytes is a strict multiple of sizeof(long). For instance, if longs are 8 bytes then you can use this routine with bytes=4 or bytes=16 but not bytes=12. This restriction is enforced through a compile-time assertion, but may be lifted in future versions of Regina.; This integer is not infinity.

Python: Not present. Python users can use the non-templated longValue() function instead.

Returns: the value of this integer.

◆ negate()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::negate

inline

Negates this integer.

This integer is changed to reflect the result.

Negating infinity will result in infinity.

◆ operator!=() [1/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator!= ( const IntegerBase< supportInfinity > & rhs ) const

inline

Determines if this is not equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are not equal.

◆ operator!=() [2/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator!= ( const IntegerBase<! supportInfinity > & rhs ) const

inline

Determines if this is not equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are not equal.

◆ operator!=() [3/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator!= ( long rhs ) const

inline

Determines if this is not equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are not equal.

◆ operator%() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator% ( const IntegerBase< supportInfinity > & 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.

◆ operator%() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator% ( long 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.; This integer is not infinite.

Parameters

other the integer to divide this by.

Returns: the remainder this modulo other.

◆ operator%=() [1/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator%= ( const IntegerBase< supportInfinity > & other )

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.

◆ operator%=() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator%= ( long other )

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.; This integer is not infinite.

Parameters

other the integer modulo which this integer will be reduced.

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

◆ operator*() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator* ( const IntegerBase< supportInfinity > & 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.

◆ operator*() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator* ( long 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.

◆ operator*=() [1/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator*= ( const IntegerBase< supportInfinity > & other )

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.

◆ operator*=() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator*= ( long other )

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.

◆ operator+() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator+ ( const IntegerBase< supportInfinity > & 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.

◆ operator+() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator+ ( long 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.

◆ operator++() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator++

inline

The preincrement operator.

This operator increments this integer by one, and returns a reference to the integer after the increment.

Python: Not present. The postincrement operator is present in Python as the member function inc().

Returns: a reference to this integer after the increment.

◆ operator++() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator++ ( int )

inline

The postincrement operator.

This operator increments this integer by one, and returns a copy of the integer before the increment.

Python: This routine is named inc() since python does not support the increment operator.

Returns: a copy of this integer before the increment took place.

◆ operator+=() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator+= ( const IntegerBase< supportInfinity > & 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.

◆ operator+=() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator+= ( long other )

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.

◆ operator-() [1/3]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator-

inline

Determines the negative of this integer.

This integer is not changed.

Negative infinity will return infinity.

Returns: the negative of this integer.

◆ operator-() [2/3]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator- ( const IntegerBase< supportInfinity > & 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.

◆ operator-() [3/3]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator- ( long 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.

◆ operator--() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator--

inline

The predecrement operator.

This operator decrements this integer by one, and returns a reference to the integer after the decrement.

Python: Not present. The postdecrement operator is present in python as the member function dec().

Returns: a reference to this integer after the decrement.

◆ operator--() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator-- ( int )

inline

The postdecrement operator.

This operator decrements this integer by one, and returns a copy of the integer before the decrement.

Python: This routine is named dec() since python does not support the decrement operator.

Returns: a copy of this integer before the decrement took place.

◆ operator-=() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator-= ( const IntegerBase< supportInfinity > & 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.

◆ operator-=() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator-= ( long other )

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.

◆ operator/() [1/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator/ ( const IntegerBase< supportInfinity > & 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().

Precondition: If this class does not support infinity, then other must be non-zero.

Parameters

other the integer to divide this by.

Returns: the quotient this divided by other.

◆ operator/() [2/2]

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::operator/ ( long 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 zero will return infinity.

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

Precondition: If this class does not support infinity, then other must be non-zero.

Parameters

other the integer to divide this by.

Returns: the quotient this divided by other.

◆ operator/=() [1/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator/= ( const IntegerBase< supportInfinity > & other )

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

Precondition: If this class does not support infinity, then other must be non-zero.

Parameters

other the integer to divide this by.

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

◆ operator/=() [2/2]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator/= ( long other )

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 zero will return infinity.

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

Precondition: If this class does not support infinity, then other must be non-zero.

Parameters

other the integer to divide this by.

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

◆ operator<() [1/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator< ( const IntegerBase< supportInfinity > & rhs ) const

inline

Determines if this is less than the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is less than the given integer.

◆ operator<() [2/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator< ( long rhs ) const

inline

Determines if this is less than the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is less than the given integer.

◆ operator<=() [1/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator<= ( const IntegerBase< supportInfinity > & rhs ) const

inline

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

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is less than or equal to the given integer.

◆ operator<=() [2/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator<= ( long rhs ) const

inline

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

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is less than or equal to the given integer.

◆ operator=() [1/12]

template<bool supportInfinity = false>

IntegerBase & regina::IntegerBase< supportInfinity >::operator= ( const char * value )

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

Whitespace may be present at the beginning or end of the given string and will simply be ignored.

If the template argument supportInfinity is true, then any string beginning with "inf" (after any initial whitesapce) will be interpreted as infinity.

Precondition: The given string represents an integer in base 10, with optional whitespace added.

Exceptions

InvalidArgument The given string was not a valid large integer representation.

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.

◆ operator=() [2/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( const IntegerBase< supportInfinity > & 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.

◆ operator=() [3/12]

template<bool supportInfinity>

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

inline

Sets this integer to the given value.

Precondition: The given integer is not infinite.

Parameters

value the new value of this integer.

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

◆ operator=() [4/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::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 at the beginning or end of the given string and will simply be ignored.

If the template argument supportInfinity is true, then any string beginning with "inf" (after any initial whitesapce) will be interpreted as infinity.

Precondition: The given string represents an integer in base 10, with optional whitespace added.

Exceptions

InvalidArgument The given string was not a valid large integer representation.

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.

◆ operator=() [5/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( int 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.

◆ operator=() [6/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( IntegerBase< supportInfinity > && src )

inlinenoexcept

Moves the given integer into this integer.

This is a fast (constant time) operation.

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

Parameters

src	the integer to move.

Returns: a reference to this integer.

◆ operator=() [7/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( IntegerBase<! supportInfinity > && src )

inlinenoexcept

Moves the given integer into this integer.

This is a fast (constant time) operation.

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

Precondition: The given integer is not infinite.

Parameters

src	the integer to move.

Returns: a reference to this integer.

◆ operator=() [8/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( long 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.

◆ operator=() [9/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::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.

◆ operator=() [10/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( unsigned long 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.

◆ operator=() [11/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( unsigned 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.

◆ operator=() [12/12]

template<bool supportInfinity>

IntegerBase< supportInfinity > & regina::IntegerBase< supportInfinity >::operator= ( unsigned 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.

◆ operator==() [1/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator== ( const IntegerBase< supportInfinity > & rhs ) const

inline

Determines if this is equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are equal.

◆ operator==() [2/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator== ( const IntegerBase<! supportInfinity > & rhs ) const

inline

Determines if this is equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are equal.

◆ operator==() [3/3]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator== ( long rhs ) const

inline

Determines if this is equal to the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this and the given integer are equal.

◆ operator>() [1/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator> ( const IntegerBase< supportInfinity > & rhs ) const

inline

Determines if this is greater than the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is greater than the given integer.

◆ operator>() [2/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator> ( long rhs ) const

inline

Determines if this is greater than the given integer.

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is greater than the given integer.

◆ operator>=() [1/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator>= ( const IntegerBase< supportInfinity > & rhs ) const

inline

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

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is greater than or equal to the given integer.

◆ operator>=() [2/2]

template<bool supportInfinity>

bool regina::IntegerBase< supportInfinity >::operator>= ( long rhs ) const

inline

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

Parameters

rhs	the integer with which this will be compared.

Returns: true if and only if this is greater than or equal to the given integer.

◆ pythonValue()

template<bool supportInfinity = false>

python_int regina::IntegerBase< supportInfinity >::pythonValue ( ) const

Returns the value of this integer as a native Python integer.

The return value will be of the Python int type, which Python uses to store integers of arbitrary magnitude (much like Regina does with its Integer and LargeInteger classes).

Precondition: This integer is not infinity.

C++: Not present.

Returns: the value of this integer as a Python integer.

◆ raiseToPower()

template<bool supportInfinity = false>

void regina::IntegerBase< supportInfinity >::raiseToPower ( unsigned long exp )

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.

◆ randomBinary()

template<bool supportInfinity = false>

static IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::randomBinary ( unsigned long n )

static

Generate a pseudo-random integer that is uniformly distributed in the interval [0,2^n).

The random number generation here does not use Regina's own RandomEngine class, but instead uses a separate random number generator provided by GMP.

Parameters

n	the maximum number of bits in the pseudo-random integer.

Returns: a pseudo-random integer.

◆ randomBoundedByThis()

template<bool supportInfinity = false>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::randomBoundedByThis ( ) const

Generate a pseudo-random integer that is uniformly distributed in the interval [0,*this).

The random number generation here does not use Regina's own RandomEngine class, but instead uses a separate random number generator provided by GMP.

Precondition: This integer is strictly positive.

Warning: Even if this integer is small, this routine is still slow - it always goes through the GMP large integer routines so that the random number generation algorithm is consistent. If you need a fast random number generator and this integer is small, consider using the standard rand() function instead.

Returns: a pseudo-random integer.

◆ randomCornerBinary()

template<bool supportInfinity = false>

static IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::randomCornerBinary ( unsigned long n )

static

Generate a pseudo-random integer that is distributed in the interval [0,2^n), with a tendency to have long strings of 0s and 1s in its binary expansion.

The random number generation here does not use Regina's own RandomEngine class, but instead uses a separate random number generator provided by GMP.

Parameters

n	the maximum number of bits in the pseudo-random integer.

Returns: a pseudo-random integer.

◆ rawData() [1/2]

template<bool supportInfinity>

mpz_ptr regina::IntegerBase< supportInfinity >::rawData

inline

Returns the raw GMP data that describes this integer.

This routine allows IntegerBase to interact directly with libgmp and libgmpxx if necessary.

Warning: This routine will have the side-effect of converting this integer to a (bulkier and slower) GMP representation, regardless of whether it is small enough to fit within a native integer. Excessive use of this routine could lead to a significant performance loss. It is best to use this only when isNative() is already known to return false.

Precondition: This integer is not infinite.

Python: Not present.

Returns: the raw GMP data.

◆ rawData() [2/2]

template<bool supportInfinity>

mpz_srcptr regina::IntegerBase< supportInfinity >::rawData

inline

Returns the raw GMP data that describes this integer.

This routine allows IntegerBase to interact directly with libgmp and libgmpxx if necessary.

Warning: This routine will have the side-effect of converting this integer to a (bulkier and slower) GMP representation, regardless of whether it is small enough to fit within a native integer. Excessive use of this routine could lead to a significant performance loss. It is best to use this only when isNative() is already known to return false.

Precondition: This integer is not infinite.

Python: Not present.

Returns: the raw GMP data.

◆ safeLongValue()

template<bool supportInfinity>

long regina::IntegerBase< supportInfinity >::safeLongValue

inline

Returns the value of this integer as a long, or throws an exception if this is not possible.

If this integer is within the required range, regardless of whether the underlying representation is a native or large integer, this routine will return the correct result.

Exceptions

NoSolution This integer is too large or small to fit into a long.

Returns: the value of this integer.

◆ setRaw()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::setRaw ( mpz_srcptr fromData )

inline

Set this to a copy of the given raw GMP integer.

This routine allows IntegerBase to interact directly with libgmp and libgmpxx if necessary.

Python: Not present.

Parameters

fromData the raw GMP integer to clone.

◆ sign()

template<bool supportInfinity>

int regina::IntegerBase< supportInfinity >::sign

inline

Returns the sign of this integer.

In this routine, infinity is considered to have sign +1.

Returns: +1, -1 or 0 according to whether this integer is positive, negative or zero.

◆ stringValue()

template<bool supportInfinity = false>

std::string regina::IntegerBase< supportInfinity >::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 string.

◆ swap()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::swap ( IntegerBase< supportInfinity > & other )

inlinenoexcept

Swaps the values of this and the given integer.

Parameters

other the integer whose value will be swapped with this.

◆ tightDecode()

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::tightDecode ( std::istream & input )

inlinestatic

Reconstructs an integer from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

This routine does recognise infinity in the case where supportInfinity is true.

This routine is identical to calling the global template routine regina::tightDecode() with this type as the template argument.

Exceptions

InvalidInput The given input stream does not begin with a tight encoding of an integer of this type.

Python: Not present. Use tightDecoding() instead, which takes a string as its argument.

Parameters

input an input stream that begins with the tight encoding for an integer.

Returns: the integer represented by the given tight encoding.

◆ tightDecoding()

template<bool supportInfinity>

IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::tightDecoding ( const std::string & enc )

inlinestatic

Reconstructs an integer from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

This routine does recognise infinity in the case where supportInfinity is true.

This routine is identical to calling the global template routine regina::tightDecoding() with this type as the template argument.

Exceptions

InvalidArgument The given string is not a tight encoding of an integer of this type.

Parameters

enc	the tight encoding for an integer.

Returns: the integer represented by the given tight encoding.

◆ tightEncode()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::tightEncode ( std::ostream & out ) const

inline

Writes the tight encoding of this integer to the given output stream.

See the page on tight encodings for details.

There is also a corresponding global regina::tightEncode() function, for better compatibility with native C++ integer types. The global function is more efficient if the integer argument is an rvalue reference (since this const member function induces an extra deep copy).

Python: Not present. Use tightEncoding() instead, which returns a string.

Parameters

out	the output stream to which the encoded string will be written.

◆ tightEncoding()

template<bool supportInfinity>

std::string regina::IntegerBase< supportInfinity >::tightEncoding

inline

Returns the tight encoding of this integer.

See the page on tight encodings for details.

There is also a corresponding global regina::tightEncoding() function, for better compatibility with native C++ integer types. The global function is more efficient if the integer argument is an rvalue reference (since this const member function induces an extra deep copy).

Returns: the resulting encoded string.

◆ tryReduce()

template<bool supportInfinity>

void regina::IntegerBase< supportInfinity >::tryReduce

inline

Converts this integer to use a native C/C++ long representation, if this is possible.

However, if this integer is outside the range of a C/C++ long, then it will remain as a GMP large integer instead (i.e., nothing will change). Whatever happens, the contents of this integer will be preserved.

It does not matter which kind of representation this integer is currently using.

Precondition: This integer is not infinite.

Member Data Documentation

◆ infinity

template<bool supportInfinity = false>

const IntegerBase<supportInfinity> regina::IntegerBase< supportInfinity >::infinity

static

Globally available infinity.

This is only defined if supportInfinity is true. Any attempt to use it when supportInfinity is false should generate a linker error.

◆ one

template<bool supportInfinity>

const IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::one = 1

inlinestatic

Globally available one.

◆ zero

template<bool supportInfinity>

const IntegerBase< supportInfinity > regina::IntegerBase< supportInfinity >::zero

inlinestatic

Globally available zero.

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

maths/integer.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ IntegerBase() [1/16]

◆ IntegerBase() [2/16]

◆ IntegerBase() [3/16]

◆ IntegerBase() [4/16]

◆ IntegerBase() [5/16]

◆ IntegerBase() [6/16]

◆ IntegerBase() [7/16]

◆ IntegerBase() [8/16]

◆ IntegerBase() [9/16]

◆ IntegerBase() [10/16]

◆ IntegerBase() [11/16]

◆ IntegerBase() [12/16]

◆ IntegerBase() [13/16]

◆ IntegerBase() [14/16]

◆ IntegerBase() [15/16]

◆ IntegerBase() [16/16]

◆ ~IntegerBase()

Member Function Documentation

◆ abs()

◆ divByExact() [1/2]

◆ divByExact() [2/2]

◆ divExact() [1/2]

◆ divExact() [2/2]

◆ divisionAlg()

◆ gcd()

◆ gcdWith()

◆ gcdWithCoeffs() [1/2]

◆ gcdWithCoeffs() [2/2]

◆ isInfinite()

◆ isNative()

◆ isZero()

◆ lcm()

◆ lcmWith()

◆ legendre()

◆ longValue()

◆ makeInfinite()

◆ makeLarge()

◆ nativeValue()

◆ negate()

◆ operator!=() [1/3]

◆ operator!=() [2/3]

◆ operator!=() [3/3]

◆ operator%() [1/2]

◆ operator%() [2/2]

◆ operator%=() [1/2]

◆ operator%=() [2/2]

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator*=() [1/2]

◆ operator*=() [2/2]

◆ operator+() [1/2]

◆ operator+() [2/2]

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ operator-() [1/3]

◆ operator-() [2/3]

◆ operator-() [3/3]

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ operator-=() [1/2]

◆ operator-=() [2/2]

◆ operator/() [1/2]

◆ operator/() [2/2]

◆ operator/=() [1/2]

◆ operator/=() [2/2]

◆ operator<() [1/2]

◆ operator<() [2/2]

◆ operator<=() [1/2]

◆ operator<=() [2/2]

◆ operator=() [1/12]

◆ operator=() [2/12]

◆ operator=() [3/12]