Regina Calculation Engine
Classes | Macros | Typedefs | Enumerations | Enumerator | Functions | Variables
Basic Packet Types

Classes

class  regina::Container
 A packet that simply contains other packets. More...
 
struct  regina::PacketInfo< packetType >
 A template that stores information about a particular type of packet. More...
 
class  regina::Packet::ChangeEventSpan
 An object that facilitates firing packetToBeChanged() and packetWasChanged() events. More...
 
class  regina::Packet
 Represents a packet of information that may be individually edited or operated upon. More...
 
class  regina::PacketListener
 An object that can be registered to listen for packet events. More...
 
class  regina::PDF
 A packet that can hold a PDF document. More...
 
class  regina::Script
 A packet representing a Python script that can be run. More...
 
class  regina::Text
 A packet representing a text string. More...
 
class  regina::XMLPacketReader
 An XML element reader that reads the data for an individual packet. More...
 
class  regina::XMLContainerReader
 An XML packet reader that reads a single container. More...
 
class  regina::XMLPDFReader
 An XML packet reader that reads a single PDF packet. More...
 
class  regina::XMLScriptReader
 An XML packet reader that reads a single script. More...
 
class  regina::XMLTextReader
 An XML packet reader that reads a single text packet. More...
 
class  regina::XMLTreeResolutionTask
 An individual task for resolving dangling packet references after an XML data file has been read. More...
 
class  regina::XMLTreeResolver
 Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file. More...
 

Macros

#define REGINA_PACKET(class_, id)
 Defines various constants, types and virtual functions for a subclass of Packet. More...
 
#define REGINA_PACKET_FROM(class_, helper)
 An alternative to REGINA_PACKET, for scenarios where the relevant PacketInfo specialisation is not visible. More...
 

Typedefs

typedef Container regina::NContainer
 Deprecated typedef for backward compatibility. More...
 
typedef Packet regina::NPacket
 Deprecated typedef for backward compatibility. More...
 
typedef PacketListener regina::NPacketListener
 Deprecated typedef for backward compatibility. More...
 
typedef PDF regina::NPDF
 Deprecated typedef for backward compatibility. More...
 
typedef Script regina::NScript
 Deprecated typedef for backward compatibility. More...
 
typedef Text regina::NText
 Deprecated typedef for backward compatibility. More...
 
typedef std::map< std::string, Packet * > regina::XMLTreeResolver::IDMap
 A type that maps internal IDs from the data file to the corresponding packets. More...
 

Enumerations

enum  regina::PacketType {
  regina::PACKET_CONTAINER = 1, regina::PACKET_TEXT = 2, regina::PACKET_TRIANGULATION = 3, regina::PACKET_NORMALSURFACES = 6,
  regina::PACKET_NORMALSURFACELIST = 6, regina::PACKET_SCRIPT = 7, regina::PACKET_SURFACEFILTER = 8, regina::PACKET_ANGLESTRUCTURES = 9,
  regina::PACKET_ANGLESTRUCTURELIST = 9, regina::PACKET_PDF = 10, regina::PACKET_DIM4TRIANGULATION = 11, regina::PACKET_NORMALHYPERSURFACES = 13,
  regina::PACKET_NORMALHYPERSURFACELIST = 13, regina::PACKET_DIM2TRIANGULATION = 15, regina::PACKET_SNAPPEATRIANGULATION = 16, regina::PACKET_TRIANGULATION2 = 15,
  regina::PACKET_TRIANGULATION3 = 3, regina::PACKET_TRIANGULATION4 = 11, regina::PACKET_TRIANGULATION5 = 105, regina::PACKET_TRIANGULATION6 = 106,
  regina::PACKET_TRIANGULATION7 = 107, regina::PACKET_TRIANGULATION8 = 108, regina::PACKET_TRIANGULATION9 = 109, regina::PACKET_TRIANGULATION10 = 110,
  regina::PACKET_TRIANGULATION11 = 111, regina::PACKET_TRIANGULATION12 = 112, regina::PACKET_TRIANGULATION13 = 113, regina::PACKET_TRIANGULATION14 = 114,
  regina::PACKET_TRIANGULATION15 = 115
}
 Represents the different types of packet that are available in Regina. More...
 
enum  regina::PDF::OwnershipPolicy { regina::PDF::OWN_MALLOC, regina::PDF::OWN_NEW, regina::PDF::DEEP_COPY }
 Describes how a PDF packet should claim ownership of a block of binary data. More...
 

Functions

 regina::Container::Container ()
 Default constructor. More...
 
 regina::Container::Container (const std::string &label)
 Constructs a new container with the given packet label. More...
 
virtual void regina::Container::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
static XMLPacketReaderregina::Container::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual bool regina::Container::dependsOnParent () const
 Determines if this packet depends upon its parent. More...
 
virtual Packetregina::Container::internalClonePacket (Packet *parent) const
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::Container::writeXMLPacketData (std::ostream &out) const
 Writes a chunk of XML containing the data for this packet only. More...
 
 regina::Packet::ChangeEventSpan::ChangeEventSpan (Packet *packet)
 Creates a new change event object for the given packet. More...
 
 regina::Packet::ChangeEventSpan::~ChangeEventSpan ()
 Destroys this change event object. More...
 
Packetregina::open (const char *filename)
 Reads a Regina data file, and returns the corresponding packet tree. More...
 
Packetregina::open (std::istream &in)
 Reads a Regina data file from the given input stream, and returns the corresponding packet tree. More...
 
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::ReturnType regina::forPacket (PacketType packetType, FunctionObject &&func, typename ReturnsTraits< FunctionObject >::ReturnType defaultReturn, Args &&... args)
 Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime. More...
 
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::Void regina::forPacket (PacketType packetType, FunctionObject &&func, Args &&... args)
 Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime. More...
 
 regina::PDF::PDF ()
 Creates a PDF packet with no document stored. More...
 
 regina::PDF::PDF (const char *filename)
 Creates a PDF packet with data read from the given PDF file. More...
 
 regina::PDF::PDF (char *data, size_t size, OwnershipPolicy alloc)
 Creates a packet to store the given PDF data. More...
 
 regina::PDF::~PDF ()
 Destroys this PDF packet and deallocates data if required. More...
 
bool regina::PDF::isNull () const
 Determines whether this packet is currently holding a PDF document. More...
 
const char * regina::PDF::data () const
 Returns a pointer to the block of raw data that forms this PDF document. More...
 
size_t regina::PDF::size () const
 Returns the size of this PDF document in bytes. More...
 
void regina::PDF::reset ()
 Empties this PDF packet so that no document is stored. More...
 
void regina::PDF::reset (char *data, size_t size, OwnershipPolicy alloc)
 Refills this PDF packet with the given PDF data. More...
 
bool regina::PDF::savePDF (const char *filename) const
 Saves this PDF document to the given file in PDF format. More...
 
virtual void regina::PDF::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
static XMLPacketReaderregina::PDF::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual bool regina::PDF::dependsOnParent () const
 Determines if this packet depends upon its parent. More...
 
virtual Packetregina::PDF::internalClonePacket (Packet *parent) const
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::PDF::writeXMLPacketData (std::ostream &out) const
 Writes a chunk of XML containing the data for this packet only. More...
 
 regina::Script::Script ()
 Initialises to a script with no text and no variables. More...
 
const std::string & regina::Script::text () const
 Returns the complete text of this script. More...
 
void regina::Script::setText (const std::string &newText)
 Replaces the complete text of this script with the given string. More...
 
void regina::Script::append (const std::string &extraText)
 Adds the given text to the end of this script. More...
 
size_t regina::Script::countVariables () const
 Returns the number of variables associated with this script. More...
 
const std::string & regina::Script::variableName (size_t index) const
 Returns the name of the requested variable associated with this script. More...
 
long regina::Script::variableIndex (const std::string &name) const
 Returns the index of the variable stored with the given name. More...
 
Packetregina::Script::variableValue (size_t index) const
 Returns the value of the requested variable associated with this script. More...
 
Packetregina::Script::variableValue (const std::string &name) const
 Returns the value of the variable stored with the given name. More...
 
void regina::Script::setVariableName (size_t index, const std::string &name)
 Changes the name of an existing variable associated with this script. More...
 
void regina::Script::setVariableValue (size_t index, Packet *value)
 Changes the value of an existing variable associated with this script. More...
 
bool regina::Script::addVariable (const std::string &name, Packet *value)
 Attempts to add a new variable to be associated with this script. More...
 
const std::string & regina::Script::addVariableName (const std::string &name, Packet *value)
 Adds a new variable to be associated with this script, changing its name if necessary. More...
 
void regina::Script::removeVariable (const std::string &name)
 Removes the variable stored with the given name. More...
 
void regina::Script::removeVariable (size_t index)
 Removes the variable stored at the given index. More...
 
void regina::Script::removeAllVariables ()
 Removes all variables associated with this script. More...
 
virtual void regina::Script::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::Script::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
static XMLPacketReaderregina::Script::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual bool regina::Script::dependsOnParent () const
 Determines if this packet depends upon its parent. More...
 
virtual void regina::Script::packetWasRenamed (Packet *packet)
 Called after the packet label or tags have been changed. More...
 
virtual void regina::Script::packetToBeDestroyed (Packet *packet)
 Called before the packet is about to be destroyed. More...
 
virtual Packetregina::Script::internalClonePacket (Packet *parent) const
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::Script::writeXMLPacketData (std::ostream &out) const
 Writes a chunk of XML containing the data for this packet only. More...
 
 regina::Text::Text ()
 Initialises the packet to the empty string. More...
 
 regina::Text::Text (const std::string &newText)
 Initialises the packet to the given string. More...
 
 regina::Text::Text (const char *newText)
 Initialises the packet to the given string. More...
 
const std::string & regina::Text::text () const
 Returns the string stored in the packet. More...
 
void regina::Text::setText (const std::string &newText)
 Sets the packet data to the given string. More...
 
void regina::Text::setText (const char *newText)
 Sets the packet data to the given string. More...
 
virtual void regina::Text::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::Text::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
static XMLPacketReaderregina::Text::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
virtual bool regina::Text::dependsOnParent () const
 Determines if this packet depends upon its parent. More...
 
virtual Packetregina::Text::internalClonePacket (Packet *parent) const
 Makes a newly allocated copy of this packet. More...
 
virtual void regina::Text::writeXMLPacketData (std::ostream &out) const
 Writes a chunk of XML containing the data for this packet only. More...
 
 regina::XMLPacketReader::XMLPacketReader (XMLTreeResolver &resolver)
 Creates a new packet element reader. More...
 
