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

Packet administration and some basic packet types. More...

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::ChildIterator
 
A forward iterator for iterating through all immediate children of a given packet. More...
 
class  regina::SubtreeIterator
 
A forward iterator for iterating through the entire packet subtree rooted at a given packet. More...
 
class  regina::PacketChildren
 
A lightweight object that gives access to all immediate children of a given packet. More...
 
class  regina::PacketDescendants
 
A lightweight object that gives access to all strict descendants of a given packet. More...
 
class  regina::PacketShell
 Gives access to the final remains of a packet that is in the process of being destroyed. More...
 
class  regina::PacketListener
 
An object that can be registered to listen for packet events. More...
 
struct  std::iterator_traits< regina::ChildIterator >
 
struct  std::iterator_traits< regina::SubtreeIterator >
 
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 ptrdiff_t std::iterator_traits< regina::ChildIterator >::difference_type
 
typedef regina::Packetstd::iterator_traits< regina::ChildIterator >::value_type
 
typedef regina::Packet ** std::iterator_traits< regina::ChildIterator >::pointer_type
 
typedef regina::Packet *const & std::iterator_traits< regina::ChildIterator >::reference_type
 
typedef std::forward_iterator_tag std::iterator_traits< regina::ChildIterator >::iterator_category
 
typedef ptrdiff_t std::iterator_traits< regina::SubtreeIterator >::difference_type
 
typedef regina::Packetstd::iterator_traits< regina::SubtreeIterator >::value_type
 
typedef regina::Packet ** std::iterator_traits< regina::SubtreeIterator >::pointer_type
 
typedef regina::Packet *const & std::iterator_traits< regina::SubtreeIterator >::reference_type
 
typedef std::forward_iterator_tag std::iterator_traits< regina::SubtreeIterator >::iterator_category
 
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...
 

Enumerations

enum  regina::PacketType {
  regina::PACKET_CONTAINER = 1, regina::PACKET_TEXT = 2, regina::PACKET_NORMALSURFACES = 6, regina::PACKET_SCRIPT = 7,
  regina::PACKET_SURFACEFILTER = 8, regina::PACKET_ANGLESTRUCTURES = 9, regina::PACKET_PDF = 10, regina::PACKET_NORMALHYPERSURFACES = 13,
  regina::PACKET_SNAPPEATRIANGULATION = 16, regina::PACKET_LINK = 17, 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...
 

Functions

static XMLPacketReaderregina::Packet::xmlReader (Packet *parent, XMLTreeResolver &resolver)
 
Returns a newly created XML element reader that will read the contents of a single XML packet element. More...
 
 regina::Packet::Packet (const Packet &)=delete
 
Packetregina::Packet::operator= (const Packet &)=delete
 
 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...
 
 regina::Packet::ChangeEventSpan::ChangeEventSpan (const ChangeEventSpan &)=delete
 
ChangeEventSpanregina::Packet::ChangeEventSpan::operator= (const ChangeEventSpan &)=delete
 
virtual Packetregina::Packet::internalClonePacket (Packet *parent) const =0
 Makes a newly allocated copy of this packet. More...
 
void regina::Packet::writeXMLPacketTree (std::ostream &out) const
 Writes a chunk of XML containing the subtree with this packet as matriarch. More...
 
virtual void regina::Packet::writeXMLPacketData (std::ostream &out) const =0
 Writes a chunk of XML containing the data for this packet only. More...
 
virtual void regina::Packet::writeTextShort (std::ostream &out) const =0
 
Writes a short text representation of this object to the given output stream. More...
 
virtual void regina::Packet::writeTextLong (std::ostream &out) const
 
Writes a detailed text representation of this object to the given output stream. More...
 
bool regina::Packet::hasOwner () const
 Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object. More...
 
Packetregina::open (const char *filename)
 
Reads a Regina data file, and returns the corresponding packet tree. More...
 
Packetregina::open (std::istream &in)
 
Reads a Regina data file from the given input stream, and returns the corresponding packet tree. More...
 
 regina::ChildIterator::ChildIterator ()
 
Creates a past-the-end iterator. More...
 
 regina::ChildIterator::ChildIterator (const ChildIterator &)=default
 
Default copy constructor. More...
 
 regina::ChildIterator::ChildIterator (Packet *current)
 
Creates a new iterator pointing to the given child packet. More...
 
ChildIteratorregina::ChildIterator::operator= (const ChildIterator &)=default
 Default copy assignment operator. More...
 
bool regina::ChildIterator::operator== (const ChildIterator &rhs) const
 Tests whether this and the given iterator are equal. More...
 
bool regina::ChildIterator::operator!= (const ChildIterator &rhs) const
 Tests whether this and the given iterator are different. More...
 
ChildIteratorregina::ChildIterator::operator++ ()
 
Preincrement operator. More...
 
ChildIterator regina::ChildIterator::operator++ (int)
 
Postincrement operator. More...
 
Packet *const & regina::ChildIterator::operator* () const
 
Returns the packet that this iterator is currently pointing to. More...
 
 regina::SubtreeIterator::SubtreeIterator ()
 
Creates a past-the-end iterator. More...
 
 regina::SubtreeIterator::SubtreeIterator (const SubtreeIterator &)=default
 
Default copy constructor. More...
 
 regina::SubtreeIterator::SubtreeIterator (Packet *subtree)
 
Creates a new iterator pointing to the first packet within the given subtree. More...
 
