Provides core functionality for facet pairings (that is, dual graphs) of dim-dimensional triangulations. More...

#include <triangulation/detail/facetpairing.h>

Inheritance diagram for regina::detail::FacetPairingBase< dim >:

Public Types
using	IsoList = std::vector< Isomorphism< dim > >
	A list of isomorphisms on facet pairings. More...

Public Member Functions
void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. 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...

std::string	tightEncoding () const
	Returns the tight encoding of this object. More...

Constructors, Destructors and Assignment
	FacetPairingBase (const FacetPairingBase &src)
	Creates a new copy of the given facet pairing. More...

	FacetPairingBase (FacetPairingBase &&src) noexcept
	Moves the given facet pairing into this facet pairing. More...

	FacetPairingBase (const Triangulation< dim > &tri)
	Creates the facet pairing of given triangulation. More...

	FacetPairingBase (std::istream &in)
	Reads a new facet pairing from the given input stream. More...

	~FacetPairingBase ()
	Deallocates any memory used by this structure. More...

FacetPairingBase &	operator= (const FacetPairingBase &src)
	Copies the given facet pairing into this facet pairing. More...

FacetPairingBase &	operator= (FacetPairingBase &&src) noexcept
	Moves the given facet pairing into this facet pairing. More...

void	swap (FacetPairingBase &other) noexcept
	Swaps the contents of this and the given facet pairing. More...

Basic Queries
size_t	size () const
	Returns the number of simplices whose facets are described by this facet pairing. More...

const FacetSpec< dim > &	dest (const FacetSpec< dim > &source) const
	Returns the other facet to which the given simplex facet is paired. More...

const FacetSpec< dim > &	dest (size_t simp, int facet) const
	Returns the other facet to which the given simplex facet is paired. More...

const FacetSpec< dim > &	operator[] (const FacetSpec< dim > &source) const
	Returns the other facet to which the given simplex facet is paired. More...

bool	isUnmatched (const FacetSpec< dim > &source) const
	Determines whether the given simplex facet has been left deliberately unmatched. More...

bool	isUnmatched (size_t simp, int facet) const
	Determines whether the given simplex facet has been left deliberately unmatched. More...

bool	isClosed () const
	Determines whether this facet pairing is closed. More...

bool	operator== (const FacetPairing< dim > &other) const
	Determines if this and the given facet pairing are identical. More...

bool	operator!= (const FacetPairing< dim > &other) const
	Determines if this and the given facet pairing are not identical. More...

Connected components
bool	isConnected () const
	Determines whether this facet pairing is connected. More...

std::optional< Cut >	divideConnected (size_t minSide) const
	Returns a cut that divides this facet pairing into two connected pieces, both of size at least minSide. More...

Isomorphic Representations
bool	isCanonical () const
	Determines whether this facet pairing is in canonical form. More...

std::pair< FacetPairing< dim >, Isomorphism< dim > >	canonical () const
	Returns the canonical form of this facet pairing, along with one isomorphism that transforms this pairing into canonial form. More...

std::pair< FacetPairing< dim >, IsoList >	canonicalAll () const
	Returns the canonical form of this facet pairing, along with the list of all isomorphisms that transform this pairing into canonial form. More...

IsoList	findAutomorphisms () const
	Returns the set of all combinatorial automorphisms of this facet pairing, assuming the pairing is already in canonical form. More...

Static Public Member Functions
static FacetPairing< dim >	tightDecoding (const std::string &enc)
	Reconstructs an object of type T from its given tight encoding. More...

Protected Attributes
size_t	size_
	The number of simplices under consideration. More...

FacetSpec< dim > *	pairs_
	The other facet to which each simplex facet is paired. More...

Input and Output
void	writeTextShort (std::ostream &out) const
	Writes a human-readable representation of this facet pairing to the given output stream. More...

std::string	textRep () const
	Returns a text-based representation that can be used to reconstruct this facet pairing. More...

std::string	toTextRep () const
	Deprecated routine that returns a text-based representation that can be used to reconstruct this facet pairing. More...

void	tightEncode (std::ostream &out) const
	Writes the tight encoding of this facet pairing to the given output stream. More...

