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 XMLPacketReader * | regina::Container::xmlReader (Packet *parent, XMLTreeResolver &resolver)
virtual bool | regina::Container::dependsOnParent () const
| Determines if this packet depends upon its parent. More...
virtual Packet * | regina::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...
Packet * | regina::open (const char *filename)
| Reads a Regina data file, and returns the corresponding packet tree. More...
Packet * | regina::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 XMLPacketReader * | regina::PDF::xmlReader (Packet *parent, XMLTreeResolver &resolver)
virtual bool | regina::PDF::dependsOnParent () const
| Determines if this packet depends upon its parent. More...
virtual Packet * | regina::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...
Packet * | regina::Script::variableValue (size_t index) const
| Returns the value of the requested variable associated with this script. More...
Packet * | regina::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 XMLPacketReader * | regina::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 Packet * | regina::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 XMLPacketReader * | regina::Text::xmlReader (Packet *parent, XMLTreeResolver &resolver)
virtual bool | regina::Text::dependsOnParent () const
| Determines if this packet depends upon its parent. More...
virtual Packet * | regina::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 Packet * | regina::XMLPacketReader::packet ()
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::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 XMLElementReader * | regina::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 Packet * | regina::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 Packet * | regina::XMLPDFReader::packet () override
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::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 Packet * | regina::XMLScriptReader::packet () override
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::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 Packet * | regina::XMLTextReader::packet () override
| Returns the newly allocated packet that has been read by this element reader. More...
virtual XMLElementReader * | regina::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 IDMap & | regina::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

XMLTreeResolver & | regina::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

Packet * | regina::Packet::parent () const
| Determines the parent packet in the tree structure. More...
Packet * | regina::Packet::firstChild () const
| Determines the first child of this packet in the tree structure. More...
Packet * | regina::Packet::lastChild () const
| Determines the last child of this packet in the tree structure. More...
Packet * | regina::Packet::nextSibling () const
| Determines the next sibling of this packet in the tree structure. More...
Packet * | regina::Packet::prevSibling () const
| Determines the previous sibling of this packet in the tree structure. More...
Packet * | regina::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

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

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. 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 XMLPacketReader * | regina::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 Packet * | regina::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.
  id | the 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.
  helper | the 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

typedef Container regina::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

typedef Packet regina::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

typedef PacketListener regina::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

typedef Script regina::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

typedef Text regina::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

enum regina::PDF::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

enum regina::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

  subReader | the 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

  tag | the 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

  name | the name of the new variable.
  value | the 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

  name | the string upon which the new variable name will be based.
  value | the 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

  adornment | the 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

  extraText | the 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

  packet | the packet whose data is about to change.

## childrenToBeReordered()

void regina::PacketListener::childrenToBeReordered | ( | Packet * | packet | ) |

inline virtual

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

  packet | the packet being listened to.

## childrenWereReordered()

void regina::PacketListener::childrenWereReordered | ( | Packet * | packet | ) |

inline virtual

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

  packet | the packet being listened to.

## childToBeAdded()

void regina::PacketListener::childToBeAdded | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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

  packet | the packet being listened to.
  child | the child packet to be added.

## childToBeRemoved()

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

inline virtual

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

  packet | the packet being listened to.
  child | the child packet to be removed.
  inParentDestructor | set 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
| ) |  |

inline virtual

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

  packet | the packet being listened to.
  child | the child packet to be renamed.

See also
  packetToBeRenamed()

## childWasAdded()

void regina::PacketListener::childWasAdded | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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

  packet | the packet being listened to.
  child | the child packet that was added.

## childWasRemoved()

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

inline virtual

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

  packet | the packet being listened to.
  child | the child packet that was removed.
  inParentDestructor | set 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
| ) |  |

inline virtual

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

  packet | the packet being listened to.
  child | the 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

  cloneDescendants | `true` 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.
  end | `true` 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

  label | the 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

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

Implements regina::Packet.

## dependsOnParent() [2/5]

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

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

Implements regina::Packet.

## dependsOnParent() [3/5]

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

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

Implements regina::Packet.

## dependsOnParent() [4/5]

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

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

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

inline virtual

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

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the 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
| ) |  |

override virtual

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

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the 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
| ) |  |

override virtual

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

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the 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
| ) |  |

inline override virtual

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

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the 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

  subTagName | the name of the subelement closing tag.
  subReader | the 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

  label | the 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

  label | the 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

  type | the 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

  type | the 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

  packetType | the given packet type.
  func | the function object whose bracket operator we will call with a PacketInfo<packetType> object.
  args | any 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

  packetType | the given packet type.
  func | the function object whose bracket operator we will call with a PacketInfo<packetType> object.
  defaultReturn | the value to return if the given packet type is not valid.
  args | any 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

  tag | the 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

  newChild | the child to insert.
  prevChild | the 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

  child | the 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

  child | the child to insert.