 regina::SubtreeIterator::SubtreeIterator (const Packet *subtree, Packet *current)
 
Creates a new iterator pointing to the given packet within the given subtree. More...
 
SubtreeIteratorregina::SubtreeIterator::operator= (const SubtreeIterator &)=default
 Default copy assignment operator. More...
 
bool regina::SubtreeIterator::operator== (const SubtreeIterator &rhs) const
 Tests whether this and the given iterator are equal. More...
 
bool regina::SubtreeIterator::operator!= (const SubtreeIterator &rhs) const
 Tests whether this and the given iterator are different. More...
 
SubtreeIteratorregina::SubtreeIterator::operator++ ()
 
Preincrement operator. More...
 
SubtreeIterator regina::SubtreeIterator::operator++ (int)
 
Postincrement operator. More...
 
Packet *const & regina::SubtreeIterator::operator* () const
 
Returns the packet that this iterator is currently pointing to. More...
 
 regina::PacketChildren::PacketChildren (const PacketChildren &)=default
 
Default copy constructor. More...
 
 regina::PacketChildren::PacketChildren (const Packet *parent)
 
Creates a new object for iterating through the immediate children of the given packet. More...
 
PacketChildrenregina::PacketChildren::operator= (const PacketChildren &)=default
 
Default copy assignment operator. More...
 
ChildIterator regina::PacketChildren::begin () const
 
Returns an iterator at the beginning of the range of children. More...
 
ChildIterator regina::PacketChildren::end () const
 
Returns an iterator at the end of the range of children. More...
 
 regina::PacketDescendants::PacketDescendants (const PacketDescendants &)=default
 
Default copy constructor. More...
 
 regina::PacketDescendants::PacketDescendants (const Packet *subtree)
 
Creates a new object for iterating through the strict descendants of the given packet. More...
 
PacketDescendantsregina::PacketDescendants::operator= (const PacketDescendants &)=default
 
Default copy assignment operator. More...
 
SubtreeIterator regina::PacketDescendants::begin () const
 
Returns an iterator at the beginning of the range of strict descendants. More...
 
SubtreeIterator regina::PacketDescendants::end () const
 
Returns an iterator at the end of the range of strict descendants. More...
 
 regina::PacketShell::PacketShell (const Packet *packet)
 Creates a new shell referring to the given packet. More...
 
 regina::PacketShell::PacketShell (const PacketShell &shell)=default
 Creates a copy of the given shell. More...
 
PacketShellregina::PacketShell::operator= (const PacketShell &shell)=default
 Sets this to be a copy of the given shell. More...
 
bool regina::PacketShell::operator== (const PacketShell &shell) const
 Identifies if this and the given shell refer to the same underlying packet. More...
 
bool regina::PacketShell::operator== (const Packet *packet) const
 Identifies if this shell refers to the given packet. More...
 
bool regina::PacketShell::operator!= (const PacketShell &shell) const
 Identifies if this and the given shell refer to different underlying packets. More...
 
bool regina::PacketShell::operator!= (const Packet *packet) const
 Identifies if this shell does not refer to the given packet. More...
 
const std::string & regina::PacketShell::label () const
 Returns the label associated with this individual packet. More...
 
std::string regina::PacketShell::humanLabel () const
 Returns the label associated with this individual packet, adjusted if necessary for human-readable output. More...
 
bool regina::PacketShell::hasTag (const std::string &tag) const
 Determines whether this packet has the given associated tag. More...
 
bool regina::PacketShell::hasTags () const
 Determines whether this packet has any associated tags at all. More...
 
const std::set< std::string > & regina::PacketShell::tags () const
 
Returns the set of all tags associated with this packet. More...
 
std::string regina::PacketShell::internalID () const
 Returns a unique string ID that identifies this packet. More...
 
bool regina::operator== (const Packet *packet, PacketShell shell)
 Identifies if the given shell refers to the given packet. More...
 
bool regina::operator!= (const Packet *packet, PacketShell shell)
 Identifies if the given shell does not refer to the given packet. More...
 
 regina::PacketListener::PacketListener (const PacketListener &)=delete
 
PacketListenerregina::PacketListener::operator= (const PacketListener &)=delete
 
