regina::BoundaryComponent< dim > Class Template Reference
Triangulations | Generic triangulations

A component of the boundary of a dim-manifold triangulation. More...

`#include <triangulation/generic.h>`

Inheritance diagram for regina::BoundaryComponent< dim >:

## Public Member Functions

size_t | index () const
| Returns the index of this boundary component in the underlying triangulation. More...
bool | isOrientable () const
| Determines if this boundary component is orientable. 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...
const Triangulation< dim-1 > * | build () const
| Returns the full (dim-1)-dimensional triangulation of this boundary component. More...
bool | isReal () const
| Determines if this boundary component is real. More...
bool | isIdeal () const
| Determines if this boundary component is ideal. More...
bool | isInvalidVertex () const
| Determines if this boundary component consists of a single invalid vertex and nothing else. 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 | size () const
| Returns the number of (dim-1)-faces in this boundary component. More...
size_t | countRidges () const
| Returns the number of (dim-2)-faces in this boundary component. More...
size_t | countFaces () const
| Returns the number of subdim-faces in this boundary component. More...
const std::vector< Face< dim, dim-1 > *> & | facets () const
| Returns all (dim-1)-faces in this boundary component. More...
const std::vector< Face< dim, subdim > *> & | faces () const
| Returns all subdim-faces in this boundary component. More...
Face< dim, dim-1 > * | facet (size_t index) const
| Returns the requested (dim-1)-face in this boundary component. More...
Face< dim, subdim > * | face (size_t index) const
| Returns the requested subdim-face in this boundary component. More...
Triangulation< dim > * | triangulation () const
| Returns the triangulation to which this boundary component belongs. More...
Component< dim > * | component () const
| Returns the connected component of the triangulation to which this boundary component belongs. More...
size_t | markedIndex () const
| Returns the index at which this object is stored in an MarkedVector. More...

## Static Public Attributes

static constexpr bool | canBuild
| A compile-time constant indicating whether this boundary component class supports triangulating boundary components. More...
static constexpr bool | allowVertex
| A compile-time constant indicating whether ideal and/or invalid vertex boundary components are both possible and recognised by this boundary component class. More...
static constexpr bool | allFaces
| A compile-time constant indicating whether this boundary component class stores all lower-dimensional faces (`true`), or only faces of dimension dim-1 (`false`). More...

## Protected Member Functions

const Triangulation< dim-1 > * | buildVertexLink () const
| Triangulates the vertex link for an ideal or invalid vertex boundary component. More...
void | push_back (Face< dim, subdim > *face)
| Pushes the given face onto the end of the list of subdim-faces of this boundary component. More...
void | reorderAndRelabelFaces (Triangulation< dim-1 > *tri) const
| Reorders all lower-dimensional faces of the given triangulation so that they appear in the same order as the corresponding faces of this boundary component, and relabels these faces so that their vertices are numbered in a corresponding way. More...
void | reorderAndRelabelFaces (Triangulation< tridim > *tri, const std::vector< Face< dim, tridim > * > &tridimFaces) const
| Reorders and relabels all faces of all dimensions 0,...,subdim of the given triangulation, so that for each k, the k-faces of the given triangulation appear in the same order as the corresponding k-faces in this suite, and have their vertices numbered in a corresponding way. More...

## Protected Attributes

bool | orientable_
| Is this boundary component orientable? More...
Triangulation< dim-1 > * | boundary_
| A full triangulation of the boundary component. More...
std::vector< Face< dim, subdim > * > | faces_
| The list of faces. More...

## Friends

class | Triangulation< dim >
class | detail::TriangulationBase< dim >

## Detailed Description

### template<int dim>
class regina::BoundaryComponent< dim >

A component of the boundary of a dim-manifold triangulation.

Regina recognises three types of boundary components:

