Another common problem is a memory leak caused by failing to delete an object when the pointer to it goes out of scope. C++ exceptions introduce a similar problem, because a thrown exception may by-pass the code that deletes a pointer. So I also present the template class HeapPtr, which solves both problems.

Objects of the CheckedPtr class, and its descendant CheckedClassPtr, work like pointers to a typed object. You can use a CheckedPtr object in place of a normal typed pointer in an expression. The template class CheckedPtr defines operators that behave the same way as do the built-in operators for typed pointers.

You use the template class CheckedClassPtr to describe an object that can represent a pointer to an object of some other type. The template class CheckedClassPtr is necessary because of the rules for the member access operator. I discuss this problem later in this article. These template classes support only representations of pointer to object types. They do not support representations of pointers to void, pointers to functions, or pointers to references. The limitation is imposed because pointer arithmetic works only on pointers to objects. For instance, it is an error to use the expression p++ where p is a pointer to void or a function pointer. It is not possible to declare a pointer to a reference.

The template class CheckedPtr uses C++ exceptions to signal errors. To field exceptions, you place any code that may cause an exception within a try block. When the code in a try block throws an exception, control flow continues at the nearest matching catch block associated with the try block. But first, the exception mechanism calls the destructors for any automatic objects that go out of scope.

The template class CheckedPtr employs three exception classes derived from the class xCheckedPtr, which is in turn derived from xmsg, the generic exception class defined by the C++ standard header file except. h. The CheckedPtr class may throw three possible exceptions:

• xnullptr for a dereferenced null pointer
• xoutofrange for accesses outside the range of an array to which a CheckedPtr object is limited
• xnotsamebase for pointer arithmetic with pointers that do not refer to the same array.

When a logical expression involves a CheckedPtr object, the expression will use this conversion operator, which mimics the use of pointer types in the same situation. For instance:

CheckedPtr<char> a(0), b(0);
bool r = a || b; // returns false

T& operator*() const;
T& operator[](ptrdiff_t) const;

The member function operator[] uses an integral value of type ptrdiff_t for the right operand. C++ uses this type to represent the subtraction of two pointers of the same type. ptrdiff_t is defined in the standard C++ header file stddef.h. It is a signed type, typically either int or long. The operators for the template class CheckedPtr which require an integral operand use ptrdiff_t for this purpose.

The member function operator*() calls operator[](0), which validates the returned reference. Before operator[] returns a reference to an object represented by the operation, it first checks that the represented pointer is not null. If it is, the function throws an xnullptr exception. Next, the function checks that the resulting reference is to a valid array element. If it is not, the function throws an xoutofrange exception. It is valid for a pointer to reference the location that is just beyond the end of an array, but it is not valid to dereference that pointer value. For instance, it is valid C++ to write:

char a[10];
char *end = a+10;
for( char *p = a; p < end; p++ )
   ;

This implementation of template class CheckedPtr has an incompatibility with valid pointer usage. For instance, the following variation of the previous example is valid C++ code:

char a[10];
for( char *p = a; p < &a[10]; ++p )
   ;

char a[10];
const CheckedPtr<char> cpa(a,10);
for( CheckedPtr<char> p = cpa;
   p < &cpa[10]; ++p )
   ;

A less than well-known fact is that the subscript operator is commutative in C and C++. That is, the expression p[n] is equivalent to the expression n[p]. Unfortunately, C++ does not allow the subscript operator to be a non-member function. If it did, then defining the template function:

template<class T> inline
T& operator[]( ptrdiff_t i,
   const CheckedPtr<T>& cp )
   { return cp.operator[i]; }

char *CheckedClassPtr<char>::operator->() const;

If the C++ language definition were relaxed by allowing the member access operator to be a non-member function, it would eliminate the need for the CheckedClassPtr. If this were the case, you could define a non-member function template for the member access operator. The compiler would generate an error only if it generated an instance of the template function instead of when it generates an instance of the class definition.

[The draft C++ Standard has recently been altered in a slightly different way. The net effect, however, is to permit CheckedClassPtr to be instantiated even for non-class types. It will probably take a year or more for this new latitude to be reflected in commercially available compilers. — pjp]

The member function CheckedClassPtr<T>::operator-> calls CheckedPtr<T>::operator*(), which checks that the returned pointer can be dereferenced, then returns the address of the result.

