Regina Calculation Engine
Classes | Macros | Enumerations | Functions
Basic Packet Types

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

Classes

class  regina::NContainer
 A packet that simply contains other packets. More...
 
struct  regina::PacketInfo< packetType >
 A template that stores information about a particular type of packet. More...
 
class  regina::NPacket
 Represents a packet of information that may be individually edited or operated upon. More...
 
class  regina::NPacketListener
 An object that can be registered to listen for packet events. More...
 
class  regina::NPDF
 A packet that can hold a PDF document. More...
 
class  regina::NScript
 A packet representing a Python script that can be run. More...
 
class  regina::NText
 A packet representing a text string. More...
 
class  regina::NXMLPacketReader
 An XML element reader that reads the data for an individual packet. More...
 
class  regina::NXMLContainerReader
 An XML packet reader that reads a single container. More...
 
class  regina::NXMLPDFReader
 An XML packet reader that reads a single PDF packet. More...
 
class  regina::NXMLScriptReader
 An XML packet reader that reads a single script. More...
 
class  regina::NXMLTextReader
 An XML packet reader that reads a single text packet. More...
 
class  regina::NXMLTreeResolutionTask
 An individual task for resolving dangling packet references after an XML data file has been read. More...
 
class  regina::NXMLTreeResolver
 Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file. More...
 

Macros

#define REGINA_PACKET(class_, id)
 Defines various constants, types and virtual functions for a subclass of NPacket. More...
 
#define REGINA_PACKET_FROM(class_, helper)
 An alternative to REGINA_PACKET, for scenarios where the relevant PacketInfo specialisation is not visible. More...
 

Enumerations

enum  regina::PacketType {
  regina::PACKET_CONTAINER = 1, regina::PACKET_TEXT = 2, regina::PACKET_TRIANGULATION = 3, regina::PACKET_NORMALSURFACELIST = 6,
  regina::PACKET_SCRIPT = 7, regina::PACKET_SURFACEFILTER = 8, regina::PACKET_ANGLESTRUCTURELIST = 9, regina::PACKET_PDF = 10,
  regina::PACKET_DIM4TRIANGULATION = 11, regina::PACKET_NORMALHYPERSURFACELIST = 13, regina::PACKET_DIM2TRIANGULATION = 15, regina::PACKET_SNAPPEATRIANGULATION = 16,
  regina::PACKET_TRIANGULATION2 = 15, regina::PACKET_TRIANGULATION3 = 3, regina::PACKET_TRIANGULATION4 = 11, regina::PACKET_TRIANGULATION5 = 105,
  regina::PACKET_TRIANGULATION6 = 106, regina::PACKET_TRIANGULATION7 = 107, regina::PACKET_TRIANGULATION8 = 108, regina::PACKET_TRIANGULATION9 = 109,
  regina::PACKET_TRIANGULATION10 = 110, regina::PACKET_TRIANGULATION11 = 111, regina::PACKET_TRIANGULATION12 = 112, regina::PACKET_TRIANGULATION13 = 113,
  regina::PACKET_TRIANGULATION14 = 114, regina::PACKET_TRIANGULATION15 = 115
}
 Represents the different types of packet that are available in Regina. More...
 

Functions

REGINA_API NPacketregina::open (const char *filename)
 Reads a Regina data file, and returns the corresponding packet tree. More...
 
REGINA_API NPacketregina::open (std::istream &s)
 Reads a Regina data file from the given input stream, and returns the corresponding packet tree. More...
 
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::ReturnType regina::forPacket (PacketType packetType, FunctionObject &&func, typename ReturnsTraits< FunctionObject >::ReturnType defaultReturn, Args &&... args)
 Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime. More...
 
template<typename FunctionObject , typename... Args>
ReturnsTraits< FunctionObject >::Void regina::forPacket (PacketType packetType, FunctionObject &&func, Args &&... args)
 Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime. More...
 

Detailed Description

Packet administration and some basic packet types.

Macro Definition Documentation

§ REGINA_PACKET

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

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

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

This macro provides the class with:

  • a compile-time constant typeID and a deprecated compile-time constant packetType, both equal to the corresponding PacketType constant;
  • declarations and implementations of the virtual functions NPacket::type() and NPacket::typeName().

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

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

§ REGINA_PACKET_FROM

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

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

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

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

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

Enumeration Type Documentation

§ PacketType

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

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

Enumerator
PACKET_CONTAINER 

Represents a container packet, of class NContainer.

PACKET_TEXT 

Represents a text packet, of class NText.

PACKET_TRIANGULATION 

Represents a 3-dimensional triangulation, of class Triangulation<3> (or equivalently, NTriangulation).

This is identical to the constant PACKET_TRIANGULATION3.

PACKET_NORMALSURFACELIST 

Represents a normal surface list, of class NNormalSurfaceList.

PACKET_SCRIPT 

Represents a script packet, of class NScript.

PACKET_SURFACEFILTER 

Represents a normal surface filter, of class NSurfaceFilter or one of its descendant classes.

PACKET_ANGLESTRUCTURELIST 

Represents an angle structure list, of class NAngleStructureList.

PACKET_PDF 

Represents a PDF document, of class NPDF.

PACKET_DIM4TRIANGULATION 

Represents a 4-dimensional triangulation, of class Triangulation<4> (or equivalently, Dim4Triangulation).

This is identical to the constant PACKET_TRIANGULATION4.

