Regina 7.4 Calculation Engine
regina::PacketData< Held > Class Template Reference

A lightweight helper class that allows an object of type Held to connect with the wrapped packet class that contains it. More...

#include <packet/packet.h>

Classes

class  PacketChangeSpan
 An object that facilitates firing packetToBeChanged() and packetWasChanged() events. More...
 

Public Types

using PacketChangeGroup = PacketChangeSpan
 A type alias for PacketChangeSpan, used when a span is being used purely for optimisation purposes.
 

Public Member Functions

 PacketData ()=default
 Default constructor that sets heldBy_ to PacketHeldBy::None.
 
 PacketData (const PacketData &) noexcept
 Copy constructor that ignores its argument, and instead sets heldBy_ to PacketHeldBy::None.
 
PacketDataoperator= (const PacketData &)
 Assignment operator that ignores its argument and does nothing.
 
std::shared_ptr< PacketOf< Held > > packet ()
 Returns the packet that holds this data, if there is one.
 
std::shared_ptr< const PacketOf< Held > > packet () const
 Returns the packet that holds this data, if there is one.
 
std::string anonID () const
 A unique string ID that can be used in place of a packet ID.
 

Protected Attributes

PacketHeldBy heldBy_ { PacketHeldBy::None }
 Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>.
 

Friends

class PacketOf< Held >
 

Detailed Description

template<typename Held>
class regina::PacketData< Held >

A lightweight helper class that allows an object of type Held to connect with the wrapped packet class that contains it.

For every wrapped packet type of the form PacketOf<Held>, the corresponding class Held must derive from PacketData<Held>. See the Packet class notes for more information about packets, and for what else must be implemented for each wrapped packet type.

This base class is extremely lightweight: the only data that it contains is a single PacketHeldBy enumeration value. All of the class constructors set this value to PacketHeldBy::None; it is the responsibility of subclasses (e.g., PacketOf<Held>) to change this where necessary.

Python
Not present, but the routines anonID() and packet() will be provided directly through the various subclasses.

Member Typedef Documentation

◆ PacketChangeGroup

template<typename Held >
using regina::PacketData< Held >::PacketChangeGroup = PacketChangeSpan

A type alias for PacketChangeSpan, used when a span is being used purely for optimisation purposes.

This type alias is used in the same way as Packet::PacketChangeGroup: it is purely for the benefit of the human reader, used to indicate that an event span is present purely for optimisation (and in particular, that the code would still be correct without it).

See Packet::PacketChangeGroup for further details.

Constructor & Destructor Documentation

◆ PacketData() [1/2]

template<typename Held >
regina::PacketData< Held >::PacketData ( )
default

Default constructor that sets heldBy_ to PacketHeldBy::None.

◆ PacketData() [2/2]

template<typename Held >
regina::PacketData< Held >::PacketData ( const PacketData< Held > & )
inlinenoexcept

Copy constructor that ignores its argument, and instead sets heldBy_ to PacketHeldBy::None.

This is because heldBy_ stores information about the C++ type of this object, not the object being copied.

This constructor is provided so that Held can (if it wants) use an implicitly-declared copy or move constructor.

Member Function Documentation

◆ anonID()

template<typename Held >
std::string regina::PacketData< Held >::anonID ( ) const

A unique string ID that can be used in place of a packet ID.

This is an alternative to Packet::internalID(), and is designed for use when Held is not actually wrapped by a PacketOf<Held>. (An example of such a scenario is when a normal surface list needs to write its triangulation to file, but the triangulation is a standalone object that is not stored in a packet.)

The ID that is returned will:

  • remain fixed throughout the lifetime of the program for a given object, even if the contents of the object are changed;
  • not clash with the anonID() returned from any other object, or with the internalID() returned from any packet of any type;

These IDs are not preserved when copying or moving one object to another, and are not preserved when writing to a Regina data file and then reloading the file contents.

Warning
If this object is wrapped in a PacketOf<Held>, then anonID() and Packet::internalID() may return different values.

See Packet::internalID() for further details.

Returns
a unique ID that identifies this object.

◆ operator=()

template<typename Held >
PacketData & regina::PacketData< Held >::operator= ( const PacketData< Held > & )
inline

Assignment operator that ignores its argument and does nothing.

This is because heldBy_ stores information about the C++ type of this object, not the object being copied.

This operator is provided so that Held can (if it wants) use an implicitly-declared copy or move assignment operator.

Returns
a reference to this object.

◆ packet() [1/2]

template<typename Held >
std::shared_ptr< PacketOf< Held > > regina::PacketData< Held >::packet ( )
inline

Returns the packet that holds this data, if there is one.

If this object is being held by a packet p of type PacketOf<Held>, then that packet p will be returned. Otherwise, if this is a "standalone" object of type Held, then this routine will return null.

There is a special case when dealing with a packet q that holds a SnapPea triangulation. Here q is of type PacketOf<SnapPeaTriangulation>, and it holds a Triangulation<3> "indirectly" in the sense that Packetof<SnapPeaTriangulation> derives from SnapPeaTriangulation, which in turn derives from Triangulation<3>. In this scenario:

  • calling Triangulation<3>::packet() will return null, since there is no "direct" PacketOf<Triangulation<3>>;
  • calling SnapPeaTriangulation::packet() will return the enclosing packet q, since there is a PacketOf<SnapPeaTriangulation>;
  • calling the special routine Triangulation<3>::inAnyPacket() will also return the "indirect" enclosing packet q.

The function inAnyPacket() is specific to Triangulation<3>, and is not offered for other Held types.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

◆ packet() [2/2]

template<typename Held >
std::shared_ptr< const PacketOf< Held > > regina::PacketData< Held >::packet ( ) const
inline

Returns the packet that holds this data, if there is one.

See the non-const version of this function for further details, and in particular for how this functions operations in the special case of a packet that holds a SnapPea triangulation.

Returns
the packet that holds this data, or null if this data is not (directly) held by a packet.

Member Data Documentation

◆ heldBy_

template<typename Held >
PacketHeldBy regina::PacketData< Held >::heldBy_ { PacketHeldBy::None }
protected

Indicates whether this Held object is in fact the inherited data for a PacketOf<Held>.

As a special case, this field is also used to indicate when a Triangulation<3> is in fact the inherited data for a SnapPeaTriangulation. See the PacketHeldBy enumeration for more details on the different values that this data member can take.


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