Make Qt exception safer.

Squashed commit of the branch haralds-haralds-qt-s60-topics/topic/exceptions,
which also contains the full history.

Rev-By: Harald Fernengel
Rev-By: Ralf Engels

1 files changed, 132 insertions, 0 deletions

diff --git a/src/corelib/tools/qscopedpointer.cpp b/src/corelib/tools/qscopedpointer.cpp
new file mode 100644
index 0000000..8150a18
--- /dev/null
+++ b/src/corelib/tools/qscopedpointer.cpp
@@ -0,0 +1,132 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the $MODULE$ of the Qt Toolkit.
+**
+** $TROLLTECH_DUAL_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \class QScopedPointer
+    \brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.
+    \since 4.6
+    \reentrant
+    \ingroup misc
+
+    Managing heap allocated objects manually is hard and error prone, with the
+    common result that code leaks memory and is hard to maintain.
+    QScopedPointer is a small utility class that heavily simplifies this by
+    assigning stack-based memory ownership to heap allocations, more generally
+    called resource acquisition is initialization(RAII).
+
+    QScopedPointer guarantees that the object pointed to will get deleted when
+    the current scope dissapears, and it also has no way of releasing
+    ownership, hence clearly communicating the lifetime and ownership of the
+    object. These guarantees are convenient when reading the code.
+
+    Consider this function which does heap allocations, and have various exit points:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 0
+
+    It's encumbered by the manual delete calls. With QScopedPointer, the code
+    can be simplified to:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 1
+
+    The code the compiler generates for QScopedPointer is the same as when
+    writing it manually. Code that makes use of \a delete are candidates for
+    QScopedPointer usage(and if not, possibly another type of smart pointer
+    such as QSharedPointer). QScopedPointer intentionally has no copy
+    constructor or assignment operator, such that ownership and lifetime is
+    clearly communicated.
+
+    The const qualification on a regular C++ pointer can also be expressed with
+    a QScopedPointer:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 2
+
+    \note QScopedPointer does not work with arrays.
+
+    \sa QSharedPointer
+*/
+
+/*!
+    \fn QScopedPointer::QScopedPointer(T *p = 0)
+
+    Constructs this QScopedPointer instance and sets its pointer to \a p.
+*/
+
+/*!
+    \fn QScopedPointer::~QScopedPointer()
+
+    Destroys this QScopedPointer object. Delete the object its pointer points
+    to.
+*/
+
+/*!
+    \fn T *QScopedPointer::data() const
+
+    Returns the value of the pointer referenced by this object. QScopedPointer
+    still owns the object pointed to.
+*/
+
+/*!
+    \fn T &QScopedPointer::operator*() const
+
+    Provides access to the scoped pointer's object.
+
+    If the contained pointer is \c null, behavior is undefined.
+    \sa isNull()
+*/
+
+/*!
+    \fn T *QScopedPointer::operator->() const
+
+    Provides access to the scoped pointer's object.
+
+    If the contained pointer is \c null, behavior is undefined.
+
+    \sa isNull()
+*/
+
+/*!
+    \fn QScopedPointer::operator bool() const
+
+    Returns \c true if this object is not \c null. This function is suitable
+    for use in \tt if-constructs, like:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 3
+
+    \sa isNull()
+*/
+
+/*!
+    \fn bool QScopedPointer::isNull() const
+
+    Returns \c true if this object is holding a pointer that is \c null.
+*/
+
+/*!
+    \fn void QScopedPointer::reset(T *other = 0)
+
+    Deletes the existing object its pointing to if any, and sets its pointer to
+    \a other. QScopedPointer now owns \a other and will delete it in its
+    destructor.
+
+    If \a other is equal to the value returned by data(), behavior is
+    undefined.
+*/
+
+/*!
+    \fn T *QScopedPointer::take()
+
+    Returns the value of the pointer referenced by this object. The pointer of this
+    QScopedPointer object will be reset to \c null.
+*/
+
+QT_END_NAMESPACE
+
+#endif