Regina 7.3 Calculation Engine
Public Types | Public Member Functions | Protected Member Functions | List of all members
regina::Attachment Class Referenceabstract

A packet that can hold an arbitrary file attachment. More...

#include <packet/attachment.h>

Inheritance diagram for regina::Attachment:
regina::Packet regina::Output< Packet >

Public Types

enum  OwnershipPolicy { OWN_MALLOC , OWN_NEW , DEEP_COPY }
 Describes how an attachment packet should claim ownership of a block of binary data. More...
 

Public Member Functions

 Attachment ()
 Creates a packet with no attachment stored. More...
 
 Attachment (const char *pathname)
 Creates a new attachment containing the contents of the given file. More...
 
 Attachment (char *data, size_t size, OwnershipPolicy alloc, std::string filename)
 Creates a new attachment containing the given binary data. More...
 
 Attachment (const Attachment &src)
 Creates a new deep copy of the given attachment. More...
 
 ~Attachment () override
 Destroys this attachment packet and deallocates data if required. More...
 
Attachmentoperator= (const Attachment &src)
 Sets this to be a deep copy of the given attachment. More...
 
void swap (Attachment &other)
 Swaps the contents of this and the given attachment. More...
 
bool isNull () const
 Determines whether this packet is currently holding a non-empty attachment. More...
 
const char * data () const
 Returns a pointer to the block of raw data that forms this attachment. More...
 
size_t size () const
 Returns the size of this attachment in bytes. More...
 
const std::string & filename () const
 Returns the filename associated with this attachment. More...
 
std::string extension () const
 Returns the extension of the filename associated with this attachment. More...
 
void reset ()
 Empties this packet so that no attachment is stored. More...
 
void reset (char *data, size_t size, OwnershipPolicy alloc, std::string filename)
 Refills this attachment packet with the given binary data. More...
 
bool save (const char *pathname) const
 Saves the contents of this attachment to the given file. More...
 
bool operator== (const Attachment &other) const
 Determines if this and the given attachment hold identical data. More...
 
bool operator!= (const Attachment &other) const
 Determines if this and the given attachment hold different data. More...
 
void writeTextShort (std::ostream &out) const override
 Writes a short text representation of this object to the given output stream. More...
 
std::string str () const
 Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 
Packet Identification
virtual PacketType type () const =0
 Returns the unique integer ID representing this type of packet. More...
 
virtual std::string typeName () const =0
 Returns an English name for this type of packet. More...
 
const std::string & label () const
 Returns the label associated with this individual packet. More...
 
std::string humanLabel () const
 Returns the label associated with this individual packet, adjusted if necessary for human-readable output. More...
 
std::string adornedLabel (const std::string &adornment) const
 Returns the label of this packet adorned with the given string. More...
 
void setLabel (const std::string &label)
 Sets the label associated with this individual packet. More...
 
std::string fullName () const
 Returns a descriptive text string for the packet. More...
 
Tags
bool hasTag (const std::string &tag) const
 Determines whether this packet has the given associated tag. More...
 
bool hasTags () const
 Determines whether this packet has any associated tags at all. More...
 
bool addTag (const std::string &tag)
 Associates the given tag with this packet. More...
 
bool removeTag (const std::string &tag)
 Removes the association of the given tag with this packet. More...
 
void removeAllTags ()
 Removes all associated tags from this packet. More...
 
const std::set< std::string > & tags () const
 Returns the set of all tags associated with this packet. More...
 
Event Handling
bool listen (PacketListener *listener)
 Registers the given packet listener to listen for events on this packet. More...
 
bool isListening (PacketListener *listener)
 Determines whether the given packet listener is currently listening for events on this packet. More...
 
bool unlisten (PacketListener *listener)
 Unregisters the given packet listener so that it no longer listens for events on this packet. More...
 
Tree Queries
bool samePacket (const Packet &other) const
 Determines whether this and the given object refer to the same packet. More...
 
bool hasParent () const
 Determines if this packet has a parent in the tree structure. More...
 
std::shared_ptr< Packetparent () const
 Determines the parent packet in the tree structure. More...
 
std::shared_ptr< PacketfirstChild () const
 Determines the first child of this packet in the tree structure. More...
 
std::shared_ptr< PacketlastChild () const
 Determines the last child of this packet in the tree structure. More...
 
std::shared_ptr< PacketnextSibling () const
 Determines the next sibling of this packet in the tree structure. More...
 
std::shared_ptr< PacketprevSibling () const
 Determines the previous sibling of this packet in the tree structure. More...
 
std::shared_ptr< Packetroot () const
 Determines the root of the tree to which this packet belongs. More...
 
unsigned levelsDownTo (const Packet &descendant) const
 Counts the number of levels between this packet and its given descendant in the tree structure. More...
 
unsigned levelsUpTo (const Packet &ancestor) const
 Counts the number of levels between this packet and its given ancestor in the tree structure. More...
 
bool isAncestorOf (const Packet &descendant) const
 Determines if this packet is equal to or an ancestor of the given packet in the tree structure. More...
 
size_t countChildren () const
 Returns the number of immediate children of this packet. More...
 
size_t countDescendants () const
 Returns the total number of strict descendants of this packet. More...
 
size_t totalTreeSize () const
 Determines the total number of packets in the tree or subtree for which this packet is matriarch. More...
 
Tree Manipulation
void prepend (std::shared_ptr< Packet > child)
 Inserts the given packet as the first child of this packet. More...
 
void insertChildFirst (std::shared_ptr< Packet > child)
 Deprecated routine that inserts the given packet as the first child of this packet. More...
 