virtual Packetregina::XMLPacketReader::packet ()
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::XMLPacketReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
 Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual void regina::XMLPacketReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader)
 Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual XMLElementReaderregina::XMLPacketReader::startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
 Signifies that a subelement of this XML element is about to be parsed. More...
 
virtual void regina::XMLPacketReader::endSubElement (const std::string &subTagName, XMLElementReader *subReader)
 Signifies that parsing has finished for a subelement of this XML element. More...
 
virtual void regina::XMLPacketReader::abort (XMLElementReader *subReader)
 Signifies that XML parsing has been aborted. More...
 
 regina::XMLContainerReader::XMLContainerReader (XMLTreeResolver &resolver)
 Creates a new container reader. More...
 
virtual Packetregina::XMLContainerReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
 regina::XMLPDFReader::XMLPDFReader (XMLTreeResolver &resolver)
 Creates a new PDF reader. More...
 
virtual Packetregina::XMLPDFReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::XMLPDFReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
 Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual void regina::XMLPDFReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
 Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...
 
 regina::XMLScriptReader::XMLScriptReader (XMLTreeResolver &resolver)
 Creates a new script reader. More...
 
virtual Packetregina::XMLScriptReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::XMLScriptReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
 Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual void regina::XMLScriptReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
 Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...
 
 regina::XMLTextReader::XMLTextReader (XMLTreeResolver &resolver)
 Creates a new text packet reader. More...
 
virtual Packetregina::XMLTextReader::packet () override
 Returns the newly allocated packet that has been read by this element reader. More...
 
virtual XMLElementReaderregina::XMLTextReader::startContentSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps) override
 Used instead of startSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual void regina::XMLTextReader::endContentSubElement (const std::string &subTagName, XMLElementReader *subReader) override
 Used instead of endSubElement() for XML subelements that are not child packets or packet tags. More...
 
virtual regina::XMLTreeResolutionTask::~XMLTreeResolutionTask ()
 A default construct that does nothing. More...
 
virtual void regina::XMLTreeResolutionTask::resolve (const XMLTreeResolver &resolver)=0
 Called by XMLTreeResolver after the entire data file has been read. More...
 
 regina::XMLTreeResolver::XMLTreeResolver ()
 Constructs a resolver with no tasks queued. More...
 
 regina::XMLTreeResolver::~XMLTreeResolver ()
 Destroys any tasks that were queued but not performed. More...
 
void regina::XMLTreeResolver::queueTask (XMLTreeResolutionTask *task)
 Queues a task for processing. More...
 
void regina::XMLTreeResolver::storeID (const std::string &id, Packet *packet)
 Stores the fact that the given packet is stored in the data file using the given internal ID. More...
 
const IDMapregina::XMLTreeResolver::ids () const
 Returns the map from internal IDs to packets, as stored in the data file. More...
 
void regina::XMLTreeResolver::resolve ()
 Calls XMLTreeResolutionTask::resolve() for all queued tasks. More...
 

Variables

XMLTreeResolverregina::XMLPacketReader::resolver_
 The master resolver that will be used to fix dangling packet references after the entire XML file has been read. More...
 

Constructors and Destructors

 regina::Packet::Packet (Packet *parent=0)
 Constructor that inserts the new packet into the overall tree structure. More...
 
virtual regina::Packet::~Packet ()
 Destructor that also orphans this packet and destroys all of its descendants. More...
 

Packet Identification

virtual PacketType regina::Packet::type () const =0
 Returns the unique integer ID representing this type of packet. More...
 
virtual std::string regina::Packet::typeName () const =0
 Returns an English name for this type of packet. More...
 
const std::string & regina::Packet::label () const
 Returns the label associated with this individual packet. More...
 
std::string regina::Packet::humanLabel () const
 Returns the label associated with this individual packet, adjusted if necessary for human-readable output. More...
 
std::string regina::Packet::adornedLabel (const std::string &adornment) const
 Returns the label of this packet adorned with the given string. More...
 
void regina::Packet::setLabel (const std::string &label)
 Sets the label associated with this individual packet. More...
 
std::string regina::Packet::fullName () const
 Returns a descriptive text string for the packet. More...
 

Tags

bool regina::Packet::hasTag (const std::string &tag) const
 Determines whether this packet has the given associated tag. More...
 
bool regina::Packet::hasTags () const
 Determines whether this packet has any associated tags at all. More...
 
bool regina::Packet::addTag (const std::string &tag)
 Associates the given tag with this packet. More...
 
bool regina::Packet::removeTag (const std::string &tag)
 Removes the association of the given tag with this packet. More...
 
void regina::Packet::removeAllTags ()
 Removes all associated tags from this packet. More...
 
const std::set< std::string > & regina::Packet::tags () const
 Returns the set of all tags associated with this packet. More...
 

Event Handling

bool regina::Packet::listen (PacketListener *listener)
 Registers the given packet listener to listen for events on this packet. More...
 
bool regina::Packet::isListening (PacketListener *listener)
 Determines whether the given packet listener is currently listening for events on this packet. More...
 
bool regina::Packet::unlisten (PacketListener *listener)
 Unregisters the given packet listener so that it no longer listens for events on this packet. More...
 

Tree Queries

Packetregina::Packet::parent () const
 Determines the parent packet in the tree structure. More...
 
Packetregina::Packet::firstChild () const
 Determines the first child of this packet in the tree structure. More...
 
Packetregina::Packet::lastChild () const
 Determines the last child of this packet in the tree structure. More...
 
Packetregina::Packet::nextSibling () const
 Determines the next sibling of this packet in the tree structure. More...
 
Packetregina::Packet::prevSibling () const
 Determines the previous sibling of this packet in the tree structure. More...
 
Packetregina::Packet::root () const
 Determines the root of the tree to which this packet belongs. More...
 
unsigned regina::Packet::levelsDownTo (const Packet *descendant) const
 Counts the number of levels between this packet and its given descendant in the tree structure. More...
 
unsigned regina::Packet::levelsUpTo (const Packet *ancestor) const
 Counts the number of levels between this packet and its given ancestor in the tree structure. More...
 
bool regina::Packet::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 regina::Packet::countChildren () const
 Returns the number of immediate children of this packet. More...
 
size_t regina::Packet::countDescendants () const
 Returns the total number of descendants of this packet. More...
 
size_t regina::Packet::totalTreeSize () const
 Determines the total number of packets in the tree or subtree for which this packet is matriarch. More...
 

Tree Manipulation

void regina::Packet::insertChildFirst (Packet *child)
 Inserts the given packet as the first child of this packet. More...
 
void regina::Packet::insertChildLast (Packet *child)
 Inserts the given packet as the last child of this packet. More...
 
void regina::Packet::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 regina::Packet::makeOrphan ()
 Cuts this packet away from its parent in the tree structure and instead makes it matriarch of its own tree. More...
 
void regina::Packet::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 regina::Packet::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 regina::Packet::swapWithNextSibling ()
 Swaps this packet with its next sibling in the sequence of children beneath their common parent packet. More...
 
void regina::Packet::moveUp (unsigned steps=1)
 Moves this packet the given number of steps towards the beginning of its sibling list. More...
 
void regina::Packet::moveDown (unsigned steps=1)
 Moves this packet the given number of steps towards the end of its sibling list. More...
 
void regina::Packet::moveToFirst ()
 Moves this packet to be the first in its sibling list. More...
 
void regina::Packet::moveToLast ()
 Moves this packet to be the last in its sibling list. More...
 
void regina::Packet::sortChildren ()
 Sorts the immediate children of this packet according to their packet labels. More...
 

Searching and Iterating

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

virtual bool regina::Packet::dependsOnParent () const =0
 Determines if this packet depends upon its parent. More...
 
bool regina::Packet::isPacketEditable () const
 Determines whether this packet can be altered without invalidating or otherwise upsetting any of its immediate children. More...
 

Cloning

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

File I/O

bool regina::Packet::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 regina::Packet::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 regina::Packet::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 regina::Packet::internalID () const
 Returns a unique string ID that identifies this packet. More...
 
static XMLPacketReaderregina::Packet::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 Returns a newly created XML element reader that will read the contents of a single XML packet element. More...
 
virtual Packetregina::Packet::internalClonePacket (Packet *parent) const =0
 Makes a newly allocated copy of this packet. More...
 
void regina::Packet::writeXMLPacketTree (std::ostream &out) const
 Writes a chunk of XML containing the subtree with this packet as matriarch. More...
 
virtual void regina::Packet::writeXMLPacketData (std::ostream &out) const =0
 Writes a chunk of XML containing the data for this packet only. More...
 
virtual void regina::Packet::writeTextShort (std::ostream &out) const =0
 Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::Packet::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
bool regina::Packet::hasOwner () const
 Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object. More...
 

Constructors and Destructors

virtual regina::PacketListener::~PacketListener ()
 Destroys this listener. More...
 

Packet Listener Interface

class regina::PacketListener::Packet
 Allow packets to automatically deregister listeners as they are destroyed. More...
 
void regina::PacketListener::unregisterFromAllPackets ()
 Unregisters this listener from any packets to which it is currently listening. More...
 
virtual void regina::PacketListener::packetToBeChanged (Packet *packet)
 Called before the contents of the packet are to be changed. More...
 
virtual void regina::PacketListener::packetWasChanged (Packet *packet)
 Called after the contents of the packet have been changed. More...
 
virtual void regina::PacketListener::packetToBeRenamed (Packet *packet)
 Called before the packet label or tags are to be changed. More...
 
virtual void regina::PacketListener::packetWasRenamed (Packet *packet)
 Called after the packet label or tags have been changed. More...
 
virtual void regina::PacketListener::packetToBeDestroyed (Packet *packet)
 Called before the packet is about to be destroyed. More...
 
virtual void regina::PacketListener::childToBeAdded (Packet *packet, Packet *child)
 Called before a child packet is to be inserted directly beneath the packet. More...
 
virtual void regina::PacketListener::childWasAdded (Packet *packet, Packet *child)
 Called after a child packet has been inserted directly beneath the packet. More...
 
virtual void regina::PacketListener::childToBeRemoved (Packet *packet, Packet *child, bool inParentDestructor)
 Called before a child packet is to be removed from directly beneath the packet. More...
 
virtual void regina::PacketListener::childWasRemoved (Packet *packet, Packet *child, bool inParentDestructor)
 Called after a child packet has been removed from directly beneath the packet. More...
 
virtual void regina::PacketListener::childrenToBeReordered (Packet *packet)
 Called before the child packets directly beneath the packet are to be reordered. More...
 
