Topic: Specifications for auto_ptr and counted_ptr.


Author: gregor@netcom.com (Greg Colvin)
Date: 1995/05/25
Raw View
I have gotten some inquiries about the auto_ptr template (which was accepted
by X3J16/WG21) and the counted_ptr template (which was not), so here are the
specifications from my final proposal "Exception Safe Smart Pointers.
Revised. Again." ANSI X3J16/94-0202R1, WG 21/N0589R1.


The template auto_ptr
---------------------
The auto_ptr template provides a semantics of strict ownership. An auto_ptr
owns the object it holds a pointer to, and deletes that object when it itself
is destroyed. An object may be safely pointed to by only one auto_ptr, so
copying an auto_ptr copies the pointer and transfers ownership to the
destination.

   Interface
   ---------
   template<class X> class auto_ptr {
      X* px; // exposition only
   public:
      explicit auto_ptr(X* p=0);
      template<class U> auto_ptr(auto_ptr<U>& r);
      ~auto_ptr();
      template<class U> auto_ptr& operator=(auto_ptr<U>& r);
      X& operator*() const;
      X* operator->() const;
      X* get() const;
      X* release();
      void reset(X* p=0);
   };

   Semantics
   ---------
   An auto_ptr<X> object holds a pointer to an object of class X, presented
   here as X* px. In the following table: p and px are pointers to an object
   of class X or a class derived from X for which delete(X*) is defined and
   accessible, or else null; d is an auto_ptr<D> where D is X or a class
   derived from X; a is an auto_ptr<X>; and m is a member of X.

      Expression           Value             Effect
      ------------------   ---------------   ---------------------
      auto_ptr<X> a(p)                       a.px = p
      auto_ptr<X> a(d)                       a.px = d.release()
      a.~auto_ptr<X>()                       delete a.px
      a = d                reference to a    a.reset(d.release())
      *a                   *a.px
      a->m                 a.px->m
      a.get()              a.px
      a.release()          a.px              a.px = 0
      a.reset(p)                             delete a.px, a.px = p


The template counted_ptr
------------------------
The counted_ptr template provides a semantics of joint ownership. Each
counted_ptr has an interest in the object it holds a pointer to, which it
gives up when it itself is destroyed. An object may be safely pointed to by
more than one counted_ptr, so long as the object is not deleted while any
owner retains an interest.

   Interface
   ---------
   template<class X> class counted_ptr {
      X* px; // exposition only
   public:
      explicit counted_ptr(X* p=0);
      template<class U> counted_ptr(const counted_ptr<U>& r);
      ~counted_ptr();
      template<class U> counted_ptr& operator=(const counted_ptr<U>& r);
      X& operator*() const;
      X* operator->() const;
      X* get() const;
      bool unique() const;
      template<class D> counted_ptr<D> dyn_cast() const;
   };

   Semantics
   ---------
   A counted_ptr<X> object holds a pointer to an object of class X, presented
   here as X* px. In the following table: p and px are pointers to an object
   of class X or a class derived from X for which delete(X*) is defined and
   accessible; d is a counted_ptr<D> where D is X or a class derived from X;
   c is a counted_ptr<X>; m is a member of X; and u is an counted_ptr<U>.

      Expression           Value                Effect
      ------------------   ------------------   ----------------------------
      counted_ptr<X> c(p)                       c.px = (X*)p
      counted_ptr<X> c(d)                       c.px = (X*)d.px
      c.~counted_ptr<X>()                       if (c.unique()) delete c.px
      c = d                reference to c       c.px = (X*)d.px
      *c                   *c.px
      c->m                 c.px->m
      c.get()              c.px
      c.unique()           true if and only if
                           there exists no other
                           u which is a copy of c
                           such that
                           c.px == u.dyn_cast<X>().px
      u.dyn_cast<U>()      counted_ptr<U>(dynamic_cast<X>(u.px))