void	writeDot (std::ostream &out, const char *prefix=nullptr, bool subgraph=false, bool labels=false) const
	Writes the graph corresponding to this facet pairing in the Graphviz DOT language. More...

std::string	dot (const char *prefix=nullptr, bool subgraph=false, bool labels=false) const
	Returns a Graphviz DOT representation of the graph that describes this facet pairing. More...

static FacetPairing< dim >	fromTextRep (const std::string &rep)
	Reconstructs a facet pairing from a text-based representation. More...

static FacetPairing< dim >	tightDecode (std::istream &input)
	Reconstructs a facet pairing from its given tight encoding. More...

static void	writeDotHeader (std::ostream &out, const char *graphName=nullptr)
	Writes header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings. More...

static std::string	dotHeader (const char *graphName=nullptr)
	Returns header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings. More...

template<typename Action , typename... Args>
static void	findAllPairings (size_t nSimplices, BoolSet boundary, int nBdryFacets, Action &&action, Args &&... args)
	Generates all possible facet pairings satisfying the given constraints. More...

	FacetPairingBase (size_t size)
	Creates a new facet pairing. More...

FacetSpec< dim > &	dest (const FacetSpec< dim > &source)
	Returns the other facet to which the given simplex facet is paired. More...

FacetSpec< dim > &	dest (size_t simp, int facet)
	Returns the other facet to which the given simplex facet is paired. More...

FacetSpec< dim > &	operator[] (const FacetSpec< dim > &source)
	Returns the other facet to which the given simplex facet is paired. More...

bool	noDest (const FacetSpec< dim > &source) const
	Determines whether the matching for the given simplex facet has not yet been determined. More...

bool	noDest (size_t simp, int facet) const
	Determines whether the matching for the given simplex facet has not yet been determined. More...

bool	isCanonicalInternal (IsoList *list=nullptr) const
	Determines whether this facet pairing is in canonical (smallest lexicographical) form, given a small set of assumptions. More...

Detailed Description

template<int dim>
class regina::detail::FacetPairingBase< dim >

Provides core functionality for facet pairings (that is, dual graphs) of dim-dimensional triangulations.

Such a facet pairing is represented by the class FacetPairing<dim>, which uses this as a base class. End users should not need to refer to FacetPairingBase directly.

See the FacetPairing class notes for further information.

Both this class and the "end user" class FacetPairing<dim> implement C++ move semantics, and FacetPairing<dim> also adheres to the C++ Swappable requirement. These classes are designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Python: This base class is not present, but the "end user" class FacetPairing<dim> is.

Template Parameters

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

Member Typedef Documentation

◆ IsoList

template<int dim>

using regina::detail::FacetPairingBase< dim >::IsoList = std::vector<Isomorphism<dim> >

A list of isomorphisms on facet pairings.

In particular, this class uses the IsoList type to return the set of all automorphisms of a facet pairing.

Constructor & Destructor Documentation

◆ FacetPairingBase() [1/5]

template<int dim>

regina::detail::FacetPairingBase< dim >::FacetPairingBase ( const FacetPairingBase< dim > & src )

inline

Creates a new copy of the given facet pairing.

Parameters

src	the facet pairing to clone.

◆ FacetPairingBase() [2/5]

template<int dim>

regina::detail::FacetPairingBase< dim >::FacetPairingBase ( FacetPairingBase< dim > && src )

inlinenoexcept

Moves the given facet pairing into this facet pairing.

This is a fast (constant time) operation.

The facet pairing that is passed (src) will no longer be usable.

Parameters

src	the facet pairing to move.

◆ FacetPairingBase() [3/5]

template<int dim>

regina::detail::FacetPairingBase< dim >::FacetPairingBase ( const Triangulation< dim > & tri )

Creates the facet pairing of given triangulation.

This is the facet pairing that describes how the facets of simplices in the given triangulation are joined together, as described in the class notes.

Precondition: The given triangulation is not empty.

Parameters

tri	the triangulation whose facet pairing should be constructed.

◆ FacetPairingBase() [4/5]

template<int dim>

