Regina Calculation Engine

Represents an expression involving generators from a group presentation or a free group. More...
#include <algebra/ngrouppresentation.h>
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...  
NGroupExpression (const std::string &input, bool *valid=NULL)  
Attempts to interpret the given input string as a word in a group. More...  
NGroupExpression &  operator= (const NGroupExpression &cloneMe) 
Makes this expression a clone of the given expression. More...  
bool  operator== (const NGroupExpression &comp) const 
Equality operator. More...  
bool  operator!= (const NGroupExpression &comp) const 
Inequality operator. More...  
std::list< NGroupExpressionTerm > &  terms () 
Returns the list of terms in this expression. More...  
const std::list < NGroupExpressionTerm > &  terms () const 
Returns a constant reference to the list of terms in this expression. More...  
REGINA_DEPRECATED std::list < NGroupExpressionTerm > &  getTerms () 
Deprecated routine that returns the list of terms in this expression. More...  
REGINA_DEPRECATED const std::list < NGroupExpressionTerm > &  getTerms () const 
Deprecated routine that returns a constant reference to the list of terms in this expression. More...  
size_t  countTerms () const 
Returns the number of terms in this expression. More...  
REGINA_DEPRECATED size_t  getNumberOfTerms () const 
Deprecated routine that returns the number of terms in this expression. More...  
size_t  wordLength () const 
Returns the length of the word, i.e. More...  
bool  isTrivial () const 
Tests whether this is the trivial (unit) word. More...  
void  erase () 
Erases all terms from this this word. More...  
NGroupExpressionTerm &  term (size_t index) 
Returns the term at the given index in this expression. More...  
const NGroupExpressionTerm &  term (size_t index) const 
Returns a constant reference to the term at the given index in this expression. More...  
REGINA_DEPRECATED NGroupExpressionTerm &  getTerm (size_t index) 
Deprecated routine that returns the term at the given index in this expression. More...  
REGINA_DEPRECATED const NGroupExpressionTerm &  getTerm (size_t index) const 
Deprecated routine that returns a constant reference to the term at the given index in this expression. More...  
unsigned long  generator (size_t index) const 
Returns the generator corresonding to the term at the given index in this expression. More...  
REGINA_DEPRECATED unsigned long  getGenerator (size_t index) const 
Deprecated routine that returns the generator corresponding to the term at the given index in this expression. More...  
long  exponent (size_t index) const 
Returns the exponent corresonding to the term at the given index in this expression. More...  
REGINA_DEPRECATED long  getExponent (size_t index) const 
Deprecated routine that returns the exponent corresponding 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  addTermsFirst (const NGroupExpression &word) 
Multiplies this expression on the left by the given word. More...  
void  addTermsLast (const NGroupExpression &word) 
Multiplies this expression on the right by the given word. More...  
bool  addStringFirst (const std::string &input) 
Multiplies this expression on the left by the word respresented by the given string. More...  
bool  addStringLast (const std::string &input) 
Multiplies this expression on the right by the word respresented by the given string. More...  
void  cycleRight () 
Cycles this word by moving the leftmost term around to the rightmost. More...  
void  cycleLeft () 
Cycles this word by moving the rightmost term around to the leftmost. 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...  
std::list< std::map< unsigned long, NGroupExpressionTerm > >  relabellingsThisToOther (const NGroupExpression &other, bool cyclic=false) const 
Determines whether or not one can relabel the generators in this word to obtain the given other word. 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, bool utf8=false) const 
Writes a text representation of this expression to the given output stream, using either numbered generators or alphabetic generators. More...  
void  writeTextShort (std::ostream &out) const 
Writes a short text representation of this object 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...  
REGINA_DEPRECATED std::string  toString () const 
A deprecated alias for str(). More...  
REGINA_DEPRECATED std::string  toStringLong () const 
A deprecated alias for detail(). More...  
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.

inline 
The terms that make up this expression.
Creates a new expression with no terms.

inline 
Creates a new expression that is a clone of the given expression.
cloneMe  the expression to clone. 
regina::NGroupExpression::NGroupExpression  (  const std::string &  input, 
bool *  valid = NULL 

) 
Attempts to interpret the given input string as a word in a group.
Regina can recognise strings in the following four basic forms:
a^7b^2
aaaaaaaBB
a^7B^2
g0^7g1^2
The string may contain whitespace, which will simply be ignored.
The argument valid may be null
, but if it is nonnull then the boolean it points to will be used for error reporting. This routine sets valid to true
if the string was successfully interpreted, or false
if the algorithm failed to interpret the string.
Regardless of whether valid is null
, if the string could not be interpreted then this expression will be initialised to the trivial word.
null
.input  the input string that is to be interpreted. 
valid  used for error reporting as described above, or null if no error reporting is required. 
bool regina::NGroupExpression::addStringFirst  (  const std::string &  input  ) 
Multiplies this expression on the left by the word respresented by the given string.
See the stringbased constructor NGroupExpression(const std::string&, bool*) for further information on how this string should be formatted.
If the given string cannot be interpreted as a word in a group, then this expression will be left untouched.
input  a string representation of the word to multiply with this expression. 
true
if the given string could interpreted (and therefore the multiplication was completed successfully), or false
if the given string could not be interpreted (in which case this expression will be left untouched). bool regina::NGroupExpression::addStringLast  (  const std::string &  input  ) 
Multiplies this expression on the right by the word respresented by the given string.
See the stringbased constructor NGroupExpression(const std::string&, bool*) for further information on how this string should be formatted.
If the given string cannot be interpreted as a word in a group, then this expression will be left untouched.
input  a string representation of the word to multiply with this expression. 
true
if the given string could interpreted (and therefore the multiplication was completed successfully), or false
if the given string could not be interpreted (in which case this expression will be left untouched).

