regina::NGroupExpression Class Reference
Algebraic Structures

Represents an expression involving generators from a group presentation or a free group. More...

`#include <algebra/ngrouppresentation.h>`

Inheritance diagram for regina::NGroupExpression:

## Public Member Functions

| NGroupExpression ()
| The terms that make up this expression. More...
| NGroupExpression (const NGroupExpression &cloneMe)
| Creates a new expression that is a clone of the given expression. More...
std::list< NGroupExpressionTerm > & | getTerms ()
| Returns the list of terms in this expression. More...
const std::list < NGroupExpressionTerm > & | getTerms () const
| Returns a constant reference to the list of terms in this expression. More...
unsigned long | getNumberOfTerms () const
| Returns the number of terms in this expression. More...
unsigned long | wordLength () const
| Returns the length of the word, i.e. More...
void | erase ()
| Erases all terms from this this word. More...
NGroupExpressionTerm & | getTerm (unsigned long index)
| Returns the term at the given index in this expression. More...
const NGroupExpressionTerm & | getTerm (unsigned long index) const
| Returns a constant reference to the term at the given index in this expression. More...
unsigned long | getGenerator (unsigned long index) const
| Returns the generator corresonding to the term at the given index in this expression. More...
long | getExponent (unsigned long index) const
| Returns the exponent corresonding to the term at the given index in this expression. More...
void | addTermFirst (const NGroupExpressionTerm &term)
| Adds the given term to the beginning of this expression. More...
void | addTermFirst (unsigned long generator, long exponent)
| Adds the given term to the beginning of this expression. More...
void | addTermLast (const NGroupExpressionTerm &term)
| Adds the given term to the end of this expression. More...
void | addTermLast (unsigned long generator, long exponent)
| Adds the given term to the end of this expression. More...
void | addTermsLast (const NGroupExpression &word)
| Multiplies *this on the right by word. More...
void | addTermsFirst (const NGroupExpression &word)
| Multiplies *this on the left by word. More...
void | cycleRight ()
| Given a word of the form g_i1^j1 g_i2^j2 ... More...
void | cycleLeft ()
| Given a word of the form g_i1^j1 g_i2^j2 ... More...
NGroupExpression * | inverse () const
| Returns a newly created expression that is the inverse of this expression. More...
void | invert ()
| Inverts this expression. More...
NGroupExpression * | power (long exponent) const
| Returns a newly created expression that is this expression raised to the given power. More...
bool | simplify (bool cyclic=false)
| Simplifies this expression. More...
bool | substitute (unsigned long generator, const NGroupExpression &expansion, bool cyclic=false)
| Replaces every occurrence of the given generator with the given substite expression. More...
void | writeXMLData (std::ostream &out) const
| Writes a chunk of XML containing this expression. More...
std::string | toTeX () const
| Returns a TeX representation of this expression. More...
void | writeTeX (std::ostream &out) const
| Writes a TeX represesentation of this expression to the given output stream. More...
void | writeText (std::ostream &out, bool shortword=false) const
| Writes a text representation of this expression to the given output stream, using either numbered generators or alphabetic generators. More...
virtual void | writeTextShort (std::ostream &out) const
| The text representation will be of the form `g2^4 g13^-5 g4`. More...
Public Member Functions inherited from regina::ShareableObject
| ShareableObject ()
| Default constructor that does nothing. More...
virtual | ~ShareableObject ()
| Default destructor that does nothing. More...
virtual void | writeTextLong (std::ostream &out) const
| Writes this object in long text format to the given output stream. More...
std::string | str () const
| Returns the output from writeTextShort() as a string. More...
std::string | toString () const
| A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
std::string | detail () const
| Returns the output from writeTextLong() as a string. More...
std::string | toStringLong () const
| A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...

## Additional Inherited Members

Protected Member Functions inherited from regina::boost::noncopyable
| noncopyable ()
| A constructor which does nothing. More...
| ~noncopyable ()
| A destructor which does nothing. More...

## Detailed Description

Represents an expression involving generators from a group presentation or a free group.

An expression is represented as word, i.e, a sequence of powers of generators all of which are multiplied in order. Each power of a generator corresponds to an individual NGroupExpressionTerm.

