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


Represents a single-variable Laurent polynomial with coefficients of type T. More...

#include <maths/laurent.h>

Inheritance diagram for regina::Laurent< T >:
regina::ShortOutput< Laurent< T >, true > regina::Output< Laurent< T >, supportsUtf8 >

Public Types

typedef T Coefficient
 The type of each coefficient of the polynomial. More...
 

Public Member Functions

 Laurent ()
 Creates the zero polynomial. More...
 
 Laurent (long exponent)
 Creates the polynomial x^d for the given exponent d. More...
 
 Laurent (const Laurent< T > &value)
 Creates a new copy of the given polynomial. More...
 
template<typename U >
 Laurent (const Laurent< U > &value)
 Creates a new copy of the given polynomial. More...
 
 Laurent (Laurent< T > &&value) noexcept
 Moves the contents of the given polynomial to this new polynomial. More...
 
template<typename iterator >
 Laurent (long minExp, iterator begin, iterator end)
 
Creates a new polynomial from the given sequence of coefficients. More...
 
 Laurent (long minExp, std::initializer_list< T > coefficients)
 
Creates a new polynomial from a hard-coded sequence of coefficients. More...
 
 ~Laurent ()
 Destroys this polynomial. More...
 
void init ()
 Sets this to become the zero polynomial. More...
 
void init (long exponent)
 Sets this to become the polynomial x^d for the given exponent d. More...
 
template<typename iterator >
void init (long minExp, iterator begin, iterator end)
 
Sets this to become the polynomial described by the given sequence of coefficients. More...
 
long minExp () const
 Returns the smallest exponent that appears in this polynomial with a non-zero coefficient. More...
 
long maxExp () const
 Returns the largest exponent that appears in this polynomial with a non-zero coefficient. More...
 
bool isZero () const
 Returns whether this is the zero polynomial. More...
 
const T & operator[] (long exp) const
 
Returns the given coefficient of this polynomial. More...
 
void set (long exp, const T &value)
 
Changes the given coefficient of this polynomial. More...
 
bool operator== (const Laurent< T > &rhs) const
 Tests whether this and the given polynomial are equal. More...
 
bool operator!= (const Laurent< T > &rhs) const
 Tests whether this and the given polynomial are not equal. More...
 
Laurentoperator= (const Laurent< T > &value)
 Sets this to be a copy of the given polynomial. More...
 
template<typename U >
Laurentoperator= (const Laurent< U > &value)
 Sets this to be a copy of the given polynomial. More...
 
Laurentoperator= (Laurent< T > &&value) noexcept
 Moves the contents of the given polynomial to this polynomial. More...
 
void swap (Laurent< T > &other)
 Swaps the contents of this and the given polynomial. More...
 
void shift (long s)
 Multiplies this polynomial by x^s for some integer s. More...
 
void scaleUp (long k)
 Multiplies all exponents in this polynomial by k for some integer k. More...
 
void scaleDown (long k)
 Divides all exponents in this polynomial by k for some integer k. More...
 
void negate ()
 Negates this polynomial. More...
 
Laurentoperator*= (const T &scalar)
 Multiplies this polynomial by the given constant. More...
 
Laurentoperator/= (const T &scalar)
 Divides this polynomial by the given constant. More...
 
Laurentoperator+= (const Laurent< T > &other)
 Adds the given polynomial to this. More...
 
Laurentoperator-= (const Laurent< T > &other)
 Subtracts the given polynomial from this. More...
 
Laurentoperator*= (const Laurent< T > &other)
 Multiplies this by the given polynomial. More...
 
void writeTextShort (std::ostream &out, bool utf8=false, const char *variable=nullptr) const
 
Writes this polynomial to the given output stream, using the given variable name instead of x. More...
 
std::string str (const char *variable) const
 Returns this polynomial as a human-readable string, using the given variable name instead of x. More...
 
