WDSS-IIw2: code::SmartPtr< X > Class Template Reference

The STL's auto_ptr ( in <memory> ) has destructive copy semantics. This means that if you copy two auto_ptr's and delete the second, the first one is left dangling. Such an auto_ptr has its uses but those uses don't include being able to store your objects in containers.

SmartPtr implements a different philosophy. In this case, a copy of a SmartPtr will increase the number of references to two. The object is deleted only when all references to it vanish.

Note that SmartPtr expects that the pointer you are handing it has been allocated with new; it won't work for arrays allocated with new[] or for objects that have been malloc'ed.


Public Member Functions
	SmartPtr (X *p=0)
	Hand a pointer over to be reference-counted and maintained.
bool	is_unique () const
	Is the pointed-to-object unique?
int	copies () const
	Returns number of references to this SmartPtr.
bool	is_ptr_valid () const
	Is the pointer that we are holding valid?
	SmartPtr (const SmartPtr< X > &orig)
	Copy constructor.
SmartPtr< const X >	const_ptr () const
	Will return a reference-counted pointer to const X, so that functions that promise not to change the object can ask for, and receive, SmartPtr<const X>.
SmartPtr &	operator= (const SmartPtr< X > &orig)
bool	operator< (const SmartPtr< X > &other) const
	To enable easy mapping of SmartPtrs of ordered objects to STL containers, the < operator is overloaded to compare the objects being pointed to.
bool	operator== (const SmartPtr< X > &other) const
	To enable easy mapping of SmartPtrs of ordered objects to STL containers, the == operator is overloaded to compare the objects being pointed to.
bool	is_stored_before (const SmartPtr< X > &other) const
	In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances.
	~SmartPtr ()
	Delete handed in pointer (using delete ) when the last SmartPtr that holds the pointer is destroyed.
X &	operator * () const
	Use like a regular pointer; Asserts that the pointer is not null.
X *	operator-> () const
	Use like a regular pointer; Asserts that the pointer is not null.
	SmartPtr (X p, int n)
	Copy constructor out of the internal data of an already existing ptr.
template<class D>
SmartPtr< D >	recast ()
	Recast this SmartPtr to the desired type.
template<class D>
SmartPtr< const D >	recast () const
Public Attributes
X *	ptr
	Internal pointer storage.
int *	numCopies
	Internal number of copies storage.

Constructor & Destructor Documentation

template<class X>

code::SmartPtr< X >::SmartPtr ( X * p = 0 ) [inline]

Hand a pointer over to be reference-counted and maintained.

Note that SmartPtr expects that the pointer you are handing it has been allocated with "new". When the last copy of SmartPtr that points to this object is deleted, this object is also deleted. Make sure that no more than one SmartPtr handles a pointer.

template<class X>

code::SmartPtr< X >::SmartPtr ( const SmartPtr< X > & orig ) [inline]

Copy constructor.

Is not destructive; simply does reference counting.

template<class X>

code::SmartPtr< X >::~SmartPtr ( ) [inline]

Delete handed in pointer (using delete ) when the last SmartPtr that holds the pointer is destroyed.

template<class X>

code::SmartPtr< X >::SmartPtr	(	X *	p,
		int *	n
	)			`[inline]`

Copy constructor out of the internal data of an already existing ptr.

Member Function Documentation

template<class X>

SmartPtr<const X> code::SmartPtr< X >::const_ptr ( ) const [inline]

Will return a reference-counted pointer to const X, so that functions that promise not to change the object can ask for, and receive, SmartPtr<const X>.

template<class X>

int code::SmartPtr< X >::copies ( ) const [inline]

Returns number of references to this SmartPtr.

template<class X>

bool code::SmartPtr< X >::is_ptr_valid ( ) const [inline]

Is the pointer that we are holding valid?

Note that this is a test only on whether the pointer is valid. There is no test of whether the object is valid; Usually objects that require initialization, etc. will have a isValid() member function. To prevent typographical errors, the name of this function is different. Just because the pointer is valid doesn't mean that the object is valid.

Use this function to check the return value from a function that promises to return a SmartPtr to something. The SmartPtr will hold an invalid pointer on error.

Returns:: true if pointer is valid (no error) and false if the pointer is invalid (error).

template<class X>

bool code::SmartPtr< X >::is_stored_before ( const SmartPtr< X > & other ) const [inline]

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances.

In that case, pointers need to be compared using is_stored_before()

When the objects themselves are ordered, you should be using the < operator.

template<class X>

bool code::SmartPtr< X >::is_unique ( ) const [inline]

Is the pointed-to-object unique?

You can use this function to determine whether there is anybody else holding references to this object.

Returns:: true if the pointed-to-object is unique and false if there are one or more other modules/classes holding references to this object.

template<class X>

X& code::SmartPtr< X >::operator * ( ) const [inline]

Use like a regular pointer; Asserts that the pointer is not null.

template<class X>

X* code::SmartPtr< X >::operator-> ( ) const [inline]

Use like a regular pointer; Asserts that the pointer is not null.

template<class X>

bool code::SmartPtr< X >::operator< ( const SmartPtr< X > & other ) const [inline]

To enable easy mapping of SmartPtrs of ordered objects to STL containers, the < operator is overloaded to compare the objects being pointed to.

Hence, for this to be usable, the class X should have a < operator defined.

The behavior of the < and == operators is as follows:

when neither pointer is valid, == would return true.
when only one pointer is valid, the invalid pointer is always less than the valid pointer.
when both pointers are valid, the objects pointed to are compared.

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances. In that case, pointers need to be compared. Use is_stored_before()

template<class X>

SmartPtr& code::SmartPtr< X >::operator= ( const SmartPtr< X > & orig ) [inline]

See also:: copy constructor.

template<class X>

bool code::SmartPtr< X >::operator== ( const SmartPtr< X > & other ) const [inline]

To enable easy mapping of SmartPtrs of ordered objects to STL containers, the == operator is overloaded to compare the objects being pointed to.

Hence, for this to be usable, the class X should have a == operator defined.

The behavior of the < and == operators is as follows:

when neither pointer is valid, == would return true.
when only one pointer is valid, the invalid pointer is always less than the valid pointer.
when both pointers are valid, the objects pointed to are compared.

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances. In that case, pointers need to be compared. Use is_stored_before()

template<class X>

template<class D>

SmartPtr<const D> code::SmartPtr< X >::recast ( ) const [inline]

template<class X>

template<class D>

SmartPtr<D> code::SmartPtr< X >::recast ( ) [inline]

Recast this SmartPtr to the desired type.

An empty SmartPtr is returned if type conversion fails.

class A { ... }; class B: public A { ... }; class C: public B { ... }; class Unrelated { ... };

SmartPtr b = new C (); SmartPtr a = b.recast<A>(); // upcast SmartPtr<C> c = b.recast<C>(); // downcast assert (a.copies() == 3);

SmartPtr<Unrelated> u = b.recast<Unrelated>(); assert (!u.is_ptr_valid()); assert (a.copies() == 3);

code::SmartPtr< X > Class Template Reference

Detailed Description

template<class X>
class code::SmartPtr< X >

Public Member Functions

Public Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

code::SmartPtr< X > Class Template Reference

Detailed Description

template<class X> class code::SmartPtr< X >

Public Member Functions

Public Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class X>
class code::SmartPtr< X >