- A real boundary component is formed from unglued facets of top-dimensional simplices of the triangulation. For example, a real boundary component of a 3-manifold triangulation is formed from boundary triangles in the 2-skeleton.
- An ideal boundary component consists of a single ideal vertex; that is, a vertex whose link is a closed (dim-1)-manifold but not a sphere. This is only possible for dimensions dim ≥ 3.
- An invalid vertex boundary component consists of a single invalid invalid vertex that does not belong to a real boundary component. This means the vertex link must be an ideal (dim-1)-manifold, or an invalid (dim-1)-manifold with no real boundary. Invalid vertex boundary components are only possible for dimensions dim ≥ 4.

Ideal and invalid vertex boundary components are only recognised when dim is one of Regina's standard dimensions. This is because, in higher dimensions, the relevant conditions rely on undecidable problems.

Regina stores different skeletal information for different types of boundary components:

- For real boundary components in standard dimensions, Regina stores all boundary faces of all dimensions 0,1,...,dim-1.
- For real boundary components in higher (non-standard) dimensions, Regina only stores the boundary (dim-1)-faces (i.e., the unglued facets of top-dimensional simplices that make up the boundary component). This is simply to avoid excessive memory usage.
- For ideal and invalid vertex boundary components, Regina stores the relevant vertex. Such boundary components do not contain any faces of any dimension greater than zero.

We can encounter some interesting cases with invalid triangulations. Consider some face whose link has more than one boundary component (which makes the face invalid). This means that different parts of the (dim)-manifold boundary are effectively "pinched" together. If this happens, the different parts of the boundary that are pinched might or might not be listed as part of the same boundary component; if not then the offending face will be included in all of these boundary components. Nevertheless, only one of these can be considered the "official" boundary component of the face as returned by Face::boundaryComponent(). This is all a bit of a mess, but then again the entire triangulation is invalid and so you almost certainly have bigger problems to deal with.

Boundary components are highly temporary: whenever a triangulation changes, all of its boundary component objects will be deleted and new ones will be created in their place.

Boundary component objects are all created, managed and destroyed by the class Triangulation<dim>. See the Triangulation notes for further information on working with dim-dimensional triangulations.

For dimension dim = 3, this template is specialised and offers more functionality. In order to use this specialised class, you will need to include the corresponding header triangulation/dim3.h.

Python:
  Python does not support templates. Instead this class can be used by appending the dimension as a suffix (e.g., BoundaryComponent2 and BoundaryComponent3 for dimensions 2 and 3).

Template Parameters

  dim | the dimension of the underlying triangulation. This must be between 2 and 15 inclusive.

## Member Function Documentation

## build()

const Triangulation<dim-1>* regina::detail::BoundaryComponentStorage< dim, allFaces, allowVertex, canBuild_ >::build | ( |  | ) | const

inline inherited

Returns the full (dim-1)-dimensional triangulation of this boundary component.

Note that this triangulation is read-only (though of course you can clone it and then operate upon the clone).

If this is a real boundary component (i.e., it is built from one or more (dim-1)-faces), then the triangulation of this boundary component is as follows:

- Let i lie between 0 and size()-1 inclusive. Then simplex i of the returned (dim-1)-dimensional triangulation is a copy of `facet(i)` of this boundary component, and its vertices 0,...,dim-1 are numbered in the same way. To relate these (dim-1)-face vertex numbers to the vertex numbers of top-dimensional simplices in the overall dim-dimensional triangulation, see Simplex<dim>::faceMapping<dim-1>().
- If this boundary component stores lower-dimensional faces (i.e., if the template argument allFaces is `true`), then a similar correspondence holds for these lower-dimensional faces also: for each i, k-face i of the returned triangulation is a copy of `face<k>(i)` of this boundary component, and its vertices are numbered in the same way.

If this boundary component consists only of a single vertex (i.e., this is an ideal or invalid vertex boundary component), then this routine returns the triangulation of the corresponding vertex link. See Vertex::link() for details.

This routine is fast, since it caches the boundary triangulation. Moreover, it is guaranteed that the full skeleton of this (dim-1)-dimensional triangulation will have been generated already.

Returns
  the triangulation of this boundary component.

## buildVertexLink()

const Triangulation<dim-1>* regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::buildVertexLink | ( |  | ) | const

inline protected inherited

Triangulates the vertex link for an ideal or invalid vertex boundary component.