The derived class redefines the operators that return references to the class object, such as operator+=, and operators that return copies of the class object, such as operator+, to return references or objects of class CheckedClassPtr rather than CheckedPtr. This let you use the member access operator with expression that return type CheckedClassPtr, such as p++->f()

char c;
char *p = &c;
c++;    // OK

The template class CheckedPtr defines the postfix and prefix increment and decrement operators, which behave like the same built in operators for pointer types. The postfix operators return a reference to the operand object. The postfix operators, which have an (unused) int parameter, create a copy of the operand before modifying it. These operator functions return this copy as the result, which is how postfix operators behave for pointers and other built-in types.

When the member functions operator+ or operator- are called with a left operand of class CheckedPtr and a right operand of some integral type, they call in turn operator+= or operator-=, respectively. These member functions each create a copy of the left operand object and call the appropriate assignment operator for the copied object. They then return this copy as the result, leaving the original object operand unmodified. The addition operator is commutative, so the template header file defines an additional non-member function for operator+ where the left operand is an integral type and the right operand is of type CheckedPtr.

C++ defines subtraction for two pointers of the same type. The result of this subtraction is the number of objects separating the pointers. The template header file also defines subtraction operator functions that perform this kind of subtraction when at least one of the object is of class CheckedPtr. These functions check that the two pointers refer to the same array. If the operands do not, they throw an xnotsamebase exception.

HeapPtr<char> hp(100);
for(int i = 0; i < 100; i++)
   hp[i] = 0;   // won't work
char *p = hp;
for(int i = 0; i < 100; i++)
   p[i] = 0; // OK

You should not use expressions like this, however:

char *p = HeapPtr<char>(100);

HeapPtr defines three assignment operators and three function call operators that work like the three constructors. These operators have the same effect as destroying and reconstructing the object. For instance:

HeapPtr<int> hp; // null pointer
hp(100);         // allocate array of 100 ints
hp = new int(0); // delete previous, allocate int
hp = 100;        // delete previous, allocate array

HeapPtr<X> hp; // empty HeapPtr
CheckedPtr<X> cp( hp(new X) );
   // initialize HeapPtr and CheckPtr
   // to point to same object

// empty HeapPtr
HeapPtr<X> hp;
// allocate an array of
CheckedPtr<X> cp(hp(100), 100 );

#ifndef NDEBUG
 #define PTRTYPEDEF(type) \
    typedef CheckedPtr<type> type##ptr
 #define CLASSPTRTYPEDEF(type) \
    typedef CheckedClassPtr<type> type##ptr
#else
 #define PTRTYPEDEF(type) typedef *type##ptr
 #define CLASSPTRTYPEDEF(type) type *type##ptr
#endif

PTRTYPEDEF(char);    // defines type charptr
CLASSPTRTYEPDEF(complex);    // define type complexptr

const CheckedPtr<char> p;

char *const p;

#ifndef NDEBUG
#define CONSTPTRTYPEDEF(type) \
   typedef CheckedPtr<const type> \
       const##type##ptr
#define CONSTCLASSPTRTYPEDEF(type) \
   typedef CheckedClassPtr<const type> \
       const##type##ptr
#else
#define CONSTPTRTYPEDEF(type) \
   const type *const##type##ptr
#define CONSTCLASSPTRTYPEDEF(type) \
   const type *const##type##ptr
#endif

CONSTPTRTYPEDEF(char);
   // defines the type constcharptr

#ifndef NDEBUG
#define FIXEDARRAY(array) \
   (array),sizeof(array)/sizeof((array)[0])
#else
#define FIXEDARRAY(array) (array)
#endif

char a[10];
charptr pa(FIXEDARRAY(a));
for( charptr p = pa; p < pa+10; ++p )
   *p = 0;

#ifndef NDEBUG
#define HEAPPTRARRAY(hp,n) hp=(n),(n)
#else
#define HEAPPTRARRAY(hp,n) hp=(n)
#endif

// nothing allocated
HeapPtr<char> ha;
// array of 10
charptr pa(HEAPPTRARRAY(ha,10));
for( charptr p = pa; p < 10; ++p )
   *p = 0;
// ha deletes array when it goes out of scope