 regina::PacketListener::PacketListener ()=default
 A default constructor that does nothing. 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...
 

Variables

constexpr PacketType regina::PACKET_TRIANGULATION = PACKET_TRIANGULATION3
 Deprecated alias for PACKET_TRIANGULATION3. More...
 
constexpr PacketType regina::PACKET_NORMALSURFACELIST = PACKET_NORMALSURFACES
 Deprecated alias for PACKET_NORMALSURFACES. More...
 
constexpr PacketType regina::PACKET_ANGLESTRUCTURELIST = PACKET_ANGLESTRUCTURES
 Deprecated alias for PACKET_ANGLESTRUCTURES. More...
 
constexpr PacketType regina::PACKET_DIM4TRIANGULATION = PACKET_TRIANGULATION4
 Deprecated alias for PACKET_TRIANGULATION4. More...
 
constexpr PacketType regina::PACKET_NORMALHYPERSURFACELIST = PACKET_NORMALHYPERSURFACES
 Deprecated alias for PACKET_NORMALHYPERSURFACES. More...
 
constexpr PacketType regina::PACKET_DIM2TRIANGULATION = PACKET_TRIANGULATION2
 Deprecated alias for PACKET_TRIANGULATION2. More...
 

Friends

class regina::PacketListener::Packet
 Allow packets to automatically deregister listeners as they are destroyed. 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...
 
static void regina::Packet::safeDelete (Packet *p)
 
Either destroys or orphans the given packet, according to whether it has safe pointers that currently reference it. More...
 

Packet Identification

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

Tags

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

Event Handling

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

Tree Queries

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

SubtreeIterator regina::Packet::begin ()
 
Returns an iterator at the beginning of the range of packets in the subtree rooted at this packet. More...
 
SubtreeIterator regina::Packet::end ()
 
Returns an iterator beyond the end of the range of packets in the subtree rooted at this packet. More...
 
PacketDescendants regina::Packet::descendants () const
 Returns a lightweight object for iterating through all strict descendants of this packet in the packet tree. More...
 
PacketChildren regina::Packet::children () const
 Returns a lightweight object for iterating through the immediate children of this packet. More...
 
Packetregina::Packet::nextTreePacket ()
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
const Packetregina::Packet::nextTreePacket () const
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
Packetregina::Packet::firstTreePacket (const std::string &type)
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
const Packetregina::Packet::firstTreePacket (const std::string &type) const
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
Packetregina::Packet::nextTreePacket (const std::string &type)
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
const Packetregina::Packet::nextTreePacket (const std::string &type) const
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
Packetregina::Packet::findPacketLabel (const std::string &label)
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 
const Packetregina::Packet::findPacketLabel (const std::string &label) const
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 

Packet Dependencies

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

Cloning

Packetregina::Packet::clone (bool cloneDescendants=false, bool end=true) const
 Clones this packet (and possibly its descendants), assigns to it a suitable unused label and inserts the clone into the tree as a sibling of this packet. More...
 

File I/O

bool regina::Packet::save (const char *filename, bool compressed=true) const
 
Saves the subtree rooted at this packet to the given Regina data file, using Regina's native XML file format. More...
 
bool regina::Packet::save (std::ostream &s, bool compressed=true) const
 
Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file. More...
 
void regina::Packet::writeXMLFile (std::ostream &out) const
 
Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format. More...
 
std::string regina::Packet::internalID () const
 Returns a unique string ID that identifies this packet. More...
 

Constructors and Destructors

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

Packet Listener Interface

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 (PacketShell 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)
 Called before a child packet is to be removed from directly beneath the packet. More...
 
virtual void regina::PacketListener::childWasRemoved (Packet *packet, Packet *child)
 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 override { \
return id; \
} \
inline virtual std::string typeName() const override { \
return PacketInfo<id>::name(); \
}
PacketType
Represents the different types of packet that are available in Regina.
Definition: packettype.h:57

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

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

This macro provides the class with:

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

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

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

◆ REGINA_PACKET_FROM

#define REGINA_PACKET_FROM (   class_,
  helper 
)
Value:
public: \
static constexpr const PacketType typeID = helper::typeID; \
inline virtual PacketType type() const override { \
return helper::typeID; \
} \
inline virtual std::string typeName() const override { \
return helper::name(); \
}
PacketType
Represents the different types of packet that are available in Regina.
Definition: packettype.h:57

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

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

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

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

Typedef Documentation

◆ NContainer

Deprecated typedef for backward compatibility.

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

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

◆ NPacket

Deprecated typedef for backward compatibility.

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

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

◆ NPacketListener

Deprecated typedef for backward compatibility.

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

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

◆ NPDF

typedef PDF regina::NPDF

Deprecated typedef for backward compatibility.

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

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

◆ NScript

Deprecated typedef for backward compatibility.

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

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

◆ NText

Deprecated typedef for backward compatibility.

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

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

Enumeration Type Documentation

◆ 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_NORMALSURFACES 

Represents a normal surface list, of class 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_PDF 

Represents a PDF document, of class PDF.

PACKET_NORMALHYPERSURFACES 

Represents a normal hypersurface list, of class NormalHypersurfaces.

PACKET_SNAPPEATRIANGULATION 

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

PACKET_LINK 

Represents a knot or link in the 3-sphere, of class Link.

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

◆ addTag()

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

Associates the given tag with this packet.

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

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

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

◆ adornedLabel()

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

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

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

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

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

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

◆ begin() [1/3]

SubtreeIterator regina::Packet::begin ( )
inline


Returns an iterator at the beginning of the range of packets in the subtree rooted at this packet.

Subtree iteration is depth-first, where a parent packet is always processed before its descendants. Therefore the iterator returned by begin() will always point to this packet itself.

The begin() and end() routines allow you to iterate through an entire packet subtree using C++11 range-based for loops:

Packet* subtree = ...;
for (Packet* p : *subtree) { ... }

In Python, each packet can be treated as an iterable object, again iterating through the corresponding subtree:

subtree = ...
for p in subtree:
...

See also descendants() for iterating through just the strict descendants in the subtree (i.e., excluding this packet itself), and children() for iterating just through the immediate children of this packet (not the full subtree).

Note
This routine is non-const because dereferencing a SubtreeIterator returns a non-const packet pointer.
Python
As well as treating each packet as an iterable object, Regina supplies a member function Packet.subtree() which returns an iterable object. Iterating over a packet directly is exactly the same as iterating over Packet.subtree(); the latter is offered because it may be clearer for readers.
Returns
an iterator at the beginning of this subtree.