Returns
  the triangulated vertex link.

## component()

Component<dim>* regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::component | ( |  | ) | const

inline inherited

Returns the connected component of the triangulation to which this boundary component belongs.

Returns
  the component containing this boundary component.

## countFaces()

size_t regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::countFaces | ( |  | ) | const

inline inherited

Returns the number of subdim-faces in this boundary component.

This routine is only available where dim is one of Regina's standard dimensions.

Python:
  Python does not support templates. Instead, Python users should call this function in the form `countFaces(subdim)`; that is, the template parameter subdim becomes the first argument of the function.

Template Parameters

  subdim | the dimension of the faces to query. This must be between 0 and dim-1 inclusive.

Returns
  the number of subdim-faces.

## countRidges()

size_t regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::countRidges | ( |  | ) | const

inline inherited

Returns the number of (dim-2)-faces in this boundary component.

If this is an ideal or invalid vertex boundary component, then this routine will return 0.

Returns
  the number of (dim-2)-faces in this boundary component.

## detail()

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

## face()

Face<dim, subdim>* regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::face | ( | size_t | index | ) | const

inline inherited

Returns the requested subdim-face in this boundary component.

Note that the index of a face in the boundary component need not be the index of the same face in the overall triangulation. However, if this is a real boundary component (i.e., it is built from one or more (dim-1)-faces), then the index of each subdim-face in this boundary component will match the index of the corresponding subdim-face in the (dim-1)-manifold triangulation returned by build().

This routine is only available where dim is one of Regina's standard dimensions.

Python:
  Python does not support templates. Instead, Python users should call this function in the form `face(subdim, index)`; that is, the template parameter subdim becomes the first argument of the function.

Template Parameters

  subdim | the dimension of the face to query. This must be between 0 and dim-1 inclusive.

Parameters

  index | the index of the desired face, ranging from 0 to countFaces<subdim>()-1 inclusive.

Returns
  the requested face.

## faces()

const std::vector<Face<dim, subdim>*>& regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::faces | ( |  | ) | const

inline inherited

Returns all subdim-faces in this boundary component.

The reference that is returned will remain valid only for as long as this boundary component object exists. In particular, the reference will become invalid any time that the triangulation changes (since all boundary component objects will be destroyed and others rebuilt in their place).

Python:
  Python users should call this function in the form `faces(subdim)`. It will then return a Python list containing all the subdim-faces of the boundary component. Be warned that, unlike in C++, this Python list will be a snapshot of the faces when this function is called, and will not be kept up-to-date as the triangulation changes.

Template Parameters

  subdim | the dimension of the faces to query. This must be between 0 and dim-1 inclusive.

Returns
  access to the list of all subdim-faces.

## facet()

Face<dim, dim-1>* regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::facet | ( | size_t | index | ) | const

inline inherited

Returns the requested (dim-1)-face in this boundary component.

These are the top-dimensional faces for a real boundary component.

Note that the index of a face in the boundary component need not be the index of the same face in the overall triangulation. However, if this is a real boundary component (i.e., it is built from one or more (dim-1)-faces), then the index of each (dim-1)-face in this boundary component will match the index of the corresponding top-dimensional simplex in the (dim-1)-manifold triangulation returned by build().

Parameters

  index | the index of the desired face, ranging from 0 to size()-1 inclusive.

Returns
  the requested face.

## facets()

const std::vector<Face<dim, dim-1>*>& regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::facets | ( |  | ) | const

inline inherited

Returns all (dim-1)-faces in this boundary component.

The reference that is returned will remain valid only for as long as this boundary component object exists. In particular, the reference will become invalid any time that the triangulation changes (since all boundary component objects will be destroyed and others rebuilt in their place).

Python:
  This routine returns a python list.

Returns
  the list of all (dim-1)-faces.

## index()

template<int dim>

size_t regina::detail::BoundaryComponentBase< dim >::index | ( |  | ) | const

inline inherited

Returns the index of this boundary component in the underlying triangulation.

Returns
  the index of this boundary component.

## isIdeal()

bool regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::isIdeal | ( |  | ) | const

