Represents a Laurent polynomial in the two variables x, y with coefficients of type T. More...

#include <maths/laurent2.h>

Inheritance diagram for regina::Laurent2< T >:

Public Types
using	Coefficient = T
	The type of each coefficient of the polynomial. More...

Public Member Functions
	Laurent2 ()=default
	Creates the zero polynomial. More...

	Laurent2 (long xExp, long yExp)
	Creates the polynomial `x^d y^e` for the given exponents d and e. More...

	Laurent2 (const Laurent2< T > &value)
	Creates a new copy of the given polynomial. More...

	Laurent2 (Laurent2< T > &&value) noexcept=default
	Moves the contents of the given polynomial to this new polynomial. More...

	Laurent2 (const Laurent2< T > &toShift, long xShift, long yShift)
	Creates a copy of the given polynomial with all terms multiplied by `x^d y^e` for some integers d and e. More...

template<typename U >
	Laurent2 (const Laurent2< U > &value)
	Creates a new copy of the given polynomial. More...

template<typename iterator , typename deref = decltype(*iterator())>
	Laurent2 (iterator begin, iterator end)
	Creates a new polynomial from the given collection of coefficients. More...

	Laurent2 (std::initializer_list< std::tuple< long, long, T > > coefficients)
	Creates a new polynomial from a hard-coded collection of non-zero coefficients. More...

void	init ()
	Sets this to become the zero polynomial. More...

void	init (long xExp, long yExp)
	Sets this to become the polynomial `x^d y^e` for the given exponents d and e. More...

bool	isZero () const
	Returns whether this is the zero polynomial. More...

const T &	operator() (long xExp, long yExp) const
	Returns the given coefficient of this polynomial. More...

void	set (long xExp, long yExp, const T &value)
	Changes the given coefficient of this polynomial. More...

bool	operator== (const Laurent2< T > &rhs) const
	Tests whether this and the given polynomial are equal. More...

bool	operator!= (const Laurent2< T > &rhs) const
	Tests whether this and the given polynomial are not equal. More...

bool	operator< (const Laurent2< T > &rhs) const
	Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials. More...

bool	operator> (const Laurent2< T > &rhs) const
	Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials. More...

bool	operator<= (const Laurent2< T > &rhs) const
	Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials. More...

bool	operator>= (const Laurent2< T > &rhs) const
	Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials. More...

Laurent2 &	operator= (const Laurent2< T > &value)
	Sets this to be a copy of the given polynomial. More...

template<typename U >
Laurent2 &	operator= (const Laurent2< U > &value)
	Sets this to be a copy of the given polynomial. More...

Laurent2 &	operator= (Laurent2< T > &&value) noexcept=default
	Moves the contents of the given polynomial to this polynomial. More...

void	swap (Laurent2< T > &other) noexcept
	Swaps the contents of this and the given polynomial. More...

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

void	invertX ()
	Replaces `x` with `x^-1` in this polynomial. More...

void	invertY ()
	Replaces `y` with `y^-1` in this polynomial. More...

Laurent2 &	operator*= (const T &scalar)
	Multiplies this polynomial by the given constant. More...

Laurent2 &	operator/= (const T &scalar)
	Divides this polynomial by the given constant. More...

Laurent2 &	operator+= (const Laurent2< T > &other)
	Adds the given polynomial to this. More...

Laurent2 &	operator-= (const Laurent2< T > &other)
	Subtracts the given polynomial from this. More...

Laurent2 &	operator*= (const Laurent2< T > &other)
	Multiplies this by the given polynomial. More...

void	writeTextShort (std::ostream &out, bool utf8=false, const char varX=nullptr, const char varY=nullptr) const
	Writes this polynomial to the given output stream, using the given variable names instead of `x` and `y`. More...

std::string	str (const char varX, const char varY=nullptr) const
	Returns this polynomial as a human-readable string, using the given variable names instead of `x` and `y`. More...

std::string	utf8 (const char varX, const char varY=nullptr) const
	Returns this polynomial as a human-readable string using unicode characters, using the given variable names instead of `x` and `y`. More...

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

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

template<typename U >
Laurent2< T > &	operator= (const Laurent2< U > &other)

void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. More...

std::string	str () const
	Returns a short text representation of this object. More...

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...

std::string	detail () const
	Returns a detailed text representation of this object. More...

Friends
class	Link

template<typename U >
Laurent2< U >	operator* (const Laurent2< U > &, const Laurent2< U > &)