PACKET_NORMALHYPERSURFACELIST 

Represents a normal hypersurface list, of class NNormalHypersurfaceList.

PACKET_DIM2TRIANGULATION 

Represents a 2-dimensional triangulation, of class Triangulation<2> (or equivalently, Dim2Triangulation).

This is identical to the constant PACKET_TRIANGULATION2.

PACKET_SNAPPEATRIANGULATION 

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

PACKET_TRIANGULATION2 

Represents a 2-dimensional triangulation, of class Triangulation<2> (or equivalently, Dim2Triangulation).

This is identical to the constant PACKET_DIM2TRIANGULATION.

PACKET_TRIANGULATION3 

Represents a 3-dimensional triangulation, of class Triangulation<3> (or equivalently, NTriangulation).

This is identical to the constant PACKET_TRIANGULATION.

PACKET_TRIANGULATION4 

Represents a 4-dimensional triangulation, of class Triangulation<4> (or equivalently, Dim4Triangulation).

This is identical to the constant PACKET_DIM4TRIANGULATION.

PACKET_TRIANGULATION5 

Represents a 5-dimensional triangulation, of class Triangulation<5>.

PACKET_TRIANGULATION6 

Represents a 6-dimensional triangulation, of class Triangulation<6>.

PACKET_TRIANGULATION7 

Represents a 7-dimensional triangulation, of class Triangulation<7>.

PACKET_TRIANGULATION8 

Represents a 8-dimensional triangulation, of class Triangulation<8>.

PACKET_TRIANGULATION9 

Represents a 9-dimensional triangulation, of class Triangulation<9>.

PACKET_TRIANGULATION10 

Represents a 10-dimensional triangulation, of class Triangulation<10>.

PACKET_TRIANGULATION11 

Represents a 11-dimensional triangulation, of class Triangulation<11>.

PACKET_TRIANGULATION12 

Represents a 12-dimensional triangulation, of class Triangulation<12>.

PACKET_TRIANGULATION13 

Represents a 13-dimensional triangulation, of class Triangulation<13>.

PACKET_TRIANGULATION14 

Represents a 14-dimensional triangulation, of class Triangulation<14>.

PACKET_TRIANGULATION15 

Represents a 15-dimensional triangulation, of class Triangulation<15>.

Function Documentation

§ forPacket() [1/2]

template<typename FunctionObject , typename... Args>
ReturnsTraits<FunctionObject>::ReturnType regina::forPacket ( PacketType  packetType,
FunctionObject &&  func,
typename ReturnsTraits< FunctionObject >::ReturnType  defaultReturn,
Args &&...  args 
)

Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible packet types known to Regina.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new packet type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated bracket operator, so that func.operator()<PacketInfo<t>>(...) is defined for any valid PacketType enum value t. Then, when the user calls forPacket(packetType, func, defaultReturn, ...), this routine will call func.operator()<PacketInfo<packetType>>(...) and pass back the corresponding return value. If packetType does not denote a valid packet type, then forPacket() will pass back defaultReturn instead.

There is also a variant of forPacket() that works with void functions, and so does not take the extra defaultReturn argument.

Precondition
The function object must have a typedef ReturnType indicating the return type of the corresponding templated bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.
Python:
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
defaultReturnthe value to return if the given packet type is not valid.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
the return value from the corresponding bracket operator of func, or defaultReturn if the given packet type is not valid.

§ forPacket() [2/2]

template<typename FunctionObject , typename... Args>
ReturnsTraits<FunctionObject>::Void regina::forPacket ( PacketType  packetType,
FunctionObject &&  func,
Args &&...  args 
)

Allows the user to call a template function whose template parameter matches a given value of PacketType, which is not known until runtime.

In essence, this routine contains a switch/case statement that runs through all possible packet types known to Regina.

The advantages of this routine are that (i) the user does not need to repeatedly type such switch/case statements themselves; and (ii) if a new packet type is added then only a small amount of code needs to be extended to incorporate it.

In detail: the function object func must define a templated bracket operator, so that func.operator()<PacketInfo<t>>(...) is defined for any valid PacketType enum value t. Then, when the user calls forPacket(packetType, func, ...), this routine will call func.operator()<PacketInfo<packetType>>(...) in turn. If packetType does not denote a valid packet type, then forPacket() will do nothing.

There is also a variant of forPacket() that works with functions with return values, and which takes an extra defaultReturn argument.

Precondition
There must not exist a type FunctionObject::ReturnType (or, if FunctionObject is a reference to a class/struct F, there must likewise not exist a type F::ReturnType). The existence of a type FunctionObject::ReturnType will cause the non-void variant of forPacket() to be used instead.
Python:
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose bracket operator we will call with a PacketInfo<packetType> object.
argsany additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.
Returns
nothing; the return type ReturnsTraits<FunctionObject>::Void simply evaluates to void.

§ open() [1/2]

REGINA_API NPacket* regina::open ( const char *  filename)

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

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

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

Internationalisation:
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.
Python:
This function is not automatically imported into the global namespace when running regina-python or when opening a Python console in the graphical user interface. This is to avoid overriding Python's own built-in open() function. You can access Regina's open() function by calling regina.open().
Parameters
filenamethe pathname of the file to read from.
Returns
the packet tree read from file, or 0 on error (as explained above).

§ open() [2/2]

REGINA_API NPacket* regina::open ( std::istream &  s)

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

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

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

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

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).