regina::detail::FacetPairingBase< dim >::FacetPairingBase ( std::istream & in )

Reads a new facet pairing from the given input stream.

This routine reads data in the format written by textRep().

This routine will skip any initial whitespace in the given input stream. Once it finds its first non-whitespace character, it will read the entire line from the input stream and expect that line to containin the text representation of a facet pairing.

Exceptions

InvalidInput The data found in the input stream is invalid, incomplete, or incorrectly formatted.

Parameters

in	the input stream from which to read.

◆ ~FacetPairingBase()

template<int dim>

regina::detail::FacetPairingBase< dim >::~FacetPairingBase

inline

Deallocates any memory used by this structure.

◆ FacetPairingBase() [5/5]

template<int dim>

regina::detail::FacetPairingBase< dim >::FacetPairingBase ( size_t size )

inlineprotected

Creates a new facet pairing.

All internal arrays will be allocated but not initialised.

Precondition: size is at least 1.

Parameters

size	the number of simplices under consideration in this new facet pairing.

Member Function Documentation

◆ canonical()

template<int dim>

std::pair< FacetPairing< dim >, Isomorphism< dim > > regina::detail::FacetPairingBase< dim >::canonical

inline

Returns the canonical form of this facet pairing, along with one isomorphism that transforms this pairing into canonial form.

Note that, while the canoncial form is uniquely determined, the isomorphism is not (since the facet pairing could have non-trivial automorphisms). If you need all such isomorphisms then you should call canonicalAll() instead.

See the FacetPairing class notes for more information on isomorphisms, automorphisms and canonical form.

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.

Returns: a pair (c, iso), where c is the canonical form and iso is one isomorphism that converts this facet pairing into c.

◆ canonicalAll()

template<int dim>

std::pair< FacetPairing< dim >, typename FacetPairingBase< dim >::IsoList > regina::detail::FacetPairingBase< dim >::canonicalAll

inline

Returns the canonical form of this facet pairing, along with the list of all isomorphisms that transform this pairing into canonial form.

Note that the list that is returned will be a left coset of the automorphism group of this facet pairing, and also a right coset of the automorphism group of the canonical form.

If you only need one such isomorphism (not all), then you should call canonical() instead.

See the FacetPairing class notes for more information on isomorphisms, automorphisms and canonical form.

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.

Returns: a pair (c, isos), where c is the canonical form and isos is the list of all isomorphisms that convert this facet pairing into c.

◆ dest() [1/4]

template<int dim>

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest ( const FacetSpec< dim > & source )

inlineprotected

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ dest() [2/4]

template<int dim>

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest ( const FacetSpec< dim > & source ) const

inline

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ dest() [3/4]

template<int dim>

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest	(	size_t	simp,
		int	facet
	)

inlineprotected

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: the other facet to which the given facet is paired.

◆ dest() [4/4]

template<int dim>

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::dest	(	size_t	simp,
		int	facet
	)		const

inline

Returns the other facet to which the given simplex facet is paired.

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: the other facet to which the given facet is paired.

◆ detail()

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

◆ divideConnected()

template<int dim>

std::optional< Cut > regina::detail::FacetPairingBase< dim >::divideConnected ( size_t minSide ) const

Returns a cut that divides this facet pairing into two connected pieces, both of size at least minSide.

If solutions exist, then the cut that is returned will have minimum weight amongst all solutions (i.e., will have the smallest number of matched simplex facets that cross the two sides of the resulting partition). If there are still multiple solutions, then the cut that is returned will have the two pieces with sizes that are as close as possible to equal. If there are still multiple solutions, then the choice will be arbitrary.

Note that it is possible that no solution exists (e.g. this could happen if the matching is a star graph and minSide is greater than 1).

Warning: Currently the implementation of this routine is exhaustive, and so the running time is exponential in the size of this facet pairing.

Parameters

minSide the minimum number of simplices in each of the two connected pieces; this must be at least 1.

Returns: the best possible cut as described above, or no value if no such cut exists.

◆ dot()

template<int dim>

std::string regina::detail::FacetPairingBase< dim >::dot	(	const char *	prefix = `nullptr`,
		bool	subgraph = `false`,
		bool	labels = `false`
	)		const

