Basic Packet Types

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

## Classes

class | regina::Container
| A packet that simply contains other packets. More...
struct | regina::PacketInfo< packetType >
| A template that stores information about a particular type of packet. More...
class | regina::Packet
| Represents a packet of information that may be individually edited or operated upon. More...
class | regina::PacketListener
| An object that can be registered to listen for packet events. More...
class | regina::PDF
| A packet that can hold a PDF document. More...
class | regina::Script
| A packet representing a Python script that can be run. More...
class | regina::Text
| A packet representing a text string. More...
class | regina::XMLPacketReader
| An XML element reader that reads the data for an individual packet. More...
class | regina::XMLContainerReader
| An XML packet reader that reads a single container. More...
class | regina::XMLPDFReader
| An XML packet reader that reads a single PDF packet. More...
class | regina::XMLScriptReader
| An XML packet reader that reads a single script. More...
class | regina::XMLTextReader
| An XML packet reader that reads a single text packet. More...
class | regina::XMLTreeResolutionTask
| An individual task for resolving dangling packet references after an XML data file has been read. More...
class | regina::XMLTreeResolver
| Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file. More...

## Macros

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

## Typedefs

typedef Container | regina::NContainer
| Deprecated typedef for backward compatibility. More...
typedef Packet | regina::NPacket
| Deprecated typedef for backward compatibility. More...
typedef PacketListener | regina::NPacketListener
| Deprecated typedef for backward compatibility. More...
typedef PDF | regina::NPDF
| Deprecated typedef for backward compatibility. More...
typedef Script | regina::NScript
| Deprecated typedef for backward compatibility. More...
typedef Text | regina::NText
| Deprecated typedef for backward compatibility. More...

## Enumerations

enum

regina::PacketType {
regina::PACKET_CONTAINER = 1, regina::PACKET_TEXT = 2, regina::PACKET_TRIANGULATION = 3, regina::PACKET_NORMALSURFACES = 6,
regina::PACKET_NORMALSURFACELIST = 6, regina::PACKET_SCRIPT = 7, regina::PACKET_SURFACEFILTER = 8, regina::PACKET_ANGLESTRUCTURES = 9,
regina::PACKET_ANGLESTRUCTURELIST = 9, regina::PACKET_PDF = 10, regina::PACKET_DIM4TRIANGULATION = 11, regina::PACKET_NORMALHYPERSURFACES = 13,
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

Packet * | regina::open (const char *filename)
| Reads a Regina data file, and returns the corresponding packet tree. More...
Packet * | regina::open (std::istream &in)
| Reads a Regina data file from the given input stream, and returns the corresponding packet tree. More...
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; \
inline virtual PacketType type() const { \
return id; \
} \
inline virtual std::string typeName() const { \
return PacketInfo<id>::name(); \
}
regina::PacketType
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 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().

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 Packet.
  id | the corresponding PacketType constant.

## REGINA_PACKET_FROM

#define REGINA_PACKET_FROM | ( |  | class_,
|  |  | helper
| ) |  |

Value:
public: \
static constexpr const PacketType typeID = helper::typeID; \
inline virtual PacketType type() const { \
return helper::typeID; \
} \
inline virtual std::string typeName() const { \
return helper::name(); \
}
regina::PacketType
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 Packet, and in return it provides the same constants, types and virtual functions that REGINA_PACKET does. However, unlike REGINA_PACKET, it does not rely on PacketInfo for its implementation. Instead it calls upon the given class helper, which must provide:

- 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 Packet.
  helper | the helper class that provides the implementation details, as described above.

## Typedef Documentation

## NContainer

typedef Container regina::NContainer

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NContainer has now been renamed to Container.

## NPacket

typedef Packet regina::NPacket

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NPacket has now been renamed to Packet.

## NPacketListener

typedef PacketListener regina::NPacketListener

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NPacketListener has now been renamed to PacketListener.

## NPDF

typedef PDF regina::NPDF

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NPDF has now been renamed to PDF.

## NScript

typedef Script regina::NScript

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NScript has now been renamed to Script.

## NText

typedef Text regina::NText

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NText has now been renamed to Text.

