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

Classes
class	regina::Attachment
	A packet that can hold an arbitrary file attachment. More...

class	regina::Container
	A packet that simply contains other packets. More...

class	regina::Packet
	Represents a packet of information that may be individually edited or operated upon. More...

class	regina::ChildIterator< const_ >
	A forward iterator for iterating through all immediate children of a given packet. More...

class	regina::SubtreeIterator< const_ >
	A forward iterator for iterating through the entire packet subtree rooted at a given packet. More...

class	regina::PacketChildren< const_ >
	A lightweight object that gives access to all immediate children of a given packet. More...

class	regina::PacketDescendants< const_ >
	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...

class	regina::PacketInfo
	A class used to query general information about different packet types. 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...

Macros
#define	REGINA_PACKET(id, name)
	Defines various constants and virtual functions for a subclass of Packet. More...

Enumerations
enum	regina::PacketType { regina::PACKET_NONE = 0 , 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_ATTACHMENT = 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 }
	Represents the different types of packet that are available in Regina. More...

Functions
void	regina::swap (Attachment &a, Attachment &b)
	Swaps the contents of the given attachment packets. More...

void	regina::swap (Container &, Container &)
	Swap function for container packets that does nothing. More...

template<typename Held >
std::shared_ptr< PacketOf< Held > >	regina::make_packet (Held &&src)
	Converts a temporary Held object into a new wrapped packet, without making a deep copy. More...

template<typename Held >
std::shared_ptr< PacketOf< Held > >	regina::make_packet (Held &&src, const std::string &label)
	Converts a temporary Held object into a new wrapped packet, without making a deep copy. More...

template<typename Held , typename... Args>
std::shared_ptr< PacketOf< Held > >	regina::make_packet (std::in_place_t, Args &&... args)
	Creates a new packet that wraps a Held object, passing the given arguments to the Held constructor. More...

template<typename Held >
std::shared_ptr< PacketOf< Held > >	regina::make_packet ()
	Creates a new packet that wraps a default-constructed Held object. More...

template<typename Held >
Held &	regina::static_packet_cast (Packet &p)
	Casts a reference from Packet to Held, assuming that the given packet is actually a PacketOf<Held>. More...

template<typename Held >
const Held &	regina::static_packet_cast (const Packet &p)
	Casts a const reference from Packet to Held, assuming that the given packet is actually a PacketOf<Held>. More...

std::shared_ptr< Packet >	regina::open (const char *filename)
	Reads a Regina data file, and returns the corresponding packet tree. More...

std::shared_ptr< Packet >	regina::open (std::istream &in)
	Reads a Regina data file from the given input stream, and returns the corresponding packet tree. 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...

void	regina::swap (Script &a, Script &b)
	Swaps the contents of the given script packets. More...

void	regina::swap (Text &a, Text &b)
	Swaps the contents of the given text packets. More...

Detailed Description

Packet administration and some basic packet types.

Macro Definition Documentation

◆ REGINA_PACKET

#define REGINA_PACKET	(	id,
		name
	)

Value:

    public: \
        static constexpr const PacketType typeID = id; \
        inline PacketType type() const override { \
            return id; \
        } \
        inline std::string typeName() const override { \
            return name; \
        }

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

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

This macro provides the class with:

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

Parameters

id	the corresponding PacketType constant.
name	the human-readable name of this packet type.

Enumeration Type Documentation

◆ PacketType

enum regina::PacketType

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

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

Enumerator
PACKET_NONE	Does not represent any of Regina's packet types. This can be used (for example) for initialising a PacketType variable.
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_ATTACHMENT	Represents an arbitrary file attachment, of class Attachment.
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>.

Function Documentation

◆ make_packet() [1/4]

template<typename Held >

std::shared_ptr< PacketOf< Held > > regina::make_packet ( )

Creates a new packet that wraps a default-constructed Held object.

This is equivalent to calling make_packet<Held>(std::in_place).

The packet that is returned will be newly created, and will have no packet label.