Detailed Description

template<typename T>
class regina::Laurent2< T >

Represents a Laurent polynomial in the two variables x, y with coefficients of type T.

A Laurent polynomial differs from an ordinary polynomial in that it allows negative exponents (so, for example, you can represent a polynomial such as 2 + 3x^2 + y/x - 1/y^3).

The type T must represent a ring with no zero divisors. In particular, it must:

support basic arithmetic operations;
support assignments of the form x = int and tests of the form x == int and x < int;
have a default constructor that assigns an explicit value of zero.

This means that Regina's numerical types such as Integer and Rational are supported, but native data types such as int and long are not (since they have no zero-initialising default constructor).

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.

The underlying storage method for this class is sparse: only the non-zero coefficients are stored.

See also the class Laurent, which describes Laurent polynomials in just one variable.

Python: In Python, the class Laurent2 refers to the specific template class Laurent2<Integer>.

Member Typedef Documentation

◆ Coefficient

template<typename T >

using regina::Laurent2< T >::Coefficient = T

The type of each coefficient of the polynomial.

Constructor & Destructor Documentation

◆ Laurent2() [1/8]

template<typename T >

regina::Laurent2< T >::Laurent2 ( )

default

Creates the zero polynomial.

◆ Laurent2() [2/8]

template<typename T >

regina::Laurent2< T >::Laurent2	(	long	xExp,
		long	yExp
	)

inlineexplicit

Creates the polynomial x^d y^e for the given exponents d and e.

Parameters

xExp	the exponent d, which is attached to x.
yExp	the exponent e, which is attached to y.

◆ Laurent2() [3/8]

template<typename T >

regina::Laurent2< T >::Laurent2 ( const Laurent2< T > & value )

inline

Creates a new copy of the given polynomial.

This constructor induces a deep copy of value.

A note for developers: even though this routine is identical to the templated copy constructor, it must be declared and implemented separately. Otherwise the compiler might create its own (incorrect) copy constructor automatically.

Parameters

value the polynomial to clone.

◆ Laurent2() [4/8]

template<typename T >

regina::Laurent2< T >::Laurent2 ( Laurent2< T > && value )

defaultnoexcept

Moves the contents of the given polynomial to this new polynomial.

This is a fast (constant time) operation.

The polynomial that was passed (value) will no longer be usable.

Parameters

value the polynomial to move.

◆ Laurent2() [5/8]

template<typename T >

regina::Laurent2< T >::Laurent2	(	const Laurent2< T > &	toShift,
		long	xShift,
		long	yShift
	)

Creates a copy of the given polynomial with all terms multiplied by x^d y^e for some integers d and e.

This constructor induces a deep (and modified) copy of value.

Parameters

toShift	the polynomial to clone and shift.
xShift	the integer d, which will be added to all exponents for x.
yShift	the integer e, which will be added to all exponents for y.

◆ Laurent2() [6/8]

template<typename T >

template<typename U >

regina::Laurent2< T >::Laurent2 ( const Laurent2< U > & value )

inline

Creates a new copy of the given polynomial.

This constructor induces a deep copy of value.

Precondition: Objects of type T can be assigned values of type U.

Parameters

value the polynomial to clone.

◆ Laurent2() [7/8]

template<typename T >

template<typename iterator , typename deref >

regina::Laurent2< T >::Laurent2	(	iterator	begin,
		iterator	end
	)

inline

Creates a new polynomial from the given collection of coefficients.

The coefficients should be presented as a collection of tuples of the form (d, e, v), each representing a term of the form v x^d y^e.

The tuples may be given in any order. An empty sequence will be treated as the zero polynomial.

Unlike the std::initializer_list constructor, zero coefficients are allowed (these will be silently ignored), and multiple coefficients with the same exponents are also allowed (these will be aggregated using the += operator).

Python: Instead of the iterators begin and end, this routine takes a python list of tuples.

Template Parameters

iterator	an iterator type which, when dereferenced, gives a std::tuple of the form (d, e, v), where d and e can be assigned to long integers, and where v can be assigned to type T.
deref	a dummy argument that should be ignored. This is present to ensure that iterator can be dereferenced, so that a call such as Laurent2(int, int) falls through to the (long, long) constructor, and not this iterator-based constructor instead.

Parameters

begin	the beginning of the set of coefficients, as outlined above.
end	a past-the-end iterator indicating the end of the set of coefficients.