For instance, the expression `g1^2 g3^-1 g6` contains the three terms `g1^2`, `g3^-1` and `g6^1` in that order.

## Constructor & Destructor Documentation

regina::NGroupExpression::NGroupExpression | ( |  | ) |

inline

The terms that make up this expression.

Creates a new expression with no terms.

regina::NGroupExpression::NGroupExpression | ( | const NGroupExpression & | cloneMe | ) |

inline

Creates a new expression that is a clone of the given expression.

Parameters

  cloneMe | the expression to clone.

## Member Function Documentation

void regina::NGroupExpression::addTermFirst | ( | const NGroupExpressionTerm & | term | ) |

inline

Adds the given term to the beginning of this expression.

Parameters

  term | the term to add.

void regina::NGroupExpression::addTermFirst | ( | unsigned long | generator,
|  | long | exponent
| ) |  |

inline

Adds the given term to the beginning of this expression.

Parameters

  generator | the number of the generator corresponding to the new term.
  exponent | the exponent to which the given generator is raised.

void regina::NGroupExpression::addTermLast | ( | const NGroupExpressionTerm & | term | ) |

inline

Adds the given term to the end of this expression.

Parameters

  term | the term to add.

void regina::NGroupExpression::addTermLast | ( | unsigned long | generator,
|  | long | exponent
| ) |  |

inline

Adds the given term to the end of this expression.

Parameters

  generator | the number of the generator corresponding to the new term.
  exponent | the exponent to which the given generator is raised.

void regina::NGroupExpression::addTermsFirst | ( | const NGroupExpression & | word | ) |

Multiplies *this on the left by word.

void regina::NGroupExpression::addTermsLast | ( | const NGroupExpression & | word | ) |

Multiplies *this on the right by word.

void regina::NGroupExpression::cycleLeft | ( |  | ) |

Given a word of the form g_i1^j1 g_i2^j2 ...

g_in^jn converts the word into g_in^jn g_i1^j1 g_i1^j1 ... g_in-1^jn-1

void regina::NGroupExpression::cycleRight | ( |  | ) |

Given a word of the form g_i1^j1 g_i2^j2 ...

g_in^jn converts the word into g_i2^j2 ... g_in^jn g_i1^j1

void regina::NGroupExpression::erase | ( |  | ) |

inline

Erases all terms from this this word.

This effectively turns this word into the identity element.

long regina::NGroupExpression::getExponent | ( | unsigned long | index | ) | const

inline

Returns the exponent corresonding to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and getNumberOfTerms()-1 inclusive.

Returns
  the requested exponent.

unsigned long regina::NGroupExpression::getGenerator | ( | unsigned long | index | ) | const

inline

Returns the generator corresonding to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and getNumberOfTerms()-1 inclusive.

Returns
  the number of the requested generator.

unsigned long regina::NGroupExpression::getNumberOfTerms | ( |  | ) | const

inline

Returns the number of terms in this expression.

For instance, the expression `g1^2 g3^-1 g6` contains three terms. See also getWordLength().

Returns
  the number of terms.

NGroupExpressionTerm& regina::NGroupExpression::getTerm | ( | unsigned long | index | ) |

Returns the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Parameters

  index | the index of the term to return; this must be between 0 and getNumberOfTerms()-1 inclusive.

Returns
  the requested term.

const NGroupExpressionTerm& regina::NGroupExpression::getTerm | ( | unsigned long | index | ) | const

Returns a constant reference to the term at the given index in this expression.

Index 0 represents the first term, index 1 represents the second term and so on.

Warning
  This routine is O(n) where n is the number of terms in this expression.

Python:
  Not present; only the non-const version of this routine is available.

Parameters

  index | the index of the term to return; this must be between 0 and getNumberOfTerms()-1 inclusive.

Returns
  the requested term.

std::list< NGroupExpressionTerm > & regina::NGroupExpression::getTerms | ( |  | ) |

inline

Returns the list of terms in this expression.

These are the actual terms stored internally; any modifications made to this list will show up in the expression itself.

For instance, the expression `g1^2 g3^-1 g6` has list consisting of three terms `g1^2`, `g3^-1` and `g6^1` in that order.

Python:
  Not present; only the const version of this routine is available.

Returns
  the list of terms.

const std::list< NGroupExpressionTerm > & regina::NGroupExpression::getTerms | ( |  | ) | const