## 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_CONTAINER | Represents a container packet, of class Container.
PACKET_TEXT | Represents a text packet, of class Text.

PACKET_TRIANGULATION

Deprecated alias for PACKET_TRIANGULATION3.

Deprecated:
  This constant has been renamed to PACKET_TRIANGULATION3.

PACKET_NORMALSURFACES | Represents a normal surface list, of class NormalSurfaces.

PACKET_NORMALSURFACELIST

Deprecated alias for PACKET_NORMALSURFACES.

Deprecated:
  This constant has been renamed to PACKET_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_ANGLESTRUCTURELIST

Deprecated alias for PACKET_ANGLESTRUCTURES.

Deprecated:
  This constant has been renamed to PACKET_ANGLESTRUCTURES.

PACKET_PDF | Represents a PDF document, of class PDF.

PACKET_DIM4TRIANGULATION

Deprecated alias for PACKET_TRIANGULATION4.

Deprecated:
  This constant has been renamed to PACKET_TRIANGULATION4.

PACKET_NORMALHYPERSURFACES | Represents a normal hypersurface list, of class NormalHypersurfaces.

PACKET_NORMALHYPERSURFACELIST

Deprecated alias for PACKET_NORMALHYPERSURFACES.

Deprecated:
  This constant has been renamed to PACKET_NORMALHYPERSURFACES.

PACKET_DIM2TRIANGULATION

Deprecated alias for PACKET_TRIANGULATION2.

Deprecated:
  This constant has been renamed to PACKET_TRIANGULATION2.

PACKET_SNAPPEATRIANGULATION | Represents a triangulation in the embedded SnapPea kernel, of class SnapPeaTriangulation.
PACKET_TRIANGULATION2 | Represents a 2-dimensional triangulation, of class Triangulation<2>.
PACKET_TRIANGULATION3 | Represents a 3-dimensional triangulation, of class Triangulation<3>.
PACKET_TRIANGULATION4 | Represents a 4-dimensional triangulation, of class Triangulation<4>.
PACKET_TRIANGULATION5 | Represents a 5-dimensional triangulation, of class Triangulation<5>.
PACKET_TRIANGULATION6 | Represents a 6-dimensional triangulation, of class Triangulation<6>.
PACKET_TRIANGULATION7 | Represents a 7-dimensional triangulation, of class Triangulation<7>.
PACKET_TRIANGULATION8 | Represents a 8-dimensional triangulation, of class Triangulation<8>.
PACKET_TRIANGULATION9 | Represents a 9-dimensional triangulation, of class Triangulation<9>.
PACKET_TRIANGULATION10 | Represents a 10-dimensional triangulation, of class Triangulation<10>.
PACKET_TRIANGULATION11 | Represents a 11-dimensional triangulation, of class Triangulation<11>.
PACKET_TRIANGULATION12 | Represents a 12-dimensional triangulation, of class Triangulation<12>.
PACKET_TRIANGULATION13 | Represents a 13-dimensional triangulation, of class Triangulation<13>.
PACKET_TRIANGULATION14 | Represents a 14-dimensional triangulation, of class Triangulation<14>.
PACKET_TRIANGULATION15 | Represents a 15-dimensional triangulation, of class Triangulation<15>.

## 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

  packetType | the given packet type.
  func | the function object whose bracket operator we will call with a PacketInfo<packetType> object.
  defaultReturn | the value to return if the given packet type is not valid.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

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

  packetType | the given packet type.
  func | the function object whose bracket operator we will call with a PacketInfo<packetType> object.
  args | any additional arguments to pass to the bracket operator for func. These will be copied/moved, so if you wish to pass references then you may need to wrap them in std::ref or std::cref.

Returns
  nothing; the return type `ReturnsTraits<FunctionObject>::Void` simply evaluates to `void`.

## open() [1/2]

Packet* regina::open | ( | const char * | filename | ) |

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

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

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

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

  filename | the pathname of the file to read from.

Returns
  the packet tree read from file, or 0 on error (as explained above).

## open() [2/2]

Packet* regina::open | ( | std::istream & | in | ) |

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

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

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

Precondition
  The given stream is open for reading.

Python:
  Not present.

Parameters

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