virtual void regina::PacketListener::childrenWereReordered (Packet *packet)
 Called after the child packets directly beneath the packet have been reordered. More...
 
virtual void regina::PacketListener::childToBeRenamed (Packet *packet, Packet *child)
 Called before one of this packet's immediate children has its label or tags changed. More...
 
virtual void regina::PacketListener::childWasRenamed (Packet *packet, Packet *child)
 Called after one of this packet's immediate children has its label or tags changed. More...
 

Detailed Description

Packet administration and some basic packet types.

Macro Definition Documentation

◆ REGINA_PACKET

#define REGINA_PACKET (   class_,
  id 
)
Value:
public: \
static constexpr const PacketType typeID = id; \
inline virtual PacketType type() const { \
return id; \
} \
inline virtual std::string typeName() const { \
return PacketInfo<id>::name(); \
}

Defines various constants, types and virtual functions for a subclass of Packet.

Every subclass of Packet must include REGINA_PACKET at the beginning of the class definition.

This macro provides the class with:

  • a compile-time constant typeID that is equal to the corresponding PacketType constant;
  • declarations and implementations of the virtual functions Packet::type() and Packet::typeName().

The implementation of this macro relies on the helper class PacketInfo<id>. If the relevant specialisation of PacketInfo is not visible (as is the case, for instance, with templated packet classes such as Triangulation<dim>), then you may replace REGINA_PACKET with the macro REGINA_PACKET_FROM, which allows you to provide an alternative implementation.

Parameters
class_the name of this descendant class of Packet.
idthe corresponding PacketType constant.

◆ REGINA_PACKET_FROM

#define REGINA_PACKET_FROM (   class_,
  helper 
)
Value:
public: \
static constexpr const PacketType typeID = helper::typeID; \
inline virtual PacketType type() const { \
return helper::typeID; \
} \
inline virtual std::string typeName() const { \
return helper::name(); \
}

An alternative to REGINA_PACKET, for scenarios where the relevant PacketInfo specialisation is not visible.

This is intended for use with template classes such as Triangulation<dim>, where the corresponding PacketInfo specialisations are defined in a separate header to avoid triggering unwanted instantiations of every possible Triangulation class.

Like REGINA_PACKET, this macro should be placed in the definition of the relevant subclass of Packet, and in return it provides the same constants, types and virtual functions that REGINA_PACKET does. However, unlike REGINA_PACKET, it does not rely on PacketInfo for its implementation. Instead it calls upon the given class helper, which must provide:

  • a compile-time constant typeID which is equal to the PacketType constant corresponding to this packet class;
  • a static function name() that returns a string giving the human-readable name of this packet type.
Parameters
class_the name of this descendant class of Packet.
helperthe helper class that provides the implementation details, as described above.

Typedef Documentation

◆ IDMap

typedef std::map<std::string, Packet*> regina::XMLTreeResolver::IDMap

A type that maps internal IDs from the data file to the corresponding packets.

See ids() for details.

◆ NContainer

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NContainer has now been renamed to Container.

◆ NPacket

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPacket has now been renamed to Packet.

◆ NPacketListener

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPacketListener has now been renamed to PacketListener.

◆ NPDF

typedef PDF regina::NPDF

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPDF has now been renamed to PDF.

◆ NScript

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NScript has now been renamed to Script.

◆ NText

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NText has now been renamed to Text.

Enumeration Type Documentation

◆ OwnershipPolicy

Describes how a PDF packet should claim ownership of a block of binary data.

Python:\n Not present.
Enumerator
OWN_MALLOC 

The packet should claim ownership of the block, and should assume that it was allocated using malloc().

OWN_NEW 

The packet should claim ownership of the block, and should assume that it was allocated using new[].

DEEP_COPY 

The packet should not claim ownership of the block, but should instead make its own deep copy.

◆ PacketType

Represents the different types of packet that are available in Regina.

IDs 0-9999 are reserved for future use by Regina. If you are extending Regina to include your own packet type, you should choose an ID >= 10000.

Enumerator
PACKET_CONTAINER 

Represents a container packet, of class Container.

PACKET_TEXT 

Represents a text packet, of class Text.

PACKET_TRIANGULATION 

Deprecated alias for PACKET_TRIANGULATION3.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION3.
PACKET_NORMALSURFACES 

Represents a normal surface list, of class NormalSurfaces.

PACKET_NORMALSURFACELIST 

Deprecated alias for PACKET_NORMALSURFACES.

Deprecated:
This constant has been renamed to PACKET_NORMALSURFACES.
PACKET_SCRIPT 

Represents a script packet, of class Script.

PACKET_SURFACEFILTER 

Represents a normal surface filter, of class SurfaceFilter or one of its descendant classes.

PACKET_ANGLESTRUCTURES 

Represents an angle structure list, of class AngleStructures.

PACKET_ANGLESTRUCTURELIST 

Deprecated alias for PACKET_ANGLESTRUCTURES.

Deprecated:
This constant has been renamed to PACKET_ANGLESTRUCTURES.
PACKET_PDF 

Represents a PDF document, of class PDF.

PACKET_DIM4TRIANGULATION 

Deprecated alias for PACKET_TRIANGULATION4.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION4.
PACKET_NORMALHYPERSURFACES 

Represents a normal hypersurface list, of class NormalHypersurfaces.

PACKET_NORMALHYPERSURFACELIST 

Deprecated alias for PACKET_NORMALHYPERSURFACES.

Deprecated:
This constant has been renamed to PACKET_NORMALHYPERSURFACES.
PACKET_DIM2TRIANGULATION 

Deprecated alias for PACKET_TRIANGULATION2.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION2.
PACKET_SNAPPEATRIANGULATION 

Represents a triangulation in the embedded SnapPea kernel, of class SnapPeaTriangulation.

PACKET_TRIANGULATION2 

Represents a 2-dimensional triangulation, of class Triangulation<2>.

PACKET_TRIANGULATION3 

Represents a 3-dimensional triangulation, of class Triangulation<3>.

PACKET_TRIANGULATION4 

Represents a 4-dimensional triangulation, of class Triangulation<4>.

PACKET_TRIANGULATION5 

Represents a 5-dimensional triangulation, of class Triangulation<5>.

PACKET_TRIANGULATION6 

Represents a 6-dimensional triangulation, of class Triangulation<6>.

PACKET_TRIANGULATION7 

Represents a 7-dimensional triangulation, of class Triangulation<7>.

PACKET_TRIANGULATION8 

Represents a 8-dimensional triangulation, of class Triangulation<8>.

PACKET_TRIANGULATION9 

Represents a 9-dimensional triangulation, of class Triangulation<9>.

PACKET_TRIANGULATION10 

Represents a 10-dimensional triangulation, of class Triangulation<10>.

PACKET_TRIANGULATION11 

Represents a 11-dimensional triangulation, of class Triangulation<11>.

PACKET_TRIANGULATION12 

Represents a 12-dimensional triangulation, of class Triangulation<12>.

PACKET_TRIANGULATION13 

Represents a 13-dimensional triangulation, of class Triangulation<13>.

PACKET_TRIANGULATION14 

Represents a 14-dimensional triangulation, of class Triangulation<14>.

PACKET_TRIANGULATION15 

Represents a 15-dimensional triangulation, of class Triangulation<15>.

Function Documentation

◆ abort()

virtual void regina::XMLPacketReader::abort ( XMLElementReader subReader)
virtual

Signifies that XML parsing has been aborted.

This element reader will be destroyed shortly after this routine is called.

The default implementation does nothing.

Parameters
subReaderthe corresponding child reader if a subelement is currently being parsed, or 0 otherwise. If this parameter is non-zero, it is guaranteed that abort() has already been called upon the child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLElementReader.

◆ addTag()

bool regina::Packet::addTag ( const std::string &  tag)

Associates the given tag with this packet.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

Precondition
The given tag is not the empty string.
Parameters
tagthe tag to add.
Returns
true if the given tag was successfully added, or false if the given tag was already present beforehand.

◆ addVariable()

bool regina::Script::addVariable ( const std::string &  name,
Packet value 
)
inline

Attempts to add a new variable to be associated with this script.

If a variable with the given name is already stored, this routine will do nothing.

If you need to ensure that a new variable is always added, even if the variable name needs to change, see the routine addVariableName() instead.

Warning
The index of the new variable might not be countVariables()-1, and this operation may change the indices of other variables also. This is because (at present) variables are kept stored in sorted order by name.
Parameters
namethe name of the new variable.
valuethe value of the new variable; this is allowed to be null.
Returns
true if the variable was successfully added, or false if a variable with the given name was already stored.

◆ addVariableName()

const std::string& regina::Script::addVariableName ( const std::string &  name,
Packet value 
)

Adds a new variable to be associated with this script, changing its name if necessary.

If the given variable name does not already exist as a variable name in this script, then it will be used without modification. Otherwise a new variable name will be constructed by appending additional characters to name.

Warning
The index of the new variable might not be countVariables()-1, and this operation may change the indices of other variables also. This is because (at present) variables are kept stored in sorted order by name.
Parameters
namethe string upon which the new variable name will be based.
valuethe value of the new variable; this is allowed to be null.
Returns
the name of the variable that was added; this might or might not be equal to name.

◆ adornedLabel()

std::string regina::Packet::adornedLabel ( const std::string &  adornment) const

Returns the label of this packet adorned with the given string.

An adornment typically shows how a packet has been created and/or modified. For instance, the adornment argument might be "Filled", or "Summand #1".

The way in which the packet label is adorned depends upon the label itself (in particular, an empty packet label will be handled in a sensible way). The way in which the packet label is adorned is subject to change in future versions of Regina.

Note that, whilst this routine returns a modified version of the packet label, the label itself will not be permamently changed.

Parameters
adornmentthe string that will be used to adorn this packet label. The adornment should just be a piece of English, ideally beginning with an upper-case letter. It should not contain any surrounding punctuation such as brackets or a dash (this will be added automatically by this routine as required).
Returns
a copy of the packet label with the given adornment.

◆ append()

void regina::Script::append ( const std::string &  extraText)
inline

Adds the given text to the end of this script.

Parameters
extraTextthe text to add.

◆ ChangeEventSpan()

regina::Packet::ChangeEventSpan::ChangeEventSpan ( Packet packet)
inline

Creates a new change event object for the given packet.

If this is the only ChangeEventSpan currently in existence for the given packet, this constructor will call PacketListener::packetToBeChanged() for all registered listeners for the given packet.

