Represents a signature of a splitting surface in a closed 3-manifold triangulation. More...

#include <split/signature.h>

Inheritance diagram for regina::Signature:

Public Member Functions
	Signature (const std::string &str)
	Creates a new signature by parsing the given signature string. More...

	Signature (const Signature &sig)
	Creates a new copy of the given signature. More...

	Signature (Signature &&src) noexcept
	Moves the given signature into this new signature. More...

	~Signature ()
	Destroys this signature. More...

Signature &	operator= (const Signature &sig)
	Copies the given signature into this signature. More...

Signature &	operator= (Signature &&src) noexcept
	Moves the given signature into this signature. More...

void	swap (Signature &other) noexcept
	Swaps the contents of this and the given signature. More...

unsigned	order () const
	Returns the order of this signature. More...

bool	operator== (const Signature &other) const
	Determines whether this and the given signature are identical. More...

bool	operator!= (const Signature &other) const
	Determines whether this and the given signature are not identical. More...

Triangulation< 3 >	triangulate () const
	Returns the 3-manifold triangulation corresponding to this splitting surface signature. More...

std::string	str (const std::string &cycleOpen, const std::string &cycleClose, const std::string &cycleJoin) const
	Returns a customised string representation of this signature. More...

void	writeCycles (std::ostream &out, const std::string &cycleOpen, const std::string &cycleClose, const std::string &cycleJoin) const
	Writes a customised string representation of this signature to the given output stream. 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
	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...

Static Public Member Functions
static Signature	parse (const std::string &str)
	Deprecated routine that parses the given signature string. More...

Friends
class	regina::SigPartialIsomorphism

class	regina::SigCensus

Detailed Description

Represents a signature of a splitting surface in a closed 3-manifold triangulation.

A splitting surface is (for these purposes) a compact normal surface consisting of precisely one quad per tetrahedron and no other normal (or almost normal) discs.

A signature of order n is a string consisting of 2n letters arranged into cycles, where n is the number of quads in the splitting surface. From a signature, the corresponding splitting surface and then the entire 3-manifold triangulation can be recreated.

A signature of order n uses the first n letters of the alphabet, each precisely twice. Case is important; the meaning of a letter changes according to whether it appears in upper-case or lower-case.