void append (std::shared_ptr< Packet > child)
 Inserts the given packet as the last child of this packet. More...
 
void insertChildLast (std::shared_ptr< Packet > child)
 Deprecated routine that inserts the given packet as the last child of this packet. More...
 
void insert (std::shared_ptr< Packet > newChild, std::shared_ptr< Packet > prevChild)
 Inserts the given packet as a child of this packet at the given location in this packet's child list. More...
 
void insertChildAfter (std::shared_ptr< Packet > newChild, std::shared_ptr< Packet > prevChild)
 Deprecated routine that inserts the given packet as a child of this packet at the given location in this packet's child list. More...
 
void makeOrphan ()
 Cuts this packet away from its parent in the tree structure and instead makes it the root of its own tree. More...
 
void reparent (const std::shared_ptr< Packet > &newParent, bool first=false)
 Cuts this packet away from its parent in the tree structure, and inserts it as a child of the given packet instead. More...
 
void transferChildren (const std::shared_ptr< Packet > &newParent)
 Cuts all of this packet's children out of the packet tree, and reinserts them as children of the given packet instead. More...
 
void swapWithNextSibling ()
 Swaps this packet with its next sibling in the sequence of children beneath their common parent packet. More...
 
void moveUp (unsigned steps=1)
 Moves this packet the given number of steps towards the beginning of its sibling list. More...
 
void moveDown (unsigned steps=1)
 Moves this packet the given number of steps towards the end of its sibling list. More...
 
void moveToFirst ()
 Moves this packet to be the first in its sibling list. More...
 
void moveToLast ()
 Moves this packet to be the last in its sibling list. More...
 
void sortChildren ()
 Sorts the immediate children of this packet according to their packet labels. More...
 
Searching and Iterating
SubtreeIterator< false > begin ()
 Returns a C++ non-const iterator at the beginning of the range of packets in the subtree rooted at this packet. More...
 
SubtreeIterator< true > begin () const
 Returns a C++ const iterator at the beginning of the range of packets in the subtree rooted at this packet. More...
 
SubtreeIterator< false > end ()
 Returns a C++ non-const iterator beyond the end of the range of packets in the subtree rooted at this packet. More...
 
SubtreeIterator< true > end () const
 Returns a C++ const iterator beyond the end of the range of packets in the subtree rooted at this packet. More...
 
auto __iter__ () const
 Returns a Python iterator over the packets in the subtree rooted at this packet. More...
 
PacketDescendants< false > descendants ()
 Returns a lightweight object for iterating through all strict descendants of this packet in the packet tree. More...
 
PacketDescendants< true > descendants () const
 Returns a lightweight object for iterating through all strict descendants of this packet in the packet tree. More...
 
PacketChildren< false > children ()
 Returns a lightweight object for iterating through the immediate children of this packet. More...
 
PacketChildren< true > children () const
 Returns a lightweight object for iterating through the immediate children of this packet. More...
 
std::shared_ptr< PacketnextTreePacket ()
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
std::shared_ptr< const PacketnextTreePacket () const
 Finds the next packet after this in a complete depth-first iteration of the entire tree structure to which this packet belongs. More...
 
std::shared_ptr< PacketnextTreePacket (PacketType type)
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
std::shared_ptr< const PacketnextTreePacket (PacketType type) const
 Finds the next packet after this of the requested type in a complete depth-first iteration of the entire tree structure. More...
 
std::shared_ptr< PacketfirstTreePacket (PacketType type)
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
std::shared_ptr< const PacketfirstTreePacket (PacketType type) const
 Finds the first packet of the requested type in a complete depth-first iteration of the tree structure. More...
 
std::shared_ptr< PacketfindPacketLabel (const std::string &label)
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 
std::shared_ptr< const PacketfindPacketLabel (const std::string &label) const
 Finds the packet with the requested label in the tree or subtree for which this packet is matriarch. More...
 