Parameters
packetthe packet whose data is about to change.

◆ childrenToBeReordered()

void regina::PacketListener::childrenToBeReordered ( Packet packet)
inlinevirtual

Called before the child packets directly beneath the packet are to be reordered.

Once the reordering is done, childrenWereReordered() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ childrenWereReordered()

void regina::PacketListener::childrenWereReordered ( Packet packet)
inlinevirtual

Called after the child packets directly beneath the packet have been reordered.

Before this reordering is done, childrenToBeReordered() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ childToBeAdded()

void regina::PacketListener::childToBeAdded ( Packet packet,
Packet child 
)
inlinevirtual

Called before a child packet is to be inserted directly beneath the packet.

Once the child is removed, childWasAdded() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet to be added.

◆ childToBeRemoved()

void regina::PacketListener::childToBeRemoved ( Packet packet,
Packet child,
bool  inParentDestructor 
)
inlinevirtual

Called before a child packet is to be removed from directly beneath the packet.

Note that the child packet may be about to be destroyed (although this destruction will not have happened yet). Once the child is removed, childWasRemoved() will be called also.

Note also that this packet (the parent) may have already entered its destructor (which removes and destroys all child packets as a matter of course). In this situation it may be unsafe to query or update this packet, and so the third argument inParentDestructor is provided to indicate such a situation.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet to be removed.
inParentDestructorset to true if the parent packet is in fact being destroyed, and the child was simply removed as part of the standard subtree destruction.

◆ childToBeRenamed()

void regina::PacketListener::childToBeRenamed ( Packet packet,
Packet child 
)
inlinevirtual

Called before one of this packet's immediate children has its label or tags changed.

Before this change, childToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet to be renamed.
See also
packetToBeRenamed()

◆ childWasAdded()

void regina::PacketListener::childWasAdded ( Packet packet,
Packet child 
)
inlinevirtual

Called after a child packet has been inserted directly beneath the packet.

Before this child is added, childToBeAdded() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet that was added.

◆ childWasRemoved()

void regina::PacketListener::childWasRemoved ( Packet packet,
Packet child,
bool  inParentDestructor 
)
inlinevirtual

Called after a child packet has been removed from directly beneath the packet.

Note that the child packet may be about to be destroyed (although this destruction will not have happened yet). Before this child is removed, childToBeRemoved() will be called also.

Note also that this packet (the parent) may have already entered its destructor (which removes and destroys all child packets as a matter of course). In this situation it may be unsafe to query or update this packet, and so the third argument inParentDestructor is provided to indicate such a situation.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet that was removed.
inParentDestructorset to true if the parent packet is in fact being destroyed, and the child was simply removed as part of the standard subtree destruction.

◆ childWasRenamed()

void regina::PacketListener::childWasRenamed ( Packet packet,
Packet child 
)
inlinevirtual

Called after one of this packet's immediate children has its label or tags changed.

Before this change, childToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
childthe child packet that was renamed.
See also
packetWasRenamed()

◆ clone()

Packet* regina::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.

Note that any string tags associated with this packet will not be cloned.

If this packet has no parent in the tree structure, no clone will be created and 0 will be returned.

Parameters
cloneDescendantstrue if the descendants of this packet should also be cloned and inserted as descendants of the new packet. If this is passed as false (the default), only this packet will be cloned.
endtrue if the new packet should be inserted at the end of the parent's list of children (the default), or false if the new packet should be inserted as the sibling immediately after this packet.
Returns
the newly inserted packet, or 0 if this packet has no parent.

◆ Container() [1/2]

regina::Container::Container ( )
inline

Default constructor.

◆ Container() [2/2]

regina::Container::Container ( const std::string &  label)
inline

Constructs a new container with the given packet label.

This constructor is (for example) helpful when you are building a complex packet tree to save to a Regina data file, and you are using containers to organise the data in this tree.

Parameters
labelthe packet label for this new container.

◆ countChildren()

size_t regina::Packet::countChildren ( ) const

Returns the number of immediate children of this packet.

Grandchildren and so on are not counted.

Returns
the number of immediate children.

◆ countDescendants()

size_t regina::Packet::countDescendants ( ) const
inline

Returns the total number of descendants of this packet.

This includes children, grandchildren and so on. This packet is not included in the count.

Returns
the total number of descendants.

◆ countVariables()

size_t regina::Script::countVariables ( ) const
inline

Returns the number of variables associated with this script.

Returns
the number of variables.

◆ data()

const char * regina::PDF::data ( ) const
inline

Returns a pointer to the block of raw data that forms this PDF document.

The number of bytes in this block can be found by calling size().

If no PDF document is currently stored (i.e., isNull() returns true), then this routine will return a null pointer.

Python:\n Not present.
Returns
the raw PDF data.

◆ dependsOnParent() [1/5]

bool regina::Container::dependsOnParent ( ) const
inlinevirtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implements regina::Packet.

◆ dependsOnParent() [2/5]

bool regina::Text::dependsOnParent ( ) const
inlinevirtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implements regina::Packet.

◆ dependsOnParent() [3/5]

bool regina::PDF::dependsOnParent ( ) const
inlinevirtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implements regina::Packet.

◆ dependsOnParent() [4/5]

bool regina::Script::dependsOnParent ( ) const
inlinevirtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implements regina::Packet.

◆ dependsOnParent() [5/5]

virtual bool regina::Packet::dependsOnParent ( ) const
pure virtual

Determines if this packet depends upon its parent.

This is true if the parent cannot be altered without invalidating or otherwise upsetting this packet.

Returns
true if and only if this packet depends on its parent.

Implemented in regina::SnapPeaTriangulation, regina::NormalSurfaces, regina::Triangulation< dim >, regina::Triangulation< dim-1 >, regina::Triangulation< 3 >, regina::Script, regina::NormalHypersurfaces, regina::SurfaceFilter, regina::PDF, regina::AngleStructures, regina::Triangulation< 4 >, regina::Triangulation< 2 >, regina::Text, and regina::Container.

◆ endContentSubElement() [1/4]

void regina::XMLPacketReader::endContentSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
inlinevirtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >, regina::detail::XMLTriangulationReaderBase< 2 >, regina::detail::XMLTriangulationReaderBase< 3 >, regina::detail::XMLTriangulationReaderBase< 4 >, regina::XMLTextReader, regina::XMLNormalHypersurfacesReader, regina::XMLScriptReader, regina::XMLNormalSurfacesReader, regina::XMLAngleStructuresReader, regina::XMLFilterPacketReader, regina::XMLPDFReader, and regina::XMLSnapPeaReader.

◆ endContentSubElement() [2/4]

virtual void regina::XMLPDFReader::endContentSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
overridevirtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

◆ endContentSubElement() [3/4]

virtual void regina::XMLScriptReader::endContentSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
overridevirtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

◆ endContentSubElement() [4/4]

void regina::XMLTextReader::endContentSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
inlineoverridevirtual

Used instead of endSubElement() for XML subelements that are not child packets or packet tags.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startContentSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLPacketReader.

◆ endSubElement()

virtual void regina::XMLPacketReader::endSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
virtual

Signifies that parsing has finished for a subelement of this XML element.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented from regina::XMLElementReader.

◆ findPacketLabel() [1/2]

Packet* regina::Packet::findPacketLabel ( const std::string &  label)

Finds the packet with the requested label in the tree or subtree for which this packet is matriarch.

Note that label comparisons are case sensitive.

Parameters
labelthe label to search for.
Returns
the packet with the requested label, or 0 if there is no such packet.

◆ findPacketLabel() [2/2]

const Packet* regina::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.

Note that label comparisons are case sensitive.

Parameters
labelthe label to search for.
Returns
the packet with the requested label, or 0 if there is no such packet.

◆ firstChild()

Packet * regina::Packet::firstChild ( ) const
inline

Determines the first child of this packet in the tree structure.

This routine takes small constant time.

Returns
the first child packet, or 0 if there is none.

◆ firstTreePacket() [1/2]

Packet* regina::Packet::firstTreePacket ( const std::string &  type)

Finds the first packet of the requested type in a complete depth-first iteration of the tree structure.

Note that this packet must be the matriarch of the entire tree.

A parent packet is always reached before its children. The tree matriarch will be the first packet visited in a complete depth-first iteration.

Parameters
typethe type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive.
Returns
the first such packet, or 0 if there are no packets of the requested type.

◆ firstTreePacket() [2/2]

const Packet* regina::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.

Note that this packet must be the matriarch of the entire tree.

A parent packet is always reached before its children. The tree matriarch will be the first packet visited in a complete depth-first iteration.

Parameters
typethe type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive.
Returns
the first such packet, or 0 if there are no packets of the requested type.

◆ forPacket() [1/2]

template<typename FunctionObject , typename... Args>
ReturnsTraits<FunctionObject>::Void regina::forPacket ( PacketType  packetType,
FunctionObject &&  func,
Args &&...  args 
)

Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible packet types known to Regina.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new packet type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated bracket operator, so that func.operator()<PacketInfo<t>>(...) is defined for any valid PacketType enum value t. Then, when the user calls forPacket(packetType, func, ...), this routine will call func.operator()<PacketInfo<packetType>>(...) in turn. If packetType does not denote a valid packet type, then forPacket() will do nothing.

There is also a variant of forPacket() that works with functions with return values, and which takes an extra defaultReturn argument.

Precondition
There must not exist a type FunctionObject::ReturnType (or, if FunctionObject is a reference to a class/struct F, there must likewise not exist a type F::ReturnType). The existence of a type FunctionObject::ReturnType will cause the non-void variant of forPacket() to be used instead.
Python:\n Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
nothing; the return type ReturnsTraits<FunctionObject>::Void simply evaluates to void.

◆ forPacket() [2/2]

template<typename FunctionObject , typename... Args>
ReturnsTraits<FunctionObject>::ReturnType regina::forPacket ( PacketType  packetType,
FunctionObject &&  func,
typename ReturnsTraits< FunctionObject >::ReturnType  defaultReturn,
Args &&...  args 
)

Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible packet types known to Regina.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new packet type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated bracket operator, so that func.operator()<PacketInfo<t>>(...) is defined for any valid PacketType enum value t. Then, when the user calls forPacket(packetType, func, defaultReturn, ...), this routine will call func.operator()<PacketInfo<packetType>>(...) and pass back the corresponding return value. If packetType does not denote a valid packet type, then forPacket() will pass back defaultReturn instead.

There is also a variant of forPacket() that works with void functions, and so does not take the extra defaultReturn argument.

