Regina Calculation Engine
|
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::Packet * | std::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::Packet * | std::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 XMLPacketReader * | regina::Packet::xmlReader (Packet *parent, XMLTreeResolver &resolver) |
Returns a newly created XML element reader that will read the contents of a single XML packet element. More... | |
regina::Packet::Packet (const Packet &)=delete | |
Packet & | regina::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 | |
ChangeEventSpan & | regina::Packet::ChangeEventSpan::operator= (const ChangeEventSpan &)=delete |
virtual Packet * | regina::Packet::internalClonePacket (Packet *parent) const =0 |
Makes a newly allocated copy of this packet. More... | |
void | regina::Packet::writeXMLPacketTree (std::ostream &out) const |
Writes a chunk of XML containing the subtree with this packet as matriarch. More... | |
virtual void | regina::Packet::writeXMLPacketData (std::ostream &out) const =0 |
Writes a chunk of XML containing the data for this packet only. More... | |
virtual void | regina::Packet::writeTextShort (std::ostream &out) const =0 |
Writes a short text representation of this object to the given output stream. More... | |
virtual void | regina::Packet::writeTextLong (std::ostream &out) const |
Writes a detailed text representation of this object to the given output stream. More... | |
bool | regina::Packet::hasOwner () const |
Indicates whether some other object in the calculation engine is responsible for ultimately destroying this object. More... | |
Packet * | regina::open (const char *filename) |
Reads a Regina data file, and returns the corresponding packet tree. More... | |
Packet * | regina::open (std::istream &in) |
Reads a Regina data file from the given input stream, and returns the corresponding packet tree. More... | |
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... | |
ChildIterator & | regina::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... | |
ChildIterator & | regina::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... | |
SubtreeIterator & | regina::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... | |
SubtreeIterator & | regina::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... | |
PacketChildren & | regina::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... | |
PacketDescendants & | regina::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... | |
PacketShell & | regina::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 | |
PacketListener & | regina::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 | |
Packet * | regina::Packet::parent () const |
Determines the parent packet in the tree structure. More... | |
Packet * | regina::Packet::firstChild () const |
Determines the first child of this packet in the tree structure. More... | |
Packet * | regina::Packet::lastChild () const |
Determines the last child of this packet in the tree structure. More... | |
Packet * | regina::Packet::nextSibling () const |
Determines the next sibling of this packet in the tree structure. More... | |
Packet * | regina::Packet::prevSibling () const |
Determines the previous sibling of this packet in the tree structure. More... | |
Packet * | regina::Packet::root () const |
Determines the root of the tree to which this packet belongs. More... | |
unsigned | regina::Packet::levelsDownTo (const Packet *descendant) const |
Counts the number of levels between this packet and its given descendant in the tree structure. More... | |
unsigned | regina::Packet::levelsUpTo (const Packet *ancestor) const |
Counts the number of levels between this packet and its given ancestor in the tree structure. More... | |
bool | regina::Packet::isGrandparentOf (const Packet *descendant) const |
Determines if this packet is equal to or an ancestor of the given packet in the tree structure. More... | |
size_t | regina::Packet::countChildren () const |
Returns the number of immediate children of this packet. More... | |
size_t | regina::Packet::countDescendants () const |
Returns the total number of 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... | |
Packet * | regina::Packet::nextTreePacket () |
Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More... | |
const Packet * | regina::Packet::nextTreePacket () const |
Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More... | |
Packet * | regina::Packet::firstTreePacket (const std::string &type) |
Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More... | |
const Packet * | regina::Packet::firstTreePacket (const std::string &type) const |
Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More... | |
Packet * | regina::Packet::nextTreePacket (const std::string &type) |
Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More... | |
const Packet * | regina::Packet::nextTreePacket (const std::string &type) const |
Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More... | |
Packet * | regina::Packet::findPacketLabel (const std::string &label) |
Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More... | |
const Packet * | regina::Packet::findPacketLabel (const std::string &label) const |
Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More... | |
Packet Dependencies | |
virtual bool | regina::Packet::dependsOnParent () const =0 |
Determines if this packet depends upon its parent. More... | |
bool | regina::Packet::isPacketEditable () const |
Determines whether this packet can be altered without invalidating or otherwise upsetting any of its immediate children. More... | |
Cloning | |
Packet * | regina::Packet::clone (bool cloneDescendants=false, bool end=true) const |
Clones this packet (and possibly its descendants), assigns to it a suitable unused label and inserts the clone into the tree as a sibling of this packet. More... | |
File I/O | |
bool | regina::Packet::save (const char *filename, bool compressed=true) const |
Saves the subtree rooted at this packet to the given Regina data file, using Regina's native XML file format. More... | |
bool | regina::Packet::save (std::ostream &s, bool compressed=true) const |
Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file. More... | |
void | regina::Packet::writeXMLFile (std::ostream &out) const |
Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format. More... | |
std::string | regina::Packet::internalID () const |
Returns a unique string ID that identifies this packet. More... | |
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... | |
Packet administration and some basic packet types.
#define REGINA_PACKET | ( | class_, | |
id | |||
) |
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:
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.
class_ | the name of this descendant class of Packet. |
id | the corresponding PacketType constant. |
#define REGINA_PACKET_FROM | ( | class_, | |
helper | |||
) |
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:
class_ | the name of this descendant class of Packet. |
helper | the helper class that provides the implementation details, as described above. |
typedef Container regina::NContainer |
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
typedef Packet regina::NPacket |
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
typedef PDF regina::NPDF |
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
typedef Script regina::NScript |
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
typedef Text regina::NText |
Deprecated typedef for backward compatibility.
This typedef will be removed in a future release of Regina.
enum regina::PacketType |
Represents the different types of packet that are available in Regina.
IDs 0-9999 are reserved for future use by Regina. If you are extending Regina to include your own packet type, you should choose an ID >= 10000.
Enumerator | |
---|---|
PACKET_CONTAINER | Represents a container packet, of class Container. |
PACKET_TEXT | Represents a text packet, of class Text. |
PACKET_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 | |
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>. |
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.
tag | the tag to add. |
true
if the given tag was successfully added, or false
if the given tag was already present beforehand. 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.
adornment | the string that will be used to adorn this packet label. The adornment should just be a piece of English, ideally beginning with an upper-case letter. It should not contain any surrounding punctuation such as brackets or a dash (this will be added automatically by this routine as required). |
|
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:
In Python, each packet can be treated as an iterable object, again iterating through the corresponding 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).
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.
|
inline |
Returns an iterator at the beginning of the range of children.
__iter__()
, as described in the class notes.
|
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.
__iter__()
, as described in the class notes.
|
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.
packet | the packet whose data is about to change. |
|
inline |
Creates a past-the-end iterator.
|
default |
Default copy constructor.
|
inline |
Creates a new iterator pointing to the given child packet.
current | the child packet that the new iterator should point to, or 0 if the new iterator should be past-the-end. |
|
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:
In Python, this routine returns an iterable object:
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).
|
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.
packet | the packet being listened to. |
|
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.
packet | the packet being listened to. |
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.
packet | the packet being listened to. |
child | the child packet to be added. |
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:
null
(since the parent packet is already well into its destruction process).null
to both functions.The default implementation of this routine is to do nothing.
packet | the packet being listened to, or null if this routine is being called from within this packet's destructor. |
child | the child packet to be removed, or null if this routine is being called from within the child's destructor. |
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.
packet | the packet being listened to. |
child | the child packet to be renamed. |
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.
packet | the packet being listened to. |
child | the child packet that was added. |
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:
null
(since the parent packet is already well into its destruction process).null
to both functions.The default implementation of this routine is to do nothing.
packet | the packet being listened to, or null if this routine is being called from within this packet's destructor. |
child | the child packet that was removed, or null if this routine is being called from within the child's destructor. |
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.
packet | the packet being listened to. |
child | the child packet that was renamed. |
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.
cloneDescendants | true if the descendants of this packet should also be cloned and inserted as descendants of the new packet. If this is passed as false (the default), only this packet will be cloned. |
end | true if the new packet should be inserted at the end of the parent's list of children (the default), or false if the new packet should be inserted as the sibling immediately after this packet. |
size_t regina::Packet::countChildren | ( | ) | const |
Returns the number of immediate children of this packet.
Grandchildren and so on are not counted.
|
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.
|
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.
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.
|
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:
In Python, this routine returns an iterable object:
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.
|
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.
|
inline |
Returns an iterator at the end of the range of children.
__iter__()
, as described in the class notes.
|
inline |
Returns an iterator at the end of the range of strict descendants.
__iter__()
, as described in the class notes.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.
label | the label to search for. |
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.
label | the label to search for. |
|
inline |
Determines the first child of this packet in the tree structure.
This routine takes small constant time.
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.
type | the type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive. |
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.
type | the type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive. |
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.
packetType | the given packet type. |
func | the function object whose bracket operator we will call with a PacketInfo<packetType> object. |
defaultReturn | the value to return if the given packet type is not valid. |
args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref. |
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.
packetType | the given packet type. |
func | the function object whose bracket operator we will call with a PacketInfo<packetType> object. |
args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref. |
ReturnsTraits<FunctionObject>::Void
simply evaluates to void
. 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().
|
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).
true
if and only if some other object owns this object.
|
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.
tag | the tag to search for. |
true
if the given tag is found, false
otherwise.
|
inline |
Determines whether this packet has the given associated tag.
See Packet::tags() for further details on packet tags.
tag | the tag to search for. |
true
if the given tag is found, false
otherwise.
|
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.
true
if this packet has any tags, false
otherwise.
|
inline |
Determines whether this packet has any associated tags at all.
See Packet::tags() for further details on packet tags.
true
if this packet has any tags, false
otherwise.
|
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.
|
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.
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.
newChild | the child to insert. |
prevChild | the preexisting child of this packet after which newChild will be inserted, or 0 if newChild is to be the first child of this packet. |
void regina::Packet::insertChildFirst | ( | Packet * | child | ) |
Inserts the given packet as the first child of this packet.
This routine takes small constant time.
child | the child to insert. |
void regina::Packet::insertChildLast | ( | Packet * | child | ) |
Inserts the given packet as the last child of this packet.
This routine takes small constant time.
child | the child to insert. |
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.
parent | the parent beneath which the new packet will eventually be inserted. |
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.
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.
|
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.
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.
descendant | the other packet whose relationships we are examining. |
true
if and only if this packet is equal to or an ancestor of descendant
.
|
inline |
Determines whether the given packet listener is currently listening for events on this packet.
See the PacketListener class notes for details.
listener | the listener to search for. |
true
if the given listener is currently registered with this packet, or false
otherwise. 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.
true
if and only if this packet may be edited.
|
inline |
Returns the label associated with this individual packet.
An example is MyTriangulation
.
|
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.
|
inline |
Determines the last child of this packet in the tree structure.
This routine takes small constant time.
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.
descendant
, or can be obtained from descendant
using only child-to-parent steps.descendant | the packet whose relationship with this packet we are examining. |
|
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.
ancestor
, or can be obtained from ancestor
using only parent-to-child steps.ancestor | the packet whose relationship with this packet we are examining. |
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.
listener | the listener to register. |
true
if the given listener was successfully registered, or false
if the given listener was already registered beforehand. 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.
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.
void regina::Packet::moveToFirst | ( | ) |
Moves this packet to be the first in its sibling list.
This routine takes small constant time.
void regina::Packet::moveToLast | ( | ) |
Moves this packet to be the last in its sibling list.
This routine takes small constant time.
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.
|
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.
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.
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.
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().
type | the type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive. |
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().
type | the type of packet to search for, as returned by typeName(). Note that string comparisons are case sensitive. |
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.
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()
.filename | the pathname of the file to read from. |
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.
in | the input stream to read from. |
|
inline |
Tests whether this and the given iterator are different.
|
inline |
Tests whether this and the given iterator are different.
|
inline |
Identifies if this and the given shell refer to different underlying packets.
shell | the shell to compare with this. |
true
if and only if both shells refer to different packets.
|
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.
packet | the packet to test against; this may be null . |
true
if and only if this shell does not refer to the given packet.
|
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.
packet | the packet to test against; this may be null . |
shell | the packet shell to test against. |
true
if and only if the given shell does not refer to the given packet.
|
inline |
Returns the packet that this iterator is currently pointing to.
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.
|
inline |
Returns the packet that this iterator is currently pointing to.
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.
|
inline |
Preincrement operator.
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.
|
inline |
Postincrement operator.
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.
|
inline |
Preincrement operator.
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.
|
inline |
Postincrement operator.
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.
|
default |
Default copy assignment operator.
|
default |
Default copy assignment operator.
|
default |
Default copy assignment operator.
|
default |
Default copy assignment operator.
|
default |
Sets this to be a copy of the given shell.
Both shells will refer to the same underlying packet.
shell | the shell to clone. |
|
inline |
Tests whether this and the given iterator are equal.
|
inline |
Tests whether this and the given iterator are equal.
|
inline |
Identifies if this and the given shell refer to the same underlying packet.
shell | the shell to compare with this. |
true
if and only if both shells refer to the same packet.
|
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.
packet | the packet to test against; this may be null . |
true
if and only if this shell refers to the given packet.
|
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.
packet | the packet to test against; this may be null . |
shell | the packet shell to test against. |
true
if and only if the given shell refers to the given packet.
|
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.
parent | the parent beneath which to insert this packet, or 0 if this packet is to be the matriarch of a new tree. |
|
default |
Default copy constructor.
|
inline |
Creates a new object for iterating through the immediate children of the given packet.
parent | the packet whose children we will iterate through. |
|
default |
Default copy constructor.
|
inline |
Creates a new object for iterating through the strict descendants of the given packet.
subtree | the packet whose strict descendants we will iterate through. |
|
protecteddefault |
A default constructor that does nothing.
|
inline |
Creates a new shell referring to the given packet.
packet | the packet to refer to. |
|
default |
Creates a copy of the given shell.
Both shells will refer to the same underlying packet.
shell | the shell to clone. |
|
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.
packet | the packet being listened to. |
|
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.
packet | gives access to the packet being listened to. |
Reimplemented in regina::Script.
|
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.
packet | the packet being listened to. |
|
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.
packet | the packet being listened to. |
Reimplemented in regina::SnapPeaTriangulation.
|
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.
packet | the packet being listened to. |
Reimplemented in regina::Script.
|
inline |
Determines the parent packet in the tree structure.
This routine takes small constant time.
|
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.
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.
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.
tag | the tag to remove. |
true
if the given tag was removed, or false
if the given tag was not actually associated with this packet. 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.
newParent | the new parent of this packet, i.e., the packet beneath which this packet will be inserted. |
first | true if this packet should be inserted as the first child of the given parent, or false (the default) if it should be inserted as the last child. |
Packet* regina::Packet::root | ( | ) | const |
Determines the root of the tree to which this packet belongs.
|
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.
p | the packet to delete or orphan. It is safe to pass null (in which case this routine does nothing). |
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.
filename | the pathname of the file to write to. |
compressed | true if the XML data should be compressed, or false if it should be written as plain text. |
true
if and only if the file was successfully written. 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.
s | the output stream to which to write. |
compressed | true if the XML data should be compressed, or false if it should be written as plain text. |
true
if and only if the data was successfully written. void regina::Packet::setLabel | ( | const std::string & | label | ) |
Sets the label associated with this individual packet.
label | the new label to give this packet. |
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).
|
inline |
Creates a past-the-end iterator.
|
default |
Default copy constructor.
|
inline |
Creates a new iterator pointing to the first packet within the given subtree.
Dereferencing this iterator will return subtree itself.
subtree | the 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). |
Creates a new iterator pointing to the given packet within the given subtree.
subtree | the 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). |
current | the 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. |
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.
|
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.
@return the set of all tags associated with this packet.
|
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.
@return the set of all tags associated with this packet.
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.
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.
newParent | the new parent beneath which the children will be inserted. |
|
pure virtual |
Returns the unique integer ID representing this type of packet.
This is the same for all packets of this class.
|
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.
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.
listener | the listener to unregister. |
true
if the given listener was successfully unregistered, or false
if the given listener was not registered in the first place. void regina::PacketListener::unregisterFromAllPackets | ( | ) |
Unregisters this listener from any packets to which it is currently listening.
|
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.
out | the 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.
|
pure virtual |
Writes a short text representation of this object to the given output stream.
This must be reimplemented by subclasses.
out | the 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.
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.
out | the output stream to which the XML data file should be written. |
|
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.
out | the 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.
|
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.
out | the output stream to which the XML should be written. |
|
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.
parent | the packet which will become the new packet's parent in the tree structure, or 0 if the new packet is to be tree matriarch. |
resolver | the master resolver that will be used to fix dangling packet references after the entire XML file has been read. |
|
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.
|
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.
|
virtual |
Destroys this listener.
This listener will be unregistered from any packets to which it is currently listening.
constexpr PacketType regina::PACKET_ANGLESTRUCTURELIST = PACKET_ANGLESTRUCTURES |
Deprecated alias for PACKET_ANGLESTRUCTURES.
constexpr PacketType regina::PACKET_DIM2TRIANGULATION = PACKET_TRIANGULATION2 |
Deprecated alias for PACKET_TRIANGULATION2.
constexpr PacketType regina::PACKET_DIM4TRIANGULATION = PACKET_TRIANGULATION4 |
Deprecated alias for PACKET_TRIANGULATION4.
constexpr PacketType regina::PACKET_NORMALHYPERSURFACELIST = PACKET_NORMALHYPERSURFACES |
Deprecated alias for PACKET_NORMALHYPERSURFACES.
constexpr PacketType regina::PACKET_NORMALSURFACELIST = PACKET_NORMALSURFACES |
Deprecated alias for PACKET_NORMALSURFACES.
constexpr PacketType regina::PACKET_TRIANGULATION = PACKET_TRIANGULATION3 |
Deprecated alias for PACKET_TRIANGULATION3.
|
friend |
Allow packets to automatically deregister listeners as they are destroyed.