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

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

Classes

struct  regina::PacketInfo< PACKET_CONTAINER >
 Stores information about the container packet. More...
 
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::NPacket::ChangeEventSpan
 An object that facilitates firing packetToBeChanged() and packetWasChanged() events. More...
 
class  regina::NPacketListener
 An object that can be registered to listen for packet events. More...
 
struct  regina::PacketInfo< PACKET_PDF >
 Stores information about the PDF packet. More...
 
class  regina::NPDF
 A packet that can hold a PDF document. More...
 
struct  regina::PacketInfo< PACKET_SCRIPT >
 Stores information about the script packet. More...
 
class  regina::NScript
 A packet representing a Python script that can be run. More...
 
struct  regina::PacketInfo< PACKET_TEXT >
 Stores information about the text packet. 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...
 

Enumerations

enum  regina::NPDF::OwnershipPolicy { regina::NPDF::OWN_MALLOC, regina::NPDF::OWN_NEW, regina::NPDF::DEEP_COPY }
 Describes how a PDF packet should claim ownership of a block of binary data. More...
 
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_DIM2TRIANGULATION = 15, regina::PACKET_SNAPPEATRIANGULATION = 16
}
 Represents the different types of packet that are available in Regina. More...
 

Functions

REGINA_API NPacket * regina::open (const char *filename)
 Reads a Regina data file, and returns the corresponding packet tree. More...
 
template<typename FunctionObject >
FunctionObject::ReturnType regina::forPacket (PacketType packetType, FunctionObject func, typename FunctionObject::ReturnType defaultReturn)
 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 VoidFunctionObject >
void regina::forPacket (PacketType packetType, VoidFunctionObject func)
 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

#define REGINA_PACKET (   class_,
  id 
)
Value:
public: \
enum { packetType = id }; \
inline virtual PacketType getPacketType() const { \
return id; \
} \
inline virtual std::string getPacketTypeName() const { \
return PacketInfo<id>::name(); \
}
PacketType
Represents the different types of packet that are available in Regina.
Definition: packettype.h:59

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 enum constant packetType, which is equal to the corresponding PacketType constant;
  • declarations and implementations of the virtual functions NPacket::getPacketType() and NPacket::getPacketTypeName().
Parameters
class_the name of this descendant class of NSurfaceFilter.
idthe corresponding PacketType constant.

Enumeration Type Documentation

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

Python:
Not present.
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.

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-manifold triangulation, of class NTriangulation.

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_DIM2TRIANGULATION 

Represents a 2-manifold triangulation, of class Dim2Triangulation.

PACKET_SNAPPEATRIANGULATION 

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

Function Documentation

template<typename FunctionObject >
FunctionObject::ReturnType regina::forPacket ( PacketType  packetType,
FunctionObject  func,
typename FunctionObject::ReturnType  defaultReturn 
)

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 unary bracket operator, so that func(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(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 two-argument variant of forPacket() that works with void functions.

Precondition
The function object must have a typedef ReturnType indicating the return type of the corresponding templated unary bracket operator. Inheriting from Returns<...> is a convenient way to ensure this.
Python:
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose unary bracket operator we will call with a PacketInfo<packetType> object.
defaultReturnthe value to return if the given packet type is not valid.
Returns
the return value from the corresponding unary bracket operator of func, or defaultReturn if the given packet type is not valid.
template<typename VoidFunctionObject >
void regina::forPacket ( PacketType  packetType,
VoidFunctionObject  func 
)

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 unary bracket operator, so that func(PacketInfo<t>) is defined for any valid PacketType enum value t. Then, when the user calls forPacket(packetType, func), this routine will call func(PacketInfo<packetType>) in turn. If packetType does not denote a valid packet type, then forPacket() will do nothing.

There is also a three-argument variant of forPacket() that works with functions with return values.

Python:
Not present.
Parameters
packetTypethe given packet type.
functhe function object whose unary bracket operator we will call with a PacketInfo<packetType> object.
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.
Parameters
filenamethe pathname of the file to read from.
Returns
the packet tree read from file, or 0 on error (as explained above).

Copyright © 1999-2014, 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@debian.org).