Returns a Graphviz DOT representation of the graph that describes this facet pairing.

Every vertex of this graph represents a simplex, and every edge represents a pair of simplex facets that are joined together. Note that for a closed triangulation this graph will be entirely (dim + 1)-valent; for triangulations with boundary facets, some graph vertices will have degree dim or less.

The graph can either be written as a complete DOT graph, or as a clustered subgraph within some larger DOT graph (according to whether the argument subgraph is passed as false or true).

If a complete DOT graph is being written, the output may be used as a standalone DOT file ready for use with Graphviz.

If a subgraph is being written, the output will contain a single subgraph section that should be inserted into some larger DOT file. Note that the output generated by dotHeader() or writeDotHeader(), followed by one or more subgraphs and then a closing curly brace will suffice. The subgraph name will begin with the string pairing_.

The argument prefix will be prepended to the name of each graph vertex, and will also be used in the name of the graph or subgraph. Using unique prefixes becomes important if you are calling dot() or writeDot() several times to generate several subgraphs for use in a single DOT file. If the prefix argument is null or empty then a default prefix will be used.

Note that this routine generates undirected graphs, not directed graphs. The final DOT file should be used with either the neato or fdp programs shipped with Graphviz.

If you are simply writing this string to an output stream then you should call writeDot() instead, which is more efficient.

Parameters

prefix	a string to prepend to the name of each graph vertex, and to include in the graph or subgraph name; see above for details.
subgraph	`false` if a complete standalone DOT graph should be output, or `true` if a clustered subgraph should be output for use in some larger DOT file.
labels	indicates whether graph vertices will be labelled with the corresponding simplex numbers. This feature is currently experimental, and the default is `false`.

Returns: the output of writeDot(), as outlined above.

◆ dotHeader()

template<int dim>

static std::string regina::detail::FacetPairingBase< dim >::dotHeader ( const char * graphName = nullptr )

static

Returns header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings.

See the dot() documentation for further information on such graphs.

The output will be in the Graphviz DOT language, and will include appropriate display settings for graphs, edges and nodes. The opening brace for a graph section of the DOT file is included.

This routine may be used with dot() or writeDot() to generate a single DOT file containing the graphs for several different facet pairings. A complete DOT file can be produced by calling this routine, then calling dot() or writeDot() in subgraph mode for each facet pairing, then outputting a final closing curly brace.

Note that if you require a DOT file containing the graph for only a single facet pairing, this routine is unnecessary; you may simply call dot() or writeDot() in full graph mode instead.

This routine is suitable for generating undirected graphs, not directed graphs. The final DOT file should be used with either the neato or fdp programs shipped with Graphviz.

If you are simply writing this string to an output stream then you should call writeDotHeader() instead, which is more efficient.

Parameters

graphName the name of the graph to write in the DOT header. If this is null or empty then a default graph name will be used.

Returns: the DOT header information, as outlined above.

See also: http://www.graphviz.org/

◆ findAllPairings()

template<int dim>

template<typename Action , typename... Args>

void regina::detail::FacetPairingBase< dim >::findAllPairings	(	size_t	nSimplices,
		BoolSet	boundary,
		int	nBdryFacets,
		Action &&	action,
		Args &&...	args
	)

inlinestatic

Generates all possible facet pairings satisfying the given constraints.

Only connected facet pairings (pairings in which each simplex can be reached from each other via a series of individual matched facets) will be produced.

Each facet pairing will be produced precisely once up to isomorphism. Facet pairings are considered isomorphic if they are related by a relabelling of the simplices and/or a renumbering of the (dim + 1) facets of each simplex. Each facet pairing that is generated will be a lexicographically minimal representative of its isomorphism class, i.e., will be in canonical form as described by isCanonical().

For each facet pairing that is generated, this routine will call action (which must be a function or some other callable object).