## internalClonePacket() [1/5]

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

inline protected 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

  parent | the 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

inline protected 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

  parent | the 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

inline protected 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

  parent | the 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

protected 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

  parent | the 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

protected pure 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

  parent | the 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

  descendant | the 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

  listener | the 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

  descendant | the 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

  ancestor | the 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

  listener | the 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

  type | the 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

  type | the 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

  filename | the 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

  in | the 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 | ( |  | ) |

inline virtual

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

inline override virtual

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

inline override virtual

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

inline override virtual

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

inline override virtual

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

  parent | the 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 | ) |

inline virtual

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

  packet | the packet being listened to.

## packetToBeDestroyed() [1/2]

void regina::PacketListener::packetToBeDestroyed | ( | Packet * | packet | ) |

inline 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

  packet | the 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

  packet | the packet being listened to.

Reimplemented from regina::PacketListener.

## packetToBeRenamed()

void regina::PacketListener::packetToBeRenamed | ( | Packet * | packet | ) |

inline virtual

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

  packet | the packet being listened to.

See also
  childToBeRenamed()

## packetWasChanged()

void regina::PacketListener::packetWasChanged | ( | Packet * | packet | ) |

inline virtual

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

  packet | the packet being listened to.

Reimplemented in regina::SnapPeaTriangulation.

## packetWasRenamed() [1/2]

void regina::PacketListener::packetWasRenamed | ( | Packet * | packet | ) |

inline 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

  packet | the 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

  packet | the 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

  data | the block of binary data that forms the PDF document, or `null` if no document is to be stored.
  size | the 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.
  alloc | describes 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

  filename | the 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

  task | the 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

  tag | the 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

  name | the 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

  index | the 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

  newParent | the new parent of this packet, i.e., the packet beneath which this packet will be inserted.
  first | `true` 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

  data | the block of binary data that forms the new PDF document, or `null` if no document is to be stored.
  size | the 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.
  alloc | describes 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

  resolver | the 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

  filename | the pathname of the file to write to.
  compressed | `true` 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

  s | the output stream to which to write.
  compressed | `true` 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

  filename | the 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

  label | the 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

  newText | the 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

  newText | the 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

  newText | the 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

  index | the index of the variable whose name should change; this must be between 0 and countVariables()-1 inclusive.
  name | the 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

  index | the index of the variable whose value should change; this must be between 0 and countVariables()-1 inclusive.
  value | the 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
| ) |  |

inline virtual

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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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
| ) |  |

override virtual

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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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
| ) |  |

override virtual

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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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
| ) |  |

inline override virtual

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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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

  id | the internal ID of the given packet, as stored in the data file.
  packet | the 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

  newText | the new value for the packet.

## Text() [3/3]

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

inline

Initialises the packet to the given string.

Parameters

  newText | the 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

  newParent | the 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

  listener | the 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

  name | the 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

  index | the 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

  name | the 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

  index | the 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

inline 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

  out | the 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

  out | the output stream to which to write.

Reimplemented from regina::Packet.

## writeTextLong() [3/3]

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

inline 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

  out | the 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

inline 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

  out | the output stream to which to write.

Implements regina::Packet.

## writeTextShort() [2/5]

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

inline 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

  out | the output stream to which to write.

Implements regina::Packet.

## writeTextShort() [3/5]

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

inline 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

  out | the output stream to which to write.

Implements regina::Packet.

## writeTextShort() [4/5]

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

inline 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

  out | the 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

  out | the 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

  out | the output stream to which the XML data file should be written.

## writeXMLPacketData() [1/5]

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

inline protected 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

  out | the output stream to which the XML should be written.

Implements regina::Packet.

## writeXMLPacketData() [2/5]

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

protected 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

  out | the output stream to which the XML should be written.

Implements regina::Packet.

## writeXMLPacketData() [3/5]

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

protected 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

  out | the output stream to which the XML should be written.

Implements regina::Packet.

## writeXMLPacketData() [4/5]

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

protected 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

  out | the output stream to which the XML should be written.

Implements regina::Packet.

## writeXMLPacketData() [5/5]

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

protected pure 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

  out | the 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

  out | the output stream to which the XML should be written.

## XMLContainerReader()

regina::XMLContainerReader::XMLContainerReader | ( | XMLTreeResolver & | resolver | ) |

inline

Creates a new container reader.

Parameters

  resolver | the 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

  resolver | the 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

  resolver | the 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

  parent | the packet which will become the new packet's parent in the tree structure, or 0 if the new packet is to be tree matriarch.
  resolver | the 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

  resolver | the 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

  resolver | the 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 | ( |  | ) |

inline virtual

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