◆ Laurent2() [8/8]

template<typename T >

regina::Laurent2< T >::Laurent2 ( std::initializer_list< std::tuple< long, long, T > > coefficients )

inline

Creates a new polynomial from a hard-coded collection of non-zero coefficients.

The coefficients should be presented as a collection of tuples of the form (d, e, v) each representing a term of the form v x^d y^e.

The tuples may be given in any order. An empty sequence will be treated as the zero polynomial.

In practice, this means you can create a hard-coded polynomial using syntax such as:

Laurent2<Integer> p = { { 0, 0, 3 }, { 1, -1, 2 } };

Precondition: Each tuple has a non-zero value v, and no two tuples share the same pair of exponents (d, e).

Python: Not available, but there is a Python constructor that takes a list of coefficients (which need not be constant).

Parameters

coefficients the set of all non-zero coefficients, as outlined above.

Member Function Documentation

◆ detail()

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ init() [1/2]

template<typename T >

void regina::Laurent2< T >::init

inline

Sets this to become the zero polynomial.

◆ init() [2/2]

template<typename T >

void regina::Laurent2< T >::init	(	long	xExp,
		long	yExp
	)

inline

Sets this to become the polynomial x^d y^e for the given exponents d and e.

Parameters

xExp	the new exponent d, which is attached to x.
yExp	the new exponent e, which is attached to y.

◆ invertX()

template<typename T >

void regina::Laurent2< T >::invertX

inline

Replaces x with x^-1 in this polynomial.

This polynomial is changed directly.

◆ invertY()

template<typename T >

void regina::Laurent2< T >::invertY

inline

Replaces y with y^-1 in this polynomial.

This polynomial is changed directly.

◆ isZero()

template<typename T >

bool regina::Laurent2< T >::isZero

inline

Returns whether this is the zero polynomial.

Returns: true if and only if this is the zero polynomial.

◆ negate()

template<typename T >

void regina::Laurent2< T >::negate

inline

Negates this polynomial.

This polynomial is changed directly.

◆ operator!=()

template<typename T >

bool regina::Laurent2< T >::operator!= ( const Laurent2< T > & rhs ) const

inline

Tests whether this and the given polynomial are not equal.

Parameters

rhs	the polynomial to compare with this.

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

◆ operator()()

template<typename T >

const T & regina::Laurent2< T >::operator()	(	long	xExp,
		long	yExp
	)		const

inline

Returns the given coefficient of this polynomial.

There are no restrictions on the exponents xExp and yExp.

Python: In Python, this is the square bracket operator, not the round bracket operator; that is, Python users can access coefficients through the syntax poly[xExp, yExp]. Moreover, this operator can also set cofficients; that is, you can write poly[xExp, yExp] = value. However, when getting a coefficient this operator will return by value (to enforce constness), which means for example you cannot write something like poly[xExp, yExp].negate().

C++: C++ users must always set coefficients using the separate routine set(), since this bracket operator is const.

Parameters

xExp	the exponent attached to x.
yExp	the exponent attached to y.

Returns: the coefficient of the term with the given exponents.

◆ operator*=() [1/2]

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator*= ( const Laurent2< T > & other )

Multiplies this by the given polynomial.

This and the given polynomial need not have the same range of non-zero coefficients.

Parameters

other the polynomial to multiply this by.

Returns: a reference to this polynomial.

◆ operator*=() [2/2]

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator*= ( const T & scalar )

inline

Multiplies this polynomial by the given constant.

Parameters

scalar the scalar factor to multiply by.

Returns: a reference to this polynomial.

◆ operator+=()

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator+= ( const Laurent2< T > & other )

Adds the given polynomial to this.

This and the given polynomial need not have the same range of non-zero coefficients.

Parameters

other the polynomial to add to this.

Returns: a reference to this polynomial.

◆ operator-=()

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator-= ( const Laurent2< T > & other )

Subtracts the given polynomial from this.

This and the given polynomial need not have the same range of non-zero coefficients.

Parameters

other the polynomial to subtract from this.

Returns: a reference to this polynomial.

◆ operator/=()

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator/= ( const T & scalar )

inline

Divides this polynomial by the given constant.

This uses the division operator /= for the coefficient type T.

Precondition: The argument scalar is non-zero.

Parameters

scalar the scalar factor to divide by.

Returns: a reference to this polynomial.

◆ operator<()

template<typename T >