The first argument to action must be a const reference to a FacetPairing<dim>. This will be the facet pairing that was found. If action wishes to keep the facet pairing, it should take a deep copy (not a reference), since the facet pairing may be changed and reused after action returns.
If action takes a FacetPairing<dim>::IsoList as its second argument (which may be as a reference, and may have const/volatile qualifiers), then this will be the list of all automorphisms of the facet pairing that was found. This list will be passed by value using move semantics. If action does not take a second argument, or if the second argument is of a different type, then the list of automorphisms will not be passed.
If there are any additional arguments supplied in the list args, then these will be passed as subsequent arguments to action.
action must return void.

Because this class cannot represent an empty facet pairing, if the argument nSimplices is zero then no facet pairings will be generated at all.

Warning: If you are allowing a large number of boundary facets, then the automorphisms groups could be enormous. In this case it is highly recommended that your action does not take the list of all automorphisms as its second argument, since this will avoid the enormous memory cost of storing and passing such a list.

Todo:

Optimise (long-term): When generating facet pairings, do some checking to eliminate cases in which simplex (k > 0) can be swapped with simplex 0 to produce a smaller representation of the same pairing.

Feature: Allow cancellation of facet pairing generation.

Python: This function is available, and action may be a pure Python function. However, its form is more restricted: action must take both a facet pairing and its automorphisms (i.e., the automorphisms argument is not optional); moreover, it cannot take any additional arguments beyond these. As a consequence, the additional args list is omitted also.

Parameters

nSimplices	the number of simplices whose facets should be (potentially) matched.
boundary	determines whether any facets may be left unmatched. This set should contain `true` if pairings with at least one unmatched facet are to be generated, and should contain `false` if pairings with no unmatched facets are to be generated.
nBdryFacets	specifies the precise number of facets that should be left unmatched. If this parameter is negative, it is ignored and no additional restriction is imposed. If parameter boundary does not contain `true`, this parameter is likewise ignored. If parameter boundary does contain true and this parameter is non-negative, only pairings with precisely this many unmatched facets will be generated. In particular, if this parameter is positive then pairings with no unmatched facets will not be produced irrespective of whether `false` is contained in parameter boundary. Note that, in order to produce any pairings at all, this parameter must be of the same parity as `nSimplices * (dim+1)`, and can be at most `(dim-1) * nSimplices + 2`.
action	a function (or other callable object) to call for each facet pairing that is found.
args	any additional arguments that should be passed to action, following the initial facet pairing argument and the optional automorphism argument.

◆ findAutomorphisms()

template<int dim>

FacetPairingBase< dim >::IsoList regina::detail::FacetPairingBase< dim >::findAutomorphisms

inline

Returns the set of all combinatorial automorphisms of this facet pairing, assuming the pairing is already in canonical form.

See the FacetPairing class notes for more information on isomorphisms, automorphisms and canonical form.

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.; This facet pairing is in canonical form. This is crucial, since this routine uses optimisations that can cause unpredictable breakages if this facet pairing is not in canonical form.

Returns: the list of all automorphisms.

◆ fromTextRep()

template<int dim>

static FacetPairing< dim > regina::detail::FacetPairingBase< dim >::fromTextRep ( const std::string & rep )

static

Reconstructs a facet pairing from a text-based representation.

This text-based representation must be in the format produced by routine textRep().

Exceptions

InvalidArgument The given string was not a valid text-based representation of a facet pairing on a positive number of simplices.

Parameters

rep	a text-based representation of a facet pairing, as produced by routine textRep().

Returns: the corresponding facet pairing.

◆ isCanonical()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isCanonical ( ) const

Determines whether this facet pairing is in canonical form.

See the FacetPairing class notes for more information on isomorphisms, automorphisms and canonical form.

Precondition: This facet pairing is connected, i.e., it is possible to reach any simplex from any other simplex via a series of matched facet pairs.

Returns: true if and only if this facet pairing is in canonical form.

◆ isCanonicalInternal()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isCanonicalInternal ( IsoList * list = nullptr ) const

protected

Determines whether this facet pairing is in canonical (smallest lexicographical) form, given a small set of assumptions.

If the argument list is non-null, then:

If this facet pairing is in canonical form, the given list will be filled with the set of all combinatorial automorphisms of this facet pairing.
If not, the given list will be returned empty.

