regina::detail::FaceBase< dim, subdim > Class Template Reference
Implementation details

Helper class that provides core functionality for a subdim-face in the skeleton of a dim-dimensional triangulation. More...

`#include <triangulation/detail/face.h>`

Inheritance diagram for regina::detail::FaceBase< dim, subdim >:

## Public Member Functions

size_t | index () const
| Returns the index of this face within the underlying triangulation. More...
Triangulation< dim > * | triangulation () const
| Returns the triangulation to which this face belongs. More...
Component< dim > * | component () const
| Returns the component of the triangulation to which this face belongs. More...
BoundaryComponent< dim > * | boundaryComponent () const
| Returns the boundary component of the triangulation to which this face belongs. More...
bool | isBoundary () const
| Determines if this face lies entirely on the boundary of the triangulation. More...
template<int lowerdim>
Face< dim, lowerdim > * | face (int face) const
| Returns the lowerdim-face of the underlying triangulation that appears as the given lowerdim-dimensional subface of this face. More...
template<int lowerdim>
Perm< dim+1 > | faceMapping (int face) const
| Examines the given lowerdim-dimensional subface of this face, and returns the mapping between the underlying lowerdim-face of the triangulation and the individual vertices of this face. 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
| Writes a detailed text representation of this object to the given output stream. More...
size_t | degree () const
| Returns the degree of this face. More...
const FaceEmbedding< dim, dim - codim > & | embedding (size_t index) const
| Returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation. More...
std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator | begin () const
| A begin function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator | end () const
| An end function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation. More...
const FaceEmbedding< dim, dim - codim > & | front () const
| Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
const FaceEmbedding< dim, dim - codim > & | back () const
| Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation. More...
bool | inMaximalForest () const
| Determines whether a codimension-1-face represents a dual edge in the maximal forest that has been chosen for the dual 1-skeleton of the triangulation. More...
bool | isValid () const
| Determines if this face is valid. More...
bool | hasBadIdentification () const
| Determines if this face is identified with itself under a non-identity permutation. More...
bool | hasBadLink () const
| Determines if this face does not have an appropriate link. More...
bool | isLinkOrientable () const
| Determines if the link of this face is orientable. More...
size_t | markedIndex () const
| Returns the index at which this object is stored in an MarkedVector. 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...

## Static Public Member Functions

static Perm< dim+1 > | ordering (unsigned face)
| Given a subdim-face number within a dim-dimensional simplex, returns the corresponding canonical ordering of the simplex vertices. More...
static unsigned | faceNumber (Perm< dim+1 > vertices)
| Identifies which subdim-face in a dim-dimensional simplex is represented by the first (subdim + 1) elements of the given permutation. More...
static bool | containsVertex (unsigned face, unsigned vertex)
| Tests whether the given subdim-face of a dim-dimensional simplex contains the given vertex of the simplex. More...

## Static Public Attributes

static constexpr int | nFaces
| The total number of subdim-dimensional faces in each dim-dimensional simplex. More...

## Protected Member Functions

| FaceBase (Component< dim > *component)
| Creates a new face. More...
void | push_back (const FaceEmbedding< dim, dim - codim > &emb)
| Internal routine to help build the skeleton of a triangulation. More...
void | markBadIdentification ()
| Marks this face as having a non-identity self-identification. More...
void | markBadLink ()
| Marks this face as having a bad link. More...
void | markLinkNonorientable ()
| Marks the link of this face as non-orientable. More...

## Friends

class | Triangulation< dim >
class | TriangulationBase< dim >

## Detailed Description

### template<int dim, int subdim>
class regina::detail::FaceBase< dim, subdim >

Helper class that provides core functionality for a subdim-face in the skeleton of a dim-dimensional triangulation.

Each subdim-face is described by a Face<dim, subdim> object, which uses this as a base class. End users should not need to refer to FaceBase directly.

See the Face template class notes for further information.

Python:\n This base class is not present, but the "end user" class
  Face<dim, subdim> is.

Template Parameters

  dim | the dimension of the underlying triangulation. This must be between 2 and 15 inclusive.
  subdim | the dimension of the faces that this class represents. This must be between 0 and dim-1 inclusive.

## Member Function Documentation

## back()

const FaceEmbedding< dim, dim - codim > & regina::detail::FaceStorage< dim, codim >::back | ( |  | ) | const