Cloning
std::shared_ptr< PacketcloneAsSibling (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...
 

Protected Member Functions

std::shared_ptr< PacketinternalClonePacket () const override
 Makes a new copy of this packet. More...
 
void writeXMLPacketData (std::ostream &out, FileFormat format, bool anon, PacketRefs &refs) const override
 Writes a chunk of XML containing the full subtree with this packet as matriarch. More...
 

File I/O

bool save (const char *filename, bool compressed=true, FileFormat format=REGINA_CURRENT_FILE_FORMAT) const
 Saves the subtree rooted at this packet to the given Regina data file, using Regina's native XML file format. More...
 
bool save (std::ostream &s, bool compressed=true, FileFormat format=REGINA_CURRENT_FILE_FORMAT) const
 Writes the subtree rooted at this packet to the given output stream, in the format of a Regina XML data file. More...
 
void writeXMLFile (std::ostream &out, FileFormat format=REGINA_CURRENT_FILE_FORMAT) const
 Writes the subtree rooted at this packet to the given output stream in Regina's native XML file format. More...
 
std::string internalID () const
 Returns a unique string ID that identifies this packet. More...
 
virtual void writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
template<typename... Args>
void writeXMLHeader (std::ostream &out, const char *element, FileFormat format, bool anon, PacketRefs &refs, bool newline, std::pair< const char *, Args >... attr) const
 Writes the opening XML tag for this packet. More...
 
void writeXMLTreeData (std::ostream &out, FileFormat format, PacketRefs &refs) const
 Writes any generic XML sub-elements for this packet that come from the packet tree. More...
 
void writeXMLFooter (std::ostream &out, const char *element, FileFormat format) const
 Writes the closing XML tag for this packet. More...
 
void writeXMLAnon (std::ostream &out, FileFormat format, PacketRefs &refs, const Packet &p) const
 Writes the given packet inside its own anonymous block. More...
 
virtual void addPacketRefs (PacketRefs &refs) const
 Records which other packets this packet refers to within the overall packet tree. More...
 
using PacketRefs = std::map< const Packet *, bool >
 Used during the XML output routines to manage references between packets in an XML data file. More...
 

Detailed Description

A packet that can hold an arbitrary file attachment.

The attachment is stored as a block of data in memory. If the attachment was originally read from the filesystem, this link is not maintained (i.e., if the source file subsequently changes, the attachment data stored in this packet will not change to reflect this).

This packet may or may not contain an attachment at any given time. This can be tested by calling isNull(), and can be changed by calling reset().

This class does not distinguish between an empty file attachment versus no attachment at all. In both cases, isNull() will return true.

Like all packet types, this class does not support C++ move semantics since this would interfere with the structure of the packet tree. It does support copy construction, copy assignment and swaps; however, these operations only copy/swap the mathematical content, not the packet infrastructure (e.g., they do not touch packet labels, or the packet tree, or event listeners).

Until Regina 6.0.1, this class was called PDF. It was renamed and expanded in Regina 7.0 to allow for any kind of file to be attached.

Member Typedef Documentation

◆ PacketRefs

using regina::Packet::PacketRefs = std::map<const Packet*, bool>
protectedinherited

Used during the XML output routines to manage references between packets in an XML data file.

If some packet needs to refer to a packet P, then P will appear as a key this map; the corresponding value will be false initially, and will change to true once P has been written to the XML file.

Member Enumeration Documentation

◆ OwnershipPolicy

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

Python
Not present. For Python users, blocks are always copied (i.e., the ownership policy is always DEEP_COPY).
Enumerator
OWN_MALLOC 

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

OWN_NEW 

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

DEEP_COPY 

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

Constructor & Destructor Documentation

◆ Attachment() [1/4]

regina::Attachment::Attachment ( )
inline

Creates a packet with no attachment stored.

Until some content is assigned (e.g., by the assignment operator, or by a non-trivial call to reset()), isNull() will return true.

◆ Attachment() [2/4]

regina::Attachment::Attachment ( const char *  pathname)

Creates a new attachment containing the contents of the given file.

The file will be read immediately, but no ongoing link will be maintained. That is, if the given file should later change its contents on the filesystem, the change will not be reflected in this attachment packet.

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

The filename that is stored with this attachment (i.e., the string that will be returned by filename()) will be the argument pathname with any directory prefixes removed (i.e., just the final filename component). If an error occurs when attempting to remove directory prefixes, the filename will be the empty string.

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.
Parameters
pathnamethe full pathname of the attachment to read.

◆ Attachment() [3/4]

regina::Attachment::Attachment ( char *  data,
size_t  size,
OwnershipPolicy  alloc,
std::string  filename 
)
inline

Creates a new attachment containing the given binary data.

The data array must contain a block of binary data, of size bytes. There is no notion of null termination: the data block may contain null bytes within it, and does not need to be terminated by a null byte at the end.

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

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

Python
The argument data should be a Python bytes object. The size and alloc arguments are not present, since a bytes object knows its size, and in Python the only available ownership policy is to make a deep copy.
Parameters
datathe block of binary data that forms the attachment, or null if no attachment is to be stored.
sizethe number of bytes in this block of binary data; if actual data is passed (i.e., data is not null) then this must be strictly positive.
allocdescribes if/how this packet should claim ownership of the given block of data; see the notes above for details.
filenamethe filename to associated with this attachment; typically this would be a filename only, with no directory prefixes. See filename() for details on how this string will be used.

◆ Attachment() [4/4]

regina::Attachment::Attachment ( const Attachment src)
inline

Creates a new deep copy of the given attachment.

Like all packet types, this only copies the content of the attachment, not the packet infrastructure (e.g., it will not copy the packet label, it will not clone the given packet's children, and it will not insert the new packet into any packet tree).

This is safe to call even if src does not contain a non-empty attachment (i.e., if src.isNull() returns true).

Parameters
srcthe attachment packet whose contents should be copied.

◆ ~Attachment()

regina::Attachment::~Attachment ( )
inlineoverride

Destroys this attachment packet and deallocates data if required.

Member Function Documentation

◆ __iter__()

auto regina::Packet::__iter__ ( ) const
inherited

Returns a Python iterator over the packets in the subtree rooted at this packet.

Subtree iteration is depth-first, where a parent packet is always processed before its descendants. In particular, this packet (as the root of the subtree) will be processed first.

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

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

Regina also supplies Python users with a member function Packet.subtree(), which returns an iterable object. Iterating over Packet.subtree() is exactly the same as iterating the packet itself; the subtree() function is offered because the intention may be clearer for readers.

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

C++
Not present. For C++ users, Packet provides the usual begin() and end() functions instead. In particular, you can iterate over a packet subtree in the usual C++ way using a range-based for loop.
Returns
an iterator over the subtree rooted at this packet.

◆ addPacketRefs()

void regina::Packet::addPacketRefs ( PacketRefs refs) const
inlineprotectedvirtualinherited

Records which other packets this packet refers to within the overall packet tree.

For each packet p that this packet refers to, this routine should insert the pair (p, false) into the given map.

This will be run before writing the packet tree to an XML data file. By recording that this packet refers to some other packet p, this will ensure that the XML header for p will include an explicit ID that this packet can then refer to.

Later on, as the XML is written, the value refs[p] will be changed from false to true once p has been written.

If your packet requires that the contents of p appear before this packet it the XML data file, then writeXMLPacketData() should check refs to see if p has already been written, and if not, it should write p in a new anonymous block.

It is fine if p does not actually belong to this packet tree. However, in this case writeXMLPacketData() must take responsibility to ensure that p is written to file. This would need to be done via writeXMLAnon(); moreover, as before, it should only be done only after checking refs to ensure this p has not already been written.

The default implementation of this routine does nothing.

Parameters
refsthe map in which any dependencies should be recorded.

Reimplemented in regina::PacketOf< Held >, and regina::Script.

◆ addTag()

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

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
inherited

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

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

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

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

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

◆ append()

void regina::Packet::append ( std::shared_ptr< Packet child)
inherited

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

This packet will take ownership of child, in the sense that every parent packet stores (either directly or indirectly) a shared_ptr to every one of its descendants in the packet tree.

In Regina 7.0 and earlier, this routine was called insertChildLast().

This routine takes small constant time.

Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Exceptions
InvalidArgumentThe argument child already has a parent packet. Note that, although this tests one of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
childthe child to insert.

◆ begin() [1/2]

SubtreeIterator< false > regina::Packet::begin ( )
inlineinherited

Returns a C++ non-const 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. In particular, the iterator returned by begin() will always point to this packet itself.

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

std::shared_ptr<Packet> subtree = ...;
for (Packet& p : *subtree) { ... }
Packet()=default
Constructor that initialises the packet to have no parent and no children.

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned iterator.

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

Python
Not present. For Python users, Packet implements the Python iterable interface. You can iterate over the packets in a subtree in the usual Python way, by treating the subtree root as you would any native Python container. See iter() for details.
Returns
an iterator at the beginning of this subtree.

◆ begin() [2/2]

SubtreeIterator< true > regina::Packet::begin ( ) const
inlineinherited

Returns a C++ const 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. In particular, the iterator returned by begin() will always point to this packet itself.

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

std::shared_ptr<const Packet> subtree = ...;
for (const Packet& p : *subtree) { ... }

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned iterator.

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

Python
Not present. For Python users, Packet implements the Python iterable interface. You can iterate over the packets in a subtree in the usual Python way, by treating the subtree root as you would any native Python container. See iter() for details.
Returns
an iterator at the beginning of this subtree.

◆ children() [1/2]

PacketChildren< false > regina::Packet::children ( )
inlineinherited

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 range-based for loops:

std::shared_ptr<Packet> parent = ...;
for (Packet& child : parent->children()) { ... }
std::shared_ptr< Packet > parent() const
Determines the parent packet in the tree structure.
Definition: packet.h:4051

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.

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned object.

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.

◆ children() [2/2]

PacketChildren< true > regina::Packet::children ( ) const
inlineinherited

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 range-based for loops:

std::shared_ptr<const Packet> parent = ...;
for (const Packet& child : 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.

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned object.

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.

◆ cloneAsSibling()

std::shared_ptr< Packet > regina::Packet::cloneAsSibling ( bool  cloneDescendants = false,
bool  end = true 
) const
inherited

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 null will be returned.

In Regina 6.0.1 and earlier, this function was called clone(). It was renamed in Regina 7.0 to emphasise that this is not just a deep copy, and is not guaranteed to succeed.

Note
Since Regina 7.0, if a normal surface/hypersurface or angle structure list is cloned, then the new clone will refer back to the original triangulation, even if we are cloning an entire packet tree. This is because there is no guarantee that the original triangulation was cloned also (it could live outside the cloned subtree, or might not be part of a packet tree at all).
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 null if this packet has no parent.

◆ countChildren()

size_t regina::Packet::countChildren ( ) const
inherited

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
inlineinherited

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.

◆ data()

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

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

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

If this packet does not currently hold a non-empty attachment (i.e., if isNull() returns true), then this routine will return null.

Python
This routine returns a Python bytes object. Unlike the C++ version of this routine, the Python version returns a deep copy of the raw data (so this routine becomes slower, but the resulting byte sequence can be freely modified).
Returns
the raw attachment data.

◆ descendants() [1/2]

PacketDescendants< false > regina::Packet::descendants ( )
inlineinherited

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 range-based for loops:

std::shared_ptr<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.

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned object.

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.

◆ descendants() [2/2]

PacketDescendants< true > regina::Packet::descendants ( ) const
inlineinherited

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 range-based for loops:

std::shared_ptr<const Packet> parent = ...;
for (const Packet& desc : 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.

Since Regina 7.0, the return type is templated in order to support both const and non-const iteration. It is recommended that you just use auto if you need to store a local copy of the returned object.

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.

◆ detail()

std::string regina::Output< Packet , false >::detail ( ) const
inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns
a detailed text representation of this object.

◆ end() [1/2]

SubtreeIterator< false > regina::Packet::end ( )
inlineinherited

Returns a C++ non-const iterator beyond the end of the range of packets in the subtree rooted at this packet.

In C++, these begin() and end() routines allow you to iterate through an entire packet subtree using range-based for loops.

See the begin() documentation for further details.

Python
Not present. For Python users, Packet implements the Python iterable interface. You can iterate over the packets in a subtree in the usual Python way, by treating the subtree root as you would any native Python container. See iter() for details.
Returns
an iterator beyond the end of this subtree.

◆ end() [2/2]

SubtreeIterator< true > regina::Packet::end ( ) const
inlineinherited

Returns a C++ const iterator beyond the end of the range of packets in the subtree rooted at this packet.

In C++, these begin() and end() routines allow you to iterate through an entire packet subtree using range-based for loops.

See the begin() documentation for further details.

Python
Not present. For Python users, Packet implements the Python iterable interface. You can iterate over the packets in a subtree in the usual Python way, by treating the subtree root as you would any native Python container. See iter() for details.
Returns
an iterator beyond the end of this subtree.

◆ extension()

std::string regina::Attachment::extension ( ) const

Returns the extension of the filename associated with this attachment.

The user interface may use the result of filename() and/or extension() to determine which external viewer to launch when the user asks to view the attachment.

The extension will include the leading period. So, for example, if filename() returns "file.pdf", then extension() will return ".pdf".

If the associated filename has no extension, or if an error occurred when attempting to deduce it, then this routine will return the empty string.

Returns
the extension of the filename for this attachment.

◆ filename()

const std::string & regina::Attachment::filename ( ) const
inline

Returns the filename associated with this attachment.

Typically this would be a filename only, with no path information.

The user interface may use the result of filename() and/or extension() to determine which external viewer to launch when the user asks to view the attachment.

There are no guarantees on the contents of this string, and user interfaces should treat it as a hint only (i.e., they may modify or even completely override it when saving the attachment as a local file). It is possible in some scenarios that this could be the empty string, or could be some other string that is not a valid filename on the current platform.

Returns
the filename associated with this attachment.

◆ findPacketLabel() [1/2]

std::shared_ptr< Packet > regina::Packet::findPacketLabel ( const std::string &  label)
inherited

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 null if there is no such packet.

◆ findPacketLabel() [2/2]

std::shared_ptr< const Packet > regina::Packet::findPacketLabel ( const std::string &  label) const
inherited

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 null if there is no such packet.

◆ firstChild()

std::shared_ptr< Packet > regina::Packet::firstChild ( ) const
inlineinherited

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

This routine takes small constant time.

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

◆ firstTreePacket() [1/2]

std::shared_ptr< Packet > regina::Packet::firstTreePacket ( PacketType  type)
inlineinherited

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.
Returns
the first such packet, or null if there are no packets of the requested type.

◆ firstTreePacket() [2/2]

std::shared_ptr< const Packet > regina::Packet::firstTreePacket ( PacketType  type) const
inlineinherited

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.
Returns
the first such packet, or null if there are no packets of the requested type.

◆ fullName()

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

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.

◆ hasParent()

bool regina::Packet::hasParent ( ) const
inlineinherited

Determines if this packet has a parent in the tree structure.

This is equivalent to, but slightly faster than, testing whether parent() returns a null pointer.

Returns
if and only if this packet has a parent.

◆ hasTag()

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

Determines whether this packet has the given associated tag.

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

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

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

◆ hasTags()

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

Determines whether this packet has any associated tags at all.

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

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

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

◆ humanLabel()

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

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.

◆ insert()

void regina::Packet::insert ( std::shared_ptr< Packet newChild,
std::shared_ptr< Packet prevChild 
)
inherited

Inserts the given packet as a child of this packet at the given location in this packet's child list.

This packet will take ownership of child, in the sense that every parent packet stores (either directly or indirectly) a shared_ptr to every one of its descendants in the packet tree.

In Regina 7.0 and earlier, this routine was called insertChildAfter().

This routine takes small constant time.

Precondition
Parameter newChild has no parent packet.
This packet is already the parent of prevChild.
This packet is not a descendant of newChild.
Exceptions
InvalidArgumentThe argument newChild already has a parent packet, and/or the argument prevChild is non-null and does not have this packet as its parent. Note that, although this tests some of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
newChildthe child to insert.
prevChildthe preexisting child of this packet after which newChild will be inserted, or null if newChild is to be the first child of this packet.

◆ insertChildAfter()

void regina::Packet::insertChildAfter ( std::shared_ptr< Packet newChild,
std::shared_ptr< Packet prevChild 
)
inlineinherited

Deprecated routine that inserts the given packet as a child of this packet at the given location in this packet's child list.

Deprecated:
This routine has been renamed to insert(). See insert() for further details.
Precondition
Parameter newChild has no parent packet.
This packet is already the parent of prevChild.
This packet is not a descendant of newChild.
Exceptions
InvalidArgumentThe argument newChild already has a parent packet, and/or the argument prevChild is non-null and does not have this packet as its parent. Note that, although this tests some of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
newChildthe child to insert.
prevChildthe preexisting child of this packet after which newChild will be inserted, or null if newChild is to be the first child of this packet.

◆ insertChildFirst()

void regina::Packet::insertChildFirst ( std::shared_ptr< Packet child)
inlineinherited

Deprecated routine that inserts the given packet as the first child of this packet.

Deprecated:
This routine has been renamed to prepend(). See prepend() for further details.
Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Exceptions
InvalidArgumentThe argument child already has a parent packet. Note that, although this tests one of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
childthe child to insert.

◆ insertChildLast()

void regina::Packet::insertChildLast ( std::shared_ptr< Packet child)
inlineinherited

Deprecated routine that inserts the given packet as the last child of this packet.

Deprecated:
This routine has been renamed to append(). See append() for further details.
Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Exceptions
InvalidArgumentThe argument child already has a parent packet. Note that, although this tests one of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
childthe child to insert.

◆ internalClonePacket()

std::shared_ptr< Packet > regina::Attachment::internalClonePacket ( ) const
inlineoverrideprotectedvirtual

Makes a new 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.

Returns
the newly created packet.

Implements regina::Packet.

◆ internalID()

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

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.

◆ isAncestorOf()

bool regina::Packet::isAncestorOf ( const Packet descendant) const
inherited

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

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.

◆ isNull()

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

Determines whether this packet is currently holding a non-empty attachment.

Returns
true if and only if this packet is holding a non-empty attachment.

◆ label()

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

Returns the label associated with this individual packet.

An example is MyTriangulation.

Returns
this individual packet's label.

◆ lastChild()

std::shared_ptr< Packet > regina::Packet::lastChild ( ) const
inlineinherited

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

This routine takes small constant time.

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

◆ levelsDownTo()

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

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.
Exceptions
FailedPreconditionThe argument descendant is not equal to or a descendant of this packet.
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
inlineinherited

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.
Exceptions
FailedPreconditionThis packet is not equal to or a descendant of the argument descendant.
Parameters
ancestorthe packet whose relationship with this packet we are examining.
Returns
the number of levels difference.

◆ listen()

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

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

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

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

The old parent will relinquish ownership of this packet. This means that, even if the old parent remains alive, once the last shared_ptr to this packet is destroyed then this packet itself will be destroyed also.

This makeOrphan() function is the preferred way to "delete" a packet p from a larger packet tree: simply orphan p and then dispose of any outstanding shared pointers to it (if you have any).

Even if you are not holding a shared_ptr to this packet yourself, this routine is still safe to use: it will keep an internal shared_ptr as a "guard" until makeOrphan() has completed its work, at which point the packet will be safely destroyed.

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

◆ moveDown()

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

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.
Parameters
stepsthe number of steps down to move.

◆ moveToFirst()

void regina::Packet::moveToFirst ( )
inherited

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

This routine takes small constant time.

◆ moveToLast()

void regina::Packet::moveToLast ( )
inherited

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

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.
Parameters
stepsthe number of steps up to move.

◆ nextSibling()

std::shared_ptr< Packet > regina::Packet::nextSibling ( ) const
inlineinherited

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 null if there is none.

◆ nextTreePacket() [1/4]

std::shared_ptr< Packet > regina::Packet::nextTreePacket ( )
inherited

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 null if this is the last packet in such an iteration.

◆ nextTreePacket() [2/4]

std::shared_ptr< const Packet > regina::Packet::nextTreePacket ( ) const
inherited

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 null if this is the last packet in such an iteration.

◆ nextTreePacket() [3/4]

std::shared_ptr< Packet > regina::Packet::nextTreePacket ( PacketType  type)
inlineinherited

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.
Returns
the next such packet, or null if this is the last packet of the requested type in such an iteration.

◆ nextTreePacket() [4/4]

std::shared_ptr< const Packet > regina::Packet::nextTreePacket ( PacketType  type) const
inlineinherited

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.
Returns
the next such packet, or null if this is the last packet of the requested type in such an iteration.

◆ operator!=()

bool regina::Attachment::operator!= ( const Attachment other) const
inline

Determines if this and the given attachment hold different data.

The filenames will not be compared.

It is safe to call this operator if one or both attachments is empty (i.e., isNull() returns true), in which case an empty attachment will compare as equal to any other empty attachment.

Parameters
otherthe attachment to compare with this.
Returns
true if and only if this and the given attachment contain different data.

◆ operator=()

Attachment & regina::Attachment::operator= ( const Attachment src)
inline

Sets this to be a deep copy of the given attachment.

Like all packet types, this only copies the content of the attachment, not the packet infrastructure (e.g., it will not copy the packet label, or change this packet's location in any packet tree).

This is safe to call even if src does not contain a non-empty attachment (i.e., if src.isNull() returns true).

Parameters
srcthe attachment packet whose contents should be copied.
Returns
a reference to this packet.

◆ operator==()

bool regina::Attachment::operator== ( const Attachment other) const
inline

Determines if this and the given attachment hold identical data.

The filenames will not be compared.

It is safe to call this operator if one or both attachments is empty (i.e., isNull() returns true), in which case an empty attachment will compare as equal to any other empty attachment.

Parameters
otherthe attachment to compare with this.
Returns
true if and only if this and the given attachment contain identical data.

◆ parent()

std::shared_ptr< Packet > regina::Packet::parent ( ) const
inlineinherited

Determines the parent packet in the tree structure.

This routine takes small constant time.

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

◆ prepend()

void regina::Packet::prepend ( std::shared_ptr< Packet child)
inherited

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

This packet will take ownership of child, in the sense that every parent packet stores (either directly or indirectly) a shared_ptr to every one of its descendants in the packet tree.

In Regina 7.0 and earlier, this routine was called insertChildFirst().

This routine takes small constant time.

Precondition
The given child has no parent packet.
This packet is not a descendant of the given child.
Exceptions
InvalidArgumentThe argument child already has a parent packet. Note that, although this tests one of our preconditions, there are other preconditions that are not tested, and for which no exceptions are thrown.
Parameters
childthe child to insert.

◆ prevSibling()

std::shared_ptr< Packet > regina::Packet::prevSibling ( ) const
inlineinherited

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 null if there is none.

◆ removeAllTags()

void regina::Packet::removeAllTags ( )
inherited

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

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 ( const std::shared_ptr< Packet > &  newParent,
bool  first = false 
)
inherited

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 prepend() or append().

Even if you are not holding a shared_ptr to this packet yourself, this routine is still safe to use: it will maintain a shared_ptr as a "guard" so that this packet is not inadvertently destroyed during the transfer.

You may pass newParent as null, in which case this routine behaves in the same way as makeOrphan() (and is similarly safe to use even if there are no other shared pointers to this packet).

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

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

Precondition
The given parent is not a descendant of this packet.
Parameters
newParentthe new parent of this packet, i.e., the packet beneath which this packet will be inserted.
firsttrue if this packet should be inserted as the first child of the given parent, or false (the default) if it should be inserted as the last child.

◆ reset() [1/2]

void regina::Attachment::reset ( )

Empties this packet so that no attachment is stored.

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

The old data will be deallocated if required.

◆ reset() [2/2]

void regina::Attachment::reset ( char *  data,
size_t  size,
OwnershipPolicy  alloc,
std::string  filename 
)

Refills this attachment packet with the given binary data.

The old data will be deallocated if required.

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

Warning
This cannot be used for self-assignment. If the argument data is in fact data() then this routine will most likely crash.
Python
The argument data should be a Python bytes object. The size and alloc arguments are not present, since a bytes object knows its size, and in Python the only available ownership policy is to make a deep copy.
Parameters
datathe block of binary data that forms the new attachment, or null if no attachment is to be stored.
sizethe number of bytes in this new block of binary data; if actual data is passed (i.e., data is not null) then this must be strictly positive.
allocdescribes if/how this packet should claim ownership of the given block of data; see the notes above for details.
filenamethe new filename to associated with this attachment; this will override the previously stored filename. Typically this would be a filename only, with no directory prefixes. See filename() for details on how this string will be used.

◆ root()

std::shared_ptr< Packet > regina::Packet::root ( ) const
inherited

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

Returns
the matriarch of the packet tree.

◆ samePacket()

bool regina::Packet::samePacket ( const Packet other) const
inlineinherited

Determines whether this and the given object refer to the same packet.

This is exactly the same as testing whether the underlying Packet pointers are equal, and so this routine is unnecessary for C++ users.

Instead, this routine is designed for Python users, since:

  • the Python keyword is will not work, because there could be many different Python wrappers all pointing to the same C++ object;
  • the Python equality test (==) will not work, since as of Regina 7.0 this compares objects by value (i.e., it tests whether their contents are equal).

A use case for this function could be (for example) iterating through a packet tree and identifying when a particular known packet has been found.

Parameters
otherthe packet to compare with this.
Returns
true if and only if this and the given object refer to the same underlying packet.

◆ save() [1/3]

bool regina::Packet::save ( const char *  filename,
bool  compressed = true,
FileFormat  format = REGINA_CURRENT_FILE_FORMAT 
) const
inherited

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.
formatindicates which of Regina's XML file formats to write. You should use the default (REGINA_CURRENT_FILE_FORMAT) unless you need your file to be readable by older versions of Regina. This must not be REGINA_BINARY_GEN_1, which is no longer supported.
Returns
true if and only if the file was successfully written.

◆ save() [2/3]

bool regina::Attachment::save ( const char *  pathname) const

Saves the contents of this attachment to the given file.

If this packet does not currently hold a non-empty attachment (i.e., if isNull() returns true), then this routine will do nothing and simply return false.

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

◆ save() [3/3]

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

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. This is not available in Python to avoid confusion with the filename-based save(). However, if you wish to write a Regina XML data file directly to an open Python file, you can still use writeXMLFile() for this.
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.
formatindicates which of Regina's XML file formats to write. You should use the default (REGINA_CURRENT_FILE_FORMAT) unless you need your file to be readable by older versions of Regina. This must not be REGINA_BINARY_GEN_1, which is no longer supported.
Returns
true if and only if the data was successfully written.

◆ setLabel()

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

Sets the label associated with this individual packet.

Parameters
labelthe new label to give this packet.

◆ size()

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

Returns the size of this attachment in bytes.

If this packet does not currently hold a non-empty attachment (i.e., if isNull() returns true), then this routine will return zero.

Returns
the number of bytes.

◆ sortChildren()

void regina::Packet::sortChildren ( )
inherited

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

◆ str()

std::string regina::Output< Packet , false >::str ( ) const
inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python
The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.
Returns
a short text representation of this object.

◆ swap()

void regina::Attachment::swap ( Attachment other)
inline

Swaps the contents of this and the given attachment.

Like all packet types, this only swaps the content of the attachments, not the packet infrastructure (e.g., it will not swap packet labels, or change either packet's location in any packet tree).

This is safe to call even if this packet and/or other does not contain a non-empty attachment (i.e., if isNull() returns true).

Parameters
otherthe attachment packet whose contents should be swapped with this.

◆ swapWithNextSibling()

void regina::Packet::swapWithNextSibling ( )
inherited

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 safely does nothing.

◆ tags()

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

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.
Returns
the set of all tags associated with this packet.

◆ totalTreeSize()

size_t regina::Packet::totalTreeSize ( ) const
inherited

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 ( const std::shared_ptr< Packet > &  newParent)
inherited

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.

Even if you are not holding a shared_ptr to any of this packet's children, this routine is still safe to use: it will ensure there is always some shared_ptr to guard against any children being inadvertently destroyed during the transfer.

You may pass newParent as null, in which case this routine is equivalent to calling makeOrphan() on each child (and is similarly safe to use even if there are no other shared pointers to this packet).

Precondition
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 virtualinherited

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 virtualinherited

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

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.

◆ utf8()

std::string regina::Output< Packet , false >::utf8 ( ) const
inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns
a short text representation of this object.

◆ writeTextLong()

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

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. Use detail() instead.
Parameters
outthe output stream to which to write.

Reimplemented in regina::PacketOf< Held >, regina::Script, and regina::Text.

◆ writeTextShort()

void regina::Attachment::writeTextShort ( std::ostream &  out) const
inlineoverridevirtual

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

This must be reimplemented by subclasses.

Python
Not present. Use str() instead.
Parameters
outthe output stream to which to write.

Implements regina::Packet.

◆ writeXMLAnon()

void regina::Packet::writeXMLAnon ( std::ostream &  out,
FileFormat  format,
PacketRefs refs,
const Packet p 
) const
protectedinherited

Writes the given packet inside its own anonymous block.

This could (for example) be called as the first step in writeXMLPacketData() if the packet needs some dependency p to have been explicitly written to file and this has not been done yet.

This function simply creates an anon XML block, and within it calls p.writeXMLPacketData() with the anon argument set to true.

Parameters
outthe output stream to which the anonymous block should be written.
formatindicates which of Regina's XML file formats to write.
refsmanages the necessary references between packets in the XML file; see the PacketRefs documentation for details.
pthe packet to write inside the anonymous block.

◆ writeXMLFile()

void regina::Packet::writeXMLFile ( std::ostream &  out,
FileFormat  format = REGINA_CURRENT_FILE_FORMAT 
) const
inherited

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.

Python
The argument out should be an open Python file object.
Parameters
outthe output stream to which the XML data file should be written.
formatindicates which of Regina's XML file formats to write. You should use the default (REGINA_CURRENT_FILE_FORMAT) unless you need your file to be readable by older versions of Regina. This must not be REGINA_BINARY_GEN_1, which is no longer supported.

◆ writeXMLFooter()

void regina::Packet::writeXMLFooter ( std::ostream &  out,
const char *  element,
FileFormat  format 
) const
protectedinherited

Writes the closing XML tag for this packet.

This is typically called at the end of writeXMLPacketData().

There will be no whitespace before the closing XML tag. The tag will be followed by a newline.

Parameters
outthe output stream to which the closing XML tag should be written.
elementthe name of the XML tag. If we are writing to the REGINA_XML_GEN_2 format, then this will be ignored (and may be null), and the tag name packet will be used instead.
formatindicates which of Regina's XML file formats to write.

◆ writeXMLHeader()

template<typename... Args>
void regina::Packet::writeXMLHeader ( std::ostream &  out,
const char *  element,
FileFormat  format,
bool  anon,
PacketRefs refs,
bool  newline,
std::pair< const char *, Args >...  attr 
) const
protectedinherited

Writes the opening XML tag for this packet.

This is typically called at the beginning of writeXMLPacketData().

The generic packet attributes (such as label, id if required, and type / typeid if we are writing to the second-generation format REGINA_XML_GEN_2) will be included.

If we are writing to the third-generation file format or newer, then any additional attributes specified in attr will also be included. If we are writing to the second-generation format REGINA_XML_GEN_2, then attr will be ignored.

If this packet appears as a key in the refs map, or if the anon argument indicates that we are in an anonymous block, then this routine will set refs[this] as true to record that this packet is now being written to XML.

Parameters
outthe output stream to which the opening XML tag should be written.
elementthe name of the XML tag. If we are writing to the REGINA_XML_GEN_2 format, then this will be ignored (and may be null), and the tag name packet will be used instead.
formatindicates which of Regina's XML file formats to write.
anontrue if this packet is being written within an anonymous block. If so, then the packet ID will always be written.
refsmanages the necessary references between packets in the XML file; see the PacketRefs documentation for details.
newlineindicates whether the opening XML tag should be followed by a newline. Normally this would be true, but if you need to avoid whitespace between the opening XML tag and the packet contents then you should pass false instead.
attrany additional attributes to write to the XML tag; each attribute should a pair of the form (attribute, value). When writing to the REGINA_XML_GEN_2 format, this will be ignored.

◆ writeXMLPacketData()

void regina::Attachment::writeXMLPacketData ( std::ostream &  out,
FileFormat  format,
bool  anon,
PacketRefs refs 
) const
overrideprotectedvirtual

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

This should contain:

  • any anonymous packets that need to be written before this packet (but first check refs to ensure these packets have not already been written);
  • the packet opening XML tag;
  • the packet contents;
  • any packet tags and/or child packets (but only if we are not inside an anonymous block);
  • a closing XML tag and a final newline.

For native packet types, these five stages are typically implemented using:

For wrapped packet types that use a PacketOf<Held> wrapper, you should instead just specialise the routines from XMLWriter<Held>. The PacketOf wrapper will take care of the tree-specific code (in particular, it will handle the calls to writeXMLAnon() and writeXMLTreeData()).

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.
formatindicates which of Regina's XML file formats to write.
anontrue if this packet is being written within an anonymous block. If so, then the packet ID must be included, and any packet tags and/or child packets must be excluded.
refsmanages the necessary references between packets in the XML file; see the PacketRefs documentation for details.

Implements regina::Packet.

◆ writeXMLTreeData()

void regina::Packet::writeXMLTreeData ( std::ostream &  out,
FileFormat  format,
PacketRefs refs 
) const
protectedinherited

Writes any generic XML sub-elements for this packet that come from the packet tree.

This is typically called towards the end of writeXMLPacketData(), just before the final call to writeXMLFooter().

The generic sub-elements include Regina's packet tags, as well as any child packets in the packet tree.

There will be no whitespace before the first sub-element (and so if there are no sub-elements at all then this routine will output nothing).

Precondition
This packet is not contained within an anonymous block.
Parameters
outthe output stream to which the closing XML tag should be written.
formatindicates which of Regina's XML file formats to write.
refsmanages the necessary references between packets in the XML file; see the PacketRefs documentation for details.

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

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