Precondition
The function object must have a typedef ReturnType indicating the return type of the corresponding templated bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.
Python:\n Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
defaultReturnthe value to return if the given packet type is not valid.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
the return value from the corresponding bracket operator of func, or defaultReturn if the given packet type is not valid.

◆ fullName()

std::string regina::Packet::fullName ( ) const

Returns a descriptive text string for the packet.

The string is of the form label (packet-type).

The packet label will be adjusted for human-readable output according to the behaviour of humanLabel().

Returns
the descriptive text string.

◆ hasOwner()

bool regina::Packet::hasOwner ( ) const
inline

Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object.

For packets, this returns true if and only if this packet has a parent in the packet tree (i.e., is not the root).

Returns
true if and only if some other object owns this object.

◆ hasTag()

bool regina::Packet::hasTag ( const std::string &  tag) const
inline

Determines whether this packet has the given associated tag.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

Parameters
tagthe tag to search for.
Returns
true if the given tag is found, false otherwise.

◆ hasTags()

bool regina::Packet::hasTags ( ) const
inline

Determines whether this packet has any associated tags at all.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

Returns
true if this packet has any tags, false otherwise.

◆ humanLabel()

std::string regina::Packet::humanLabel ( ) const
inline

Returns the label associated with this individual packet, adjusted if necessary for human-readable output.

In particular, if the packet has no label assigned then this routine will return "(no label)", not the empty string.

Warning
The method by which this routine adjusts packet labels is subject to change in future versions of Regina.
Returns
this individual packet's label.

◆ ids()

const XMLTreeResolver::IDMap & regina::XMLTreeResolver::ids ( ) const
inline

Returns the map from internal IDs to packets, as stored in the data file.

Packets in a data file may have individual string IDs stored alongside them, in the id attribute of the <packet> tag. These strings are optional, and do not need to be human-readable. Although packets are not required to have IDs, any IDs that are stored must be unique (i.e., two different packets cannot share the same ID).

Note that IDs read from the data file need not bear any relation to the IDs that are returned from Packet::internalID(), although this is typically how they are constructed when a file is saved.

This map will be fleshed out as the data file is read. In particular, since each task runs XMLTreeResolutionTask::resolve() only after the entire tree has been read, tasks may assume that this map contains all IDs that were explicitly stored in the data file.

Only packets with IDs will appear in this map (i.e., there may well be packets in the data file that do not appear in this map at all).

Returns
the map from internal file IDs to packets.

◆ insertChildAfter()

void regina::Packet::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.

This routine takes small constant time.

Precondition
Parameter newChild has no parent packet.
Parameter prevChild is already a child of this packet.
This packet is not a descendant of newChild.
Python:\n Since this packet takes ownership of the given
child packet, the python object containing the given child packet becomes a null object and should no longer be used. See reparent() for a way of avoiding these problems in some cases.
Parameters
newChildthe child to insert.
prevChildthe preexisting child of this packet after which newChild will be inserted, or 0 if newChild is to be the first child of this packet.

◆ insertChildFirst()

void regina::Packet::insertChildFirst ( Packet child)

Inserts the given packet as the first child of this packet.

This routine takes small constant time.

Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Python:\n Since this packet takes ownership of the given
child packet, the python object containing the given child packet becomes a null object and should no longer be used. See reparent() for a way of avoiding these problems in some cases.
Parameters
childthe child to insert.

◆ insertChildLast()

void regina::Packet::insertChildLast ( Packet child)

Inserts the given packet as the last child of this packet.

This routine takes small constant time.

Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Python:\n Since this packet takes ownership of the given
child packet, the python object containing the given child packet becomes a null object and should no longer be used. See reparent() for a way of avoiding these problems in some cases.
Parameters
childthe child to insert.

◆ internalClonePacket() [1/5]

Packet * regina::Container::internalClonePacket ( Packet parent) const
inlineprotectedvirtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implements regina::Packet.

◆ internalClonePacket() [2/5]

Packet * regina::Text::internalClonePacket ( Packet parent) const
inlineprotectedvirtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implements regina::Packet.

◆ internalClonePacket() [3/5]

Packet * regina::PDF::internalClonePacket ( Packet parent) const
inlineprotectedvirtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implements regina::Packet.

◆ internalClonePacket() [4/5]

virtual Packet* regina::Script::internalClonePacket ( Packet parent) const
protectedvirtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implements regina::Packet.

◆ internalClonePacket() [5/5]

virtual Packet* regina::Packet::internalClonePacket ( Packet parent) const
protectedpure virtual

Makes a newly allocated copy of this packet.

This routine should not insert the new packet into the tree structure, clone the packet's associated tags or give the packet a label. It should also not clone any descendants of this packet.

You may assume that the new packet will eventually be inserted into the tree beneath either the same parent as this packet or a clone of that parent.

Parameters
parentthe parent beneath which the new packet will eventually be inserted.
Returns
the newly allocated packet.

Implemented in regina::Triangulation< 3 >, regina::SnapPeaTriangulation, regina::NormalSurfaces, regina::Triangulation< 4 >, regina::SurfaceFilterProperties, regina::NormalHypersurfaces, regina::Triangulation< dim >, regina::Triangulation< dim-1 >, regina::Triangulation< 2 >, regina::SurfaceFilterCombination, regina::Script, regina::SurfaceFilter, regina::PDF, regina::AngleStructures, regina::Text, and regina::Container.

◆ internalID()

std::string regina::Packet::internalID ( ) const

Returns a unique string ID that identifies this packet.

The user has no control over this ID, and it is not human readable. It is guaranteed to remain fixed throughout the lifetime of the program for a given packet, and it is guaranteed not to clash with the ID of any other packet.

If you change the contents of a packet, its ID will not change.

If you clone a packet, the new clone will receive a different ID. If you save and then load a packet to/from file, the ID will change. These behaviours are necessary to ensure that IDs remain unique (since, for instance, you could load several copies of the same data file into memory simultaneously).

The ID is implemented as an encoding of the underlying C++ pointer. This encoding is subject to change in later versions of Regina.

Returns
a unique ID that identifies this packet.

◆ isGrandparentOf()

bool regina::Packet::isGrandparentOf ( const Packet descendant) const

Determines if this packet is equal to or an ancestor of the given packet in the tree structure.

Parameters
descendantthe other packet whose relationships we are examining.
Returns
true if and only if this packet is equal to or an ancestor of descendant.

◆ isListening()

bool regina::Packet::isListening ( PacketListener listener)
inline

Determines whether the given packet listener is currently listening for events on this packet.

See the PacketListener class notes for details.

Python:\n Not present.
Parameters
listenerthe listener to search for.
Returns
true if the given listener is currently registered with this packet, or false otherwise.

◆ isNull()

bool regina::PDF::isNull ( ) const
inline

Determines whether this packet is currently holding a PDF document.

Returns
true if and only if this packet is holding a PDF document.

◆ isPacketEditable()

bool regina::Packet::isPacketEditable ( ) const

Determines whether this packet can be altered without invalidating or otherwise upsetting any of its immediate children.

Descendants further down the packet tree are not (and should not need to be) considered.

Returns
true if and only if this packet may be edited.

◆ label()

const std::string & regina::Packet::label ( ) const
inline

Returns the label associated with this individual packet.

An example is MyTriangulation.

Returns
this individual packet's label.

◆ lastChild()

Packet * regina::Packet::lastChild ( ) const
inline

Determines the last child of this packet in the tree structure.

This routine takes small constant time.

Returns
the last child packet, or 0 if there is none.

◆ levelsDownTo()

unsigned regina::Packet::levelsDownTo ( const Packet descendant) const

Counts the number of levels between this packet and its given descendant in the tree structure.

If descendant is this packet, the number of levels is zero.

Precondition
This packet is equal to descendant, or can be obtained from descendant using only child-to-parent steps.
Parameters
descendantthe packet whose relationship with this packet we are examining.
Returns
the number of levels difference.

◆ levelsUpTo()

unsigned regina::Packet::levelsUpTo ( const Packet ancestor) const
inline

Counts the number of levels between this packet and its given ancestor in the tree structure.

If ancestor is this packet, the number of levels is zero.

Precondition
This packet is equal to ancestor, or can be obtained from ancestor using only parent-to-child steps.
Parameters
ancestorthe packet whose relationship with this packet we are examining.
Returns
the number of levels difference.

◆ listen()

bool regina::Packet::listen ( PacketListener listener)

Registers the given packet listener to listen for events on this packet.

See the PacketListener class notes for details.

Python:\n Not present.
Parameters
listenerthe listener to register.
Returns
true if the given listener was successfully registered, or false if the given listener was already registered beforehand.

◆ makeOrphan()

void regina::Packet::makeOrphan ( )

Cuts this packet away from its parent in the tree structure and instead makes it matriarch of its own tree.

The tree information for both this packet and its parent will be updated.

This routine takes small constant time.

Precondition
This packet has a parent.
This packet does not depend on its parent; see dependsOnParent() for details.
Python:\n After makeOrphan() is called, this packet will
become the root of a new packet tree that is owned by Python. In particular, if you call makeOrphan() and then delete all Python references to this packet, the entire packet subtree will be automatically destroyed.

◆ moveDown()

void regina::Packet::moveDown ( unsigned  steps = 1)

Moves this packet the given number of steps towards the end of its sibling list.

If the number of steps is larger than the greatest possible movement, the packet will be moved to the very end of its sibling list.

This routine takes time proportional to the number of steps.

Precondition
The given number of steps is strictly positive.

◆ moveToFirst()

void regina::Packet::moveToFirst ( )

Moves this packet to be the first in its sibling list.

This routine takes small constant time.

◆ moveToLast()

void regina::Packet::moveToLast ( )

Moves this packet to be the last in its sibling list.

This routine takes small constant time.

◆ moveUp()

void regina::Packet::moveUp ( unsigned  steps = 1)

Moves this packet the given number of steps towards the beginning of its sibling list.

If the number of steps is larger than the greatest possible movement, the packet will be moved to the very beginning of its sibling list.

This routine takes time proportional to the number of steps.

Precondition
The given number of steps is strictly positive.

◆ nextSibling()

Packet * regina::Packet::nextSibling ( ) const
inline

Determines the next sibling of this packet in the tree structure.

This is the child of the parent that follows this packet.

This routine takes small constant time.

Returns
the next sibling of this packet, or 0 if there is none.

◆ nextTreePacket() [1/4]

Packet* regina::Packet::nextTreePacket ( )

Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs.

Note that this packet need not be the tree matriarch.

A parent packet is always reached before its children. The tree matriarch will be the first packet visited in a complete depth-first iteration.