inline inherited

Returns the last appearance of this face within a top-dimensional simplex of the underlying triangluation.

This is equivalent to calling `embedding(degree()-1)`.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where the appearances of a face are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle). In particular, for a boundary face of codimension 2, both front() and back() will refer to the two appearances of this face on the (dim-1)-dimensional boundary.

Returns
  details of the last appearance.

## begin()

std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator regina::detail::FaceStorage< dim, codim >::begin | ( |  | ) | const

inline inherited

A begin function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

An iteration from begin() to end() will run through degree() appearances in total.

Python:\n Not present. However, Python users can call
  the Python-only routine embeddings(), which will return all appearances (from begin() through to end()) in a Python sequence.

Returns
  a iterator that points to the first appearance.

## degree()

size_t regina::detail::FaceStorage< dim, codim >::degree | ( |  | ) | const

inline inherited

Returns the degree of this face.

This is the number of different ways in which the face appears within the various top-dimensional simplices of the underlying triangulation.

Note that if this face appears multiple times within the same top-dimensional simplex, then it will be counted multiple times by this routine.

Returns
  the degree of this face.

## detail()

std::string regina::Output< Face< dim, subdim > , false >::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.

## embedding()

const FaceEmbedding< dim, dim - codim > & regina::detail::FaceStorage< dim, codim >::embedding | ( | size_t | index | ) | const

inline inherited

Returns one of the ways in which this face appears within a top-dimensional simplex of the underlying triangluation.

For convenience, you can also use begin() and end() to iterate through all such appearances.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

Parameters

  index | the index of the requested appearance. This must be between 0 and degree()-1 inclusive.

Returns
  details of the requested appearance.

## end()

std::vector< FaceEmbedding< dim, dim - codim > >::const_iterator regina::detail::FaceStorage< dim, codim >::end | ( |  | ) | const

inline inherited

An end function for iterating through all appearances of this face within the various top-dimensional simplices of the underlying triangulation.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where these appearances are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle).

An iteration from begin() to end() will run through degree() appearances in total.

Python:\n Not present. However, Python users can call
  the Python-only routine embeddings(), which will return all appearances (from begin() through to end()) in a Python sequence.

Returns
  a "beyond the end" iterator that comes immediately after the last appearance.

## front()

const FaceEmbedding< dim, dim - codim > & regina::detail::FaceStorage< dim, codim >::front | ( |  | ) | const

inline inherited

Returns the first appearance of this face within a top-dimensional simplex of the underlying triangluation.

This is equivalent to calling `*begin()`, or `embedding(0)`.

In most cases, the ordering of appearances is arbitrary. The exception is for codimension 2, where the appearances of a face are ordered in a way that follows the link around the face (which in codimension 2 is always a path or a cycle). In particular, for a boundary face of codimension 2, both front() and back() will refer to the two appearances of this face on the (dim-1)-dimensional boundary.

Returns
  details of the first appearance.

## hasBadIdentification()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::hasBadIdentification | ( |  | ) | const

inherited

Determines if this face is identified with itself under a non-identity permutation.

For example, if this face is an edge then this routine tests whether the edge is identified with itself in reverse.

Such a face will always be marked as invalid. Note that, for standard dimensions dim, there are other types of invalid faces also. See isValid() for a full discussion of what it means for a face to be valid.

Returns
  `true` if and only if this face is identified with itself under a non-identity permutation.

## hasBadLink()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::hasBadLink | ( |  | ) | const

inherited

Determines if this face does not have an appropriate link.

See condition (2) in the documentation for isValid() for a full description of what "appropriate" means.

This routine is only available where dim is one of Regina's standard dimensions, since testing this condition in arbitrary dimensions is undecidable. For higher dimensions dim, this routine is not present.

A face whose link is not appropriate will always be marked as invalid. Note that there are other types of invalid faces also. See isValid() for a full discussion of what it means for a face to be valid.

Returns
  `true` if and only if the link of this face is not appropriate.

## inMaximalForest()

bool regina::detail::FaceStorage< dim, codim >::inMaximalForest | ( |  | ) | const

inherited

Determines whether a codimension-1-face represents a dual edge in the maximal forest that has been chosen for the dual 1-skeleton of the triangulation.

