/src/libtomahawk/thirdparty/kdsingleapplicationguard/pimpl_ptr.cpp

  1#include "pimpl_ptr.h"
  2
  3/*!
  4  \class pimpl_ptr:
  5  \ingroup core smartptr
  6  \brief Owning pointer for private implementations
  7  \since_c 2.1
  8
  9  (The exception safety of this class has not been evaluated yet.)
 10
 11  pimpl_ptr is a smart immutable pointer, which owns the contained object. Unlike other smart pointers,
 12  it creates a standard constructed object when instanciated via the 
 13  \link pimpl_ptr() standard constructor\endlink.
 14  Additionally, pimpl_ptr respects constness of the pointer object and returns \c const \c T* for
 15  a const pimpl_ptr object.
 16
 17  The content of a pimpl_ptr cannot be changed during it's lifetime.
 18
 19  \section general-use General Use
 20
 21  The general use case of pimpl_ptr is the "Pimpl Idiom", i.e. hiding the private implementation of a class
 22  from the user's compiler which see \c MyClass as
 23
 24  \code
 25  class MyClass
 26  {
 27  public:
 28      MyClass();
 29      ~MyClass();
 30
 31      // public class API
 32      int value() const;
 33
 34  private:
 35      class Private; // defined later
 36      kdtools::pimpl_ptr< Private > d;
 37  };
 38  \endcode
 39
 40  but not the private parts of it. These can only be seen (and accessed) by the code knowing \c MyClass::Private:
 41
 42  \code
 43  class MyClass::Private
 44  {
 45  public:
 46      int value;
 47  };
 48
 49  MyClass::MyClass()
 50  {
 51      // d was automatically filled with new Private
 52      d->value = 42;
 53  }
 54
 55  MyClass::~MyClass()
 56  {
 57      // the content of d gets deleted automatically
 58  }
 59
 60  int MyClass::value() const
 61  {
 62      // access the private part:
 63      // since MyClass::value() is const, the returned pointee is const, too
 64      return d->value;
 65  }
 66  \endcode
 67
 68*/
 69
 70/*!
 71  \fn pimpl_ptr::pimpl_ptr()
 72
 73  Default constructor. Constructs a pimpl_tr that contains (owns) a standard constructed
 74  instance of \c T.
 75
 76  \post \c *this owns a new object.
 77*/
 78
 79/*!
 80  \fn pimpl_ptr::pimpl_ptr( T * t )
 81
 82  Constructor. Constructs a pimpl_ptr that contains (owns) \a t.
 83
 84  \post get() == obj
 85*/
 86
 87/*!
 88  \fn pimpl_ptr::~pimpl_ptr()
 89
 90  Destructor.
 91
 92  \post The object previously owned by \c *this has been deleted.
 93*/
 94
 95/*!
 96  \fn const T * pimpl_ptr::get() const
 97
 98  \returns a const pointer to the contained (owned) object.
 99  \overload
100*/
101
102/*!
103  \fn T * pimpl_ptr::get()
104
105  \returns a pointer to the contained (owned) object.
106*/
107
108/*!
109  \fn const T & pimpl_ptr::operator*() const
110
111  Dereference operator. Returns \link get() *get()\endlink.
112  \overload
113*/
114
115/*!
116  \fn T & pimpl_ptr::operator*()
117
118  Dereference operator. Returns \link get() *get()\endlink.
119*/
120
121/*!
122  \fn const T * pimpl_ptr::operator->() const
123
124  Member-by-pointer operator. Returns get().
125  \overload
126*/
127
128/*!
129  \fn T * pimpl_ptr::operator->() 
130
131  Member-by-pointer operator. Returns get().
132*/
133
134#ifdef KDTOOLSCORE_UNITTESTS
135
136#include <kdunittest/test.h>
137
138#include <QObject>
139#include <QPointer>
140
141namespace
142{
143    struct ConstTester
144    {
145        bool isConst()
146        {
147            return false;
148        }
149
150        bool isConst() const
151        {
152            return true;
153        }
154    };
155}
156
157KDAB_UNITTEST_SIMPLE( pimpl_ptr, "kdcoretools" ) {
158
159    {
160        kdtools::pimpl_ptr< QObject > p;
161        assertNotNull( p.get() );
162        assertNull( p->parent() );
163    }
164
165
166    {   
167        QPointer< QObject > o;
168        {
169            kdtools::pimpl_ptr< QObject > qobject( new QObject );
170            o = qobject.get();
171            assertEqual( o, qobject.operator->() );
172            assertEqual( o, &(qobject.operator*()) );
173        }
174        assertNull( o );
175    }
176
177    {   
178        const kdtools::pimpl_ptr< QObject > qobject( new QObject );
179        const QObject* o = qobject.get();
180        assertEqual( o, qobject.operator->() );
181        assertEqual( o, &(qobject.operator*()) );
182    }
183
184    {
185        kdtools::pimpl_ptr< QObject > o1;
186        assertTrue( o1 );
187        kdtools::pimpl_ptr< QObject > o2( 0 );
188        assertFalse( o2 );
189    }
190
191    {
192        const kdtools::pimpl_ptr< ConstTester > o1;
193        kdtools::pimpl_ptr< ConstTester > o2;
194        assertTrue( o1->isConst() );
195        assertFalse( o2->isConst() );
196        assertTrue( (*o1).isConst() );
197        assertFalse( (*o2).isConst() );
198        assertTrue( o1.get()->isConst() );
199        assertFalse( o2.get()->isConst() );
200    }
201}
202
203#endif // KDTOOLSCORE_UNITTESTS