A note on the behavior of art::Ptr
¶
The class template Ptr<T>
, which being a variety of "smart pointer", has more states than is common for pointer-like types. This is a result of the fact that it represents a persistent pointer to an object contained within a "container" in an (e.g.) Event
. To understand the available states, it is best to think of the Ptr<T>
object as containing:
- an identifier of the "container" into which it refers [this is the role of the
ProductID
], and - an identifier of which object of type
T
in that "container" is referenced by the pointer [this is the role of the "key"].
The Ptr<T>
class template also has transient data members which can be ignored for this discussion.
The permissible states of instances of Ptr<T>
are:
- Default constructed: No valid
ProductID
, no valid offset. Such aPtr
does not reference any product. - Constructed with a valid
ProductID
, but with no valid key. Such aPtr
is intended to be used as a "null pointer", indicating that there was no object in the collection for thisPtr
to reference. - Constructed with a valid
ProductID
and a valid key. Such aPtr
references the object of typeT
identified by the key in the "container" with the givenProductID
.
An instance of Ptr<T>
that is in state 3 might be in a state that can be dereferenced, but it might not be. If the product which is "pointed into" by the pointer is not present in the data (perhaps because one is reading a file to which that product was not written), the Ptr<T>
can not be dereferenced.
The above information, including the results of various different ways to interrogate the state, can be summarized in the table below:
Valid ProductID | Valid offset | isNull() | isAvailable() | explicit operator bool() | Comment |
---|---|---|---|---|---|
Y | Y | F | T/F | T/F | Variable answers depend on whether product is resolvable. |
Y | N | T | T/F | F | Variable answer depends on whether product is resolvable. |
N | N | F | F | F | Only possible through default constructor. |
Note that the unlisted combination with an invalid ProductID
but valid offset is not a possible state of Ptr
. In the event that someone calls the constructor of Ptr
taking a Handle
argument where the Handle
does not have a valid ProductID
, an exception will be thrown regardless of the validity of the provided offset.