Returns
the next packet, or 0 if this is the last packet in such an iteration.

◆ nextTreePacket() [2/4]

const Packet* regina::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.

Note that this packet need not be the tree matriarch.

A parent packet is always reached before its children. The tree matriarch will be the first packet visited in a complete depth-first iteration.

Returns
the next packet, or 0 if this is the last packet in such an iteration.

◆ nextTreePacket() [3/4]

Packet* regina::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.

Note that this packet need not be the tree matriarch. The order of tree searching is described in firstTreePacket().

Parameters
typethe type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive.
Returns
the next such packet, or 0 if this is the last packet of the requested type in such an iteration.

◆ nextTreePacket() [4/4]

const Packet* regina::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.

Note that this packet need not be the tree matriarch. The order of tree searching is described in firstTreePacket().

Parameters
typethe type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive.
Returns
the next such packet, or 0 if this is the last packet of the requested type in such an iteration.

◆ open() [1/2]

Packet* regina::open ( const char *  filename)

Reads a Regina data file, and returns the corresponding packet tree.

This uses Regina's native XML file format; it does not matter whether the XML file is compressed or uncompressed.

If the file could not be opened or the top-level packet in the tree could not be read, this routine will return 0. If some packet deeper within the tree could not be read then that particular packet (and its descendants, if any) will simply be ignored.

Internationalisation:\n This routine makes no assumptions about the
character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.
Python:\n This function is not automatically imported into the
global namespace when running regina-python or when opening a Python console in the graphical user interface. This is to avoid overriding Python's own built-in open() function. You can access Regina's open() function by calling regina.open().
Parameters
filenamethe pathname of the file to read from.
Returns
the packet tree read from file, or 0 on error (as explained above).

◆ open() [2/2]

Packet* regina::open ( std::istream &  in)

Reads a Regina data file from the given input stream, and returns the corresponding packet tree.

This uses Regina's native XML file format; it does not matter whether the XML file is compressed or uncompressed.

If the stream could not be read or if the top-level packet in the tree could not be read, then this routine will return 0. If some packet deeper within the tree could not be read then that particular packet (and its descendants, if any) will simply be ignored.

Precondition
The given stream is open for reading.
Python:\n Not present.
Parameters
inthe input stream to read from.
Returns
the packet tree read from file, or 0 on error (as explained above).

◆ packet() [1/5]

Packet * regina::XMLPacketReader::packet ( )
inlinevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >, regina::detail::XMLTriangulationReaderBase< 2 >, regina::detail::XMLTriangulationReaderBase< 3 >, regina::detail::XMLTriangulationReaderBase< 4 >, regina::XMLTextReader, regina::XMLNormalHypersurfacesReader, regina::XMLScriptReader, regina::XMLNormalSurfacesReader, regina::XMLAngleStructuresReader, regina::XMLFilterPacketReader, regina::XMLPDFReader, regina::XMLContainerReader, and regina::XMLSnapPeaReader.

◆ packet() [2/5]

Packet * regina::XMLContainerReader::packet ( )
inlineoverridevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

◆ packet() [3/5]

Packet * regina::XMLPDFReader::packet ( )
inlineoverridevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

◆ packet() [4/5]

Packet * regina::XMLScriptReader::packet ( )
inlineoverridevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

◆ packet() [5/5]

Packet * regina::XMLTextReader::packet ( )
inlineoverridevirtual

Returns the newly allocated packet that has been read by this element reader.

Deallocation of this new packet is not the responsibility of this class. Once this routine gives a non-zero return value, it should continue to give the same non-zero return value from this point onwards.

If this routine is ever to give a non-zero return value, it must be giving that non-zero return value by the time the first child packet or packet tag is encountered; otherwise child packets will not be inserted into the packet tree and/or packet tags will not be added.

The newly allocated packet should not be given a packet label. This will be done by XMLPacketReader::endSubElement().

The newly allocated packet may or may not be inserted in the packet tree structure; this does not matter (although if it is inserted it must be inserted in the correct place).

The newly allocated packet should not be given any associated packet tags. This will be done by XMLPacketReader::startSubElement().

The default implementation returns 0.

Returns
the packet that has been read, or 0 if packet reading is incomplete, the packet should be ignored or an error occurred.

Reimplemented from regina::XMLPacketReader.

◆ Packet()

regina::Packet::Packet ( Packet parent = 0)
inline

Constructor that inserts the new packet into the overall tree structure.

The new packet will be inserted as the last child of the given parent, and will be initialised with no children of its own.

Note that Packet is an abstract class and cannot be instantiated directly.

Python:\n Not present.
Parameters
parentthe parent beneath which to insert this packet, or 0 if this packet is to be the matriarch of a new tree.

◆ packetToBeChanged()

void regina::PacketListener::packetToBeChanged ( Packet packet)
inlinevirtual

Called before the contents of the packet are to be changed.

Once the contents are changed, packetWasChanged() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ packetToBeDestroyed() [1/2]

void regina::PacketListener::packetToBeDestroyed ( Packet packet)
inlinevirtual

Called before the packet is about to be destroyed.

Note that there is no matching function called after the packet is destroyed, since the set of listeners will no longer be available at that stage.

When an entire packet subtree is to be destroyed, child packets will notify their listeners of the impending destruction before parent packets will.

Note that the packet will forcibly unregister this listener immediately before packetToBeDestroyed() is called, to avoid any unpleasant consequences if this listener should also try to unregister itself. This means that, by the time this routine is called, this listener will no longer be registered with the packet in question (and any attempt to unregister it again will be harmless).

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

Reimplemented in regina::Script.

◆ packetToBeDestroyed() [2/2]

virtual void regina::Script::packetToBeDestroyed ( Packet packet)
virtual

Called before the packet is about to be destroyed.

Note that there is no matching function called after the packet is destroyed, since the set of listeners will no longer be available at that stage.

When an entire packet subtree is to be destroyed, child packets will notify their listeners of the impending destruction before parent packets will.

Note that the packet will forcibly unregister this listener immediately before packetToBeDestroyed() is called, to avoid any unpleasant consequences if this listener should also try to unregister itself. This means that, by the time this routine is called, this listener will no longer be registered with the packet in question (and any attempt to unregister it again will be harmless).

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

Reimplemented from regina::PacketListener.

◆ packetToBeRenamed()

void regina::PacketListener::packetToBeRenamed ( Packet packet)
inlinevirtual

Called before the packet label or tags are to be changed.

Once the label or tags are changed, packetWasRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
See also
childToBeRenamed()

◆ packetWasChanged()

void regina::PacketListener::packetWasChanged ( Packet packet)
inlinevirtual

Called after the contents of the packet have been changed.

Before the contents are changed, packetToBeChanged() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

Reimplemented in regina::SnapPeaTriangulation.

◆ packetWasRenamed() [1/2]

void regina::PacketListener::packetWasRenamed ( Packet packet)
inlinevirtual

Called after the packet label or tags have been changed.

Before the label or tags are changed, packetToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
See also
childWasRenamed()

Reimplemented in regina::Script.

◆ packetWasRenamed() [2/2]

virtual void regina::Script::packetWasRenamed ( Packet packet)
virtual

Called after the packet label or tags have been changed.

Before the label or tags are changed, packetToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.
See also
childWasRenamed()

Reimplemented from regina::PacketListener.

◆ parent()

Packet * regina::Packet::parent ( ) const
inline

Determines the parent packet in the tree structure.

This routine takes small constant time.

Returns
the parent packet, or 0 if there is none.

◆ PDF() [1/3]

regina::PDF::PDF ( )
inline

Creates a PDF packet with no document stored.

◆ PDF() [2/3]

regina::PDF::PDF ( char *  data,
size_t  size,
OwnershipPolicy  alloc 
)
inline

Creates a packet to store the given PDF data.

The data array must contain a full PDF document as a block of binary data.

The alloc argument shows if/how this packet claims ownership of the data. In particular, unless alloc is DEEP_COPY, this packet will claim ownership of the given data block and will deallocate it when the packet is destroyed. If alloc is DEEP_COPY then the given block of data will not be modified in any way.

It is possible to pass a null pointer as the data array, in which case the new packet will have no PDF document stored (so isNull() will return true).

Python:\n Not present.
Parameters
datathe block of binary data that forms the PDF document, or null if no document is to be stored.
sizethe number of bytes in this block of binary data; if actual data is passed (i.e., data is not null) then this must be strictly positive.
allocdescribes if/how this packet should claim ownership of the given block of data; see the notes above for details.

◆ PDF() [3/3]

regina::PDF::PDF ( const char *  filename)

Creates a PDF packet with data read from the given PDF file.

This routine does not check whether the given file looks like a PDF document; it simply loads the file contents blindly.

If the file could not be read or is empty, then no PDF document will be stored in this packet. You can test this by calling isNull().

Internationalisation:\n This routine makes no assumptions about the
character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.
Parameters
filenamethe filename of the PDF document to read.

◆ prevSibling()

Packet * regina::Packet::prevSibling ( ) const
inline

Determines the previous sibling of this packet in the tree structure.

This is the child of the parent that precedes this packet.

This routine takes small constant time.

Returns
the previous sibling of this packet, or 0 if there is none.

◆ queueTask()

void regina::XMLTreeResolver::queueTask ( XMLTreeResolutionTask task)
inline

Queues a task for processing.

When the file I/O manager calls resolve(), this will call XMLTreeResolutionTask::resolve() for each task that has been queued.

This object will claim ownership of the given task, and will destroy it after resolve() has been called (or, if resolve() is never called, when this XMLTreeResolver is destroyed).

Parameters
taskthe task to be queued.

◆ removeAllTags()

void regina::Packet::removeAllTags ( )

Removes all associated tags from this packet.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

◆ removeAllVariables()

void regina::Script::removeAllVariables ( )
inline

Removes all variables associated with this script.

◆ removeTag()

bool regina::Packet::removeTag ( const std::string &  tag)

Removes the association of the given tag with this packet.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

Parameters
tagthe tag to remove.
Returns
true if the given tag was removed, or false if the given tag was not actually associated with this packet.

◆ removeVariable() [1/2]

void regina::Script::removeVariable ( const std::string &  name)

Removes the variable stored with the given name.

If no variable is stored with the given name, this routine will do nothing.

Warning
This may change the indices of other variables, since (at present) variables are kept stored in sorted order by name.
Parameters
namethe name of the variable to remove; note that names are case sensitive.

◆ removeVariable() [2/2]

void regina::Script::removeVariable ( size_t  index)

Removes the variable stored at the given index.

