Class: TInstanceOf

Declaration: SafePointers.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPointerTo.

Inherited By:

None.

Purpose:

Contains a pointer to an object, and owns that object. Copying a TInstanceOf also copies the object (if any) to which it points. Destroying a TInstanceOf destroys the object (if any) to which it points. Like all classes derived from TPointerTo, it can be dereferenced (operator * or operator ->) like a regular pointer; but if it contains NIL (0), dereferencing it throws an exception.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

You should not derive any classes from TInstanceOf.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

TInstanceOf can only point to a class whose destructor is public, and which is copyable; that is, there must be a global function CopyPointer(AType*).

Member Function: TInstanceOf::TInstanceOf

TInstanceOf (AType * adopt =NIL)
TInstanceOf (const TInstanceOf < AType > & copy)
TInstanceOf (const TInstanceOf < AType > & copy, TMemoryHeap & whereToCreate)

Interface Category:

API.

Purpose:

Adopts the object (if any) specified. The object is not copied. Use this constructor with care: constructing multiple TInstanceOf objects from the same AType* usually leads to attempting to delete that pointer repeatedly (which is erroneous).
Copies the object (if any) to which the TInstanceOf points, and adopts the copy.
Copies the object (if any) to which the TInstanceOf points into the specified heap, and adopts the copy.

Calling Context:

Call this function directly to initialize this TInstanceOf.
Call this function directly to copy a TInstanceOf.
Call this function directly to copy a TInstanceOf.

Parameters:

AType * adopt =NIL -The object to adopt.
const TInstanceOf < AType > & copy -The TInstanceOf whose adopted object is to be copied.
const TInstanceOf < AType > & copy -The TInstanceOf whose adopted object is to be copied.
TMemoryHeap & whereToCreate -The heap from which to allocate storage for the copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInstanceOf::~TInstanceOf

~ TInstanceOf ()

Interface Category:

API.

Purpose:

Destructor which destroys both the adopted object and this object.

Calling Context:

Call this function directly to destroy both this object and the object it wraps.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInstanceOf::operator=

TInstanceOf < AType > & operator =(AType * adopt)
TInstanceOf < AType > & operator =(const TInstanceOf < AType > & copy)

Interface Category:

API.

Purpose:

Adopts the object specified, and destroys the previously adopted object (if any).
Copies the object (if any) to which the parameter points, adopts the copy, and destroys the previously adopted object (if any).

Calling Context:

Call this function directly to adopt an object.
Call this function directly to copy an object.

Parameters:

AType * adopt -The object to adopt.
const TInstanceOf < AType > & copy -The TInstanceOf whose adopted object is to be copied.

Return Value:

A reference to this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInstanceOf::operator==

bool operator ==(const AType * r) const
bool operator ==(const TInstanceOf < AType > & r) const

Interface Category:

API.

Purpose:

Compare pointers for equality.

Calling Context:

Call this function directly to determine if two pointers are identical.

Parameters:

const AType * r -The pointer to be compared with pointer wrapped by this TInstanceOf.
const TInstanceOf < AType > & r -The TInstanceOf to be compared with this TInstanceOf.

Return Value:

Returns true if this object and the parameter both point to the same object, or if both contain NIL.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

true will also be returned if both pointers are NIL.

Member Function: TInstanceOf::operator!=

bool operator != (const AType * r) const
bool operator != (const TInstanceOf < AType > & r) const

Interface Category:

API.

Purpose:

Compare pointers for inequality.

Calling Context:

Call this function directly to determine if two pointers are different.

Parameters:

const AType * r -The pointer to be compared with the pointer wrapped by this TInstanceOf.
const TInstanceOf < AType > & r -The TInstanceOf to be compared with this TInstanceOf.

Return Value:

Returns true if this object and the parameter point to different objects, or if one but not both contain NIL.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInstanceOf::Orphan

AType * Orphan ()

Interface Category:

API.

Purpose:

Returns a copy of the pointer contained in this object, and changes this object to contain NIL. The object (if any) to which this object pointed is not affected.

Calling Context:

Call this function directly to release a adopted object.

Parameters:

Takes no parameters.

Return Value:

A copy of the pointer that was contained in this object.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.