bool regina::Laurent2< T >::operator< ( const Laurent2< T > & rhs ) const

inline

Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials.

The particular total order that Regina uses is not important, and may change between Regina releases (though such changes should be very infrequent). The main purpose of this routine is to support algorithms that require a "canonical" choice of polynomial from amongst many alternatives.

Parameters

rhs	the polynomial to compare with this.

Returns: true if and only if this is less than the given polynomial under the total order that Regina uses.

◆ operator<=()

template<typename T >

bool regina::Laurent2< T >::operator<= ( const Laurent2< T > & rhs ) const

inline

Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials.

The particular total order that Regina uses is not important, and may change between Regina releases (though such changes should be very infrequent). The main purpose of this routine is to support algorithms that require a "canonical" choice of polynomial from amongst many alternatives.

Parameters

rhs	the polynomial to compare with this.

Returns: true if and only if this is less than or equal to the given polynomial under the total order that Regina uses.

◆ operator=() [1/3]

template<typename T >

Laurent2< T > & regina::Laurent2< T >::operator= ( const Laurent2< T > & value )

inline

Sets this to be a copy of the given polynomial.

This and the given polynomial need not have the same range of non-zero coefficients.

This operator induces a deep copy of value.

A note to developers: although this is identical to the templated assignment operator, it must be declared and implemented separately. See the copy constructor for further details.

Parameters

value the polynomial to copy.

Returns: a reference to this polynomial.

◆ operator=() [2/3]

template<typename T >

template<typename U >

Laurent2 & regina::Laurent2< T >::operator= ( const Laurent2< U > & value )

Sets this to be a copy of the given polynomial.

This and the given polynomial need not have the same range of non-zero coefficients.

This operator induces a deep copy of value.

Parameters

value the polynomial to copy.

Returns: a reference to this polynomial.

◆ operator=() [3/3]

template<typename T >

Laurent2 & regina::Laurent2< T >::operator= ( Laurent2< T > && value )

defaultnoexcept

Moves the contents of the given polynomial to this polynomial.

This is a fast (constant time) operation.

This and the given polynomial need not have the same range of non-zero coefficients.

The polynomial that was passed (value) will no longer be usable.

Parameters

value the polynomial to move.

Returns: a reference to this polynomial.

◆ operator==()

template<typename T >

bool regina::Laurent2< T >::operator== ( const Laurent2< T > & rhs ) const

inline

Tests whether this and the given polynomial are equal.

Parameters

rhs	the polynomial to compare with this.

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

◆ operator>()

template<typename T >

bool regina::Laurent2< T >::operator> ( const Laurent2< T > & rhs ) const

inline

Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials.

The particular total order that Regina uses is not important, and may change between Regina releases (though such changes should be very infrequent). The main purpose of this routine is to support algorithms that require a "canonical" choice of polynomial from amongst many alternatives.

Parameters

rhs	the polynomial to compare with this.

Returns: true if and only if this is greater than the given polynomial under the total order that Regina uses.

◆ operator>=()

template<typename T >

bool regina::Laurent2< T >::operator>= ( const Laurent2< T > & rhs ) const

inline

Compares this against the given polynomial under a total ordering of all two-variable Laurent polynomials.

The particular total order that Regina uses is not important, and may change between Regina releases (though such changes should be very infrequent). The main purpose of this routine is to support algorithms that require a "canonical" choice of polynomial from amongst many alternatives.

Parameters

rhs	the polynomial to compare with this.

Returns: true if and only if this is greater than or equal to the given polynomial under the total order that Regina uses.

◆ set()

template<typename T >

void regina::Laurent2< T >::set	(	long	xExp,
		long	yExp,
		const T &	value
	)

Changes the given coefficient of this polynomial.

There are no restrictions on the exponents xExp and yExp, and the new coefficient value may be zero.

Moreover, the underlying data structures ensure that this operation is cheap regardless of the exponents involved.

Python: This set() routine is available, but you can also set coefficients directly using syntax of the form p[xExp, yExp] = value.

Parameters

xExp	the exponent attached to x.
yExp	the exponent attached to y.
value	the new value of the corresponding coefficient.

◆ str() [1/2]

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ str() [2/2]

template<typename T >

std::string regina::Laurent2< T >::str	(	const char *	varX,
		const char *	varY = `nullptr`
	)		const

inline

Returns this polynomial as a human-readable string, using the given variable names instead of x and y.

Note: There is also the usual variant of str() which takes no arguments; that variant is inherited from the Output class.