Each letter represents an individual quadrilateral (the two occurrences of the letter representing the quadrilateral's two sides). Each cycle represents a chain of quadrilaterals joined together in the splitting surface. The case of a letter represents in which direction a quadrilateral is traversed within a cycle.

Cycles are arranged into cycle groups, where a cycle group consists of a series of consecutive cycles all of the same length.

An example of a signature is (abc)(a)(b)(c). This signature is of order 3 and contains two cycle groups, the first being (abc) and the second being (a)(b)(c).

A signature cannot represent a splitting surface with more than 26 quadrilaterals.

For further details on splitting surfaces and their signatures, consult Minimal triangulations and normal surfaces, Burton, PhD thesis, available from the Regina website.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Constructor & Destructor Documentation

◆ Signature() [1/3]

regina::Signature::Signature ( const std::string & str )

Creates a new signature by parsing the given signature string.

Punctuation characters in the given string will be interpreted as separating cycles. All whitespace will be ignored.

Examples of valid signatures are "(ab)(bC)(Ca)" and "AAb-bc-C". See the class notes for further details on what constitutes a valid signature.

Exceptions

InvalidArgument the given string was not a valid signature with a positive number of letters.

Parameters

str	a string representation of a splitting surface signature.

◆ Signature() [2/3]

regina::Signature::Signature ( const Signature & sig )

Creates a new copy of the given signature.

Parameters

sig	the signature to copy.

◆ Signature() [3/3]

regina::Signature::Signature ( Signature && src )

inlinenoexcept

Moves the given signature into this new signature.

This is a fast (constant time) operation.

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

Parameters

src	the signature to move.

◆ ~Signature()

regina::Signature::~Signature ( )

inline

Destroys this signature.

Member Function Documentation

◆ detail()

template<class T , bool supportsUtf8 = false>

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

◆ operator!=()

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

inline

Determines whether this and the given signature are not identical.

To be considered identical, it is not enough for two signatures to be isomorphic: their cycles and cycle groups must be presented in the same order, using the same symbols which must likewise be presented in the same order.

If either signature was parsed from a string, any choice of formatting (e.g., punctuation and/or whitespace) is irrelevant; only the mathematical content of the signatures is important here.

Parameters

other the signature to compare with this.

Returns: true if and only if this and other are not identical.

◆ operator=() [1/2]

Signature & regina::Signature::operator= ( const Signature & sig )

Copies the given signature into this signature.

It does not matter if this and the given signature use different number of symbols, cycles and/or cycle groups; if so then this signature will be adjusted accordingly.

This operator induces a deep copy of sig.

Parameters

sig	the signature to copy.

Returns: a reference to this signature.

◆ operator=() [2/2]

Signature & regina::Signature::operator= ( Signature && src )

inlinenoexcept

Moves the given signature into this signature.

This is a fast (constant time) operation.

It does not matter if this and the given signature use different number of symbols, cycles and/or cycle groups; if so then this signature will be adjusted accordingly.

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

Parameters

src	the signature to move.

Returns: a reference to this signature.

◆ operator==()

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

Determines whether this and the given signature are identical.

To be considered identical, it is not enough for two signatures to be isomorphic: their cycles and cycle groups must be presented in the same order, using the same symbols which must likewise be presented in the same order.

If either signature was parsed from a string, any choice of formatting (e.g., punctuation and/or whitespace) is irrelevant; only the mathematical content of the signatures is important here.

Parameters

other the signature to compare with this.

Returns: true if and only if this and other are identical.

◆ order()

unsigned regina::Signature::order ( ) const

inline

Returns the order of this signature.

The order is the number of quads in the corresponding splitting surface.

Returns: the order of this signature.

◆ parse()

Signature regina::Signature::parse ( const std::string & str )

inlinestatic

Deprecated routine that parses the given signature string.

Deprecated:: This routine has been replaced with a string-based constructor. See the constructor for further details.

Exceptions

InvalidArgument the given string was not a valid signature with a positive number of letters.

Parameters

str	a string representation of a splitting surface signature.

Returns: the corresponding signature.

◆ str() [1/2]

template<class T , bool supportsUtf8 = false>

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

◆ str() [2/2]

std::string regina::Signature::str	(	const std::string &	cycleOpen,
		const std::string &	cycleClose,
		const std::string &	cycleJoin
	)		const

inline

Returns a customised string representation of this signature.

Note that there is also a zero-argument version of str(), inherited through the ShortOutput base class. This zero-argument str() make sensible default choices for the three arguments required here.

Parameters

cycleOpen	the text to write at the beginning of each cycle (such as `"("`).
cycleClose	the text to write at the end of each cycle (such as `")"`).
cycleJoin	the text to write between each pair of consecutive cycles.

◆ swap()

void regina::Signature::swap ( Signature & other )

inlinenoexcept

Swaps the contents of this and the given signature.

It does not matter if this and the given signature use different number of symbols, cycles and/or cycle groups; if so then both signatures will be adjusted accordingly.

Parameters

other the signature whose contents are to be swapped with this.

◆ triangulate()

Triangulation< 3 > regina::Signature::triangulate ( ) const

Returns the 3-manifold triangulation corresponding to this splitting surface signature.

Returns: the corresponding triangulation.

◆ utf8()

template<class T , bool supportsUtf8 = false>

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

◆ writeCycles()

void regina::Signature::writeCycles	(	std::ostream &	out,
		const std::string &	cycleOpen,
		const std::string &	cycleClose,
		const std::string &	cycleJoin
	)		const

Writes a customised string representation of this signature to the given output stream.

Python: Not present; instead use the variant of str() that takes the same three string arguments and returns a string.

Parameters

out	the output stream to which to write.
cycleOpen	the text to write at the beginning of a cycle (such as `"("`).
cycleClose	the text to write at the end of a cycle (such as `")"`).
cycleJoin	the text to write between two cycles.

◆ writeTextLong()

void regina::ShortOutput< Signature , 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()

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

inline

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:

split/signature.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Signature() [1/3]

◆ Signature() [2/3]

◆ Signature() [3/3]

◆ ~Signature()

Member Function Documentation

◆ detail()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ order()

◆ parse()

◆ str() [1/2]

◆ str() [2/2]

◆ swap()

◆ triangulate()

◆ utf8()

◆ writeCycles()

◆ writeTextLong()

◆ writeTextShort()