◆ begin() [2/3]

ChildIterator regina::PacketChildren::begin ( ) const
inline


Returns an iterator at the beginning of the range of children.

Python
Not present; instead this class implements __iter__(), as described in the class notes.
Returns
the beginning iterator.

◆ begin() [3/3]

SubtreeIterator regina::PacketDescendants::begin ( ) const
inline


Returns an iterator at the beginning of the range of strict descendants.

This will point to the first child packet (if one exists) of the packet whose descendants we are iterating over.

Python
Not present; instead this class implements __iter__(), as described in the class notes.
Returns
the beginning iterator.

◆ ChangeEventSpan()

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

Creates a new change event object for the given packet.

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

Parameters
packetthe packet whose data is about to change.

◆ ChildIterator() [1/3]

regina::ChildIterator::ChildIterator ( )
inline


Creates a past-the-end iterator.

Python
Not present. The only way to create a ChildIterator is via Packet::children().

◆ ChildIterator() [2/3]

regina::ChildIterator::ChildIterator ( const ChildIterator )
default


Default copy constructor.

Python
Not present. The only way to create a ChildIterator is via Packet::children().

◆ ChildIterator() [3/3]

regina::ChildIterator::ChildIterator ( Packet current)
inline


Creates a new iterator pointing to the given child packet.

Python
Not present. The only way to create a ChildIterator is via Packet::children().
Parameters
currentthe child packet that the new iterator should point to, or 0 if the new iterator should be past-the-end.

◆ children()

PacketChildren regina::Packet::children ( ) const
inline

Returns a lightweight object for iterating through the immediate children of this packet.

This routine allows you to iterate through the immediate children of a given packet using C++11 range-based for loops:

Packet* parent = ...;
for (Packet* child : parent->children()) { ... }

In Python, this routine returns an iterable object:

parent = ...
for child in parent.children():
...

This function returns a lightweight object in the sense that it does not generate a full list of children in advance, but instead just returns a small iterator that visits each child as required. In particular, this routine has small constant time and memory.

See begin() and end(), as well as descendants(), for iterating through the subtree rooted at this packet (not just the immediate children).

Returns
an object for iterating through the children of this packet.

◆ childrenToBeReordered()

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

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

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

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ childrenWereReordered()

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

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

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

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ childToBeAdded()

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

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

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

The default implementation of this routine is to do nothing.

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

◆ childToBeRemoved()

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

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

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

Be warned: we could already be inside either this packet's or the child packet's destructor:

  • If this packet is being destroyed, then it will orphan all of its children, and then (unless they are being mananged by SafePtr safe pointers) it will delete these children also. In such a situation, both listener functions childToBeRemoved() and childWasRemoved() will be called before the child is destroyed. For both functions, packet will be passed as null (since the parent packet is already well into its destruction process).
  • If the child packet is being destroyed (but the parent is not), then it will be orphaned as part of its destructor. In such a situation, both listener functions childToBeRemoved() and childWasRemoved() will be called from within the child destructor, and child will be passed as null to both functions.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to, or null if this routine is being called from within this packet's destructor.
childthe child packet to be removed, or null if this routine is being called from within the child's destructor.

◆ childToBeRenamed()

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

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

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

The default implementation of this routine is to do nothing.

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

◆ childWasAdded()

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

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

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

The default implementation of this routine is to do nothing.

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

◆ childWasRemoved()

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

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

Before the child is removed, childToBeRemoved() will be called also.

Be warned: we could already be inside either this packet's or the child packet's destructor:

  • If this packet is being destroyed, then it will orphan all of its children, and then (unless they are being mananged by SafePtr safe pointers) it will delete these children also. In such a situation, both listener functions childToBeRemoved() and childWasRemoved() will be called before the child is destroyed. For both functions, packet will be passed as null (since the parent packet is already well into its destruction process).
  • If the child packet is being destroyed (but the parent is not), then it will be orphaned as part of its destructor. In such a situation, both listener functions childToBeRemoved() and childWasRemoved() will be called from within the child destructor, and child will be passed as null to both functions.

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to, or null if this routine is being called from within this packet's destructor.
childthe child packet that was removed, or null if this routine is being called from within the child's destructor.

◆ childWasRenamed()

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

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

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

The default implementation of this routine is to do nothing.

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

◆ clone()

Packet* regina::Packet::clone ( bool  cloneDescendants = false,
bool  end = true 
) const

Clones this packet (and possibly its descendants), assigns to it a suitable unused label and inserts the clone into the tree as a sibling of this packet.

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

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

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

◆ 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 strict descendants of this packet.

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

Returns
the total number of strict descendants.

◆ dependsOnParent()

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::Link, 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.

◆ descendants()

PacketDescendants regina::Packet::descendants ( ) const
inline

Returns a lightweight object for iterating through all strict descendants of this packet in the packet tree.

The order of iteration is exactly the same as when iterating over the full subtree rooted at this packet (as offered by Packet::begin() and Packet::end()), except that the iteration excludes this packet itself. In particular, the iteration is depth-first, and each packet in the subtree is processed before its own descendants.

This routine allows you to iterate through all strict descendants of a given packet using C++11 range-based for loops:

Packet* parent = ...;
for (Packet* desc : parent->descendants()) { ... }

In Python, this routine returns an iterable object:

parent = ...
for desc in parent.descendants():
...

This function returns a lightweight object in the sense that it does not generate a full list of descendants in advance, but instead just returns a small iterator that visits each descendant as required. In particular, this routine has small constant time and memory.

See also begin() and end() for iterating through the entire subtree including this packet, and children() for iterating over just this packet's immediate children.

Returns
an object for iterating through the strict descendants of this packet.

◆ end() [1/3]

SubtreeIterator regina::Packet::end ( )
inline


Returns an iterator beyond the end of the range of packets in the subtree rooted at this packet.

In C++, the begin() and end() routines allow you to iterate through an entire packet subtree using C++11 range-based for loops. In Python, each packet can be treated as an iterable object.

See the begin() documentation for further details.

Python
Again, see the begin() documentation for the iterable objects that Regina provides for Python users.
Returns
an iterator beyond the end of this subtree.

◆ end() [2/3]

ChildIterator regina::PacketChildren::end ( ) const
inline


Returns an iterator at the end of the range of children.

Python
Not present; instead this class implements __iter__(), as described in the class notes.
Returns
the past-the-end iterator.

◆ end() [3/3]

SubtreeIterator regina::PacketDescendants::end ( ) const
inline


Returns an iterator at the end of the range of strict descendants.

Python
Not present; instead this class implements __iter__(), as described in the class notes.
Returns
the past-the-end iterator.

◆ findPacketLabel() [1/2]

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

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

Note that label comparisons are case sensitive.

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

◆ findPacketLabel() [2/2]

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

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

Note that label comparisons are case sensitive.

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

◆ firstChild()

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

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

This routine takes small constant time.

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

◆ firstTreePacket() [1/2]

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

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

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

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

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

◆ firstTreePacket() [2/2]

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

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

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

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

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

◆ forPacket() [1/2]

template<typename FunctionObject , typename... Args>
ReturnsTraits<FunctionObject>::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
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
defaultReturnthe value to return if the given packet type is not valid.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
the return value from the corresponding bracket operator of func, or defaultReturn if the given packet type is not valid.