Warning
This may change the indices of other variables, since (at present) variables are kept stored in sorted order by name.
Parameters
indexthe index of the variable to remove; this must be between 0 and countVariables()-1 inclusive.

◆ reparent()

void regina::Packet::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.

This routine is essentially a combination of makeOrphan() followed by either insertChildFirst() or insertChildLast().

This routine takes small constant time. It is safe to use regardless of whether this packet has a parent or not.

If you wish to reparent all of the children of a given packet, see transferChildren() instead.

Precondition
This packet does not depend on its parent; see dependsOnParent() for details.
The given parent is not a descendant of this packet.
Python:\n This routine is much simpler than combinations of
makeOrphan() and insertChildFirst() / insertChildLast(), since there are no unpleasant ownership issues to deal with. However, if this packet currently has no parent then the ownership issues are unavoidable; in this case reparent() will do nothing, and one of the insertChild...() routines must be used instead.
Parameters
newParentthe new parent of this packet, i.e., the packet beneath which this packet will be inserted.
firsttrue if this packet should be inserted as the first child of the given parent, or false (the default) if it should be inserted as the last child.

◆ reset() [1/2]

void regina::PDF::reset ( )

Empties this PDF packet so that no document is stored.

After calling this routine, isNull() will return true.

The old data will be deallocated if required.

◆ reset() [2/2]

void regina::PDF::reset ( char *  data,
size_t  size,
OwnershipPolicy  alloc 
)

Refills this PDF packet with the given PDF data.

The old data will be deallocated if required.

This routine behaves like the class constructor; see the constructor documentation for details.

Python:\n Not present.
Parameters
datathe block of binary data that forms the new PDF document, or null if no document is to be stored.
sizethe number of bytes in this new block of binary data; if actual data is passed (i.e., data is not null) then this must be strictly positive.
allocdescribes if/how this packet should claim ownership of the given block of data; see the notes above for details.

◆ resolve() [1/2]

void regina::XMLTreeResolver::resolve ( )
inline

Calls XMLTreeResolutionTask::resolve() for all queued tasks.

The tasks will then be destroyed and removed from the queue (so subsequent calls to resolve() are safe and will do nothing).

◆ resolve() [2/2]

virtual void regina::XMLTreeResolutionTask::resolve ( const XMLTreeResolver resolver)
pure virtual

Called by XMLTreeResolver after the entire data file has been read.

Subclasses should override this routine to perform whatever "fleshing out" is necessary for a packet whose internal data is not yet complete.

Parameters
resolverthe master resolver managing the resolution process, as outlined in the XMLTreeResolver class notes.

◆ root()

Packet* regina::Packet::root ( ) const

Determines the root of the tree to which this packet belongs.

Returns
the matriarch of the packet tree.

◆ save() [1/2]

bool regina::Packet::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.

The XML file may be optionally compressed (Regina can happily read both compressed and uncompressed XML).

This is the preferred way of saving a Regina data file. Typically this will be called from the root of the packet tree, which will save the entire packet tree to file.

Precondition
The given packet does not depend on its parent.
Internationalisation:\n This routine makes no assumptions about the
character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.
Parameters
filenamethe pathname of the file to write to.
compressedtrue if the XML data should be compressed, or false if it should be written as plain text.
Returns
true if and only if the file was successfully written.

◆ save() [2/2]

bool regina::Packet::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.

The data file may be optionally compressed (Regina can happily read both compressed and uncompressed XML).

Typically this will be called from the root of the packet tree, which will write the entire packet tree to the given output stream.

Precondition
The given stream is open for writing.
The given packet does not depend on its parent.
Python:\n Not present.
Parameters
sthe output stream to which to write.
compressedtrue if the XML data should be compressed, or false if it should be written as plain text.
Returns
true if and only if the data was successfully written.

◆ savePDF()

bool regina::PDF::savePDF ( const char *  filename) const

Saves this PDF document to the given file in PDF format.

This routine does not check whether the contents of this packet look like a PDF document; it simply writes them blindly to the filesystem.

If no PDF document is currently stored in this PDF packet (i.e., isNull() returns true), then this routine will do nothing and simply return false.

Internationalisation:\n This routine makes no assumptions about the
character encoding used in the given file name, and simply passes it unchanged to low-level C/C++ file I/O routines.
Parameters
filenamethe name of the PDF file to write.
Returns
true if the file was successfully written, or false otherwise.

◆ Script()

regina::Script::Script ( )
inline

Initialises to a script with no text and no variables.

◆ setLabel()

void regina::Packet::setLabel ( const std::string &  label)

Sets the label associated with this individual packet.

Parameters
labelthe new label to give this packet.

◆ setText() [1/3]

void regina::Text::setText ( const char *  newText)
inline

Sets the packet data to the given string.

Parameters
newTextthe new value for the packet.

◆ setText() [2/3]

void regina::Text::setText ( const std::string &  newText)
inline

Sets the packet data to the given string.

Parameters
newTextthe new value for the packet.

◆ setText() [3/3]

void regina::Script::setText ( const std::string &  newText)
inline

Replaces the complete text of this script with the given string.

Variables are not considered part of the text; you can get and set them through other member functions (see below).

Parameters
newTextthe new text for this script.

◆ setVariableName()

void regina::Script::setVariableName ( size_t  index,
const std::string &  name 
)

Changes the name of an existing variable associated with this script.

Warning
This may change the indices of this and other variables, since (at present) variables are kept stored in sorted order by name.
Parameters
indexthe index of the variable whose name should change; this must be between 0 and countVariables()-1 inclusive.
namethe new name to assign to the variable.

◆ setVariableValue()

void regina::Script::setVariableValue ( size_t  index,
Packet value 
)

Changes the value of an existing variable associated with this script.

Parameters
indexthe index of the variable whose value should change; this must be between 0 and countVariables()-1 inclusive.
valuethe new value to assign to the variable.

◆ size()

size_t regina::PDF::size ( ) const
inline

Returns the size of this PDF document in bytes.

If no PDF document is currently stored (i.e., isNull() returns true), then this routine will return zero.

Returns
the number of bytes.

◆ sortChildren()

void regina::Packet::sortChildren ( )

Sorts the immediate children of this packet according to their packet labels.

Note that this routine is not recursive (for instance, grandchildren will not be sorted within each child packet).

