regina::NGroupExpression Class Reference
[Algebraic Structures]

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

#include <ngrouppresentation.h>

Inheritance diagram for regina::NGroupExpression:

regina::ShareableObject regina::boost::noncopyable

List of all members.

Public Member Functions

 NGroupExpression ()
 The terms that make up this expression.
 NGroupExpression (const NGroupExpression &cloneMe)
 Creates a new expression that is a clone of the given expression.
std::list
< NGroupExpressionTerm > & 
getTerms ()
 Returns the list of terms in this expression.
const std::list
< NGroupExpressionTerm > & 
getTerms () const
 Returns a constant reference to the list of terms in this expression.
unsigned long getNumberOfTerms () const
 Returns the number of terms in this expression.
NGroupExpressionTermgetTerm (unsigned long index)
 Returns the term at the given index in this expression.
const
NGroupExpressionTerm
getTerm (unsigned long index) const
 Returns a constant reference to the term at the given index in this expression.
unsigned long getGenerator (unsigned long index) const
 Returns the generator corresonding to the term at the given index in this expression.
long getExponent (unsigned long index) const
 Returns the exponent corresonding to the term at the given index in this expression.
void addTermFirst (const NGroupExpressionTerm &term)
 Adds the given term to the beginning of this expression.
void addTermFirst (unsigned long generator, long exponent)
 Adds the given term to the beginning of this expression.
void addTermLast (const NGroupExpressionTerm &term)
 Adds the given term to the end of this expression.
void addTermLast (unsigned long generator, long exponent)
 Adds the given term to the end of this expression.
NGroupExpressioninverse () const
 Returns a newly created expression that is the inverse of this expression.
NGroupExpressionpower (long exponent) const
 Returns a newly created expression that is this expression raised to the given power.
bool simplify (bool cyclic=false)
 Simplifies this expression.
bool substitute (unsigned long generator, const NGroupExpression &expansion, bool cyclic=false)
 Replaces every occurrence of the given generator with the given substite expression.
void writeXMLData (std::ostream &out) const
 Writes a chunk of XML containing this expression.
void writeToFile (NFile &out) const
 Writes this expression to the given old-style binary file.
virtual void writeTextShort (std::ostream &out) const
 The text representation will be of the form g2^4 g13^-5 g4.

Static Public Member Functions

static NGroupExpressionreadFromFile (NFile &in)
 Reads an expression from the given old-style binary file.


Detailed Description

Represents an expression involving generators from a group presentation.

An expression is represented as 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

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.

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.

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.

unsigned long regina::NGroupExpression::getNumberOfTerms (  )  const [inline]

Returns the number of terms in this expression.

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.

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.

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.

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.

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.

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.

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.

void regina::NGroupExpression::writeToFile ( NFile out  )  const

Writes this expression to the given old-style binary file.

Deprecated:
For the preferred way to write data to file, see writeXMLData() instead.
Precondition:
The given file is currently opened for writing.
Python:
Not present.
Parameters:
out the file to which to write.

static NGroupExpression* regina::NGroupExpression::readFromFile ( NFile in  )  [static]

Reads an expression from the given old-style binary file.

The expression will be newly allocated, and responsibility for its destruction lies with the caller of this routine.

Deprecated:
For the preferred way of reading group presentations from file, see class NXMLGroupPresentationReader instead.
Precondition:
The given file is currently opened for reading.
Python:
Not present.
Parameters:
in the file from which to read.
Returns:
a newly allocated expression read from the given file, or 0 if problems arose.

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.


The documentation for this class was generated from the following file:
Copyright © 1999-2006, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).