regina::SatBlockStarterSearcher Class Referenceabstract
Standard Triangulations and Subcomplexes

A helper class for locating and using starter blocks within a triangulation. More...

`#include <subcomplex/satblockstarter.h>`

## Public Member Functions

virtual | ~SatBlockStarterSearcher ()
| Destroys this object and its internal structures. More...
void | findStarterBlocks (Triangulation< 3 > *tri)
| Runs a search for every isomorphic embedding of every starter block from the global SatBlockStarterSet within the given triangulation. More...

## Protected Member Functions

virtual bool | useStarterBlock (SatBlock *starter)=0
| Used by subclasses to process each starter block embedding that is found. More...

## Protected Attributes

SatBlock::TetList | usedTets
| Keeps track of which tetrahedra have used by the current embedding of the current starter block. More...

## Detailed Description

A helper class for locating and using starter blocks within a triangulation.

This class provides a means for searching for each starter block in the global hard-coded SatBlockStarterSet within a given triangulation. More specifically, given some triangulation t, this class can locate every isomorphic embedding of every starter block in the global SatBlockStarterSet as a subcomplex of t (see Triangulation<3>::isContainedIn() for what is meant by "isomorphic embedding").

The routine findStarterBlocks() runs the search. Each time an isomorphic embedding of a starter block is discovered within the given triangulation, the pure virtual routine useStarterBlock() will be called. The block that is passed to useStarterBlock() will be a new block that refers to the particular embedding of the starter block within the given triangulation (as opposed to the original block structure referring to the prebuilt triangulation in SatBlockStarter).

For each situation that requires searching for starter blocks, a subclass of SatBlockStarterSearcher will be required. This subclass should override useStarterBlock() to perform whatever action is necessary.

Instead of locating all isomorphic embeddings of all starter blocks in the global set, the search can be made to finish early once certain conditions are met. This is done by implementing useStarterBlock() to return `false` when the search should quit.

Python:
  Not present.

## Constructor & Destructor Documentation

## ~SatBlockStarterSearcher()

regina::SatBlockStarterSearcher::~SatBlockStarterSearcher | ( |  | ) |

inline virtual

Destroys this object and its internal structures.

## Member Function Documentation

## findStarterBlocks()

void regina::SatBlockStarterSearcher::findStarterBlocks | ( | Triangulation< 3 > * | tri | ) |

Runs a search for every isomorphic embedding of every starter block from the global SatBlockStarterSet within the given triangulation.

Each time an embedding is discovered, the pure virtual routine useStarterBlock() will be called.

See the SatBlockStarterSearcher class notes for greater detail on what this search does and how it runs.

For subclasses that make use of the usedTets data member, it is worth noting that this routine empties the usedTets list on both entry and exit, as well as every time that useStarterBlock() returns after each new embedding is found.

Parameters

  tri | the triangulation in which to search for starter blocks.

## useStarterBlock()

virtual bool regina::SatBlockStarterSearcher::useStarterBlock | ( | SatBlock * | starter | ) |

protected pure virtual

Used by subclasses to process each starter block embedding that is found.

Suppose that the main search routine findStarterBlocks() has been called with some triangulation t. Each time it locates an isomorphic embedding of a starter block within t, it will call useStarterBlock(). Subclasses of SatBlockStarterSearcher should therefore override useStarterBlock() to process each embedding in whatever way is appropriate for the problem at hand.

The block passed in the argument starter is a newly created structure describing the starter block as it appears within the triangulation t. Thus different embeddings of the same starter block within t will pass different starter arguments to this routine. It is the responsibility of useStarterBlock() to either destroy the new block starter or pass ownership of it elsewhere.

When this routine is called, the data member usedTets will contain a list of all tetrahedra from the triangulation t that appear within the relevant starter block embedding. The reimplementation of useStarterBlock() may modify this list as it pleases, since the main search routine will empty the list anyway when useStarterBlock() returns. One possible use for the usedTets data member is for passing to SatBlock::isBlock() or SatRegion::expand() as the list of tetrahedra to avoid in further searches.

This routine must return a boolean; this allows subclasses to immediately terminate the main search once they have found whatever it is they were looking for. A return value of `true` signifies that the search should continue as normal, whereas a return value of `false` signifies that the search should end immediately (specifically, that findStarterBlocks() should clean up and return before all remaining embeddings of all starter blocks have been found).

Warning
  Subclasses must remember to either destroy or claim ownership of the newly created block starter.

Parameters

  starter | a newly created structure describing the starter block as it appears within the larger triangulation currently under examination.

Returns
  `true` if the search for embeddings of starter blocks should continue, or `false` if the search should stop immediately.

## Member Data Documentation

## usedTets

SatBlock::TetList regina::SatBlockStarterSearcher::usedTets

protected

Keeps track of which tetrahedra have used by the current embedding of the current starter block.

See useStarterBlock() for further details.

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

- subcomplex/satblockstarter.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).