inline inherited

Determines if this boundary component is ideal.

This is the case if and only if it consists of a single ideal vertex and no faces of any other dimensions.

See the BoundaryComponent class notes for an overview of ideal boundary components, which can only occur in dimensions ≥ 3, and which are only recognised where dim is one of Regina's standard dimensions.

Note that a boundary component formed from a single invalid vertex is not considered to be ideal. This means that, if a boundary component contains no faces of positive dimension, then one and only one of isIdeal() and isInvalidVertex() will return `true`.

This routine is only available where dim is at least 3 and is one of Regina's standard dimensions.

Returns
  `true` if and only if this boundary component is ideal.

## isInvalidVertex()

bool regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::isInvalidVertex | ( |  | ) | const

inline inherited

Determines if this boundary component consists of a single invalid vertex and nothing else.

In particular, such a boundary component must contain no faces of any positive dimension.

See the BoundaryComponent class notes for an overview of invalid vertex boundary components, which can only occur in dimensions ≥ 4, and which are only recognised where dim is one of Regina's standard dimensions.

An invalid vertex is only placed in its own boundary component if it does not already belong to some larger boundary component (for instance, if its link is an ideal (dim-1)-manifold triangulation). This means that, for a boundary component consisting of one or more (dim-1)-faces, this routine will return `false` even if the boundary component also includes one or more invalid vertices.

Note that, if a boundary component contains no faces of positive dimension, then one and only one of isIdeal() and isInvalidVertex() will return `true`.

This routine is only available where dim is at least 3 and is one of Regina's standard dimensions.

Returns
  `true` if and only if this boundary component consists of a single invalid vertex and nothing else.

## isOrientable()

template<int dim>

bool regina::detail::BoundaryComponentBase< dim >::isOrientable | ( |  | ) | const

inline inherited

Determines if this boundary component is orientable.

If this is an ideal or invalid vertex boundary component, then the orientability of the corresponding vertex link is returned.

This routine is fast; in particular, it is pre-computed and does not build a full triangulation of the boundary component.

Returns
  `true` if and only if this boundary component is orientable.

## isReal()

bool regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::isReal | ( |  | ) | const

inline inherited

Determines if this boundary component is real.

This is the case if and only if it is formed from one or more (dim-1)-faces.

See the BoundaryComponent class notes for an overview of real, ideal, and invalid vertex boundary components.

This routine is only available where dim is at least 3 and is one of Regina's standard dimensions. (In other dimensions, real boundary components are the only types of boundary component that Regina will recognise.)

Returns
  `true` if and only if this boundary component is real.

## markedIndex()

size_t regina::MarkedElement::markedIndex | ( |  | ) | const

inline inherited

Returns the index at which this object is stored in an MarkedVector.

If this object does not belong to an MarkedVector, the return value is undefined.

Returns
  the index at which this object is stored.

## push_back()

void regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::push_back | ( | Face< dim, subdim > * | face | ) |

inline protected inherited

Pushes the given face onto the end of the list of subdim-faces of this boundary component.

This class does not take ownership of the given face.

Template Parameters

  subdim | the dimension of the face to append. This must be between 0 and dim-1 inclusive.

Parameters

  face | the face to append to the list.

## reorderAndRelabelFaces() [1/2]

void regina::detail::WeakFaceListSuite< dim, subdim >::reorderAndRelabelFaces | ( | Triangulation< tridim > * | tri,
|  | const std::vector< Face< dim, tridim > *> & | tridimFaces
| ) |  | const

inline protected inherited

Reorders and relabels all faces of all dimensions 0,...,subdim of the given triangulation, so that for each k, the k-faces of the given triangulation appear in the same order as the corresponding k-faces in this suite, and have their vertices numbered in a corresponding way.

Precondition
  For each dimension k = 0,...,subdim, the k-faces of the given triangulation tri are in one-to-one correspondence with the k-faces in this suite, though not necessarily in the same order. Moreover, for each i and j, this correspondence maps the ith k-face of `tri->simplex(j)` to the ith k-face of `tridimFaces[j]`.

