RNA/UI - Reset Settings to Default Values
[blender.git] / source / kernel / gen_system / GEN_SmartPtr.h
1 #ifndef NAN_INCLUDED_GEN_SmartPtr_h
2 #define NAN_INCLUDED_GEN_SmartPtr_h
3
4 /**
5  * $Id$
6  *
7  * ***** BEGIN GPL LICENSE BLOCK *****
8  *
9  * This program is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU General Public License
11  * as published by the Free Software Foundation; either version 2
12  * of the License, or (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
22  *
23  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
24  * All rights reserved.
25  *
26  * The Original Code is: all of this file.
27  *
28  * Contributor(s): none yet.
29  *
30  * ***** END GPL LICENSE BLOCK *****
31  *
32  * @author Laurence
33  */
34
35 #include <stdlib.h> // for NULL !
36
37 /**
38  * @section GEN_SmartPtr 
39  * This class defines a smart pointer similar to that defined in 
40  * the Standard Template Library but without the painful get()
41  * semantics to access the internal c style pointer.
42  *
43  * It is often useful to explicitely decalre ownership of memory
44  * allocated on the heap within class or function scope. This
45  * class helps you to encapsulate this ownership within a value
46  * type. When an instance of this class goes out of scope it
47  * makes sure that any memory associated with it's internal pointer
48  * is deleted. It can help to inform users of an aggregate class
49  * that it owns instances of it's members and these instances 
50  * should not be shared. This is not reliably enforcable in C++
51  * but this class attempts to make the 1-1 relationship clear.
52  * 
53  * @section Example usage
54  *
55  * class foo {
56  *              ...constructors accessors etc.
57  *              int x[1000];
58  * }
59  * 
60  * class bar {
61  *  public :
62  *              static
63  *                      bar *
64  *              New(
65  *              ) {
66  *                      GEN_SmartPtr<foo> afoo = new foo();
67  *                      GEN_SmartPtr<bar> that = new bar();
68  *
69  *                      if (foo == NULL || that == NULL) return NULL;
70  *
71  *                      that->m_foo = afoo.Release();
72  *                      return that.Release();
73  *              }
74  *
75  *              ~bar() {
76  *                      // smart ptr takes care of deletion
77  *              }
78  *      private :
79  *              GEN_SmartPtr<foo> m_foo;
80  *      }
81  *                      
82  * You my also safely construct vectors of GEN_SmartPtrs and 
83  * have the vector own stuff you put into it. 
84  *
85  * e.g.
86  * { 
87  * std::vector<GEN_SmartPtr<foo> > foo_vector;
88  * foo_vector.push_back( new foo());
89  * foo_vector.push_back( new foo());
90  *
91  * foo_vector[0]->bla();
92  * } // foo_vector out of scope => heap memory freed for both foos
93  *
94  * @warning this class should only be used for objects created
95  * on the heap via the new function. It will not behave correctly
96  * if you pass ptrs to objects created with new[] nor with 
97  * objects declared on the stack. Doing this is likely to crash
98  * the program or lead to memory leaks.
99  */
100
101 template 
102         < class T >
103 class GEN_SmartPtr {
104
105 public :
106
107         /**
108          * Construction from reference - this class
109          * always assumes ownership from the rhs.
110          */
111
112         GEN_SmartPtr(
113                 const GEN_SmartPtr &rhs
114         ){
115                 m_val = rhs.Release();
116         }
117
118         /**
119          * Construction from ptr - this class always
120          * assumes that it now owns the memory associated with the
121          * ptr.
122          */
123
124         GEN_SmartPtr(
125                 T* val
126         ) :
127                 m_val (val)
128         {
129         }
130         
131         /**
132          * Defalut constructor
133          */
134
135         GEN_SmartPtr(
136         ) :
137                 m_val (NULL)
138         {
139         }
140
141         /**
142          * Type conversion from this class to the type
143          * of a pointer to the template parameter. 
144          * This means you can pass an instance of this class
145          * to a function expecting a ptr of type T.
146          */
147
148         operator T * () const {
149                 return m_val;
150         }
151
152         /**
153          * Return a reference to the internal ptr class.
154          * Use with care when you now that the internal ptr
155          * is not NULL!
156          */
157
158                 T &
159         Ref(
160         ) const {
161                 return *m_val;
162         }       
163
164         /** 
165          * Assignment operator - ownership is transfered from rhs to lhs. 
166          * There is an intenional side-effect of function of transferring
167          * ownership from the const parameter rhs. This is to insure 
168          * the 1-1 relationship.
169          * The object associated with this instance is deleted if it 
170          * is not the same as that contained in the rhs.
171          */
172
173         GEN_SmartPtr & operator=(
174                 const GEN_SmartPtr &rhs
175         ) {
176                 if (this->m_val != rhs.m_val) {
177                         delete this->m_val;
178                 }
179
180                 this->m_val = rhs.Release();
181                 return *this;
182         }
183         
184         /** 
185          * Overload the operator -> so that it's possible to access
186          * all the normal methods of the internal ptr. 
187          */
188         
189         T * operator->() const {
190                 return m_val;
191         }
192
193         /**
194          * Caller takes ownership of the object - the object will not 
195          * be deleted when the ptr goes out of scope.
196          */
197
198                 T *
199         Release(
200         ) const {
201                 T* temp = m_val;
202                 (const_cast<GEN_SmartPtr *>(this))->m_val = NULL;       
203                 return temp;
204         }
205
206         /**
207          * Force destruction of the internal object.
208          */
209         
210                 void
211         Delete(
212         ) {
213                 delete (m_val);
214                 m_val = NULL;
215         }
216
217         /** 
218          * Destructor - deletes object if it exists
219          */
220
221         ~GEN_SmartPtr(
222         ) {
223                 delete (m_val);
224         }
225
226 private :
227         
228         /// The ptr owned by this class.
229         T * m_val;
230 };
231
232 #endif
233