ICountedPointerTo

Creates a templatized smart pointer with automatic reference counting. ICountedPointerTo provides a smart C++ like pointer with this additional built-in behavior: when you create an instance of ICountedPointerTo, it automatically calls IMRefCounted::addRef on the object pointed to; when the ICountedPointerTo is destroyed, it calls IMRefCounted::removeRef to removes its reference to the object.

ICountedPointerTo also allows you to perform reference counting on objects that do not descend from IMRefCounted. In this case, it encloses, or wraps, the object in a reference-counted wrapper.


ICountedPointerTo - Member Functions and Data by Group

Constructors & Destructor

Use these functions to construct, copy, and destruct counted pointer objects.


[view class]
~ICountedPointerTo
Destroys the counted pointer.
public:
~ICountedPointerTo()
This destructor destroys the counted pointer and decrements the reference count of the object pointed to. When the count is zero, the object is deleted.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ICountedPointerTo
This function constructs an object of class ICountedPointerTo.


Overload 1
Copies a counted pointer.
public:
ICountedPointerTo(const ICountedPointerTo < AType >& share)
Use this constructor to create a copy of the given counted pointer. The constructor increments the reference count of the object pointed to by the given counted pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Construct a counted pointer object.
public:
ICountedPointerTo()
Use this function to construct an object that points to nothing. This function is slightly more efficient than calling ICountedPointerTo(0).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Constructs an ICountedPointerTo that points to the given object.
public:
ICountedPointerTo(AType* adopt)
Use this constructor to create an object of class ICountedPointerTo that points to the object specified by the adopt parameter. This constructor adopts the given object and increments its reference count. Use the newly constructed instance of ICountedPointer to make any further references to the object pointed to. Discard the raw pointer used to specify the adopted object. constructor.

adopt
A pointer to the object to be pointed to from the constructed object of class ICountedPointerTo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Accessing an Object

Use these functions to access the pointer being counted.


[view class]
getAlias
Returns a raw C++ pointer to the object to which this points.
public:
AType* getAlias() const
This function returns a raw C++ pointer to the object to which this points.

If this pointer does not refer to an object, the function returns zero.

Use this function to pass a raw C++ pointer to an existing function that expects one. Do not continue to use the pointer after this ICountedPointerTo object has been destroyed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator *
Returns a reference to the object pointed to.
public:
AType& operator *() const
This operator returns a reference to the object referred to by the counted pointer.

Exception

IInvalidRequest Thrown when your code attempts to dereference a null pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ->
Returns the object pointed to.
public:
AType* operator ->() const
This operator is called when you use a counted pointer with the C++ class member access operator ->.

Exception

An

IInvalidRequest exception is thrown when your code attempts to dereference a null pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Changing the Object Pointed to

Use these functions to point this counted pointer object at another object.


[view class]
operator =
This operator modifies the counted pointer so that it refers to a different object from the one it currently points to.


Overload 1
Changes the object pointed to.
public:
ICountedPointerTo < AType >& operator =( const ICountedPointerTo < AType >& share )

Use this operator to modify the counted pointer so that it refers to the same object as another counted pointer. If the object the pointer previously referred to was a valid object, that object's reference count is decremented. When the count is zero, that object is deleted.

share
A counted pointer to the new target object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Changes the object pointed to.
public:
ICountedPointerTo < AType >& operator =(AType* adopt)
Use this operator to modify the counted pointer so that it refers to the given object to be adopted. If the object the pointer previously referred to was a valid object, that object's reference count is decremented. The object is deleted when its reference count is zero.

The function adopts the given object and increments its reference count. Make all further references to the given object through this ICountedPointer object. Discard the raw pointer used to specify the adopted object.

adopt
The object to be pointed to. The operator assigns the adopted object to the instance of ICountedPointerTo and increments the object's reference count.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparing and Testing the Pointer

Use these functions to determine whether this object points to a particular object or the same object that another counted pointer object also points to, and whether the pointer is valid or not.


[view class]
operator !=
This function determines whether the counted pointer refers to a particular object.


Overload 1
Determines whether this pointer refers to the given object.
public:
bool operator !=(const AType* r) const
Use this function to determine if this counted pointer refers to the given object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Determines whether this pointer refers to the same object as another counted pointer.
public:
bool operator !=( const ICountedPointerTo < AType >& r ) const
Use this function to determine if this counted pointer refers to the same object as another counted pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
This operator determines whether this pointer refers to a particular object.


Overload 1
Determines whether this pointer refers to the same object as another counted pointer.
public:
bool operator ==( const ICountedPointerTo < AType >& r ) const
Use this operator to determine if this counted pointer refers to the same object as another counted pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Determines whether this pointer refers to the given object.
public:
bool operator ==(const AType* r) const
Use this function to determine if this counted pointer refers to the given object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
valid
Queries whether this counted pointer refers to a valid object.
public:
bool valid() const
This function returns true if this counted pointer refers to a valid, non-null object. Otherwise it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
validate
Asserts that this pointer refers to a valid object.
public:
void validate() const
This function asserts that this counted pointer refers to a valid object. If it does not, the function throws an exception.

Exception

IInvalidRequest This pointer does not refer to a valid object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Obtaining and Counting Object References

Use these methods to manage the reference count of an object.


[view class]
count
Returns the current reference count.
public:
unsigned long count() const
This function returns the reference count of the object to which this counted pointer refers. If this counted pointer does not refer to a valid object, it returns zero.

Note that when the counted pointer refers to an object that does not inherit from IMRefCounted, this function returns the reference count of the internal wrapper around that object

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICountedPointerTo - Inherited Member Functions and Data

Inherited Public Functions

IMStreamable
ICountedPointerTo

Inherited Public Data

Inherited Protected Functions

IMStreamable

Inherited Protected Data