regina::SurfaceFilter Class Referenceabstract
Normal Surfaces

A packet that accepts or rejects normal surfaces. More...

`#include <surfaces/surfacefilter.h>`

Inheritance diagram for regina::SurfaceFilter:

## Public Types

typedef Packet | SafePointeeType
| The type of object being pointed to. More...

## Public Member Functions

| SurfaceFilter ()
| Creates a new default surface filter. More...
| SurfaceFilter (const SurfaceFilter &cloneMe)
| Creates a new default surface filter. More...
virtual | ~SurfaceFilter ()
| Destroys this surface filter. More...
virtual bool | accept (const NormalSurface &surface) const
| Decides whether or not the given normal surface is accepted by this filter. More...
virtual SurfaceFilterType | filterType () const
| Returns the unique integer ID corresponding to the filtering method that is this particular subclass of SurfaceFilter. More...
virtual std::string | filterTypeName () const
| Returns a string description of the filtering method that is this particular subclass of SurfaceFilter. More...
virtual void | writeTextShort (std::ostream &out) const
| Writes a short text representation of this object to the given output stream. More...
virtual bool | dependsOnParent () const
| Determines if this packet depends upon its parent. 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...
Packet Identification
virtual PacketType | type () const =0
| Returns the unique integer ID representing this type of packet. More...
virtual std::string | typeName () const =0
| Returns an English name for this type of packet. More...
const std::string & | label () const
| Returns the label associated with this individual packet. More...
std::string | humanLabel () const
| Returns the label associated with this individual packet, adjusted if necessary for human-readable output. More...
std::string | adornedLabel (const std::string &adornment) const
| Returns the label of this packet adorned with the given string. More...
void | setLabel (const std::string &label)
| Sets the label associated with this individual packet. More...
std::string | fullName () const
| Returns a descriptive text string for the packet. More...
Tags
bool | hasTag (const std::string &tag) const
| Determines whether this packet has the given associated tag. More...
bool | hasTags () const
| Determines whether this packet has any associated tags at all. More...
bool | addTag (const std::string &tag)
| Associates the given tag with this packet. More...
bool | removeTag (const std::string &tag)
| Removes the association of the given tag with this packet. More...
void | removeAllTags ()
| Removes all associated tags from this packet. More...
const std::set< std::string > & | tags () const
| Returns the set of all tags associated with this packet. More...
Event Handling
bool | listen (PacketListener *listener)
| Registers the given packet listener to listen for events on this packet. More...
bool | isListening (PacketListener *listener)
| Determines whether the given packet listener is currently listening for events on this packet. More...
bool | unlisten (PacketListener *listener)
| Unregisters the given packet listener so that it no longer listens for events on this packet. More...
Tree Queries
Packet * | parent () const
| Determines the parent packet in the tree structure. More...
Packet * | firstChild () const
| Determines the first child of this packet in the tree structure. More...
Packet * | lastChild () const
| Determines the last child of this packet in the tree structure. More...
Packet * | nextSibling () const
| Determines the next sibling of this packet in the tree structure. More...
Packet * | prevSibling () const
| Determines the previous sibling of this packet in the tree structure. More...
Packet * | root () const
| Determines the root of the tree to which this packet belongs. More...
unsigned | levelsDownTo (const Packet *descendant) const
| Counts the number of levels between this packet and its given descendant in the tree structure. More...
unsigned | levelsUpTo (const Packet *ancestor) const
| Counts the number of levels between this packet and its given ancestor in the tree structure. More...
bool | isGrandparentOf (const Packet *descendant) const
| Determines if this packet is equal to or an ancestor of the given packet in the tree structure. More...
size_t | countChildren () const
| Returns the number of immediate children of this packet. More...
size_t | countDescendants () const
| Returns the total number of descendants of this packet. More...
size_t | totalTreeSize () const
| Determines the total number of packets in the tree or subtree for which this packet is matriarch. More...
Tree Manipulation
void | insertChildFirst (Packet *child)
| Inserts the given packet as the first child of this packet. More...
void | insertChildLast (Packet *child)
| Inserts the given packet as the last child of this packet. More...
void | insertChildAfter (Packet *newChild, Packet *prevChild)
| Inserts the given packet as a child of this packet at the given location in this packet's child list. More...
void | makeOrphan ()
| Cuts this packet away from its parent in the tree structure and instead makes it matriarch of its own tree. More...
void | reparent (Packet *newParent, bool first=false)
| Cuts this packet away from its parent in the tree structure, and inserts it as a child of the given packet instead. More...
void | transferChildren (Packet *newParent)
| Cuts all of this packet's children out of the packet tree, and reinserts them as children of the given packet instead. More...
void | swapWithNextSibling ()
| Swaps this packet with its next sibling in the sequence of children beneath their common parent packet. More...
void | moveUp (unsigned steps=1)
| Moves this packet the given number of steps towards the beginning of its sibling list. More...
void | moveDown (unsigned steps=1)
| Moves this packet the given number of steps towards the end of its sibling list. More...
void | moveToFirst ()
| Moves this packet to be the first in its sibling list. More...
void | moveToLast ()
| Moves this packet to be the last in its sibling list. More...
void | sortChildren ()
| Sorts the immediate children of this packet according to their packet labels. More...
Searching and Iterating
Packet * | nextTreePacket ()
| Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
const Packet * | nextTreePacket () const
| Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
Packet * | nextTreePacket (const std::string &type)
| Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
const Packet * | nextTreePacket (const std::string &type) const
| Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
Packet * | firstTreePacket (const std::string &type)
| Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
const Packet * | firstTreePacket (const std::string &type) const
| Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
Packet * | findPacketLabel (const std::string &label)
| Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
const Packet * | findPacketLabel (const std::string &label) const
| Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
Packet Dependencies
bool | isPacketEditable () const
| Determines whether this packet can be altered without invalidating or otherwise upsetting any of its immediate children. More...
Cloning
Packet * | clone (bool cloneDescendants=false, bool end=true) const
| Clones this packet (and possibly its descendants), assigns to it a suitable unused label and inserts the clone into the tree as a sibling of this packet. More...

