Applied patch [ 587450 ] Scoped Smart pointers and docs

By Jesse Lovelace (thementat)


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@16409 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -241,6 +241,8 @@
 \input sashlayw.tex
 \input sashwin.tex
 \input screendc.tex
+\input scpdarry.tex
+\input scpdptr.tex
 \input scrolbar.tex
 \input scrolwin.tex
 \input scrolevt.tex

docs/latex/wx/scpdarry.tex

@@ -0,0 +1,102 @@
+\section{wxScopedArray}\label{wxscopedarray}
+
+This is a simple scoped smart pointer array implementation that is similar to 
+the \urlref{Boost}{http://www.boost.org} smart pointers but rewritten to
+use macros instead.
+
+\wxheading{Example}
+
+Below is an example of using a wxWindows scoped smart pointer and 
+pointer array.
+
+\begin{verbatim}
+  class MyClass { /* ... */ };
+
+  // declare a smart pointer to a MyClass called wxMyClassPtr
+  wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // declare a smart pointer to an array of chars
+  wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+  ...
+
+  // define the first pointer class, must be complete
+  wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // define the second pointer class
+  wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+  // create an object with a new pointer to MyClass
+  wxMyClassPtr theObj(new MyClass());
+  // reset the pointer (deletes the previous one)
+  theObj.reset(new MyClass());
+
+  // access the pointer
+  theObj->MyFunc();
+
+  // create an object with a new array of chars
+  wxCharArray theCharObj(new char[100]);
+
+  // access the array
+  theCharObj[0] = "!";
+\end{verbatim}
+
+\wxheading{Declaring new smart pointer types}
+
+\begin{verbatim}
+    wxDECLAR_SCOPED_ARRAY( TYPE,     // type of the values
+                                CLASSNAME ); // name of the class
+\end{verbatim}
+
+A smart pointer holds a pointer to an object (which must be complete
+when wxDEFINE_SCOPED_ARRAY() is called). The memory used by the object is
+deleted when the smart pointer goes out of scope. The first argument
+of the macro is the pointer type, the second is the name of the new
+smart pointer class being created.  Below we will use wxScopedArray to
+represent the scoped pointer array class, but the user may create the class 
+with any legal name.
+
+\wxheading{Include files}
+
+<wx/ptr\_scpd.h>
+
+\wxheading{See also}
+
+\helpref{wxScopedPtr}{wxscopedptr}\rtfsp
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxScopedArray::wxScopedArray}
+
+\func{}{wxScopedArray}{\param{type}{ * T = NULL}}
+
+Creates the smart pointer with the given pointer or none if NULL.  On
+compilers that support it, this uses the explicit keyword.
+
+\membersection{wxScopedArray::reset}
+
+\func{\void}{reset}{\param{T}{ p * = NULL}}
+
+Deletes the currently held pointer and sets it to 'p' or to NULL if no 
+arguments are specified. This function does check to make sure that the
+pointer you are assigning is not the same pointer that is already stored.
+
+\membersection{wxScopedArray::operator []}
+
+\func{const T \&}{operator []}{\param{long int}{i}}
+
+This operator acts like the standard [] indexing operator for C++ arrays.  The
+function does not do bounds checking.
+
+\membersection{wxScopedArray::get}
+
+\func{const T*}{get}{\void}
+
+This operator gets the pointer stored in the smart pointer or returns NULL if
+there is none.
+
+\membersection{wxScopedArray::swap}
+
+\func{\void}{swap}{\param{wxScopedPtr}{ \& ot}}
+
+Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
+must be of the same type (hence the same class name).
+

docs/latex/wx/scpdptr.tex