std::string utf8 (const char *variable) const
 Returns this polynomial as a human-readable string using unicode characters, using the given variable name instead of x. More...
 
template<typename U >
Laurent< T > & operator= (const Laurent< 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

template<typename U >
Laurent< U > operator+ (const Laurent< U > &, const Laurent< U > &)
 
template<typename U >
Laurent< U > operator+ (Laurent< U > &&, Laurent< U > &&)
 
template<typename U >
Laurent< U > operator- (const Laurent< U > &, const Laurent< U > &)
 
template<typename U >
Laurent< U > operator- (const Laurent< U > &, Laurent< U > &&)
 
template<typename U >
Laurent< U > operator- (Laurent< U > &&, Laurent< U > &&)
 
template<typename U >
Laurent< U > operator* (const Laurent< U > &, const Laurent< U > &)
 

Detailed Description

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


Represents a single-variable Laurent polynomial with coefficients of type T.

A Laurent polynomial differs from an ordinary polynomial in that it allows negative exponents (so, unlike the Polynomial class, you can represent both 2+3x and 1+1/x).

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 (any variations to this are noted in the method documentation), 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 dense (i.e., all coefficients are explicitly stored, including zero coefficients).

See also the class Laurent2, which describes Laurent polynomials in two variables.

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

Member Typedef Documentation

◆ Coefficient

template<typename T>
typedef T regina::Laurent< T >::Coefficient

The type of each coefficient of the polynomial.

Constructor & Destructor Documentation

◆ Laurent() [1/7]

template<typename T >
regina::Laurent< T >::Laurent ( )
inline

Creates the zero polynomial.

◆ Laurent() [2/7]

template<typename T >
regina::Laurent< T >::Laurent ( long  exponent)
inlineexplicit

Creates the polynomial x^d for the given exponent d.

Parameters
exponentthe exponent to use for the new polynomial.

◆ Laurent() [3/7]

template<typename T>
regina::Laurent< T >::Laurent ( const Laurent< 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.

◆ Laurent() [4/7]

template<typename T >
template<typename U >
regina::Laurent< T >::Laurent ( const Laurent< 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.

◆ Laurent() [5/7]

template<typename T>
regina::Laurent< T >::Laurent ( Laurent< T > &&  value)
inlinenoexcept

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.

◆ Laurent() [6/7]

template<typename T >
template<typename iterator >
regina::Laurent< T >::Laurent ( long  minExp,
iterator  begin,
iterator  end 
)
inline


Creates a new polynomial from the given sequence of coefficients.

The coefficients should appear in order from the smallest exponent term to the largest. The first coefficient in the sequence will be associated with the exponent minExp.

There is no problem if the first and/or last coefficient in the sequence is zero. An empty sequence will be treated as the zero polynomial.

This constructor induces a deep copy of the given range.

Precondition
Objects of type T can be assigned values from dereferenced iterators of type iterator.
Python
Instead of the iterators begin and end, this routine takes a python list of coefficients.
Parameters
minExpthe exponent corresponding to the first coefficient in the sequence.
beginthe beginning of the sequence of coefficients.
enda past-the-end iterator indicating the end of the sequence of coefficients.

◆ Laurent() [7/7]

template<typename T>
regina::Laurent< T >::Laurent ( long  minExp,
std::initializer_list< T >  coefficients 
)
inline


Creates a new polynomial from a hard-coded sequence of coefficients.

This constructor takes a C++11 initialiser list, which should contain the coefficients in order from the smallest exponent term to the largest. The first coefficient in the sequence will be associated with the exponent minExp.

There is no problem if the first and/or last coefficient in the sequence is zero. An empty sequence will be treated as the zero polynomial.

Python
Not available, but there is a Python constructor that takes a list of coefficients (which need not be constant).
Parameters
minExpthe exponent corresponding to the first coefficient in the sequence.
coefficientsthe full sequence of coefficients.

◆ ~Laurent()

template<typename T >
regina::Laurent< T >::~Laurent ( )
inline

Destroys this polynomial.

Member Function Documentation

◆ detail()

std::string regina::Output< Laurent< 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/3]

template<typename T >
void regina::Laurent< T >::init ( )
inline

Sets this to become the zero polynomial.

◆ init() [2/3]

template<typename T >
void regina::Laurent< T >::init ( long  exponent)
inline

Sets this to become the polynomial x^d for the given exponent d.

Parameters
exponentthe new exponent to use for this polynomial.

◆ init() [3/3]

template<typename T >
template<typename iterator >
void regina::Laurent< T >::init ( long  minExp,
iterator  begin,
iterator  end 
)


Sets this to become the polynomial described by the given sequence of coefficients.

The coefficients should appear in order from the smallest exponent term to the largest. The first coefficient in the sequence will be associated with the exponent minExp.

There is no problem if the first and/or last coefficient in the sequence is zero. An empty sequence will be treated as the zero polynomial.

This routine induces a deep copy of the given range.

Precondition
Objects of type T can be assigned values from dereferenced iterators of type iterator.
Python
Instead of the iterators begin and end, this routine takes a python list of coefficients.
Parameters
minExpthe exponent corresponding to the first coefficient in the sequence.
beginthe beginning of the sequence of coefficients.
enda past-the-end iterator indicating the end of the sequence of coefficients.

◆ isZero()

template<typename T >
bool regina::Laurent< T >::isZero ( ) const
inline

Returns whether this is the zero polynomial.

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

◆ maxExp()

template<typename T >
long regina::Laurent< T >::maxExp ( ) const
inline

Returns the largest exponent that appears in this polynomial with a non-zero coefficient.

If this is the zero polynomial, then this routine returns 0.

Returns
the largest exponent.

◆ minExp()

template<typename T >
long regina::Laurent< T >::minExp ( ) const
inline

Returns the smallest exponent that appears in this polynomial with a non-zero coefficient.

If this is the zero polynomial, then this routine returns 0.

Returns
the smallest exponent.

◆ negate()

template<typename T >
void regina::Laurent< T >::negate ( )
inline

Negates this polynomial.

This field element is changed directly.

◆ operator!=()

template<typename T>
bool regina::Laurent< T >::operator!= ( const Laurent< 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*=() [1/2]

template<typename T>
Laurent< T > & regina::Laurent< T >::operator*= ( const T &  scalar)

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>
Laurent< T > & regina::Laurent< T >::operator*= ( const Laurent< T > &  other)

Multiplies this by the given polynomial.

The given polynomial need not have the same minimum and/or maximum exponents as this.

Parameters
otherthe polynomial to multiply this by.
Returns
a reference to this polynomial.

◆ operator+=()

template<typename T>
Laurent< T > & regina::Laurent< T >::operator+= ( const Laurent< T > &  other)
inline

Adds the given polynomial to this.

The given polynomial need not have the same minimum and/or maximum exponents as this.

Warning
This routine may trigger a deep copy (depending upon the range of exponents used in other). Consider using the binary + operator instead, which is better able to avoid this deep copy where possible.
Parameters
otherthe polynomial to add to this.
Returns
a reference to this polynomial.

◆ operator-=()

template<typename T>
Laurent< T > & regina::Laurent< T >::operator-= ( const Laurent< T > &  other)
inline

Subtracts the given polynomial from this.

The given polynomial need not have the same minimum and/or maximum exponents as this.

Parameters
otherthe polynomial to subtract from this.
Returns
a reference to this polynomial.

◆ operator/=()

template<typename T>
Laurent< T > & regina::Laurent< 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>
Laurent< T > & regina::Laurent< T >::operator= ( const Laurent< T > &  value)

Sets this to be a copy of the given polynomial.

This and the given polynomial need not have the same minimum and/or maximum exponents.

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 >
Laurent& regina::Laurent< T >::operator= ( const Laurent< U > &  value)

Sets this to be a copy of the given polynomial.

This and the given polynomial need not have the same minimum and/or maximum exponents.

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>
Laurent< T > & regina::Laurent< T >::operator= ( Laurent< T > &&  value)
inlinenoexcept

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 minimum and/or maximum exponents.

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::Laurent< T >::operator== ( const Laurent< 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.

◆ operator[]()

template<typename T >
const T & regina::Laurent< T >::operator[] ( long  exp) const
inline


Returns the given coefficient of this polynomial.

There are no restrictions on the exponent exp.

Python
Python users can also use this operator to set cofficients; that is, you can write poly[exp] = value. In contrast, C++ users must use the separate routine set(), due to the fact that in C++ this square bracket operator is const.
Parameters
expthe exponent of the term whose coefficient should be returned.
Returns
the coefficient of the given term.

◆ scaleDown()

template<typename T >
void regina::Laurent< T >::scaleDown ( long  k)

Divides all exponents in this polynomial by k for some integer k.

This is equivalent to replacing the variable x of the polynomial with x1/k.

Both positive and negative scaling factors k are allowed.

Precondition
k is non-zero.
All exponents in this polynomial with non-zero coefficients are multiples of k.
Parameters
kthe scaling factor to divide exponents by.

◆ scaleUp()

template<typename T >
void regina::Laurent< T >::scaleUp ( long  k)

Multiplies all exponents in this polynomial by k for some integer k.

This is equivalent to replacing the variable x of the polynomial with xk.

Both positive and negative scaling factors k are allowed.

Precondition
k is non-zero.
Parameters
kthe scaling factor to multiply exponents by.

◆ set()

template<typename T>
void regina::Laurent< T >::set ( long  exp,
const T &  value 
)


Changes the given coefficient of this polynomial.

There are no restrictions on the exponent exp, and the new coefficient value may be zero.

Note, however, that it is expensive to set a non-zero coefficient whose exponent is larger than maxExp() or smaller than minExp(), since this will typically require deallocating and reallocating the full list of coefficients.

In contrast, setting a zero coefficient for the exponent maxExp() or minExp() is cheap, even though the range of non-zero coefficients changes as a result.

Python
This set() routine is available, but you can also set coefficients directly using syntax of the form p[exp] = value.
Parameters
expthe exponent of the term whose coefficient should be changed.
valuethe new value of this coefficient.

◆ shift()

template<typename T >
void regina::Laurent< T >::shift ( long  s)
inline

Multiplies this polynomial by x^s for some integer s.

Parameters
sthe power of x to multiply by.

◆ str() [1/2]

std::string regina::Output< Laurent< 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::Laurent< T >::str ( const char *  variable) const
inline

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

Note
There is also the usual variant of str() which takes no arguments; that variant is inherited from the Output class.
Parameters
variablethe symbol to use for the variable in this polynomial. This may be null, in which case the default variable x will be used.
Returns
this polynomial as a human-readable string.

◆ swap()

template<typename T>
void regina::Laurent< T >::swap ( Laurent< T > &  other)
inline

Swaps the contents of this and the given polynomial.

This is a fast (constant time) operation.

This and the given polynomial do not need to have the same minimum and/or maximum exponents.

Parameters
otherthe polynomial whose contents should be swapped with this.

◆ utf8() [1/2]

std::string regina::Output< Laurent< 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::Laurent< T >::utf8 ( const char *  variable) const
inline

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

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
variablethe symbol to use for the variable in this polynomial. This may be null, in which case the default variable x will be used.
Returns
this polynomial as a unicode-enabled human-readable string.

◆ writeTextLong()

void regina::ShortOutput< Laurent< 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::Laurent< T >::writeTextShort ( std::ostream &  out,
bool  utf8 = false,
const char *  variable = nullptr 
) const


Writes this polynomial to the given output stream, using the given variable name instead of x.

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.
variablethe symbol to use for the variable in this polynomial. This may be null, in which case the default variable x 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).