This routine takes quadratic time in the number of immediate children (and it's slow quadratic at that).

◆ startContentSubElement() [1/4]

XMLElementReader * regina::XMLPacketReader::startContentSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
inlinevirtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >, regina::detail::XMLTriangulationReaderBase< 2 >, regina::detail::XMLTriangulationReaderBase< 3 >, regina::detail::XMLTriangulationReaderBase< 4 >, regina::XMLTextReader, regina::XMLNormalHypersurfacesReader, regina::XMLScriptReader, regina::XMLNormalSurfacesReader, regina::XMLAngleStructuresReader, regina::XMLFilterPacketReader, regina::XMLPDFReader, and regina::XMLSnapPeaReader.

◆ startContentSubElement() [2/4]

virtual XMLElementReader* regina::XMLPDFReader::startContentSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
overridevirtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

◆ startContentSubElement() [3/4]

virtual XMLElementReader* regina::XMLScriptReader::startContentSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
overridevirtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

◆ startContentSubElement() [4/4]

XMLElementReader * regina::XMLTextReader::startContentSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
inlineoverridevirtual

Used instead of startSubElement() for XML subelements that are not child packets or packet tags.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLPacketReader.

◆ startSubElement()

virtual XMLElementReader* regina::XMLPacketReader::startSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
virtual

Signifies that a subelement of this XML element is about to be parsed.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented from regina::XMLElementReader.

◆ storeID()

void regina::XMLTreeResolver::storeID ( const std::string &  id,
Packet packet 
)
inline

Stores the fact that the given packet is stored in the data file using the given internal ID.

Associations between IDs and packets can be queried through the ids() function. See ids() for further information on internal IDs.

This will be called automatically by XMLPacketReader as it processes packet tags in the data file. Users and/or subclasses of XMLPacketReader do not need to call this function themselves.

Parameters
idthe internal ID of the given packet, as stored in the data file.
packetthe corresponding packet.

◆ swapWithNextSibling()

void regina::Packet::swapWithNextSibling ( )

Swaps this packet with its next sibling in the sequence of children beneath their common parent packet.

Calling this routine is equivalent to calling moveDown().

This routine takes small constant time.

If this packet has no next sibling then this routine does nothing.

◆ tags()

const std::set< std::string > & regina::Packet::tags ( ) const
inline

Returns the set of all tags associated with this packet.

Each packet can have an arbitrary set of string tags associated with it. The tags are not used by this calculation engine; the feature is provided for whatever use a developer or user chooses to make of it.

Tags are case-sensitive. Tags associated with a single packet must be distinct, i.e., a particular tag cannot be associated more than once with the same packet.

Python:\n This routine returns a python list of strings.
Returns
the set of all tags associated with this packet.

◆ Text() [1/3]

regina::Text::Text ( )
inline

Initialises the packet to the empty string.

◆ text() [1/2]

const std::string & regina::Text::text ( ) const
inline

Returns the string stored in the packet.

Returns
the stored string.

◆ text() [2/2]

const std::string & regina::Script::text ( ) const
inline

Returns the complete text of this script.

Variables are not considered part of the text; you can get and set them through other member functions (see below).

Returns
the complete text of this script.

◆ Text() [2/3]

regina::Text::Text ( const char *  newText)
inline

Initialises the packet to the given string.

Parameters
newTextthe new value for the packet.

◆ Text() [3/3]

regina::Text::Text ( const std::string &  newText)
inline

Initialises the packet to the given string.

Parameters
newTextthe new value for the packet.

◆ totalTreeSize()

size_t regina::Packet::totalTreeSize ( ) const

Determines the total number of packets in the tree or subtree for which this packet is matriarch.

This packet is included in the count.

Returns
the total tree or subtree size.

◆ transferChildren()

void regina::Packet::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.

The children of this packet will be appended to the end of the new parent's child list, in the same order as they were previously.

This is equivalent to calling reparent() on each child, but should be somewhat faster if there are many children to move.

Precondition
None of the children of this packet depend on their current parent; see dependsOnParent() for details.
The given parent is not a descendant of this packet.
Parameters
newParentthe new parent beneath which the children will be inserted.

◆ type()

virtual PacketType regina::Packet::type ( ) const
pure virtual

Returns the unique integer ID representing this type of packet.

This is the same for all packets of this class.

Returns
the packet type ID.

◆ typeName()

virtual std::string regina::Packet::typeName ( ) const
pure virtual

Returns an English name for this type of packet.

An example is Triangulation3. This is the same for all packets of this class.

Returns
the packet type name.

◆ unlisten()

bool regina::Packet::unlisten ( PacketListener listener)

Unregisters the given packet listener so that it no longer listens for events on this packet.

See the PacketListener class notes for details.

Python:\n Not present.
Parameters
listenerthe listener to unregister.
Returns
true if the given listener was successfully unregistered, or false if the given listener was not registered in the first place.

◆ unregisterFromAllPackets()

void regina::PacketListener::unregisterFromAllPackets ( )

Unregisters this listener from any packets to which it is currently listening.

◆ variableIndex()

long regina::Script::variableIndex ( const std::string &  name) const

Returns the index of the variable stored with the given name.

Parameters
namethe name of the requested variable; note that names are case sensitive.
Returns
the index of the requested variable as an integer between 0 and countVariables()-1 inclusive, or -1 if there is no variable with the given name.

◆ variableName()

const std::string& regina::Script::variableName ( size_t  index) const

Returns the name of the requested variable associated with this script.

Parameters
indexthe index of the requested variable; this must be between 0 and countVariables()-1 inclusive.
Returns
the name of the requested variable.

◆ variableValue() [1/2]

Packet* regina::Script::variableValue ( const std::string &  name) const

Returns the value of the variable stored with the given name.

Variables may take the value null.

If no variable is stored with the given name, then null will likewise be returned.

Parameters
namethe name of the requested variable; note that names are case sensitive.
Returns
the value of the requested variable.

◆ variableValue() [2/2]

Packet* regina::Script::variableValue ( size_t  index) const

Returns the value of the requested variable associated with this script.

Variables may take the value null.

Parameters
indexthe index of the requested variable; this must be between 0 and countVariables()-1 inclusive.
Returns
the value of the requested variable.

◆ writeTextLong() [1/3]

void regina::Text::writeTextLong ( std::ostream &  out) const
inlinevirtual

Writes a detailed text representation of this object to the given output stream.

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Reimplemented from regina::Packet.

◆ writeTextLong() [2/3]

virtual void regina::Script::writeTextLong ( std::ostream &  out) const
virtual

Writes a detailed text representation of this object to the given output stream.

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Reimplemented from regina::Packet.

◆ writeTextLong() [3/3]

void regina::Packet::writeTextLong ( std::ostream &  out) const
inlinevirtual

Writes a detailed text representation of this object to the given output stream.

This may be reimplemented by subclasses, but the parent Packet class offers a reasonable default implementation.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Reimplemented in regina::SnapPeaTriangulation, regina::SurfaceFilterProperties, regina::NormalSurfaces, regina::Triangulation< dim >, regina::Triangulation< dim-1 >, regina::SurfaceFilterCombination, regina::Triangulation< 3 >, regina::Script, regina::NormalHypersurfaces, regina::AngleStructures, regina::Triangulation< 4 >, regina::Triangulation< 2 >, and regina::Text.

◆ writeTextShort() [1/5]

void regina::Container::writeTextShort ( std::ostream &  out) const
inlinevirtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Implements regina::Packet.

◆ writeTextShort() [2/5]

void regina::Text::writeTextShort ( std::ostream &  out) const
inlinevirtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Implements regina::Packet.

◆ writeTextShort() [3/5]

void regina::PDF::writeTextShort ( std::ostream &  out) const
inlinevirtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Implements regina::Packet.

◆ writeTextShort() [4/5]

void regina::Script::writeTextShort ( std::ostream &  out) const
inlinevirtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Implements regina::Packet.

◆ writeTextShort() [5/5]

virtual void regina::Packet::writeTextShort ( std::ostream &  out) const
pure virtual

Writes a short text representation of this object to the given output stream.

This must be reimplemented by subclasses.

Python:\n Not present.
Parameters
outthe output stream to which to write.

Implemented in regina::SnapPeaTriangulation, regina::NormalSurfaces, regina::Triangulation< dim >, regina::Triangulation< dim-1 >, regina::Triangulation< 3 >, regina::Script, regina::NormalHypersurfaces, regina::SurfaceFilter, regina::PDF, regina::AngleStructures, regina::Triangulation< 4 >, regina::Triangulation< 2 >, regina::Text, and regina::Container.

◆ writeXMLFile()

void regina::Packet::writeXMLFile ( std::ostream &  out) const

Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format.

Ths is similar to calling save(), except that (i) the user has a more flexible choice of output stream, and (ii) the XML will always be written in plain text (i.e., it will not be compressed).

If you simply wish to save your data to a file on the filesystem, you should call save() instead.

Typically this will be called from the root of the packet tree, which will write the entire packet tree to the output stream.

The output from this routine cannot be used as a piece of an XML file; it must be the entire XML file. For a piece of an XML file, see routine writeXMLPacketTree() instead.

Precondition
This packet does not depend upon its parent.
Python:\n The argument out is not present; instead the
XML data is written to standard output.
Parameters
outthe output stream to which the XML data file should be written.

◆ writeXMLPacketData() [1/5]

void regina::Container::writeXMLPacketData ( std::ostream &  out) const
inlineprotectedvirtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implements regina::Packet.

◆ writeXMLPacketData() [2/5]

virtual void regina::Text::writeXMLPacketData ( std::ostream &  out) const
protectedvirtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implements regina::Packet.

◆ writeXMLPacketData() [3/5]

virtual void regina::PDF::writeXMLPacketData ( std::ostream &  out) const
protectedvirtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implements regina::Packet.

◆ writeXMLPacketData() [4/5]

virtual void regina::Script::writeXMLPacketData ( std::ostream &  out) const
protectedvirtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implements regina::Packet.

◆ writeXMLPacketData() [5/5]

virtual void regina::Packet::writeXMLPacketData ( std::ostream &  out) const
protectedpure virtual

Writes a chunk of XML containing the data for this packet only.

You may assume that the packet opening tag (including the packet type and label) has already been written, and that all child packets followed by the corresponding packet closing tag will be written immediately after this routine is called. This routine need only write the internal data stored in this specific packet.

Parameters
outthe output stream to which the XML should be written.

Implemented in regina::Triangulation< 3 >, regina::SnapPeaTriangulation, regina::NormalSurfaces, regina::Triangulation< 4 >, regina::NormalHypersurfaces, regina::Triangulation< dim >, regina::Triangulation< dim-1 >, regina::Triangulation< 2 >, regina::Script, regina::SurfaceFilter, regina::PDF, regina::AngleStructures, regina::Text, and regina::Container.

◆ writeXMLPacketTree()

void regina::Packet::writeXMLPacketTree ( std::ostream &  out) const
protected

Writes a chunk of XML containing the subtree with this packet as matriarch.

This is the preferred way of writing a packet tree to file.

The output from this routine is only a piece of XML; it should not be used as a complete XML file. For a complete XML file, see routine writeXMLFile() instead.

Parameters
outthe output stream to which the XML should be written.

◆ XMLContainerReader()

regina::XMLContainerReader::XMLContainerReader ( XMLTreeResolver resolver)
inline

Creates a new container reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ XMLPacketReader()

regina::XMLPacketReader::XMLPacketReader ( XMLTreeResolver resolver)
inline

Creates a new packet element reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ XMLPDFReader()

regina::XMLPDFReader::XMLPDFReader ( XMLTreeResolver resolver)
inline

Creates a new PDF reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ xmlReader()

static XMLPacketReader* regina::Packet::xmlReader ( Packet parent,
XMLTreeResolver resolver 
)
static

Returns a newly created XML element reader that will read the contents of a single XML packet element.

You may assume that the packet to be read is of the same type as the class in which you are implementing this routine.

The XML element reader should read exactly what writeXMLPacketData() writes, and vice versa.

parent represents the packet which will become the new packet's parent in the tree structure, and may be assumed to have already been read from the file. This information is for reference only, and does not need to be used. The XML element reader can either insert or not insert the new packet beneath parent in the tree structure as it pleases. Note however that parent will be 0 if the new packet is to become a tree matriarch.

If the new packet needs to store pointers to other packets that might not have been read yet (such as a script packet that needs pointers to its variables), then it should queue a new XMLTreeResolutionTask to the given XMLTreeResolver. After the complete data file has been read, XMLTreeResolver::resolve() will run all of its queued tasks, at which point the new packet can resolve any dangling references.

This routine is not actually provided for Packet itself, but must be declared and implemented for every packet subclass that will be instantiated.

Python:\n Not present.
Parameters
parentthe packet which will become the new packet's parent in the tree structure, or 0 if the new packet is to be tree matriarch.
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.
Returns
the newly created XML element reader.

◆ XMLScriptReader()

regina::XMLScriptReader::XMLScriptReader ( XMLTreeResolver resolver)
inline

Creates a new script reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ XMLTextReader()

regina::XMLTextReader::XMLTextReader ( XMLTreeResolver resolver)
inline

Creates a new text packet reader.

Parameters
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.

◆ XMLTreeResolver()

regina::XMLTreeResolver::XMLTreeResolver ( )
inline

Constructs a resolver with no tasks queued.

◆ ~ChangeEventSpan()

regina::Packet::ChangeEventSpan::~ChangeEventSpan ( )
inline

Destroys this change event object.

If this is the only ChangeEventSpan currently in existence for the given packet, this destructor will call PacketListener::packetWasChanged() for all registered listeners for the given packet.

◆ ~Packet()

virtual regina::Packet::~Packet ( )
virtual

Destructor that also orphans this packet and destroys all of its descendants.

◆ ~PacketListener()

virtual regina::PacketListener::~PacketListener ( )
virtual

Destroys this listener.

This listener will be unregistered from any packets to which it is currently listening.

◆ ~PDF()

regina::PDF::~PDF ( )
inline

Destroys this PDF packet and deallocates data if required.

◆ ~XMLTreeResolutionTask()

regina::XMLTreeResolutionTask::~XMLTreeResolutionTask ( )
inlinevirtual

A default construct that does nothing.

◆ ~XMLTreeResolver()

regina::XMLTreeResolver::~XMLTreeResolver ( )
inline

Destroys any tasks that were queued but not performed.

Variable Documentation

◆ resolver_

XMLTreeResolver& regina::XMLPacketReader::resolver_
protected

The master resolver that will be used to fix dangling packet references after the entire XML file has been read.

Friends

◆ Packet

friend class Packet
friend

Allow packets to automatically deregister listeners as they are destroyed.

regina::PacketType
PacketType
Represents the different types of packet that are available in Regina.
Definition: packettype.h:56

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