The Simons     Component Library

           

---

ObjectID Class Reference

#include <ObjectID.h>

Inheritance diagram for ObjectID:

List of all members.

---

Detailed Description

ObjectID: a typed reference to an Object.

ObjectID is a strongly typed, reference counting pointer that refers to an Object. ObjectID variables may be initialised to Object* objects and all subtypes. ObjectID variables may alias objects held by other ObjectID variables, or any subtype. When an ObjectID acquires an object, it increments the object's reference count. When an ObjectID releases an object, it decrements the object's reference count. If the reference count reaches zero, the object is automatically deleted.

ObjectID is the root of the pointer hierarchy. It defines in one place all the basic behaviour of reference counted memory management. All other typed pointers inherit from ObjectID, providing trivial inlined methods which call ObjectID methods. The pointer types are provided by subclassing, rather than by a template class, so that automatic type upcasting may promote a pointer type up to a pointer supertype. Type downcasting is achieved through toType() and tryType(). These both convert their pointer-argument to a more specific type, provided the dynamic type of the contained object is at least as specific. Upon failure, toType() raises an exception, while tryType() returns a null pointer.

Public Member Functions
	ObjectID ()
	Declare an ObjectID.
	~ObjectID ()
	Release an ObjectID.
	ObjectID (const Null *)
	Initialise an ObjectID explicitly to null.
	ObjectID (const Object *)
	Initialise an ObjectID to refer to an object.
	ObjectID (const ObjectID &)
	Initialise an ObjectID to alias another ObjectID.
ObjectID &	operator= (const Object *)
	Reassign this ObjectID to refer to an Object.
ObjectID &	operator= (const ObjectID &)
	Reassign this ObjectID to alias another ObjectID.
Object *	operator-> () const
	Invoke a method on this ObjectID variable.
const Object *	pointer () const
	Return the encapsulated pointer.
Protected Member Functions
Void	assign (const Object *)
	Reassign this ObjectID to refer to an object.
Void	assign (const ObjectID &)
	Reassign this ObjectID to alias another ObjectID.
Void	nullPointer (ObjectID) const
	Report a failed pointer dereference.
Void	typeFailure (ObjectID) const
	Report a failed type conversion attempt.
Protected Attributes
Object *	basicPointer
	The encapsulated primitive pointer.
Friends
bool	operator== (const ObjectID &, const ObjectID &)
	Compare two ObjectIDs for identity of reference.
bool	operator!= (const ObjectID &, const ObjectID &)
	Compare two ObjectIDs for non-identity of reference.
template<class T> T *	toType (const ObjectID &)
	Perform a guaranteed dynamic type conversion.
template<class T> T *	tryType (const ObjectID &)
	Perform a tentative dynamic type conversion.

---

Constructor & Destructor Documentation

ObjectID::ObjectID (   )

Declare an ObjectID. Returns: a null ObjectID.

ObjectID::~ObjectID (   )

Release an ObjectID.

ObjectID::ObjectID (  const Null *  null  )

Initialise an ObjectID explicitly to null. Parameters: null  - the null value. Returns: an ObjectID referring to null.

ObjectID::ObjectID (  const Object *  object  )

Initialise an ObjectID to refer to an object. Parameters: object  - the object. Returns: an ObjectID referring to the object.

ObjectID::ObjectID (  const ObjectID &  pointer  )

Initialise an ObjectID to alias another ObjectID. Parameters: pointer  - the other ObjectID. Returns: an ObjectID referring to the same object as the other ObjectID.

---

Member Function Documentation

Void ObjectID::assign (  const ObjectID &  pointer  )  [protected]

Reassign this ObjectID to alias another ObjectID. Parameters: pointer  - the other ObjectID. Returns: an ObjectID referring to the same object as the other ObjectID.

Void ObjectID::assign (  const Object *  object  )  [protected]

Reassign this ObjectID to refer to an object. Parameters: object  - the object. Returns: an ObjectID referring to the object.

Void ObjectID::nullPointer (  ObjectID  exemplar  )  const [protected]

Report a failed pointer dereference. Raise a NullPointer exception, using the exemplar Object as an indicator of the expected Type. Parameters: exemplar  - an exemplar Object of the expected Type.

Object * ObjectID::operator-> (   )  const

Invoke a method on this ObjectID variable. Returns: the result of the method. Reimplemented in BagID, CGIReaderID, CollectionID, DataErrorID, DeviceBusyID, DeviceErrorID, EntryID, ExceptionID, FileStreamID, FormatStreamID, InputID, ListID, MapID, MethodErrorID, NoElementsID, NoResponseID, NotFoundID, NullPointerID, ObjectErrorID, OutOfRangeID, OutputID, ReaderID, ReadFailureID, RelationID, SequenceID, SetID, StreamID, StringID, TextInputID, TextOutputID, TypeFailureID, TypeID, UndefinedID, UnorderedID, ValueID, VectorID, WebOutputID, WriteFailureID, WriterID, XMLReaderID, and XMLWriterID.

ObjectID & ObjectID::operator= (  const ObjectID &  pointer  )  [inline]

Reassign this ObjectID to alias another ObjectID. Parameters: pointer  - the other ObjectID. Returns: an ObjectID referring to the same Object as the other ObjectID.

ObjectID & ObjectID::operator= (  const Object *  object  )  [inline]

Reassign this ObjectID to refer to an Object. Parameters: object  - the Object. Returns: an ObjectID referring to the Object.

const Object * ObjectID::pointer (   )  const [inline]

Return the encapsulated pointer. Returns: the encapsulated pointer.

Void ObjectID::typeFailure (  ObjectID  exemplar  )  const [protected]

Report a failed type conversion attempt. Raise a TypeFailure exception, using the exemplar Object as an indicator of the expected Type. Parameters: exemplar  - an exemplar Object of the expected Type.

---

Friends And Related Function Documentation

bool operator!= (  const ObjectID &  first, const ObjectID &  second )  [friend]

Compare two ObjectIDs for non-identity of reference.

bool operator== (  const ObjectID &  first, const ObjectID &  second )  [friend]

Compare two ObjectIDs for identity of reference.

template<class T> T* toType (  const ObjectID &  pointer  )  [friend]

Perform a guaranteed dynamic type conversion.   SpecificID specific = toType<Specific>(general); Retrieves an object of some specific type T from a smart pointer of some more general type, expecting the conversion to succeed. Typically used in guaranteed type downcasting, where the anticipated result type is known and expected. Upon success, returns a primitive T* object pointer. Upon failure, raises a TypeFailure exception, since a guaranteed result was expected. Parameters: pointer  - a smart pointer of some general type. Returns: a primitive object pointer of some specific type.

template<class T> T* tryType (  const ObjectID &  pointer  )  [friend]

Perform a tentative dynamic type conversion.   SpecificID specific = tryType<Specific>(general); Retrieves an object of some specific type T from a smart pointer of some more general type, anticipating success or failure equally. Typically used in tentative type downcasting, where the anticipated result type is not known and not necessarily expected. Upon success, returns a primitive T* object pointer. Upon failure, returns 0, which allows the result to be tested directly inside if(...) statements. Generally, the result is assigned to a smart pointer, which will contain the object upon success and null upon failure. The result of this conversion should be checked in the program. Parameters: pointer  - a smart pointer of some general type. Returns: a primitive object pointer of some specific type.

---

Member Data Documentation

Object* ObjectID::basicPointer [protected]

The encapsulated primitive pointer.

---

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

• ObjectID.h
• Basic.cc
• Object.cc
• Object.h

---