Precondition: The given list (if one is provided) is empty.; For each simplex t, the only case in which dest(t,i) is greater than dest(t,i+1) is where facets (t,i) and (t,i+1) are paired together.; For each simplex t > 0, it is true that dest(t,0).simp < t.; The sequence dest(1,0), dest(2,0), ..., dest(n-1,0) is strictly increasing, where n is the total number of simplices under investigation.

Parameters

list	the list into which automorphisms will be placed if this facet pairing is indeed canonical, or null if the automorphisms are not requred.

Returns: true if and only if this facet pairing is in canonical form.

◆ isClosed()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isClosed ( ) const

Determines whether this facet pairing is closed.

A closed facet pairing has no unmatched facets.

◆ isConnected()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isConnected ( ) const

Determines whether this facet pairing is connected.

A facet pairing is connected if it is possible to reach any simplex from any other simplex via a series of matched facet pairs.

For this purpose, the empty facet pairing is considered to be connected.

Returns: true if and only if this pairing is connected.

◆ isUnmatched() [1/2]

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isUnmatched ( const FacetSpec< dim > & source ) const

inline

Determines whether the given simplex facet has been left deliberately unmatched.

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: true if the given facet has been left unmatched, or false if the given facet is paired with some other facet.

◆ isUnmatched() [2/2]

template<int dim>

bool regina::detail::FacetPairingBase< dim >::isUnmatched	(	size_t	simp,
		int	facet
	)		const

inline

Determines whether the given simplex facet has been left deliberately unmatched.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: true if the given facet has been left unmatched, or false if the given facet is paired with some other facet.

◆ noDest() [1/2]

template<int dim>

bool regina::detail::FacetPairingBase< dim >::noDest ( const FacetSpec< dim > & source ) const

inlineprotected

Determines whether the matching for the given simplex facet has not yet been determined.

This is signalled by a facet matched to itself.

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: true if the matching for the given facet has not yet been determined, or false otherwise.

◆ noDest() [2/2]

template<int dim>

bool regina::detail::FacetPairingBase< dim >::noDest	(	size_t	simp,
		int	facet
	)		const

inlineprotected

Determines whether the matching for the given simplex facet has not yet been determined.

This is signalled by a facet matched to itself.

Parameters

simp	the simplex under investigation (this must be strictly less than the total number of simplices under consideration).
facet	the facet of the given simplex under investigation (between 0 and dim inclusive).

Returns: true if the matching for the given facet has not yet been determined, or false otherwise.

◆ operator!=()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::operator!= ( const FacetPairing< dim > & other ) const

Determines if this and the given facet pairing are not identical.

Parameters

other the facet pairing to compare with this.

Returns: true if and only if this and the given facet pairing are not identical.

◆ operator=() [1/2]

template<int dim>

FacetPairingBase< dim > & regina::detail::FacetPairingBase< dim >::operator= ( const FacetPairingBase< dim > & src )

inline

Copies the given facet pairing into this facet pairing.

It does not matter if this and the given facet pairing use different numbers of top-dimensional simpilices; if they do then this facet pairing will be resized accordingly.

This operator induces a deep copy of src.

Parameters

src	the facet pairing to copy.

Returns: a reference to this facet pairing.

◆ operator=() [2/2]

template<int dim>

FacetPairingBase< dim > & regina::detail::FacetPairingBase< dim >::operator= ( FacetPairingBase< dim > && src )

inlinenoexcept

Moves the given facet pairing into this facet pairing.

This is a fast (constant time) operation.

It does not matter if this and the given facet pairing use different numbers of top-dimensional simpilices; if they do then this facet pairing will be resized accordingly.

The facet pairing that is passed (src) will no longer be usable.

Parameters

src	the facet pairing to move.

Returns: a reference to this facet pairing.

◆ operator==()

template<int dim>

bool regina::detail::FacetPairingBase< dim >::operator== ( const FacetPairing< dim > & other ) const

Determines if this and the given facet pairing are identical.

Parameters

other the facet pairing to compare with this.

Returns: true if and only if this and the given facet pairing are identical.

◆ operator[]() [1/2]

template<int dim>

FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::operator[] ( const FacetSpec< dim > & source )