@@ -0,0 +1,110 @@
+\section{wxScopedPtr}\label{wxscopedptr}
+
+This is a simple scoped smart pointer implementation that is similar to 
+the \urlref{Boost}{http://www.boost.org} smart pointers but rewritten to
+use macros instead.
+
+\wxheading{Example}
+
+Below is an example of using a wxWindows scoped smart pointer and 
+pointer array.
+
+\begin{verbatim}
+  class MyClass { /* ... */ };
+
+  // declare a smart pointer to a MyClass called wxMyClassPtr
+  wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // declare a smart pointer to an array of chars
+  wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+  ...
+
+  // define the first pointer class, must be complete
+  wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // define the second pointer class
+  wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+  // create an object with a new pointer to MyClass
+  wxMyClassPtr theObj(new MyClass());
+  // reset the pointer (deletes the previous one)
+  theObj.reset(new MyClass());
+
+  // access the pointer
+  theObj->MyFunc();
+
+  // create an object with a new array of chars
+  wxCharArray theCharObj(new char[100]);
+
+  // access the array
+  theCharObj[0] = "!";
+\end{verbatim}
+
+\wxheading{Declaring new smart pointer types}
+
+\begin{verbatim}
+    wxDECLAR_SCOPED_PTR( TYPE,     // type of the values
+                                CLASSNAME ); // name of the class
+\end{verbatim}
+
+A smart pointer holds a pointer to an object (which must be complete
+when wxDEFINE_SCOPED_PTR() is called). The memory used by the object is
+deleted when the smart pointer goes out of scope. The first argument
+of the macro is the pointer type, the second is the name of the new
+smart pointer class being created.  Below we will use wxScopedPtr to
+represent the scoped pointer class, but the user may create the class with any
+legal name.
+
+\wxheading{Include files}
+
+<wx/ptr\_scpd.h>
+
+\wxheading{See also}
+
+\helpref{wxScopedArray}{wxscopedarray}\rtfsp
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxScopedPtr::wxScopedPtr}
+
+\func{}{wxScopedPtr}{\param{type}{ * T = NULL}}
+
+Creates the smart pointer with the given pointer or none if NULL.  On
+compilers that support it, this uses the explicit keyword.
+
+\membersection{wxScopedPtr::reset}
+
+\func{\void}{reset}{\param{T}{ p * = NULL}}
+
+Deletes the currently held pointer and sets it to 'p' or to NULL if no 
+arguments are specified. This function does check to make sure that the
+pointer you are assigning is not the same pointer that is already stored.
+
+\membersection{wxScopedPtr::operator *}
+
+\func{const T\&}{operator *}{\void}
+
+This operator works like the standard C++ pointer operator to return the object
+being pointed to by the pointer.  If the pointer is NULL or invalid this will
+crash.
+
+\membersection{wxScopedPtr::operator -\>}
+
+\func{const T*}{operator -\>}{\void}
+
+This operator works like the standard C++ pointer operator to return the pointer
+in the smart pointer or NULL if it is empty.
+
+\membersection{wxScopedPtr::get}
+
+\func{const T*}{get}{\void}
+
+This operator gets the pointer stored in the smart pointer or returns NULL if
+there is none.
+
+\membersection{wxScopedPtr::swap}
+
+\func{\void}{swap}{\param{wxScopedPtr}{ \& ot}}
+
+Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
+must be of the same type (hence the same class name).
+

include/wx/ptr_scpd.h

