Regina Calculation Engine
Public Member Functions | Friends | List of all members
regina::ModelLinkGraphCells Class Reference

Describes the cellular decomposition of the sphere that is induced by a given planar 4-valent graph. More...

#include <link/modellinkgraph.h>

Inheritance diagram for regina::ModelLinkGraphCells:
regina::Output< ModelLinkGraphCells >

Public Member Functions

 ~ModelLinkGraphCells ()
 Destroys this cellular decomposition. More...
 
bool isValid () const
 Determines whether the underlying graph is non-empty with a planar embedding, assuming that it is already known to be connected. More...
 
size_t countCells () const
 Returns the number of 2-cells in this cellular decomposition. More...
 
const ModelLinkGraphArcarc (size_t cell, size_t which) const
 Returns the given arc along the boundary of the given 2-cell. More...
 
size_t size (size_t cell) const
 Returns the number of arcs aloung the boundary of the given 2-cell. More...
 
const ModelLinkGraphArcbegin (size_t cell) const
 
Returns the beginning of an iterator range for walking around the boundary of the given 2-cell. More...
 
const ModelLinkGraphArcend (size_t cell) const
 
Returns the end of an iterator range for walking around the boundary of the given 2-cell. More...
 
size_t cell (const ModelLinkGraphArc &arc) const
 Returns the 2-cell that lies to the left of the given arc. More...
 
size_t cellPos (const ModelLinkGraphArc &arc) const
 Returns where the given arc appears along the boundary of the 2-cell to its left. 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...
 
ModelLinkGraphCellsoperator= (const ModelLinkGraphCells &)=delete
 
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...
 

Friends

class ModelLinkGraph
 

Detailed Description

Describes the cellular decomposition of the sphere that is induced by a given planar 4-valent graph.

The graph is represented by an object of type ModelLinkGraph, which also encodes a specific planar embedding of the graph. The nodes and arcs of this graph then form the vertices and edges of a cellular decomposition; the main purpose of this class is to deduce and describe the resulting 2-cells.

At present, this class insists that each 2-cell is a topological disc. As a consequence, this class cannot work with empty or disconnected graphs.

Constructor & Destructor Documentation

◆ ~ModelLinkGraphCells()

regina::ModelLinkGraphCells::~ModelLinkGraphCells ( )
inline

Destroys this cellular decomposition.

Member Function Documentation

◆ arc()

const ModelLinkGraphArc & regina::ModelLinkGraphCells::arc ( size_t  cell,
size_t  which 
) const
inline

Returns the given arc along the boundary of the given 2-cell.

For each cell, the arcs along the boundary are given in order as you walk anticlockwise around the cell (so the cell is on the left of each arc as you walk around the cell boundary).

Each arc is described in the form of an outgoing arc from some node of the underlying graph (so if the return ModelLinkGraphArc is a then this describes an outgoing arc from a.node()). It follows that, if the underlying graph has n nodes, then each of the 4n possible ModelLinkGraphArc values appears exactly once as arc(cell, which) for some integers cell and which.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
cellindicates which cell to query; this must be between 0 and countCells()-1 inclusive.
whichindicates which arc along the boundary of the corresponding cell to return; this must be between 0 and size(cell)-1 inclusive.
Returns
the requested arc on the boundary of the given 2-cell.

◆ begin()

const ModelLinkGraphArc * regina::ModelLinkGraphCells::begin ( size_t  cell) const
inline


Returns the beginning of an iterator range for walking around the boundary of the given 2-cell.

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j).

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Python
Not present. Use arc() and size() instead.
      @return the beginning of an iterator range for the boundary
      of the given cell.

◆ cell()

size_t regina::ModelLinkGraphCells::cell ( const ModelLinkGraphArc arc) const
inline

Returns the 2-cell that lies to the left of the given arc.

Specifically, this function returns the number of the cell that lies to the left of the given arc as you walk along it away from arc.node().

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
arcthe given arc of the underlying graph.
Returns
the number of the cell that lies to the left of the given arc; this will be an integer between 0 and countCells()-1 inclusive.

◆ cellPos()

size_t regina::ModelLinkGraphCells::cellPos ( const ModelLinkGraphArc arc) const
inline

Returns where the given arc appears along the boundary of the 2-cell to its left.

Consider the cell c to the left of the given arc as you follow the arc away from arc.node(). The routine arc() can be used to enumerate the sequence of arcs along the boundary of this cell c, in order as you walk anticlockwise around the cell boundary. The purpose of this routine is to identify where in this sequence the given arc occurs.

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
arcthe given arc of the underlying graph.
Returns
the position of the given arc on the boundary of the cell to its left; this will be an integer between 0 and size(cell(arc))-1 inclusive.

◆ countCells()

size_t regina::ModelLinkGraphCells::countCells ( ) const
inline

Returns the number of 2-cells in this cellular decomposition.

If isValid() returns false (i.e., the underlying ModelLinkGraph is either empty or does not describe a planar embedding), then this routine will return 0 instead. Note that this routine cannot be used to test for connectivity, which is a non-negotiable precondition required by the class constructor.

Note that, if isValid() returns true, then countCells() will always return n+2 where n is the number of nodes in the underlying graph.

Returns
a strictly positive number of 2-cells if isValid() returns true, or 0 if isValid() returns false.

◆ detail()

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

◆ end()

const ModelLinkGraphArc * regina::ModelLinkGraphCells::end ( size_t  cell) const
inline


Returns the end of an iterator range for walking around the boundary of the given 2-cell.

As is usual for iterator ranges, this is a past-the-end value (i.e., this iterator cannot be dereferenced).

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j).

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Python
Not present. Use arc() and size() instead.
      @return the end of an iterator range for the boundary
      of the given cell.

◆ isValid()

bool regina::ModelLinkGraphCells::isValid ( ) const
inline

Determines whether the underlying graph is non-empty with a planar embedding, assuming that it is already known to be connected.

As described in the class notes, this class can only work with non-empty connected graphs where the corresponding ModelLinkGraph object also describes a planar embedding.

The constructor for this class requires you to pass a graph that is already known to be connected. However, assuming the graph is connected, the constructor then tests for the remaining conditions. This routine returns the results of these tests: if the underlying graph is empty or does not describe a planar embedding, then this routine will return false.

This routine is constant time, since the necessary work will have already been completed by the class constructor.

Warning
Most of the routines in this class require isValid() to return true. Essentially, if isValid() returns false, you should not attempt to query the details of the cell decomposition. See the preconditions on individual routines for further details.
Returns
true if and only if the underlying ModelLinkGraph describes a planar embedding of a non-empty graph.

◆ size()

size_t regina::ModelLinkGraphCells::size ( size_t  cell) const
inline

Returns the number of arcs aloung the boundary of the given 2-cell.

If the given cell is a k-gon, then this routine returns the integer k.

Precondition
The underlying ModelLinkGraph is non-empty, connected, and describes a planar graph embedding. Note that connectivity is already required by the class constructor, and you can test the remaining conditions by calling isValid().
Parameters
cellindicates which cell to query; this must be between 0 and countCells()-1 inclusive.
Returns
the size of the correpsonding 2-cell.

◆ str()

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

◆ utf8()

std::string regina::Output< ModelLinkGraphCells , 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::ModelLinkGraphCells::writeTextLong ( std::ostream &  out) const


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

Python
Not present.
Parameters
outthe output stream to which to write.

◆ writeTextShort()

void regina::ModelLinkGraphCells::writeTextShort ( std::ostream &  out) const


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

Python
Not present.
Parameters
outthe output stream to which to write.

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

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