0030683: Coding Rules - eliminate CLang compiler warnings -Wreturn-std-move
[occt.git] / src / Standard / Standard_Handle.hxx
1 // Copyright (c) 2014 OPEN CASCADE SAS
2 //
3 // This file is part of Open CASCADE Technology software library.
4 //
5 // This library is free software; you can redistribute it and/or modify it under
6 // the terms of the GNU Lesser General Public License version 2.1 as published
7 // by the Free Software Foundation, with special exception defined in the file
8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
9 // distribution for complete text of the license and disclaimer of any warranty.
10 //
11 // Alternatively, this file may be used under the terms of Open CASCADE
12 // commercial license or contractual agreement.
13
14 #ifndef _Standard_Handle_HeaderFile
15 #define _Standard_Handle_HeaderFile
16
17 #include <Standard_Address.hxx>
18 #include <Standard_Std.hxx>
19 #include <Standard_Stream.hxx>
20 #include <Standard_Transient.hxx>
21
22 class Standard_Transient;
23
24 //! Namespace opencascade is intended for low-level template classes and functions
25 namespace opencascade {
26
27   //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
28   //!
29   //! This class is similar to boost::intrusive_ptr<>. The reference counter
30   //! is part of the base class (Standard_Transient), thus creation of a handle
31   //! does not require allocation of additional memory for the counter.
32   //! All handles to the same object share the common counter; object is deleted
33   //! when the last handle pointing on it is destroyed. It is safe to create a new
34   //! handle from plain C pointer to the object already pointed by another handle.
35   //! The same object can be referenced by handles of different types (as soon as 
36   //! they are compatible with the object type).
37   //!
38   //! Handle has type cast operator to const reference to handle to the base
39   //! types, which allows it to be passed by reference in functions accepting 
40   //! reference to handle to base class, without copying.
41   //!
42   //! By default, the type cast operator is provided also for non-const reference.
43   //! These casts (potentially unsafe) can be disabled by defining macro
44   //! OCCT_HANDLE_NOCAST; if it is defined, generalized copy constructor
45   //! and assignment operators are defined allowing to initialize handle
46   //! of base type from handle to derived type.
47   //!
48   //! Weak pointers are not supported.
49   template <class T>
50   class handle
51   {
52   public:
53     //! STL-compliant typedef of contained type
54     typedef T element_type;
55
56   public:
57   
58     //! Empty constructor
59     handle () : entity(0) {}
60
61     //! Constructor from pointer to new object
62     handle (const T *thePtr) : entity(const_cast<T*>(thePtr))
63     {
64       BeginScope();
65     }
66
67     //! Copy constructor
68     handle (const handle& theHandle) : entity(theHandle.entity)
69     {
70       BeginScope();
71     }
72
73 #ifndef OCCT_NO_RVALUE_REFERENCE
74     //! Move constructor
75     handle (handle&& theHandle) : entity(theHandle.entity)
76     {
77       theHandle.entity = 0;
78     }
79 #endif
80
81     //! Destructor
82     ~handle ()
83     {
84       EndScope();
85     }
86
87     //! Nullify the handle
88     void Nullify()
89     {
90       EndScope();
91     }
92
93     //! Check for being null
94     bool IsNull() const { return entity == 0; } 
95
96     //! Reset by new pointer
97     void reset (T* thePtr)
98     {
99       Assign (thePtr);
100     }
101
102     //! Assignment operator
103     handle& operator= (const handle& theHandle)
104     {
105       Assign (theHandle.entity);
106       return *this;
107     }
108
109     //! Assignment to pointer
110     handle& operator= (const T* thePtr)
111     {
112       Assign (const_cast<T*>(thePtr));
113       return *this;
114     }
115
116 #ifndef OCCT_NO_RVALUE_REFERENCE
117     //! Move operator
118     handle& operator= (handle&& theHandle)
119     {
120       std::swap (this->entity, theHandle.entity);
121       return *this;
122     }
123 #endif
124
125     //! STL-like cast to pointer to referred object (note non-const).
126     //! @sa std::shared_ptr::get()
127     T* get() const { return static_cast<T*>(this->entity); }
128
129     //! Member access operator (note non-const)
130     T* operator-> () const { return static_cast<T*>(this->entity); }
131
132     //! Dereferencing operator (note non-const)
133     T& operator* () const { return *get(); }
134
135     //! Check for equality
136     template <class T2>
137     bool operator== (const handle<T2>& theHandle) const
138     { 
139       return get() == theHandle.get();
140     }
141
142     //! Check for equality
143     template <class T2>
144     bool operator== (const T2 *thePtr) const
145     { 
146       return get() == thePtr;
147     }
148
149     //! Check for equality
150     template <class T2>
151     friend bool operator== (const T2 *left, const handle& right)
152     {
153       return left == right.get();
154     }
155
156     //! Check for inequality
157     template <class T2>
158     bool operator!= (const handle<T2>& theHandle) const
159     {
160       return get() != theHandle.get();
161     }
162
163     //! Check for inequality
164     template <class T2>
165     bool operator!= (const T2 *thePtr) const
166     {
167       return get() != thePtr;
168     }
169
170     //! Check for inequality
171     template <class T2>
172     friend bool operator!= (const T2 *left, const handle& right)
173     {
174       return left != right.get();
175     }
176
177     //! Compare operator for possible use in std::map<> etc. 
178     template <class T2>
179     bool operator< (const handle<T2>& theHandle) const
180     { 
181       return get() < theHandle.get();
182     }
183
184     //! Down casting operator from handle to base type
185     template <class T2>
186     static typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
187       DownCast (const handle<T2>& theObject)
188     {
189       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
190     }
191
192     //! Down casting operator from pointer to base type
193     template <class T2>
194     static typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type 
195       DownCast (const T2* thePtr)
196     {
197       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
198     }
199
200     //! For compatibility, define down casting operator from non-base type, as deprecated
201     template <class T2>
202     Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
203     static handle DownCast (const handle<T2>& theObject, typename opencascade::std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
204     {
205       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
206     }
207
208     //! For compatibility, define down casting operator from non-base type, as deprecated
209     template <class T2>
210     Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
211     static handle DownCast (const T2* thePtr, typename opencascade::std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
212     {
213       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
214     }
215
216 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1300) || \
217     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
218     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)))
219
220     //! Conversion to bool for use in conditional expressions
221     explicit operator bool () const
222     { 
223       return entity != nullptr;
224     }
225
226 #else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
227
228     //! Conversion to bool-compatible type for use in conditional expressions
229     operator Standard_Transient* handle::* () const
230     { 
231       return entity ? &handle::entity : 0;
232     }
233
234 #endif
235
236     // Support of conversions to handle of base type:
237     // - copy and move constructors and assignment operators if OCCT_HANDLE_NOCAST is defined
238     // - operators of upcast to const reference to base type otherwise
239 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1206) || \
240     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
241     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
242
243 #ifdef OCCT_HANDLE_NOCAST
244
245     //! Generalized copy constructor.
246     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
247     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
248     handle (const handle<T2>& theHandle) :
249       entity(theHandle.entity)
250     {
251       BeginScope();
252     }
253
254     //! Generalized move constructor
255     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
256     handle (handle<T2>&& theHandle)
257       : entity(theHandle.entity)
258     {
259       theHandle.entity = 0;
260     }
261
262     //! Generalized assignment operator
263     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
264     handle operator = (const handle<T2>& theHandle)
265     {
266       Assign (theHandle.entity);
267       return *this;
268     }
269
270     //! Generalized move operator
271     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
272     handle& operator= (handle<T2>&& theHandle)
273     {
274       std::swap (this->entity, theHandle.entity);
275       return *this;
276     }
277
278 #else
279
280     //! Upcast to const reference to base type.
281     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
282     operator const handle<T2>& () const
283     {
284       return reinterpret_cast<const handle<T2>&>(*this);
285     }
286
287     //! Upcast to non-const reference to base type.
288     //! NB: this cast can be dangerous, but required for legacy code; see #26377
289     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
290     operator handle<T2>& ()
291     {
292       return reinterpret_cast<handle<T2>&>(*this);
293     }
294
295 #endif /* OCCT_HANDLE_NOCAST */
296
297 #else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
298
299 #ifdef OCCT_HANDLE_NOCAST
300
301     //! Generalized copy constructor.
302     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
303     template <class T2>
304     handle (const handle<T2>& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr) :
305       entity(theHandle.entity)
306     {
307       BeginScope();
308     }
309
310 #ifndef OCCT_NO_RVALUE_REFERENCE
311     //! Generalized move constructor
312     template <class T2>
313     handle (handle<T2>&& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr)
314       : entity(theHandle.entity)
315     {
316       theHandle.entity = 0;
317     }
318 #endif
319
320     //! Generalized assignment operator.
321     template <class T2>
322     handle operator = (const handle<T2>& theHandle)
323     {
324       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
325       (void)aTypeCheckHelperVar;
326       Assign (theHandle.entity);
327       return *this;
328     }
329
330 #ifndef OCCT_NO_RVALUE_REFERENCE
331     //! Generalized move operator
332     template <class T2>
333     handle& operator= (handle<T2>&& theHandle)
334     {
335       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
336       (void)aTypeCheckHelperVar;
337       std::swap (this->entity, theHandle.entity);
338       return *this;
339     }
340 #endif
341
342 #else
343
344     //! Upcast to const reference to base type.
345     //! NB: this implementation will cause ambiguity errors on calls to overloaded
346     //! functions accepting handles to different types, since compatibility is 
347     //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
348     template <class T2>
349     operator const handle<T2>& () const
350     {
351       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
352       // (handle is being cast to const& to handle of non-base type)
353       return reinterpret_cast<typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, const handle<T2>&>::type>(*this);
354     }
355
356     //! Upcast to non-const reference to base type.
357     //! NB: this cast can be dangerous, but required for legacy code; see #26377
358     template <class T2>
359     Standard_DEPRECATED("Passing non-const reference to handle of base type in function is unsafe; use variable of exact type")
360     operator handle<T2>& ()
361     {
362       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
363       // (handle is being cast to const& to handle of non-base type)
364       return reinterpret_cast<typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle<T2>&>::type>(*this);
365     }
366
367 #endif /* OCCT_HANDLE_NOCAST */
368
369 #endif /* compiler switch */
370
371   private:
372
373     //! Assignment
374     void Assign (Standard_Transient *thePtr)
375     {
376       if (thePtr == entity)
377         return;
378       EndScope();
379       entity = thePtr;
380       BeginScope();
381     }
382   
383     //! Increment reference counter of referred object 
384     void BeginScope()
385     {
386       if (entity != 0)
387         entity->IncrementRefCounter();
388     }
389
390     //! Decrement reference counter and if 0, destroy referred object
391     void EndScope()
392     {
393       if (entity != 0 && entity->DecrementRefCounter() == 0)
394         entity->Delete();
395       entity = 0;
396     }
397
398     template <class T2> friend class handle;
399
400   private:
401     Standard_Transient* entity;
402   };
403
404 } // namespace opencascade
405
406 //! Define Handle() macro
407 #define Handle(Class) opencascade::handle<Class>
408
409 //! Computes a hash code for the standard handle, in the range [1, theUpperBound]
410 //! @param TheTransientType the type of the object the handle is referred to
411 //! @param theHandle the standard handle which hash code is to be computed
412 //! @param theUpperBound the upper bound of the range a computing hash code must be within
413 //! @return a computed hash code, in the range [1, theUpperBound]
414 template <class TheTransientType>
415 Standard_Integer HashCode (const Handle (TheTransientType) & theHandle, const Standard_Integer theUpperBound)
416 {
417   return ::HashCode (theHandle.get(), theUpperBound);
418 }
419
420 //! For compatibility with previous versions of OCCT, define Handle_Class alias for opencascade::handle<Class>.
421 #if (defined(_MSC_VER) && _MSC_VER >= 1800) 
422 //! For Visual Studio 2013+, define Handle_Class as non-template class to allow exporting this type in C++/CLI.
423 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; class Handle_##C1 : public Handle(C1) \
424 { \
425 public: \
426   Handle_##C1() {} \
427   Handle_##C1(Handle(C1)&& theHandle) : Handle(C1)(theHandle) {} \
428   template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
429   inline Handle_##C1(const opencascade::handle<T2>& theOther) : Handle(C1)(theOther) {} \
430   template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
431   inline Handle_##C1(const T2* theOther) : Handle(C1)(theOther) {} \
432   template<typename T> inline Handle_##C1& operator=(T theOther) { Handle(C1)::operator=(theOther); return *this; } \
433 };
434 #else
435 //! For other compilers, use simple typedef
436 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
437 #endif
438
439 #define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
440 #define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)
441
442 #endif