This routine is only available for faces of codimension 1; that is, (dim-1)-faces of a dim-dimensional triangulation.

When the skeletal structure of a triangulation is first computed, a maximal forest in the dual 1-skeleton of the triangulation is also constructed. Each dual edge in this maximal forest represents a (dim-1)-face of the (primal) triangulation.

This maximal forest will remain fixed until the triangulation changes, at which point it will be recomputed (as will all other skeletal objects, such as connected components and so on). There is no guarantee that, when it is recomputed, the maximal forest will use the same dual edges as before.

This routine identifies whether this (dim-1)-face belongs to the dual forest. In this sense it performs a similar role to Simplex::facetInMaximalForest(), but this routine is typically easier to use.

If the skeleton has already been computed, then this routine is very fast (since it just returns a precomputed answer).

Returns
  `true` if and only if this (dim-1)-face represents a dual edge in the maximal forest.

## isLinkOrientable()

bool regina::detail::FaceOrientability< allowsNonorientable >::isLinkOrientable | ( |  | ) | const

inherited

Determines if the link of this face is orientable.

This routine is fast: it uses pre-computed information, and does not need to build a full triangulation of the link.

Warning
  If this face is identified with itself under a non-identity permutation (which makes the face invalid), then the return value of this routine is undefined.

Returns
  `true` if and only if the link is orientable.

## isValid()

bool regina::detail::FaceValidity< allowsInvalid, testLinks >::isValid | ( |  | ) | const

inherited

Determines if this face is valid.

There are several conditions that might make a subdim-face of a dim-dimensional triangulation invalid:

1. if the face is identified with itself under a non-identity permutation (e.g., an edge is identified with itself in reverse, or a triangle is identified with itself under a rotation);
2. if the face does not have an appropriate link. Here the meaning of "appropriate" depends upon the type of face:
   - for a face that belongs to some boundary facet(s) of the triangulation, its link must be a topological ball;
   - for a vertex that does not belong to any boundary facets, its link must be a closed (dim - 1)-manifold;
   - for a (subdim ≥ 1)-face that does not belong to any boundary facets, its link must be a topological sphere.

Condition (1) is tested for all dimensions subdim and dim. Condition (2) is more difficult, since it relies on undecidable problems. As a result, (2) is only tested when dim is one of Regina's standard dimensions.

If this face is invalid, then it is possible to find out why. In non-standard dimensions, this must mean that the face fails condition (1) above. In standard dimensions, you can call the functions hasBadIdentification() and/or hasBadLink() to determine whether the failure is due to conditions (1) or (2) respectively.

Returns
  for standard dimensions dim, returns `true` if and only if this face is valid according to both conditions (1) and (2) above; for non-standard dimensions dim, returns `true` if and only if this face is valid according to condition (1).

## markBadIdentification()

void regina::detail::FaceValidity< allowsInvalid, testLinks >::markBadIdentification | ( |  | ) |

protected inherited

Marks this face as having a non-identity self-identification.

## markBadLink()

void regina::detail::FaceValidity< allowsInvalid, testLinks >::markBadLink | ( |  | ) |

protected inherited

Marks this face as having a bad link.

## markLinkNonorientable()

void regina::detail::FaceOrientability< allowsNonorientable >::markLinkNonorientable | ( |  | ) |

protected inherited

Marks the link of this face as non-orientable.

## push_back()

void regina::detail::FaceStorage< dim, codim >::push_back | ( | const FaceEmbedding< dim, dim - codim > & | emb | ) |

inline protected inherited

Internal routine to help build the skeleton of a triangulation.

This routine pushes the given object onto the end of the internal list of appearances of this face within top-dimensional simplices.

Parameters

  emb | the appearance to push onto the end of the internal list.

## str()

std::string regina::Output< Face< dim, subdim > , false >::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:\n In addition to str(), this is also used as the
  Python "stringification" function `__str__()`.

Returns
  a short text representation of this object.

## utf8()

std::string regina::Output< Face< dim, subdim > , false >::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.

## Member Data Documentation

## nFaces

constexpr int regina::detail::FaceNumberingImpl< dim, subdim, lex >::nFaces

static constexpr inherited

The total number of subdim-dimensional faces in each dim-dimensional simplex.

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

- triangulation/detail/face.h

Copyright © 1999-2016, 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).