Note: This function is trivial (it simply calls std::make_shared). Nevertheless, using this function is recommended since it makes it clear (and searchable) that you are correctly wrapping the new packet in a std::shared_ptr, as is required for all packets in Regina.

Python: Not present. This routine is too heavily templated for Python. Instead you can just directly call the constructor PacketOfHeld().

Returns: the new wrapped packet.

◆ make_packet() [2/4]

template<typename Held >

std::shared_ptr< PacketOf< Held > > regina::make_packet ( Held && src )

Converts a temporary Held object into a new wrapped packet, without making a deep copy.

The data will be moved out of src (using the Held move constructor).

The packet that is returned will be newly created, and will have no packet label.

Note: This function is trivial (it just calls a single move constructor). Nevertheless, using this function is recommended since it makes it clear (and searchable) that you are correctly wrapping the new packet in a std::shared_ptr, as is required for all packets in Regina.

Python: The src argument is a const reference, and this routine makes a deep copy of src. This is because Python will still maintain a reference to src, and so it is not possible to move from src.

Parameters

src	the Held object that will be moved into the new packet; this will become unusable after this function returns.

Returns: the new wrapped packet.

◆ make_packet() [3/4]

template<typename Held >

std::shared_ptr< PacketOf< Held > > regina::make_packet	(	Held &&	src,
		const std::string &	label
	)

Converts a temporary Held object into a new wrapped packet, without making a deep copy.

The data will be moved out of src (using the Held move constructor).

The packet that is returned will be newly created, and will have the given packet label.

Note: This function is trivial (it just calls a single move constructor and then Packet::setLabel()). Nevertheless, using this function is recommended since it makes it clear (and searchable) that you are correctly wrapping the new packet in a std::shared_ptr, as is required for all packets in Regina.

Python: The src argument is a const reference, and this routine makes a deep copy of src. This is because Python will still maintain a reference to src, and so it is not possible to move from src.

Parameters

src	the Held object that will be moved into the new packet; this will become unusable after this function returns.
label	the label to assign to the new packet.

Returns: the new wrapped packet.

◆ make_packet() [4/4]

template<typename Held , typename... Args>

std::shared_ptr< PacketOf< Held > > regina::make_packet	(	std::in_place_t	,
		Args &&...	args
	)

Creates a new packet that wraps a Held object, passing the given arguments to the Held constructor.

The given arguments args will be forwarded directly to the appropriate Held constructor (using C++ perfect forwarding).

The initial argument should just be std::in_place; this is so the compiler can disambiguate between this function and other variants of make_packet().

The packet that is returned will be newly created, and will have no packet label.

Note: This function is trivial (it simply calls std::make_shared). Nevertheless, using this function is recommended since it makes it clear (and searchable) that you are correctly wrapping the new packet in a std::shared_ptr, as is required for all packets in Regina.

Python: Not present. This routine is too heavily templated for Python. Instead you can just directly call the constructor PacketOfHeld(args...).

Parameters

args	the arguments to be forwarded to the appropriate Held constructor.

Returns: the new wrapped packet.

◆ open() [1/2]

std::shared_ptr< 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 null. If some packet deeper within the tree could not be read then that particular packet (and its descendants, if any) will simply be ignored.

Internationalisation: This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.

Python: This function is not automatically imported into the global namespace when running regina-python, or when opening a Python console in the graphical user interface, or even when typing from regina import *. This is to avoid overriding Python's own built-in open() function. You can access Regina's open() function by calling regina.open().

Parameters

filename the pathname of the file to read from.

Returns: the packet tree read from file, or null on error.

◆ open() [2/2]

std::shared_ptr< 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 null. If some packet deeper within the tree could not be read then that particular packet (and its descendants, if any) will simply be ignored.

Precondition: The given stream is open for reading.

Python: Not present. Instead you can use the variant of open() that takes a filename.

Parameters

in	the input stream to read from.

Returns: the packet tree read from file, or null on error.

◆ operator!=()

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

inline

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

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

Parameters

packet	the packet to test against; this may be `null`.
shell	the packet shell to test against.