inlineprotected

Returns the other facet to which the given simplex facet is paired.

This is a convenience operator whose behaviour is identical to that of dest(const FacetSpec<dim>&).

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ operator[]() [2/2]

template<int dim>

const FacetSpec< dim > & regina::detail::FacetPairingBase< dim >::operator[] ( const FacetSpec< dim > & source ) const

inline

Returns the other facet to which the given simplex facet is paired.

This is a convenience operator whose behaviour is identical to that of dest(const FacetSpec<dim>&).

If the given facet is left deliberately unmatched, the value returned will be boundary (as returned by FacetSpec<dim>::isBoundary()).

Precondition: The given facet is a real simplex facet (not boundary, before-the-start or past-the-end).

Python: This routine returns by value, not by reference, since Python cannot enforce constness otherwise.

Parameters

source the facet under investigation.

Returns: the other facet to which the given facet is paired.

◆ size()

template<int dim>

size_t regina::detail::FacetPairingBase< dim >::size

inline

Returns the number of simplices whose facets are described by this facet pairing.

Python: This is also used to implement the Python special method len().

Returns: the number of simplices under consideration.

◆ str()

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

◆ swap()

template<int dim>

void regina::detail::FacetPairingBase< dim >::swap ( FacetPairingBase< dim > & other )

inlinenoexcept

Swaps the contents of this and the given facet pairing.

Parameters

other the facet pairing whose contents are to be swapped with this.

◆ textRep()

template<int dim>

std::string regina::detail::FacetPairingBase< dim >::textRep ( ) const

Returns a text-based representation that can be used to reconstruct this facet pairing.

This reconstruction is done through the routine fromTextRep().

The text produced is not particularly readable; for a human-readable text representation, see routine str() instead.

The string returned will contain no newlines.

Returns: a text-based representation of this facet pairing.

◆ tightDecode()

template<int dim>

FacetPairing< dim > regina::detail::FacetPairingBase< dim >::tightDecode ( std::istream & input )

static

Reconstructs a facet pairing from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

Exceptions

InvalidInput The given input stream does not begin with a tight encoding of a dim-dimensional facet pairing on a positive number of simplices.

Python: Not present. Use tightDecoding() instead, which takes a string as its argument.

Parameters

input an input stream that begins with the tight encoding for a dim-dimensional facet pairing.

Returns: the facet pairing represented by the given tight encoding.

◆ tightDecoding()

static FacetPairing< dim > regina::TightEncodable< FacetPairing< dim > >::tightDecoding ( const std::string & enc )

inlinestaticinherited

Reconstructs an object of type T from its given tight encoding.

See the page on tight encodings for details.

The tight encoding should be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

Exceptions

InvalidArgument The given string is not a tight encoding of an object of type T.

Parameters

enc	the tight encoding for an object of type T.

Returns: the object represented by the given tight encoding.

◆ tightEncode()

template<int dim>

void regina::detail::FacetPairingBase< dim >::tightEncode ( std::ostream & out ) const

Writes the tight encoding of this facet pairing to the given output stream.

See the page on tight encodings for details.

Precondition: Every simplex facet is either (i) paired to another simplex facet, (ii) marked as boundary, or (iii) paired to itself (which is often used as a placeholder to indicate that the real destination has not yet been decided). In particular, before-the-start or past-the-end destinations are not allowed.

Exceptions

FailedPrecondition Some simplex facet has a destination that is explicitly disallowed by the precondition above.

Python: Not present. Use tightEncoding() instead, which returns a string.

Parameters

out	the output stream to which the encoded string will be written.

◆ tightEncoding()

std::string regina::TightEncodable< FacetPairing< dim > >::tightEncoding ( ) const

inlineinherited

Returns the tight encoding of this object.

See the page on tight encodings for details.

Exceptions

FailedPrecondition This may be thrown for some classes T if the object is in an invalid state. If this is possible, then a more detailed explanation of "invalid" can be found in the class documentation for T, under the member function T::tightEncode(). See FacetPairing::tightEncode() for an example of this.

Returns: the resulting encoded string.

◆ toTextRep()