Parameters

varX	the symbol to use for the variable x. This may be `null`, in which case the default symbol `'x'` will be used.
varY	the symbol to use for the variable y. This may be `null`, in which case the default symbol `'y'` will be used.

Returns: this polynomial as a human-readable string.

◆ swap()

template<typename T >

void regina::Laurent2< T >::swap ( Laurent2< T > & other )

inlinenoexcept

Swaps the contents of this and the given polynomial.

This is a fast (constant time) operation.

This and the given polynomial need not have the same range of non-zero coefficients.

Parameters

other the polynomial whose contents should be swapped with this.

◆ tightEncode()

template<typename T >

void regina::Laurent2< T >::tightEncode ( std::ostream & out ) const

inline

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

See the page on tight encodings for details.

Precondition: The coefficient type T must have a corresponding global regina::tightEncode() function. This is true for native C++ integer types, as well as Regina's arbitrary precision integer types (Integer and LargeInteger).

Python: Not present; use tightEncoding() instead.

Parameters

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

◆ tightEncoding()

template<typename T >

std::string regina::Laurent2< T >::tightEncoding

inline

Returns the tight encoding of this polynomial.

See the page on tight encodings for details.

Precondition: The coefficient type T must have a corresponding global regina::tightEncode() function. This is true for native C++ integer types, as well as Regina's arbitrary precision integer types (Integer and LargeInteger).

Returns: the resulting encoded string.

◆ utf8() [1/2]

template<class T , bool supportsUtf8 = false>

std::string regina::Output< T, supportsUtf8 >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ utf8() [2/2]

template<typename T >

std::string regina::Laurent2< T >::utf8	(	const char *	varX,
		const char *	varY = `nullptr`
	)		const

inline

Returns this polynomial as a human-readable string using unicode characters, using the given variable names instead of x and y.

This is similar to the output from str(), except that it uses unicode characters to make the output more pleasant to read. In particular, it makes use of superscript digits for exponents and a wider minus sign.

The string is encoded in UTF-8.

Note: There is also the usual variant of utf8() which takes no arguments; that variant is inherited from the Output class.

Parameters

varX	the symbol to use for the variable x. This may be `null`, in which case the default symbol `'x'` will be used.
varY	the symbol to use for the variable y. This may be `null`, in which case the default symbol `'y'` will be used.

Returns: this polynomial as a unicode-enabled human-readable string.

◆ writeTextLong()

void regina::ShortOutput< Laurent2< T > , supportsUtf8 >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present; instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<typename T >

void regina::Laurent2< T >::writeTextShort	(	std::ostream &	out,
		bool	utf8 = `false`,
		const char *	varX = `nullptr`,
		const char *	varY = `nullptr`
	)		const

Writes this polynomial to the given output stream, using the given variable names instead of x and y.

If utf8 is passed as true then unicode superscript characters will be used for exponents and the minus sign; these will be encoded using UTF-8. This will make the output nicer, but will require more complex fonts to be available on the user's machine.

Python: Not present; use str() or utf8() instead.

Parameters

out	the output stream to which to write.
utf8	`true` if unicode characters may be used.
varX	the symbol to use for the variable x. This may be `null`, in which case the default symbol `'x'` will be used.
varY	the symbol to use for the variable y. This may be `null`, in which case the default symbol `'y'` will be used.

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

link/link.h
maths/laurent2.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Coefficient

Constructor & Destructor Documentation

◆ Laurent2() [1/8]

◆ Laurent2() [2/8]

◆ Laurent2() [3/8]

◆ Laurent2() [4/8]

◆ Laurent2() [5/8]

◆ Laurent2() [6/8]

◆ Laurent2() [7/8]

◆ Laurent2() [8/8]

Member Function Documentation

◆ detail()

◆ init() [1/2]

◆ init() [2/2]

◆ invertX()

◆ invertY()

◆ isZero()

◆ negate()

◆ operator!=()

◆ operator()()

◆ operator*=() [1/2]

◆ operator*=() [2/2]

◆ operator+=()

◆ operator-=()

◆ operator/=()

◆ operator<()

◆ operator<=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ operator>()

◆ operator>=()

◆ set()

◆ str() [1/2]

◆ str() [2/2]

◆ swap()

◆ tightEncode()

◆ tightEncoding()

◆ utf8() [1/2]

◆ utf8() [2/2]

◆ writeTextLong()

◆ writeTextShort()