/**************************************************************************** SmartPtr: a smart pointer class. Synopsis: provides a reference counted smart pointer, similar to shared_ptr in the standard library. It is provided here to minimize reliance on the standard library, especially for older C++ compilers, which may not provide shared_ptr, or it may be in TR1, which gets messy. Examples: SmartPtr<T> p1; // initialize to null SmartPtr<T> p2 = 0; SmartPtr<T> p3(p1); // copy constructor T *rp; SmartPtr<T> p4(rp); // construct using raw pointer (explicit): better // to use MakeSmart below p1 = MakeSmart<T>(...); // build new T object by invoking constructor // T(...) with pseudo-variadic templates. // This is safer and more efficient that // using the raw-pointer constructor p1 = p2; // assignment p1 = 0; // assign null if (!p1) ... // test for null if (p1 == 0) ... if (p1) ... // test for not null ... if (p1 != 0) ... if (p1 == p2) ... // test for equality if (p1 != p2) *p1 // dereferencing p1->... p1.get(); // return the underlying raw pointer...dangerous! p1.swap(p2); // fast swap swap(p1, p2); Automatic Conversions: If S is another class, SmartPtr<S> converts to SmartPtr<T> if S* converts to T* (for example, if S is a subclass of T). Similarly, SmartPtr<S> and SmartPtr<T> may be compared if S* and T* may be compared. MakeSmart: One can write SmartPtr<T> p = MakeSmart<T>(x1, ..., xn), and this will create a smart pointer to an object constructed as T(x1, ..., xn). Besides notational convenience, it also reduces the number of memory allocations from 2 to 1, as the data and control block can be allocated in one chunck of memory. This is implemented without reliance on C++11 features, which means that there are limitations. First, the number n of arguments is limited to 9. And second, all arguments are pass by const reference. However, you can work around this by using the helper function Fwd. For example, if T has a 2-argument constructor where the second must be a non-const reference of some type, and x2 is a variable of that type, you can write MakeSmart<T>(x1, Fwd(x2)), to forward that reference through all the template nonsense in a typesafe manner. MakeRaw: One can also write T *p = MakeRaw<T>(x1, ..., xn) to create a raw pointer. This is the same as writing T *p = new T(x1, ..., xn), except that error handling is determined by the NTL_EXCEPTION flag (on => bad_alloc exception is thrown, off => error message and abort). MakeRawArray: Another utility routine: one can write T *p = MakeRawArray<T>(n) to make a plain array of n T objects. Error handling is the same as for MakeRaw. Dynamic casting: I've also supplied a dynamic cast operation for smart pointers. SmartPtr<Derived> d = MakeSmart<Derived>(); // d points to Derived SmartPtr<Base> b = d; // implicit upcast: OK SmartPtr<Derived> d1 = DynamicCast<Derived>(b); // downcast to a Derived object -- returns null for a bad cast Implementation notes: If NTL is compiled with the NTL_THREADS option, then the reference counting will be thread safe. The SmartPtrControl class heirarchy is used to make sure the right destructor is called when the ref count goes to zero. This can be an issue for forward declared classes and for subclasses. For example, if T is forward declared in a context where the ref count goes to zero, or if the object's actual type is a subclass of T and T's destructor was not declared virtual. The implementation of SmartPtr guarantees correct behavior in these situations. The null tests p, !p, p == 0, are all effected via an implicit conversion from SmartPtr<T> to a funny pointer type (a pointer to a member function, which avoids other, unwanted implicit conversions: this is the so-called "safe bool idiom"); Also, there is an implicit conversion from the same, funny pointer type to SmartPtr<T>, which is how one can use 0 to initialize and assign to a SmartPtr<T>. In C++11 both of the above effects could perhaps be achieved more directly. The new "explict bool" operator can replace the "safe bool idiom", and I would think that the new null pointer could be used to get the conversion from "0" to work. NOTES: See http://www.artima.com/cppsource/safebool.html for more on the "safe bool idiom". *****************************************************************************/ template<class T> class SmartPtr { public: explicit SmartPtr(T* p); // construct smart pointer from raw pointer (allocated with new) // EXCEPTIONS: a control block is dynamically allocated; // if this allocation fails, the object pointed to by p is destroyed // and a bad_alloc exception is thrown SmartPtr(); // initial value null ~SmartPtr(); // if ref count drops to zero, then delete referent SmartPtr(const SmartPtr& other); SmartPtr& operator=(const SmartPtr& other); // copy and asignment template<class Y> SmartPtr(const SmartPtr<Y>& other); template<class Y> SmartPtr& operator=(const SmartPtr<Y>& other); // copy and asignment T& operator*() const; T* operator->() const; // indirection T* get() const; // get underlying raw pointer void swap(SmartPtr& other); SmartPtr(fake_null_type); // allows assignment and initialization from 0 operator fake_null_type() const; // allows comparisons to 0 template<class Y> SmartPtr<Y> DynamicCast() const; }; // free swap function template<class T> void swap(SmartPtr<T>& p, SmartPtr<T>& q); // free dynamic cast function template<class X, class Y> SmartPtr<X> DynamicCast(const SmartPtr<Y>& p); // Equality testing template<class X, class Y> bool operator==(const SmartPtr<X>& a, const SmartPtr<Y>& b); template<class X, class Y> bool operator!=(const SmartPtr<X>& a, const SmartPtr<Y>& b); // MakeSmart psuedo-variadic template template<class T, class X1, ..., class Xn> SmartPtr<T> MakeSmart(const X1& x1, ..., const Xn& xn); // EXCEPTIONS: may throw if dynamic constrction of T(x1, ..., xn) fails // EXCEPTIONS: unless otherwise specified, the methods above // never throw an exception (under C++11 rules, if a destructor // is invoked that throws an exception, the program will terminate). /**************************************************************************** Experimantal: CloneablePtr<T> ...essentially same interface as SmartPtr, but allows cloning of complete objects. The differences: * must construct using MakeCloneable * a clone method is provided * implicit conversion from CloneablePtr to SmartPtr is allowed Example: CloneablePtr<Derived> d = MakeCloneable<Derived>(); // d points to Derived CloneablePtr<Base> b = d; // implicit upcast: OK CloneablePtr<Base> b1 = b.clone(); // clone of b, which is really a Derived object CloneablePtr<Derived> d1 = DynamicCast<Derived>(b1); // downcast to a Derived object -- returns null for a bad cast SmartPtr<Base> b2 = d1; Implementation: In the clone method, the object is constructed using the copy constructor for the type T, where T is the compile-time type with which the first smart pointer to this object was was created, even if the pointer has been subsequently upcasted to a base type S. Such objects must have been initially created using the MakeCloneable function. It turns out, this is hard to do in a completely standards-compliant way, because of the type erasure going on. So I settled on the current method, which does some low-level pointer arithmetic. Even with fancy things like multiple and virtual inheritance, it should work, under the assumption that if two objects have the same (runtime) type, then their memory layout is the same. I don't think anything like that is guaranteed by the standard, but this seems reasonable, and it seems to work. Like I said, it is experimental, and I would appreciate feedback from C++ gurus. Note that NTL does not use this feature, but I do have applications where this is convenient. **********************************************************************************/ template<class T> class CloneablePtr { public: CloneablePtr(); // initial value null ~CloneablePtr(); // if ref count drops to zero, then delete referent CloneablePtr(const CloneablePtr& other); CloneablePtr& operator=(const CloneablePtr& other); // copy and asignment template<class Y> CloneablePtr(const CloneablePtr<Y>& other); template<class Y> CloneablePtr& operator=(const CloneablePtr<Y>& other); // copy and asignment T& operator*() const; T* operator->() const; // indirection T* get() const; // get underlying raw pointer void swap(CloneablePtr& other); CloneablePtr(fake_null_type); // allows assignment and initialization from 0 operator fake_null_type() const; // allows comparisons to 0 template<class Y> CloneablePtr<Y> DynamicCast() const; CloneablePtr clone() const; // construct a clone, using the copy constructor // EXCEPTIONS: may throw if copy construction fails template<class Y> operator SmartPtr<Y>(); // implicit conversion from CloneablePtr<T> to SmartPtr<Y>, // allowed if T* converts implicitly to Y*. }; // free swap function template<class T> void swap(CloneablePtr<T>& p, CloneablePtr<T>& q); // free dynamic cast function template<class X, class Y> CloneablePtr<X> DynamicCast(const CloneablePtr<Y>& p); // Equality testing template<class X, class Y> bool operator==(const CloneablePtr<X>& a, const CloneablePtr<Y>& b); template<class X, class Y> bool operator!=(const CloneablePtr<X>& a, const CloneablePtr<Y>& b); // MakeCloneable psuedo-variadic template template<class T, class X1, ..., class Xn> CloneablePtr<T> MakeCloneable(const X1& x1, ..., const Xn& xn); // EXCEPTIONS: may throw if dynamic constrction of T(x1, ..., xn) fails // EXCEPTIONS: unless otherwise specified, the methods above // never throw an exception (under C++11 rules, if a destructor // is invoked that throws an exception, the program will terminate). /********************************************************************** UniquePtr<T> -- unique pointer to object with copying disabled. Useful for pointers inside classes so that we can automatically destruct them. Constructors: UniquePtr<T> p1; // initialize with null T* rp; UniquePtr<T> p1(rp); // construct using raw pointer (explicit) p1 = 0; // destroy's p1's referent and assigns null p1.make(...); // destroy's p1's referent and assigns // a fresh objected constructed via T(...), // using psuedo-variadic templates p1.reset(rp); // destroy's p1's referent and assign rp if (!p1) ... // test for null if (p1 == 0) ... if (p1) ... // test for nonnull if (p1 != 0) ... if (p1 == p2) ... // test for equality if (p1 != p2) ... *p1 // dereferencing p1->... rp = p1.get(); // fetch raw pointer rp = p1.release(); // fetch raw pointer, and set to null p1.move(p2); // move p2 to p1, destroying p1's referent // if p1 != p2 p1.swap(p2); // swap pointers swap(p1, p2); **********************************************************************/ template<class T> class UniquePtr { public: explicit UniquePtr(T *p); // construct UniquePtr from raw pointer (allocated with new) UniquePtr(); // initial value is null ~UniquePtr(); // destroys referent void reset(T* p = 0); // reset underlying pointer to p, destroying original referent template<class T, class X1, ..., class Xn> void make(const X1& x1, ..., const Xn& xn); // pseudo-variadic template, roughly equivalent to // reset(new T(x1, ..., xn)) // EXCEPTIONS: this may throw (but provides strong ES guarantee) T& operator*() const; T* operator->() const; // indirection T* get() const; // get raw pointer T* release(); // returns raw pointer, and sets the raw pointer to null void move(UniquePtr& other); // move other to *this void swap(UniquePtr& other); // swap raw pointers UniquePtr& operator=(fake_null_type); UniquePtr(fake_null_type); // allows initialization and assignment of 0 operator fake_null_type() const; // allows comparison with 0 private: UniquePtr(const UniquePtr&); // disabled void operator=(const UniquePtr&); // disabled }; // free swap function template<class T> void swap(UniquePtr<T>& p, UniquePtr<T>& q); // Equality testing template<class X> bool operator==(const UniquePtr<X>& a, const UniquePtr<X>& b); template<class X> bool operator!=(const UniquePtr<X>& a, const UniquePtr<X>& b); // EXCEPTIONS: unless otherwise specified, the methods above // never throw an exception (under C++11 rules, if a destructor // is invoked that throws an exception, the program will terminate). /********************************************************************** OptionalVal<T> -- unique pointer to object with copying enabled. Constructors: OptionalVal<T> p1; // initialize with null T* rp; OptionalVal<T> p1(rp); // construct using raw pointer (explicit) OptionalVal<T> p2(p1); // construct a copy of p1's referent p1.make(...); // destroy's p1's referent and assigns // a fresh objected constructed via T(...), // using psuedo variadic templates p1.reset(rp); // destroy's p1's referent and assign rp if (p1.exists()) ... // test for null p1.val() // dereference p1.move(p2); // move p2 to p1, destroying p1's referent // if p1 != p2 p1 = p2; // deep copy, using T's copy constructor p1.swap(p2); // swap pointers swap(p1, p2); **********************************************************************/ template<class T> class OptionalVal { public: explicit OptionalVal(T *p); // initialize using raw pointer (allocated with new) OptionalVal(); // initialize to null OptionalVal(const OptionalVal& other); // initialize using a deep copy (via T's copy constructor) OptionalVal& operator=(const OptionalVal& other); // assignment using a deep copy (via T's copy constructor) ~OptionalVal(); // destroys the referent void reset(T* p = 0); // resets the referent template<class T, class X1, ..., class Xn> void make(const X1& x1, ..., const Xn& xn); // pseudo-variadic template. // resets the referent to a new object T(x1, ..., xn) // EXCEPTIONS: may throw an exception (but provides strong ES guarantee) T& val() const; // returns reference to referent // if underlying pointer p is null, the indirection *p // is undefined behavior, but most likely leads to program termination bool exists() const; // checks that underlying pointer is not null void move(OptionalVal& other); // performs a (shallow) pointer move void swap(OptionalVal& other); // performs a (shallow) pointer swap }; // free swap function template<class T> void swap(OptionalVal<T>& p, OptionalVal<T>& q); // EXCEPTIONS: unless otherwise specified, the methods above // never throw an exception (under C++11 rules, if a destructor // is invoked that throws an exception, the program will terminate). /********************************************************************** UniqueArray<T> -- unique pointer to array of objects with copying disabled. Useful for pointers inside classes so that we can automatically destruct them. Constructors: UniqueArray<T> p1; // initialize with null T* rp; UniqueArray<T> p1(rp); // construct using raw pointer (explicit) p1 = 0; // destroy's p1's referent and assigns null p1.SetLength(n); // destroy's p1's referent and assigns // a fresh objected constructed via new T[n] p1.reset(rp); // destroy's p1's referent and assign rp if (!p1) ... // test for null if (p1 == 0) ... if (p1) ... // test for nonnull if (p1 != 0) ... if (p1 == p2) ... // test for equality if (p1 != p2) ... p1[i] // array indexing rp = p1.get(); // fetch raw pointer rp = p1.release(); // fetch raw pointer, and set to null p1.move(p2); // move p2 to p1, destroying p1's referent // if p1 != p2 p1.swap(p2); // fast swap swap(p1, p2); **********************************************************************/ template<class T> class UniqueArray { public: explicit UniqueArray(T *p); // construct from raw pointer (allocated with new[]) UniqueArray(); // initially null ~UniqueArray(); void reset(T* p = 0); // reset with raw pointer, destryong referent void SetLength(long n); // destroys referent and allocates an array of size n // EXCEPTIONS: this may throw (but provides strong ES guarantee) T& operator[](long i) const; // accesses ith element in the array (currently no range checking) T* get() const; // get raw pointer T* release(); // get raw pointer and reset to null void move(UniqueArray& other); // move raw pointer void swap(UniqueArray& other); // swap raw pointer UniqueArray& operator=(fake_null_type); UniqueArray(fake_null_type); // allows initialization and assignment of 0 operator fake_null_type() const; // allows comparison to 0 }; // free swap function template<class T> void swap(UniqueArray<T>& p, UniqueArray<T>& q); // Equality testing template<class X> bool operator==(const UniqueArray<X>& a, const UniqueArray<X>& b); template<class X> bool operator!=(const UniqueArray<X>& a, const UniqueArray<X>& b); /********************************************************************** Unique2DArray<T> -- unique pointer to array of arrays. This is very similar to UniqueArray< UniqueArray<T> >, except that we can retrofit old code that accepts objects of type T**. Constructors: Unique2DArray<T> p1; // initialize with null p1 = 0; // destroy's p1's referent and assigns null p1.reset(); p1.SetLength(n); // destroy's p1's referent and assigns // a fresh array of null pointers p1.SetDims(n, m) // creates an n x m array if (!p1) ... // test for null if (p1 == 0) ... if (p1) ... // test for nonnull if (p1 != 0) ... if (p1 == p2) ... // test for equality if (p1 != p2) ... p1[i] // array indexing T **rp; rp = p1.get(); // fetch raw pointer rp = p1.release(); // fetch raw pointer, and set to null p1.move(p2); // if p1 != p2 then: // makes p1 point to p2's referent, // setting p2 to null and destroying // p1's referent p1.swap(p2); // fast swap swap(p1, p2); **********************************************************************/ template<class T> class Unique2DArray { public: typedef T *T_ptr; Unique2DArray(); // initially null ~Unique2DArray(); // destroys the entire array and each row in the array void reset(); // reset to null void SetLength(long n); // resets the array to a vector of length n, // each entry initialized to null. // EXCEPTIONS: may throw (provides strong ES guarantee) void SetDims(long n, long m); // resets the array to a 2D array with n rows and m columns. // EXCEPTIONS: may throw (provides strong ES guarantee) void SetDimsFrom1(long n, long m); // same as above, but only initializes rows 1..n-1. // this helps with some legacy code. // EXCEPTIONS: may throw (provides strong ES guarantee) T_ptr& operator[](long i) const; // array indexing, no range checking T_ptr* get() const; // return underlying pointer T_ptr* release() { len = 0; return dp.release(); } // return underlying pointer and reset to null void move(Unique2DArray& other); // move pointers void swap(Unique2DArray& other); // swap pointers Unique2DArray& operator=(fake_null_type); Unique2DArray(fake_null_type) : dp(0), len(0) { } // allows initialization and assignment of 0 operator fake_null_type() const; // allows comparison to 0 }; // free swap function template<class T> void swap(Unique2DArray<T>& p, Unique2DArray<T>& q); // Equality testing template<class X> bool operator==(const Unique2DArray<X>& a, const Unique2DArray<X>& b); template<class X> bool operator!=(const Unique2DArray<X>& a, const Unique2DArray<X>& b);