@@ -0,0 +1,164 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/ptr_scpd.h
+// Purpose:     scoped smart pointer class
+// Author:      Jesse Lovelace <jllovela@eos.ncsu.edu>
+// Modified by:
+// Created:     06/01/02
+// RCS-ID:      $Id$
+// Copyright:   (c) Jesse Lovelace and original Boost authors (see below)
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+//  This class closely follows the implementation of the boost
+//  library scoped_ptr and is an adaption for c++ macro's in 
+//  the wxWindows project. The original authors of the boost
+//  scoped_ptr are given below with their respective copyrights.
+
+//  (C) Copyright Greg Colvin and Beman Dawes 1998, 1999.
+//  Copyright (c) 2001, 2002 Peter Dimov
+//
+//  Permission to copy, use, modify, sell and distribute this software
+//  is granted provided this copyright notice appears in all copies.
+//  This software is provided "as is" without express or implied
+//  warranty, and with no claim as to its suitability for any purpose.
+//
+//  See http://www.boost.org/libs/smart_ptr/scoped_ptr.htm for documentation.
+//
+
+#ifndef __WX_SCOPED_POINTER__
+#define __WX_SCOPED_POINTER__
+
+#include "wx/defs.h"
+
+/* checked deleters are used to make sure that the
+   type being deleted is really a complete type.
+   - Jesse Lovelace <jllovela@eos.ncsu.edu>
+*/
+
+#define wxCHECKED_DELETE(ptr)                \
+    if (true) {                                 \
+        typedef char complete[sizeof(*ptr)]; \
+        delete ptr;                          \
+    }
+
+#define wxCHECKED_DELETE_ARRAY(ptr)          \
+    if (true) {                                        \
+        typedef char complete[sizeof(*ptr)]; \
+        delete [] ptr;                       \
+    }
+
+/* These scoped pointers are *not* assignable and cannot be used
+   within a container.  Look for wxDECLARE_SHARED_PTR for this
+   functionality.
+
+   In addition, the type being used *must* be complete at the time
+   that wxDEFINE_SCOPED_* is called or a compiler error will result.
+   This is because the class checks for the completeness of the type
+   being used.
+*/
+
+
+#define wxDECLARE_SCOPED_PTR(T, name) \
+class name                          \
+{                                   \
+private:                            \
+    T * m_ptr;                      \
+                                    \
+    name(name const &);             \
+    name & operator=(name const &); \
+                                    \
+public:                             \
+    wxEXPLICIT name(T * ptr = NULL)  \
+    : m_ptr(ptr) { }                \
+                                    \
+    ~name();                        \
+                                    \
+    void reset(T * ptr = NULL)      \
+    {                               \
+        if (m_ptr != ptr)           \
+        {                           \
+            delete m_ptr;           \
+            m_ptr = ptr;            \
+        }                           \
+    }                               \
+                                    \
+    T & operator*() const           \
+    {                               \
+        wxASSERT(m_ptr != NULL);    \
+        return *m_ptr;              \
+    }                               \
+                                    \
+    T * operator->() const          \
+    {                               \
+        wxASSERT(m_ptr != NULL);    \
+        return m_ptr;               \
+    }                               \
+                                    \
+    T * get() const                 \
+    {                               \
+        return m_ptr;               \
+    }                               \
+                                    \
+    void swap(name & ot)            \
+    {                               \
+        T * tmp = ot.m_ptr;         \
+        ot.m_ptr = m_ptr;           \
+        m_ptr = tmp;                \
+    }                               \
+};
+
+#define wxDEFINE_SCOPED_PTR(T, name)\
+name::~name()                       \
+{                                   \
+    wxCHECKED_DELETE(m_ptr)      \
+}
+
+#define wxDECLARE_SCOPED_ARRAY(T, name)\
+class name                          \
+{                                   \
+private:                            \
+    T * m_ptr;                      \
+    name(name const &);             \
+    name & operator=(name const &); \
+                                    \
+public:                             \
+    wxEXPLICIT name(T * p = NULL) : m_ptr(p) \
+    {}                              \
+                                    \
+    ~name();                        \
+    void reset(T * p = NULL);       \
+                                    \
+    T & operator[](long int i) const\
+    {                               \
+        wxASSERT(m_ptr != NULL);    \
+        wxASSERT(i >= 0);           \
+        return m_ptr[i];            \
+    }                               \
+                                    \
+    T * get() const                 \
+    {                               \
+        return m_ptr;               \
+    }                               \
+                                    \
+    void swap(name & ot)            \
+    {                               \
+        T * tmp = ot.m_ptr;         \
+        ot.m_ptr = m_ptr;           \
+        m_ptr = tmp;                \
+    }                               \
+};
+
+#define wxDEFINE_SCOPED_ARRAY(T, name)  \
+name::~name()                       \
+{                                   \
+    wxCHECKED_DELETE_ARRAY(m_ptr)  \
+}                                   \
+void name::reset(T * p){            \
+    if (m_ptr != p)                 \
+    {                               \
+       wxCHECKED_DELETE_ARRAY(m_ptr); \
+       m_ptr = p;                   \
+    }                               \
+}
+
+#endif