Template Parameters

  tridim | the dimension of the given triangulation. This must be strictly larger than subdim, but it need not be equal to dim.

Parameters

  tri | a tridim-dimensional triangulation, as described above.
  tridimFaces | a list of tridim-faces that together contain all of the faces in this suite, and that are in an ordered one-to-one correspondence with the top-dimensional simplices of tri as described in the precondition above.

## reorderAndRelabelFaces() [2/2]

void regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::reorderAndRelabelFaces | ( | Triangulation< dim-1 > * | tri | ) | const

inline protected inherited

Reorders all lower-dimensional faces of the given triangulation so that they appear in the same order as the corresponding faces of this boundary component, and relabels these faces so that their vertices are numbered in a corresponding way.

This affects all faces of dimensions 0,...,(dim-2).

Precondition
  This is a real boundary component.
  tri is a triangulation of this boundary component.
  For each i, the ith top-dimensional simplex of tri corresponds to the ith (dim-1)-face of this boundary component, and has its vertices 0,...,(dim-1) labelled in the same way.

Parameters

  tri | a triangulation of this boundary component, as described above.

## size()

size_t regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::size | ( |  | ) | const

inline inherited

Returns the number of (dim-1)-faces in this boundary component.

These are the top-dimensional faces for a real boundary component.

If this is an ideal or invalid vertex boundary component, then this routine will return 0.

Returns
  the number of (dim-1)-faces in this boundary component.

## str()

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

Returns
  a short text representation of this object.

## triangulation()

Triangulation<dim>* regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::triangulation | ( |  | ) | const

inline inherited

Returns the triangulation to which this boundary component belongs.

Returns
  the triangulation containing this boundary component.

## utf8()

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

## writeTextLong()

void regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::writeTextLong | ( | std::ostream & | out | ) | const

inline inherited

Writes a detailed text representation of this object to the given output stream.

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## writeTextShort()

void regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::writeTextShort | ( | std::ostream & | out | ) | const

inline inherited

Writes a short text representation of this object to the given output stream.

Python:
  Not present.

Parameters

  out | the output stream to which to write.

## Member Data Documentation

## allFaces

constexpr bool regina::detail::BoundaryComponentFaceStorage< dim, allFaces_ >::allFaces

static inherited

A compile-time constant indicating whether this boundary component class stores all lower-dimensional faces (`true`), or only faces of dimension dim-1 (`false`).

This is a compile-time constant only, with no linkage - any attempt to create a reference or pointer to it will give a linker error.

Python:
  Not present.

## allowVertex

constexpr bool regina::detail::BoundaryComponentFaceInterface< dim, allFaces, allowVertex_ >::allowVertex

static inherited

A compile-time constant indicating whether ideal and/or invalid vertex boundary components are both possible and recognised by this boundary component class.

This is a compile-time constant only, with no linkage - any attempt to create a reference or pointer to it will give a linker error.

Python:
  Not present.

## boundary_

Triangulation<dim-1>* regina::detail::BoundaryComponentStorage< dim, allFaces, allowVertex, canBuild_ >::boundary_

protected inherited

A full triangulation of the boundary component.

This may be pre-computed when the triangulation skeleton is constructed, or it may be `null` in which case it will be built on demand. For ideal or invalid vertices, this is always `null` since the triangulation is cached by the vertex class instead.

## canBuild

constexpr bool regina::detail::BoundaryComponentStorage< dim, allFaces, allowVertex, canBuild_ >::canBuild

static inherited

A compile-time constant indicating whether this boundary component class supports triangulating boundary components.

This is a compile-time constant only, with no linkage - any attempt to create a reference or pointer to it will give a linker error.

Python:
  Not present.

## faces_

template<int dim, int subdim>

std::vector<Face<dim, subdim>*> regina::detail::WeakFaceList< dim, subdim >::faces_

protected inherited

The list of faces.

## orientable_

template<int dim>

bool regina::detail::BoundaryComponentBase< dim >::orientable_

protected inherited

Is this boundary component orientable?

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

- triangulation/forward.h
- triangulation/generic/boundarycomponent.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).