inline

Returns a constant reference to the list of terms in this expression.

For instance, the expression `g1^2 g3^-1 g6` has list consisting of three terms `g1^2`, `g3^-1` and `g6^1` in that order.

Python:
  This routine returns a python list of copied NGroupExpressionTerm objects. In particular, modifying this list or the terms within it will not modify the group expression from which they came.

Returns
  the list of terms.

NGroupExpression* regina::NGroupExpression::inverse | ( |  | ) | const

Returns a newly created expression that is the inverse of this expression.

The terms will be reversed and the exponents negated.

Returns
  the inverse of this expression.

void regina::NGroupExpression::invert | ( |  | ) |

Inverts this expression.

Does not allocate or deallocate anything.

NGroupExpression* regina::NGroupExpression::power | ( | long | exponent | ) | const

Returns a newly created expression that is this expression raised to the given power.

Note that the given exponent may be positive, zero or negative.

Parameters

  exponent | the power to which this expression should be raised.

Returns
  this expression raised to the given power.

bool regina::NGroupExpression::simplify | ( | bool | cyclic = `false` | ) |

Simplifies this expression.

Adjacent powers of the same generator will be combined, and terms with an exponent of zero will be removed. Note that it is not assumed that the underlying group is abelian.

You may declare that the expression is cyclic, in which case it is assumed that terms may be moved from the back to the front and vice versa. Thus expression `g1 g2 g1 g2 g1` simplifies to `g1^2 g2 g1 g2` if it is cyclic, but does not simplify at all if it is not cyclic.

Parameters

  cyclic | `true` if and only if the expression may be assumed to be cyclic.

Returns
  `true` if and only if this expression was changed.

bool regina::NGroupExpression::substitute | ( | unsigned long | generator,
|  | const NGroupExpression & | expansion,
|  | bool | cyclic = `false`
| ) |  |

Replaces every occurrence of the given generator with the given substite expression.

If the given generator was found, the expression will be simplified once the substitution is complete.

Parameters

  generator | the generator to be replaced.
  expansion | the substitute expression that will replace every occurrence of the given generator.
  cyclic | `true` if and only if the expression may be assumed to be cyclic; see simplify() for further details.

Returns
  `true` if and only if any substitutions were made.

std::string regina::NGroupExpression::toTeX | ( |  | ) | const

Returns a TeX representation of this expression.

See writeTeX() for details on how this is formed.

Returns
  a TeX representation of this expression.

unsigned long regina::NGroupExpression::wordLength | ( |  | ) | const

inline

Returns the length of the word, i.e.

the number of letters with exponent +1 or -1 for which this word is expressable as a product.

For instance, the expression `g1^2 g3^-1 g6` is a word of length four. See also getNumberOfTerms().

No attempt is made to remove redundant terms (so the word `g g^-1` will count as length two).

Returns
  the length of the word.

void regina::NGroupExpression::writeTeX | ( | std::ostream & | out | ) | const

Writes a TeX represesentation of this expression to the given output stream.

The text representation will be of the form `g_2^4 g_{13}^{-5} g_4`.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.

void regina::NGroupExpression::writeText | ( | std::ostream & | out,
|  | bool | shortword = `false`
| ) |  | const

Writes a text representation of this expression to the given output stream, using either numbered generators or alphabetic generators.

The text representation will be of the form `g2^4 g13^-5 g4`. If the shortword flag is true, it will assume your word is in an alphabet of no more than 26 letters, and will write the word using lower-case ASCII, i.e. `c^4 n^-5 e`.

Precondition
  If shortword is `true`, the number of generators in the corresponding group must be 26 or fewer.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.
  shortword | indicates whether to use numbered or alphabetic generators, as described above.

virtual void regina::NGroupExpression::writeTextShort | ( | std::ostream & | out | ) | const

virtual

The text representation will be of the form `g2^4 g13^-5 g4`.

Implements regina::ShareableObject.

void regina::NGroupExpression::writeXMLData | ( | std::ostream & | out | ) | const

Writes a chunk of XML containing this expression.

Python:
  Not present.

Parameters

  out | the output stream to which the XML should be written.

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

- algebra/ngrouppresentation.h

Copyright © 1999-2013, 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@debian.org).