◆ forPacket() [2/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
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
nothing; the return type ReturnsTraits<FunctionObject>::Void simply evaluates to void.

◆ 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() [1/2]

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

Determines whether this packet has the given associated tag.

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

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

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

◆ hasTag() [2/2]

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

Determines whether this packet has the given associated tag.

See Packet::tags() for further details on packet tags.

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

◆ hasTags() [1/2]

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.

◆ hasTags() [2/2]

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

Determines whether this packet has any associated tags at all.

See Packet::tags() for further details on packet tags.

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

◆ humanLabel() [1/2]

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.

◆ humanLabel() [2/2]

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

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

See Packet::label() and Packet::humanLabel() for further details on packet labels.

Returns
this individual packet's label.

◆ 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
Since this packet takes ownership of the given child packet, the python object containing the given child packet becomes a null object and should no longer be used. See reparent() for a way of avoiding these problems in some cases.
Parameters
newChildthe child to insert.
prevChildthe preexisting child of this packet after which newChild will be inserted, or 0 if newChild is to be the first child of this packet.

◆ insertChildFirst()

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


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

This routine takes small constant time.

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

◆ insertChildLast()

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


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

This routine takes small constant time.

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

◆ internalClonePacket()

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

Makes a newly allocated copy of this packet.

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

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

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

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

◆ internalID() [1/2]

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.

◆ internalID() [2/2]

std::string regina::PacketShell::internalID ( ) const
inline

Returns a unique string ID that identifies this packet.

The user has no control over this ID and it is not human readable, but it is guaranteed to be unique to this packet, and to remain fixed throughout the lifetime of the program for this packet.

See Packet::internalID() for further details.

Returns
a unique ID that identifies this packet.

◆ isGrandparentOf()

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

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

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

◆ isListening()

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

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

See the PacketListener class notes for details.

Parameters
listenerthe listener to search for.
Returns
true if the given listener is currently registered with this packet, or false otherwise.

◆ 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() [1/2]

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.

◆ label() [2/2]

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

Returns the label associated with this individual packet.

See Packet::label() and Packet::humanLabel() for further details on packet labels.

The reference that is returned should be only used as a temporary, since the underlying packet (and therefore the string that is referenced) is in the process of being destroyed.

Returns
this individual packet's label.

◆ lastChild()

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

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

This routine takes small constant time.

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

◆ levelsDownTo()

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

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

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

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

◆ levelsUpTo()

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

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

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

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

◆ listen()

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

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

See the PacketListener class notes for details.

Parameters
listenerthe listener to register.
Returns
true if the given listener was successfully registered, or false if the given listener was already registered beforehand.

◆ makeOrphan()

void regina::Packet::makeOrphan ( )


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

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

This routine takes small constant time.

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

◆ moveDown()

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

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

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

This routine takes time proportional to the number of steps.

Precondition
The given number of steps is strictly positive.

◆ moveToFirst()

void regina::Packet::moveToFirst ( )

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

This routine takes small constant time.

◆ moveToLast()

void regina::Packet::moveToLast ( )

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

This routine takes small constant time.

◆ moveUp()

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

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

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

This routine takes time proportional to the number of steps.

Precondition
The given number of steps is strictly positive.

◆ nextSibling()

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

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

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

This routine takes small constant time.

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

◆ nextTreePacket() [1/4]

Packet* regina::Packet::nextTreePacket ( )

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

Note that this packet need not be the tree matriarch.

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

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

◆ nextTreePacket() [2/4]

const Packet* regina::Packet::nextTreePacket ( ) const

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

Note that this packet need not be the tree matriarch.

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

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

◆ nextTreePacket() [3/4]

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

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

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

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

◆ nextTreePacket() [4/4]

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

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

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

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

◆ open() [1/2]

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


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

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

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

Internationalisation
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
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, or even when typing from regina import *. This is to avoid overriding Python's own built-in open() function. You can access Regina's open() function by calling regina.open().
Parameters
filenamethe pathname of the file to read from.
Returns
the packet tree read from file, or 0 on error (as explained above).

◆ open() [2/2]

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


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

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

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

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

◆ operator!=() [1/5]

bool regina::ChildIterator::operator!= ( const ChildIterator rhs) const
inline

Tests whether this and the given iterator are different.

Returns
true if and only if the two iterators are different.

◆ operator!=() [2/5]

bool regina::SubtreeIterator::operator!= ( const SubtreeIterator rhs) const
inline

Tests whether this and the given iterator are different.

Note
This routine only compares the packets that each iterator is currently pointing to. It does not compare the roots of the subtrees themselves.
Returns
true if and only if the two iterators are different.

◆ operator!=() [3/5]

bool regina::PacketShell::operator!= ( const PacketShell shell) const
inline

Identifies if this and the given shell refer to different underlying packets.

Parameters
shellthe shell to compare with this.
Returns
true if and only if both shells refer to different packets.

◆ operator!=() [4/5]

bool regina::PacketShell::operator!= ( const Packet packet) const
inline

Identifies if this shell does not refer to the given packet.

This test is also available the other way around (with PacketShell on the right); this reversed test is defined as a global function.

Parameters
packetthe packet to test against; this may be null.
Returns
true if and only if this shell does not refer to the given packet.

◆ operator!=() [5/5]

bool regina::operator!= ( const Packet packet,
PacketShell  shell 
)
inline

Identifies if the given shell does not refer to the given packet.

This test is also available the other way around (with PacketShell on the left); this reversed test is defined as a member function of PacketShell.

Parameters
packetthe packet to test against; this may be null.
shellthe packet shell to test against.
Returns
true if and only if the given shell does not refer to the given packet.

◆ operator*() [1/2]

Packet *const & regina::ChildIterator::operator* ( ) const
inline


Returns the packet that this iterator is currently pointing to.

Python
Not present; instead this class implements next(), which either returns the current child packet and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
the current packet.

◆ operator*() [2/2]

Packet *const & regina::SubtreeIterator::operator* ( ) const
inline


Returns the packet that this iterator is currently pointing to.

Python
Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
the current packet.

◆ operator++() [1/4]

ChildIterator & regina::ChildIterator::operator++ ( )
inline


Preincrement operator.

Python
Not present; instead this class implements next(), which either returns the current child packet and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
a reference to this iterator.

◆ operator++() [2/4]

ChildIterator regina::ChildIterator::operator++ ( int  )
inline


Postincrement operator.

Python
Not present; instead this class implements next(), which either returns the current child packet and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
a a copy of this iterator before it was incremented.

◆ operator++() [3/4]

SubtreeIterator & regina::SubtreeIterator::operator++ ( )
inline


Preincrement operator.

Python
Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
a reference to this iterator.

◆ operator++() [4/4]

SubtreeIterator regina::SubtreeIterator::operator++ ( int  )
inline


Postincrement operator.

Python
Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.
Returns
a copy of this iterator before it was incremented.

◆ operator=() [1/5]

ChildIterator& regina::ChildIterator::operator= ( const ChildIterator )
default

Default copy assignment operator.

◆ operator=() [2/5]

SubtreeIterator& regina::SubtreeIterator::operator= ( const SubtreeIterator )
default

Default copy assignment operator.

◆ operator=() [3/5]

PacketChildren& regina::PacketChildren::operator= ( const PacketChildren )
default


Default copy assignment operator.

Python
Not present.

◆ operator=() [4/5]

PacketDescendants& regina::PacketDescendants::operator= ( const PacketDescendants )
default


Default copy assignment operator.

Python
Not present.

◆ operator=() [5/5]

PacketShell& regina::PacketShell::operator= ( const PacketShell shell)
default

Sets this to be a copy of the given shell.

Both shells will refer to the same underlying packet.

Parameters
shellthe shell to clone.

◆ operator==() [1/5]

bool regina::ChildIterator::operator== ( const ChildIterator rhs) const
inline

Tests whether this and the given iterator are equal.

Returns
true if and only if the two iterators are equal.

◆ operator==() [2/5]

bool regina::SubtreeIterator::operator== ( const SubtreeIterator rhs) const
inline

Tests whether this and the given iterator are equal.

Note
This routine only compares the packets that each iterator is currently pointing to. It does not compare the roots of the subtrees themselves.
Returns
true if and only if the two iterators are equal.

◆ operator==() [3/5]

bool regina::PacketShell::operator== ( const PacketShell shell) const
inline

Identifies if this and the given shell refer to the same underlying packet.

Parameters
shellthe shell to compare with this.
Returns
true if and only if both shells refer to the same packet.

◆ operator==() [4/5]

bool regina::PacketShell::operator== ( const Packet packet) const
inline

Identifies if this shell refers to the given packet.

This test is also available the other way around (with PacketShell on the right); this reversed test is defined as a global function.

Parameters
packetthe packet to test against; this may be null.
Returns
true if and only if this shell refers to the given packet.

◆ operator==() [5/5]

bool regina::operator== ( const Packet packet,
PacketShell  shell 
)
inline

Identifies if the given shell refers to the given packet.

This test is also available the other way around (with PacketShell on the left); this reversed test is defined as a member function of PacketShell.

Parameters
packetthe packet to test against; this may be null.
shellthe packet shell to test against.
Returns
true if and only if the given shell refers to the given packet.

◆ 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
Not present.
Parameters
parentthe parent beneath which to insert this packet, or 0 if this packet is to be the matriarch of a new tree.

◆ PacketChildren() [1/2]

regina::PacketChildren::PacketChildren ( const PacketChildren )
default


Default copy constructor.

Python
Not present.

◆ PacketChildren() [2/2]

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


Creates a new object for iterating through the immediate children of the given packet.

Python
Not present.
Parameters
parentthe packet whose children we will iterate through.

◆ PacketDescendants() [1/2]

regina::PacketDescendants::PacketDescendants ( const PacketDescendants )
default


Default copy constructor.

Python
Not present.

◆ PacketDescendants() [2/2]

regina::PacketDescendants::PacketDescendants ( const Packet subtree)
inline


Creates a new object for iterating through the strict descendants of the given packet.

Python
Not present.
Parameters
subtreethe packet whose strict descendants we will iterate through.

◆ PacketListener()

regina::PacketListener::PacketListener ( )
protecteddefault

A default constructor that does nothing.

◆ PacketShell() [1/2]

regina::PacketShell::PacketShell ( const Packet packet)
inline

Creates a new shell referring to the given packet.

Parameters
packetthe packet to refer to.

◆ PacketShell() [2/2]

regina::PacketShell::PacketShell ( const PacketShell shell)
default

Creates a copy of the given shell.

Both shells will refer to the same underlying packet.

Parameters
shellthe shell to clone.

◆ packetToBeChanged()

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

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

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

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

◆ packetToBeDestroyed()

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

Called before the packet is about to be destroyed.

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

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

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

By the time this function is called, we are already inside the Packet destructor, and so most Packet member functions are no longer safe to call. Therefore the argument that is passed to this routine is a PacketShell, which exposes only those member functions of Packet that are still safe to call at this time. Importantly, you can safely compare a PacketShell against a Packet pointer, in case you need to identify which particular packet is being destroyed.

The default implementation of this routine is to do nothing.

Parameters
packetgives access to the packet being listened to.

Reimplemented in regina::Script.

◆ packetToBeRenamed()

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

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

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

The default implementation of this routine is to do nothing.

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

◆ packetWasChanged()

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

Called after the contents of the packet have been changed.

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

The default implementation of this routine is to do nothing.

Parameters
packetthe packet being listened to.

Reimplemented in regina::SnapPeaTriangulation.

◆ packetWasRenamed()

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

Called after the packet label or tags have been changed.

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

The default implementation of this routine is to do nothing.

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

Reimplemented in regina::Script.

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

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

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

◆ removeTag()

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

Removes the association of the given tag with this packet.

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

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

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

◆ 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
This routine is much simpler than combinations of makeOrphan() and insertChildFirst() / insertChildLast(), since there are no unpleasant ownership issues to deal with. However, if this packet currently has no parent then the ownership issues are unavoidable; in this case reparent() will do nothing, and one of the insertChild...() routines must be used instead.
Parameters
newParentthe new parent of this packet, i.e., the packet beneath which this packet will be inserted.
firsttrue if this packet should be inserted as the first child of the given parent, or false (the default) if it should be inserted as the last child.

◆ root()

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

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

Returns
the matriarch of the packet tree.

◆ safeDelete()

static void regina::Packet::safeDelete ( Packet p)
static


Either destroys or orphans the given packet, according to whether it has safe pointers that currently reference it.

In this context, a "safe pointer" is either SafePtr<Packet> or a subclass; such pointers are (for instance) used to hold packets in regina's python bindings.

If there are no safe pointers currently pointing to p, then this routine simply deletes p. If there are one or more safe pointers currently pointing to p, then this routine orphans p in the packet tree and does nothing more; the safe pointers are left to manage the lifespan of p from here onwards.

C++ code should call safeDelete() instead of delete when it wishes to delete a packet, but there is a possibility that some external body (such as a python interpreter) still holds a reference to p and might still try to access it.

Python
Not present, since when called from python there will always be a safe pointer, and so this is equivalent to makeOrphan().
Parameters
pthe packet to delete or orphan. It is safe to pass null (in which case this routine does nothing).

◆ 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
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.
Parameters
filenamethe pathname of the file to write to.
compressedtrue if the XML data should be compressed, or false if it should be written as plain text.
Returns
true if and only if the file was successfully written.

◆ save() [2/2]

bool regina::Packet::save ( std::ostream &  s,
bool  compressed = true 
) const


Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file.

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

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

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

◆ setLabel()

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

Sets the label associated with this individual packet.

Parameters
labelthe new label to give this packet.

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

◆ SubtreeIterator() [1/4]

regina::SubtreeIterator::SubtreeIterator ( )
inline


Creates a past-the-end iterator.

Python
Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

◆ SubtreeIterator() [2/4]

regina::SubtreeIterator::SubtreeIterator ( const SubtreeIterator )
default


Default copy constructor.

Python
Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

◆ SubtreeIterator() [3/4]

regina::SubtreeIterator::SubtreeIterator ( Packet subtree)
inline


Creates a new iterator pointing to the first packet within the given subtree.

Dereferencing this iterator will return subtree itself.

Python
Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.
Parameters
subtreethe packet subtree that we are iterating through. This does not need to be the root of the overall packet tree (i.e., subtree is allowed to have a non-null parent).

◆ SubtreeIterator() [4/4]

regina::SubtreeIterator::SubtreeIterator ( const Packet subtree,
Packet current 
)
inline


Creates a new iterator pointing to the given packet within the given subtree.

Python
Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.
Parameters
subtreethe packet subtree that we are iterating through. This does not need to be the root of the overall packet tree (i.e., subtree is allowed to have a non-null parent).
currentthe packet within the subtree that the new iterator should point to, or 0 if the new iterator should be past-the-end. If current is not null, then it must be equal to or a descendant of subtree.

◆ 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() [1/2]

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
This routine returns a python set.
      @return the set of all tags associated with this packet.

◆ tags() [2/2]

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


Returns the set of all tags associated with this packet.

See Packet::tags() for further details on packet tags.

The reference that is returned should be only used as a temporary, since the underlying packet (and therefore the set that is referenced) is in the process of being destroyed.

Python
This routine returns a python set.
      @return the set of all tags associated with this packet.

◆ totalTreeSize()

size_t regina::Packet::totalTreeSize ( ) const

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

This packet is included in the count.

Returns
the total tree or subtree size.

◆ transferChildren()

void regina::Packet::transferChildren ( Packet newParent)

Cuts all of this packet's children out of the packet tree, and reinserts them as children of the given packet instead.

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

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

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

◆ type()

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

Returns the unique integer ID representing this type of packet.

This is the same for all packets of this class.

Returns
the packet type ID.

◆ typeName()

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

Returns an English name for this type of packet.

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

Returns
the packet type name.

◆ unlisten()

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

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

See the PacketListener class notes for details.

Parameters
listenerthe listener to unregister.
Returns
true if the given listener was successfully unregistered, or false if the given listener was not registered in the first place.

◆ unregisterFromAllPackets()

void regina::PacketListener::unregisterFromAllPackets ( )

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

◆ writeTextLong()

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


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

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

Python
Not present.
Parameters
outthe output stream to which to write.

Reimplemented in regina::Link, 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()

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
Not present.
Parameters
outthe output stream to which to write.

Implemented in regina::Link, 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
The argument out is not present; instead the XML data is written to standard output.
Parameters
outthe output stream to which the XML data file should be written.

◆ writeXMLPacketData()

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

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

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

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

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

◆ writeXMLPacketTree()

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

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

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

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

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

◆ 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
Not present.
Parameters
parentthe packet which will become the new packet's parent in the tree structure, or 0 if the new packet is to be tree matriarch.
resolverthe master resolver that will be used to fix dangling packet references after the entire XML file has been read.
Returns
the newly created XML element reader.

◆ ~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.

This destructor calls safeDelete() on its descendants. Therefore, if any descendants have safe pointers that reference them, those descendants will remain orphaned but alive (and their lifespans will now be managed by SafePtr instead). See safeDelete() for details.

◆ ~PacketListener()

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

Destroys this listener.

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

Variable Documentation

◆ PACKET_ANGLESTRUCTURELIST

constexpr PacketType regina::PACKET_ANGLESTRUCTURELIST = PACKET_ANGLESTRUCTURES

Deprecated alias for PACKET_ANGLESTRUCTURES.

Deprecated:
This constant has been renamed to PACKET_ANGLESTRUCTURES.

◆ PACKET_DIM2TRIANGULATION

constexpr PacketType regina::PACKET_DIM2TRIANGULATION = PACKET_TRIANGULATION2

Deprecated alias for PACKET_TRIANGULATION2.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION2.

◆ PACKET_DIM4TRIANGULATION

constexpr PacketType regina::PACKET_DIM4TRIANGULATION = PACKET_TRIANGULATION4

Deprecated alias for PACKET_TRIANGULATION4.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION4.

◆ PACKET_NORMALHYPERSURFACELIST

constexpr PacketType regina::PACKET_NORMALHYPERSURFACELIST = PACKET_NORMALHYPERSURFACES

Deprecated alias for PACKET_NORMALHYPERSURFACES.

Deprecated:
This constant has been renamed to PACKET_NORMALHYPERSURFACES.

◆ PACKET_NORMALSURFACELIST

constexpr PacketType regina::PACKET_NORMALSURFACELIST = PACKET_NORMALSURFACES

Deprecated alias for PACKET_NORMALSURFACES.

Deprecated:
This constant has been renamed to PACKET_NORMALSURFACES.

◆ PACKET_TRIANGULATION

constexpr PacketType regina::PACKET_TRIANGULATION = PACKET_TRIANGULATION3

Deprecated alias for PACKET_TRIANGULATION3.

Deprecated:
This constant has been renamed to PACKET_TRIANGULATION3.

Friends

◆ Packet

friend class Packet
friend

Allow packets to automatically deregister listeners as they are destroyed.


Copyright © 1999-2021, 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).