Regina 7.3 Calculation Engine
|
Represents a Laurent polynomial in the two variables x, y with coefficients of type T. More...
#include <maths/laurent2.h>
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... | |
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... | |
std::string | tightEncoding () const |
Returns the tight encoding of this object. More... | |
Static Public Member Functions | |
static Laurent2 | tightDecode (std::istream &input) |
Reconstructs a polynomial from its given tight encoding. More... | |
static Laurent2< T > | tightDecoding (const std::string &enc) |
Reconstructs an object of type T from its given tight encoding. More... | |
Friends | |
class | Link |
template<typename U > | |
Laurent2< U > | operator* (const Laurent2< U > &, const Laurent2< U > &) |
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² + y/x - 1/y³
).
The type T must represent a ring with no zero divisors. In particular, it must:
x = int
and tests of the form x == int
and x < int
;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.
using regina::Laurent2< T >::Coefficient = T |
The type of each coefficient of the polynomial.
|
default |
Creates the zero polynomial.
|
inlineexplicit |
Creates the polynomial x^d y^e
for the given exponents d and e.
xExp | the exponent d, which is attached to x. |
yExp | the exponent e, which is attached to y. |
|
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.
value | the polynomial to clone. |
|
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.
value | the polynomial to move. |
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.
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. |
|
inline |
Creates a new copy of the given polynomial.
This constructor induces a deep copy of value.
value | the polynomial to clone. |
|
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).
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. |
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. |
|
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:
coefficients | the set of all non-zero coefficients, as outlined above. |
|
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.
|
inline |
Sets this to become the zero polynomial.
|
inline |
Sets this to become the polynomial x^d y^e
for the given exponents d and e.
xExp | the new exponent d, which is attached to x. |
yExp | the new exponent e, which is attached to y. |
|
inline |
Replaces x
with x^-1
in this polynomial.
This polynomial is changed directly.
|
inline |
Replaces y
with y^-1
in this polynomial.
This polynomial is changed directly.
|
inline |
Returns whether this is the zero polynomial.
true
if and only if this is the zero polynomial.
|
inline |
Negates this polynomial.
This polynomial is changed directly.
|
inline |
Tests whether this and the given polynomial are not equal.
rhs | the polynomial to compare with this. |
true
if and only if this and the given polynomial are not equal.
|
inline |
Returns the given coefficient of this polynomial.
There are no restrictions on the exponents xExp and yExp.
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()
.xExp | the exponent attached to x. |
yExp | the exponent attached to y. |
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.
other | the polynomial to multiply this by. |
|
inline |
Multiplies this polynomial by the given constant.
scalar | the scalar factor to multiply by. |
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.
other | the polynomial to add to this. |
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.
other | the polynomial to subtract from this. |
|
inline |
Divides this polynomial by the given constant.
This uses the division operator /= for the coefficient type T.
scalar | the scalar factor to divide by. |
|
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.
rhs | the polynomial to compare with this. |
true
if and only if this is less than the given polynomial under the total order that Regina uses.
|
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.
rhs | the polynomial to compare with this. |
true
if and only if this is less than or equal to the given polynomial under the total order that Regina uses.
|
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.
value | the polynomial to copy. |
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.
value | the polynomial to copy. |
|
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.
value | the polynomial to move. |
|
inline |
Tests whether this and the given polynomial are equal.
rhs | the polynomial to compare with this. |
true
if and only if this and the given polynomial are equal.
|
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.
rhs | the polynomial to compare with this. |
true
if and only if this is greater than the given polynomial under the total order that Regina uses.
|
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.
rhs | the polynomial to compare with this. |
true
if and only if this is greater than or equal to the given polynomial under the total order that Regina uses. 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.
p[xExp, yExp] = value
.xExp | the exponent attached to x. |
yExp | the exponent attached to y. |
value | the new value of the corresponding coefficient. |
|
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.
__str__()
will use precisely this function, and for most classes the Python __repr__()
function will incorporate this into its output.
|
inline |
Returns this polynomial as a human-readable string, using the given variable names instead of x
and y
.
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. |
|
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.
other | the polynomial whose contents should be swapped with this. |
|
inlinestatic |
Reconstructs a polynomial 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.
InvalidInput | The given input stream does not begin with a tight encoding of a two-variable Laurent polynomial. |
input | an input stream that begins with the tight encoding for a two-variable Laurent polynomial. |
|
inlinestaticinherited |
Reconstructs an object of type T from its given tight encoding.
See the page on tight encodings for details.
The tight encoding should 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).
InvalidArgument | The given string is not a tight encoding of an object of type T. |
enc | the tight encoding for an object of type T. |
|
inline |
Writes the tight encoding of this polynomial to the given output stream.
See the page on tight encodings for details.
out | the output stream to which the encoded string will be written. |
|
inlineinherited |
Returns the tight encoding of this object.
See the page on tight encodings for details.
FailedPrecondition | This may be thrown for some classes T if the object is in an invalid state. If this is possible, then a more detailed explanation of "invalid" can be found in the class documentation for T, under the member function T::tightEncode(). See FacetPairing::tightEncode() for an example of this. |
|
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.
|
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.
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. |
|
inlineinherited |
A default implementation for detailed output.
This routine simply calls T::writeTextShort() and appends a final newline.
out | the output stream to which to write. |
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.
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. |