UtilPtr

The UtilPtr class provides a way for automating memory management. UtilPtr is basically a reference-counting pointer. A UtilPtr<T> is created from a T* and initially has a reference count of 1. As the UtilPtr is copied into other UtilPtrs, the reference count is incremented, and as the UtilPtrs go out of scope, the reference count is decremented. When the last UtilPtr that points to an object is destroyed, then the object pointed to is deleted. The important thing to remember is not to create more than one UtilPtr<T> from the same T*. Instead, create one UtilPtr and then copy it into the others. Because if you use the same T* to create more than one UtilPtr<T>, then the object will get deleted more than once, which is a very bad thing.

template <class T>
class UtilPtr {
public:
  UtilPtr();
  UtilPtr(T*);
  UtilPtr(const UtilPtr<T>&);
  ~UtilPtr();
  UtilPtr<T>& operator=(const UtilPtr<T>&);
  UtilPtr<T>& operator=(T*);
  Bool operator==(const UtilPtr<T>&) const;
  Bool operator==(T*) const;
  T* operator->() const;
  T& operator*() const;
  operator T*() const;
};

UtilPtr(): This constructor creates a null UtilPtr.
UtilPtr(T* x): This constructor creates a UtilPtr that points to the same object as x. Note that it is a bad idea to use x once use have created a UtilPtr from it, since x is not a reference counting pointer, and the object it points to will be deleted once all of the UtilPtrs that point to the object have gone out of scope, so then x will be pointing into thin air. For the same reason, you should never create more than one UtilPtr directly from x.
UtilPtr(const UtilPtr<T>& x): This constructor creates a UtilPtr which points to the same object as x. Note that using this constructor, or using operator= are the only only acceptable ways to copy a UtilPtr. (Note that passing a UtilPtr as an argument is okay, since it implicitly uses this constructor.) It is not okay to convert a UtilPtr<T> into a T* and then construct another UtilPtr<T> from that T*.
~UtilPtr(): The destructor for UtilPtr decrements the reference count of the object, and also deletes the object if the reference count goes to zero.
UtilPtr<T>& operator=(const UtilPtr<T>& x): This operator allows assigning a UtilPtr to point to the object which another UtilPtr points to. The reference counts of the objects involved are automatically adjusted.
UtilPtr<T>& operator=(T* x): Like the above operator, but makes the UtilPtr point to the object which the T* points to. Note that all the same cautions that apply to the T* constructor also apply here.
Bool operator==(const UtilPtr<T>& x): Compares two UtilPtrs.
Bool operator==(T* x): Compares a UtilPtr<T> with a T*.
T* operator->(): This works just like you would expect operator-> to work with a regular pointer.
T& operator*(): This works just like you would expect operator* to work with a regular pointer.
operator T*(): This conversion operator allows converting a UtilPtr<T> into a T*. Note that the T* may not be valid after the UtilPtr<T> goes out of scope.