Regina Calculation Engine
Public Types | Public Member Functions | Friends | List of all members
regina::Laurent2< T > Class Template Reference


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 >:
regina::ShortOutput< Laurent2< T >, true > regina::Output< Laurent2< T >, supportsUtf8 >

Public Types

typedef T Coefficient
 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...
 
 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...
 
Laurent2operator= (const Laurent2< T > &value)
 Sets this to be a copy of the given polynomial. More...
 
template<typename U >
Laurent2operator= (const Laurent2< U > &value)
 Sets this to be a copy of the given polynomial. More...
 
Laurent2operator= (Laurent2< T > &&value) noexcept=default
 Moves the contents of the given polynomial to this polynomial. More...
 
void swap (Laurent2< T > &other)
 Swaps the contents of this and the given polynomial. More...
 
void negate ()
 Negates this polynomial. More...
 
Laurent2operator*= (const T &scalar)
 Multiplies this polynomial by the given constant. More...
 
Laurent2operator/= (const T &scalar)
 Divides this polynomial by the given constant. More...
 
Laurent2operator+= (const Laurent2< T > &other)
 Adds the given polynomial to this. More...
 
Laurent2operator-= (const Laurent2< T > &other)
 Subtracts the given polynomial from this. More...
 
Laurent2operator*= (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...
 
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:

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 is designed to avoid deep copies wherever possible. In particular, it supports C++11 move constructors and move assignment. Functions that take or return objects by value are designed to be just as efficient as working with references or pointers, and long chains of operators such as a = b * c + d do not make unwanted deep copies.

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>
typedef T regina::Laurent2< T >::Coefficient

The type of each coefficient of the polynomial.

Constructor & Destructor Documentation

◆ Laurent2() [1/7]

template<typename T>
regina::Laurent2< T >::Laurent2 ( )
default

Creates the zero polynomial.

◆ Laurent2() [2/7]

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
xExpthe exponent d, which is attached to x.
yExpthe exponent e, which is attached to y.

◆ Laurent2() [3/7]

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
valuethe polynomial to clone.

◆ Laurent2() [4/7]

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
valuethe polynomial to move.

◆ Laurent2() [5/7]

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
toShiftthe polynomial to clone and shift.
xShiftthe integer d, which will be added to all exponents for x.
yShiftthe integer e, which will be added to all exponents for y.

◆ Laurent2() [6/7]

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
valuethe polynomial to clone.

◆ Laurent2() [7/7]

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.

This constructor takes a C++11 initialiser list, which should contain 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.
Parameters
coefficientsthe set of all non-zero coefficients, as outlined above.

Member Function Documentation

◆ detail()

std::string regina::Output< Laurent2< 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
xExpthe new exponent d, which is attached to x.
yExpthe new exponent e, which is attached to y.

◆ isZero()

template<typename T >
bool regina::Laurent2< T >::isZero ( ) const
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 field element 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
rhsthe 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. In contrast, C++ users must use the separate routine set(), due to the fact that in C++ this bracket operator is const.
Parameters
xExpthe exponent attached to x.
yExpthe 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 T &  scalar)
inline

Multiplies this polynomial by the given constant.

Parameters
scalarthe scalar factor to multiply by.
Returns
a reference to this polynomial.

◆ operator*=() [2/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
otherthe polynomial to multiply this 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
otherthe 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
otherthe 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
scalarthe scalar factor to divide by.
Returns
a reference to this polynomial.

◆ 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
valuethe 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
valuethe 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
valuethe 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
rhsthe polynomial to compare with this.
Returns
true if and only if this and the given polynomial are equal.

◆ 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
xExpthe exponent attached to x.
yExpthe exponent attached to y.
valuethe new value of the corresponding coefficient.

◆ str() [1/2]

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


Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python
In addition to str(), this is also used as the Python "stringification" function __str__().
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
varXthe symbol to use for the variable x. This may be null, in which case the default symbol 'x' will be used.
varYthe 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)
inline

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
otherthe polynomial whose contents should be swapped with this.

◆ utf8() [1/2]

std::string regina::Output< Laurent2< 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 fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string 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
varXthe symbol to use for the variable x. This may be null, in which case the default symbol 'x' will be used.
varYthe 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.
Parameters
outthe 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.
Parameters
outthe output stream to which to write.
utf8true if unicode characters may be used.
varXthe symbol to use for the variable x. This may be null, in which case the default symbol 'x' will be used.
varYthe symbol to use for the variable y. This may be null, in which case the default symbol 'y' will be used.
Returns
a reference to the given output stream.

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

Copyright © 1999-2021, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).