inline 
Adds the given term to the beginning of this expression.
term  the term to add. 

inline 
Adds the given term to the beginning of this expression.
generator  the number of the generator corresponding to the new term. 
exponent  the exponent to which the given generator is raised. 

inline 
Adds the given term to the end of this expression.
term  the term to add. 

inline 
Adds the given term to the end of this expression.
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 expression on the left by the given word.
This expression will be modified directly.
word  the word to multiply with this expression. 
void regina::NGroupExpression::addTermsLast  (  const NGroupExpression &  word  ) 
Multiplies this expression on the right by the given word.
This expression will be modified directly.
word  the word to multiply with this expression. 

inline 
Returns the number of terms in this expression.
For instance, the expression g1^2 g3^1 g6
contains three terms. See also getWordLength().
void regina::NGroupExpression::cycleLeft  (  ) 
Cycles this word by moving the rightmost term around to the leftmost.
All other terms shift one step to the right.
If the word is of the form g_i1^j1 g_i2^j2 ... g_in^jn
, this converts it into the word g_in^jn g_i1^j1 g_i1^j1 ... g_in1^jn1
.
void regina::NGroupExpression::cycleRight  (  ) 
Cycles this word by moving the leftmost term around to the rightmost.
All other terms shift one step to the left.
If the word is of the form g_i1^j1 g_i2^j2 ... g_in^jn
, this converts it into the word g_i2^j2 ... g_in^jn g_i1^j1
.

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 humanreadable, 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 
Erases all terms from this this word.
This effectively turns this word into the identity element.

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.
index  the index of the term to return; this must be between 0 and countTerms()1 inclusive. 

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.
index  the index of the term to return; this must be between 0 and countTerms()1 inclusive. 

inline 
Deprecated routine that returns the exponent corresponding to the term at the given index in this expression.

inline 
Deprecated routine that returns the generator corresponding to the term at the given index in this expression.

inline 
Deprecated routine that returns the number of terms in this expression.

inline 
Deprecated routine that returns the term at the given index in this expression.

inline 
Deprecated routine that returns a constant reference to the term at the given index in this expression.

inline 
Deprecated routine that returns the list of terms in this expression.

inline 
Deprecated routine that returns a constant reference to the list of terms in this expression.
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.
void regina::NGroupExpression::invert  (  ) 
Inverts this expression.
Does not allocate or deallocate anything.

inline 
Tests whether this is the trivial (unit) word.
No attempt is made to remove redundant terms (so the word g g^1
will be treated as nontrivial).
true
if and only if this is the trivial word.

inline 
Inequality operator.
Checks to see whether or not these two words represent different literal strings.
comp  the expression to compare against this. 
true
if this and the given string literal are not identical.

inline 
Makes this expression a clone of the given expression.
cloneMe  the expression to clone. 

inline 
Equality operator.
Checks to see whether or not these two words represent the same literal string.
comp  the expression to compare against this. 
true
if this and the given string literal are identical. 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.
exponent  the power to which this expression should be raised. 
std::list< std::map< unsigned long, NGroupExpressionTerm > > regina::NGroupExpression::relabellingsThisToOther  (  const NGroupExpression &  other, 
bool  cyclic = false 

)  const 
Determines whether or not one can relabel the generators in this word to obtain the given other word.
If so, returns a nonempty list of all such relabellings. If not, returns an empty list.
Relabellings are partiallydefined permutations on the generator set, also allowing for possible inversions if cyclic is true
.
true
, then both this word and other have been cyclically reduced.other  the word to compare against this. 
cyclic  if false we get a list of exact relabellings from this word to other. If true , it can be up to cyclic permutation and inversion. 
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.
cyclic  true if and only if the expression may be assumed to be cyclic. 
true
if and only if this expression was changed.

inherited 
Returns a short text representation of this object.
This text should be humanreadable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.
__str__()
.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.
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. 
true
if and only if any substitutions were made. NGroupExpressionTerm& regina::NGroupExpression::term  (  size_t  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.
index  the index of the term to return; this must be between 0 and countTerms()1 inclusive. 
const NGroupExpressionTerm& regina::NGroupExpression::term  (  size_t  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.
index  the index of the term to return; this must be between 0 and countTerms()1 inclusive. 

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.

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.

inherited 
A deprecated alias for str().

inherited 
A deprecated alias for detail().
std::string regina::NGroupExpression::toTeX  (  )  const 
Returns a TeX representation of this expression.
See writeTeX() for details on how this is formed.

inherited 
Returns a short text representation of this object using unicode characters.
Like str(), this text should be humanreadable, 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 UTF8.

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 countTerms().
No attempt is made to remove redundant terms (so the word g g^1
will count as length two).
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
.
out  the output stream to which to write. 
void regina::NGroupExpression::writeText  (  std::ostream &  out, 
bool  shortword = false , 

bool  utf8 = 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 lowercase ASCII, i.e., c^4 n^5 e
. If the utf8 flag is true
, all exponents will be written using superscript characters encoded in UTF8.
true
, the number of generators in the corresponding group must be 26 or fewer.out  the output stream to which to write. 
shortword  indicates whether to use numbered or alphabetic generators, as described above. 
utf8  true if exponents should be written using unicode superscript characters, or false if they should be written using a caret (^) symbol. 

inherited 
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::NGroupExpression::writeTextShort  (  std::ostream &  out  )  const 
Writes a short text representation of this object to the given output stream.
The text representation will be of the form g2^4 g13^5 g4
.
out  the output stream to which to write. 
void regina::NGroupExpression::writeXMLData  (  std::ostream &  out  )  const 
Writes a chunk of XML containing this expression.
out  the output stream to which the XML should be written. 