## Static Public Member Functions

static XMLFilterReader * | xmlFilterReader (Packet *parent)
| Returns a newly created XML filter reader that will read the details of a particular type of surface filter. More...
static XMLPacketReader * | xmlReader (Packet *parent, XMLTreeResolver &resolver)

## Protected Member Functions

virtual void | writeXMLFilterData (std::ostream &out) const
| Writes a chunk of XML containing the details of this filter. More...
virtual Packet * | internalClonePacket (Packet *parent) const
| Makes a newly allocated copy of this packet. More...
virtual void | writeXMLPacketData (std::ostream &out) const
| Writes a chunk of XML containing the data for this packet only. More...

## File I/O

bool | save (const char *filename, bool compressed=true) const
| Saves the subtree rooted at this packet to the given Regina data file, using Regina's native XML file format. More...
bool | save (std::ostream &s, bool compressed=true) const
| Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file. More...
void | writeXMLFile (std::ostream &out) const
| Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format. More...
std::string | internalID () const
| Returns a unique string ID that identifies this packet. More...
virtual void | writeTextLong (std::ostream &out) const
| Writes a detailed text representation of this object to the given output stream. More...
bool | hasOwner () const
| Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object. More...
void | writeXMLPacketTree (std::ostream &out) const
| Writes a chunk of XML containing the subtree with this packet as matriarch. More...

## Detailed Description

A packet that accepts or rejects normal surfaces.

Different subclasses of SurfaceFilter represent different filtering methods.

When deriving classes from SurfaceFilter:

- A new value must be added to the SurfaceFilterType enum in surfacefiltertype.h to represent the new filter type.
- The file filterregistry-impl.h must be updated to reflect the new filter type (the file itself contains instructions on how to do this).
- A corresponding specialisation of SurfaceFilterInfo<> must be defined, typically in the same header as the new filter class.
- The macro REGINA_SURFACE_FILTER must be added to the beginning of the new filter class. This will declare and define various constants, typedefs and virtual functions (see the REGINA_SURFACE_FILTER macro documentation for details).
- A copy constructor `class(const class& cloneMe)` must be declared and implemented. You may assume that parameter cloneMe is of the same class as that whose constructor you are writing.
- Virtual functions accept(), internalClonePacket(), writeTextLong() and writeXMLFilterData() must be overridden.
- Static function xmlFilterReader() must be declared and implemented as described in the documentation below.

Todo:
  Feature: Implement property lastAppliedTo.

## Member Typedef Documentation

## SafePointeeType

typedef Packet regina::SafePointeeBase< Packet >::SafePointeeType

inherited

The type of object being pointed to.

## Member Function Documentation

## detail()

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

## str()

std::string regina::Output< Packet , 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:\n 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< Packet , 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.

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

- surfaces/surfacefilter.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).