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:

Public Types
using	ArcIterator = const ModelLinkGraphArc *
	An iterator type used when traversing the boundary of a 2-cell. More...

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...

size_t	size (size_t cell) const
	Returns the number of arcs aloung the boundary of the given 2-cell. More...

const ModelLinkGraphArc &	arc (size_t cell, size_t which) const
	Returns the given arc along the boundary of the given 2-cell. More...

auto	arcs (size_t cell) const
	Returns an object that allows iteration through and random access to all arcs along the boundary of the given 2-cell. More...

ArcIterator	begin (size_t cell) const
	Returns the beginning of an iterator range for walking around the boundary of the given 2-cell. More...

ArcIterator	end (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...

bool	operator== (const ModelLinkGraphCells &other) const
	Determines if this and the given cellular decomposition are combinatorially identical. More...

bool	operator!= (const ModelLinkGraphCells &other) const
	Determines if this and the given cellular decomposition are not combinatorially identical. 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...

ModelLinkGraphCells &	operator= (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.

Cellular decompositions do not support value semantics: they cannot be copied, swapped, or manually constructed. Instead they are computed properties of model graphs, and are only accessible via const reference through the member function ModelLinkGraph::cells().

Member Typedef Documentation

◆ ArcIterator

using regina::ModelLinkGraphCells::ArcIterator = const ModelLinkGraphArc*

An iterator type used when traversing the boundary of a 2-cell.

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

cell	indicates which cell to query; this must be between 0 and countCells()-1 inclusive.
which	indicates 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.

◆ arcs()

auto regina::ModelLinkGraphCells::arcs ( size_t cell ) const

inline

Returns an object that allows iteration through and random access to all arcs along the boundary of the given 2-cell.

Suppose that the ith cell is a k-gon. Then this object gives access to 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.

The object that is returned is lightweight, and can be happily copied by value. The C++ type of the object is subject to change, so C++ users should use auto (just like this declaration does).

The returned object is guaranteed to be an instance of ListView, which means it offers basic container-like functions and supports range-based for loops. The elements of the list will be read-only objects of type ModelLinkGraphArc, and so your code might look like:

for (const ModelLinkGraphArc& a : cells.arcs(cell)) { ... }

regina::ModelLinkGraphCells::cell

size_t cell(const ModelLinkGraphArc &arc) const

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

Definition: modellinkgraph.h:1803

Using arcs(cell) is equivalent to iterating over the iterator range (begin(cell), end(cell)). Using arcs() generates a tiny amount of extra overhead, but you may also find it more readable.

Parameters

cell	indicates which cell to query; this must be between 0 and countCells()-1 inclusive.

Returns: access to the list of all arcs along the boundary of the given cell.

◆ begin()

ModelLinkGraphCells::ArcIterator 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), and iterating over the entire range (begin(cell), end(cell)) is equivalent to iterating over arcs(cell).

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. Python users can iterate over arcs(cell) instead.

Returns: 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

arc	the 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

arc	the 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()

ModelLinkGraphCells::ArcIterator 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), and iterating over the entire range (begin(cell), end(cell)) is equivalent to iterating over arcs(cell).

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. Python users can iterate over arcs(cell) instead.

Returns: 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.

◆ operator!=()

bool regina::ModelLinkGraphCells::operator!= ( const ModelLinkGraphCells & other ) const

inline

Determines if this and the given cellular decomposition are not combinatorially identical.

Here "identical" means that both decompositions have the same number of cells, these cells are presented in the same order, and their boundaries enter and exit the same numbered arcs of the same numbered nodes, using the same directions of traversal and the same starting points on each cell boundary.

Parameters

other the cellular decomposition to compare with this.

Returns: true if and only if the two cellular decompositions are not combinatorially identical.

◆ operator==()

bool regina::ModelLinkGraphCells::operator== ( const ModelLinkGraphCells & other ) const

Determines if this and the given cellular decomposition are combinatorially identical.

Here "identical" means that both decompositions have the same number of cells, these cells are presented in the same order, and their boundaries enter and exit the same numbered arcs of the same numbered nodes, using the same directions of traversal and the same starting points on each cell boundary.

Parameters

other the cellular decomposition to compare with this.

Returns: true if and only if the two cellular decompositions are combinatorially identical.

◆ 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

cell	indicates 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 use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python: The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

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 not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned 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. Use detail() instead.

Parameters

out	the 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. Use str() instead.

Parameters

out	the output stream to which to write.

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

link/modellinkgraph.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ ArcIterator

Constructor & Destructor Documentation

◆ ~ModelLinkGraphCells()

Member Function Documentation

◆ arc()

◆ arcs()

◆ begin()

◆ cell()

◆ cellPos()

◆ countCells()

◆ detail()

◆ end()

◆ isValid()

◆ operator!=()

◆ operator==()

◆ size()

◆ str()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()