Returns: true if and only if the given shell does not refer to the given packet.

◆ operator==()

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

inline

Identifies if the given shell refers to the given packet.

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

Parameters

packet	the packet to test against; this may be `null`.
shell	the packet shell to test against.

Returns: true if and only if the given shell refers to the given packet.

◆ static_packet_cast() [1/2]

template<typename Held >

const Held & regina::static_packet_cast ( const Packet & p )

Casts a const reference from Packet to Held, assuming that the given packet is actually a PacketOf<Held>.

This is analogous to static_cast<const Held&>(). It is provided because we cannot perform a direct static cast between Packet and Held (since the two classes do not have a one-way inheritance relationship).

Precondition: The given reference refers to an object of type PacketOf<Held>.

Warning: If you try to use static_packet_cast<Triangulation<3>> on a reference to a PacketOf<SnapPeaTriangulation>, this will not work, since PacketOf<SnapPeaTriangulation> is not a subclass of PacketOf<Triangulation<3>>. The behaviour in this scenario is undefined. You should use regina::static_triangulation3_cast() instead.

Python: Not present. Casting is unnecessary in Python.

Parameters

p	a reference, presented as a packet.

Returns: the same reference, presented using the type Held.

◆ static_packet_cast() [2/2]

template<typename Held >

Held & regina::static_packet_cast ( Packet & p )

Casts a reference from Packet to Held, assuming that the given packet is actually a PacketOf<Held>.

This is analogous to static_cast<Held&>(). It is provided because we cannot perform a direct static cast between Packet and Held (since the two classes do not have a one-way inheritance relationship).

Precondition: The given reference refers to an object of type PacketOf<Held>.

Warning: If you try to use static_packet_cast<Triangulation<3>> on a reference to a PacketOf<SnapPeaTriangulation>, this will not work, since PacketOf<SnapPeaTriangulation> is not a subclass of PacketOf<Triangulation<3>>. The behaviour in this scenario is undefined. You should use regina::static_triangulation3_cast() instead.

Python: Not present. Casting is unnecessary in Python.

Parameters

p	a reference, presented as a packet.

Returns: the same reference, presented using the type Held.

◆ swap() [1/4]

void regina::swap	(	Attachment &	a,
		Attachment &	b
	)

inline

Swaps the contents of the given attachment packets.

This global routine simply calls Attachment::swap(); it is provided so that Attachment meets the C++ Swappable requirements.

Parameters

a	the first attachment packet whose contents should be swapped.
b	the second attachment packet whose contents should be swapped.

◆ swap() [2/4]

void regina::swap	(	Container &	,
		Container &
	)

inline

Swap function for container packets that does nothing.

This is only here for consistency with the other packet types. For container packets, the swap operation does nothing since containers have no "real" content of their own. See the member function Container::swap() for further explanation.

◆ swap() [3/4]

void regina::swap	(	Script &	a,
		Script &	b
	)

inline

Swaps the contents of the given script packets.

This global routine simply calls Script::swap(); it is provided so that Script meets the C++ Swappable requirements.

Parameters

a	the first script packet whose contents should be swapped.
b	the second script packet whose contents should be swapped.

◆ swap() [4/4]

void regina::swap	(	Text &	a,
		Text &	b
	)

inline

Swaps the contents of the given text packets.

This global routine simply calls Text::swap(); it is provided so that Text meets the C++ Swappable requirements.

Parameters

a	the first text packet whose contents should be swapped.
b	the second text packet whose contents should be swapped.

Classes

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ REGINA_PACKET

Enumeration Type Documentation

◆ PacketType

Function Documentation

◆ make_packet() [1/4]

◆ make_packet() [2/4]

◆ make_packet() [3/4]

◆ make_packet() [4/4]

◆ open() [1/2]

◆ open() [2/2]

◆ operator!=()

◆ operator==()

◆ static_packet_cast() [1/2]

◆ static_packet_cast() [2/2]

◆ swap() [1/4]

◆ swap() [2/4]

◆ swap() [3/4]

◆ swap() [4/4]