template<int dim>

std::string regina::detail::FacetPairingBase< dim >::toTextRep

inline

Deprecated routine that returns a text-based representation that can be used to reconstruct this facet pairing.

Deprecated:: This routine has been renamed to textRep(). See the textRep() documentation for further details.

Returns: a text-based representation of this facet pairing.

◆ utf8()

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

◆ writeDot()

template<int dim>

void regina::detail::FacetPairingBase< dim >::writeDot	(	std::ostream &	out,
		const char *	prefix = `nullptr`,
		bool	subgraph = `false`,
		bool	labels = `false`
	)		const

Writes the graph corresponding to this facet pairing in the Graphviz DOT language.

See dot() for further details on what this output contains.

This routine is equivalent to (but faster than) writing the string returned by dot() to the given output stream.

Python: Not present. Use dot() instead, which returns a string.

Parameters

out	the output stream to which to write.
prefix	a string to prepend to the name of each graph vertex, and to include in the graph or subgraph name; see above for details.
subgraph	`false` if a complete standalone DOT graph should be output, or `true` if a clustered subgraph should be output for use in some larger DOT file.
labels	indicates whether graph vertices will be labelled with the corresponding simplex numbers. This feature is currently experimental, and the default is `false`.

See also: http://www.graphviz.org/

◆ writeDotHeader()

template<int dim>

static void regina::detail::FacetPairingBase< dim >::writeDotHeader	(	std::ostream &	out,
		const char *	graphName = `nullptr`
	)

static

Writes header information for a Graphviz DOT file that will describe the graphs for one or more facet pairings.

See dotHeader() for further details on what this output contains.

This routine is equivalent to (but faster than) writing the string returned by dotHeader() to the given output stream.

Python: Not present. Use dotHeader() instead, which returns a string.

Parameters

out	the output stream to which to write.
graphName	the name of the graph to write in the DOT header. If this is null or empty then a default graph name will be used.

See also: http://www.graphviz.org/

◆ writeTextLong()

void regina::ShortOutput< FacetPairingBase< dim > , false >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present. Instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<int dim>

void regina::detail::FacetPairingBase< dim >::writeTextShort ( std::ostream & out ) const

Writes a human-readable representation of this facet pairing to the given output stream.

The string returned will contain no newlines.

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ pairs_

template<int dim>

FacetSpec<dim>* regina::detail::FacetPairingBase< dim >::pairs_

protected

The other facet to which each simplex facet is paired.

If a simplex facet is left unmatched, the corresponding element of this array will be boundary (as returned by FacetSpec<dim>::isBoundary()). If the destination for a particular facet has not yet been decided, the facet will be paired to itself.

◆ size_

template<int dim>

size_t regina::detail::FacetPairingBase< dim >::size_

protected

The number of simplices under consideration.

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

triangulation/detail/facetpairing.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Input and Output

Detailed Description

Member Typedef Documentation

◆ IsoList

Constructor & Destructor Documentation

◆ FacetPairingBase() [1/5]

◆ FacetPairingBase() [2/5]

◆ FacetPairingBase() [3/5]

◆ FacetPairingBase() [4/5]

◆ ~FacetPairingBase()

◆ FacetPairingBase() [5/5]

Member Function Documentation

◆ canonical()

◆ canonicalAll()

◆ dest() [1/4]

◆ dest() [2/4]

◆ dest() [3/4]

◆ dest() [4/4]

◆ detail()

◆ divideConnected()

◆ dot()

◆ dotHeader()

◆ findAllPairings()

◆ findAutomorphisms()

◆ fromTextRep()

◆ isCanonical()

◆ isCanonicalInternal()

◆ isClosed()

◆ isConnected()

◆ isUnmatched() [1/2]

◆ isUnmatched() [2/2]

◆ noDest() [1/2]

◆ noDest() [2/2]

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()

◆ str()

◆ swap()

◆ textRep()

◆ tightDecode()

◆ tightDecoding()

◆ tightEncode()

◆ tightEncoding()

◆ toTextRep()

◆ utf8()

◆ writeDot()

◆ writeDotHeader()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ pairs_

◆ size_