FreeFOAM The Cross-Platform CFD Toolkit
Xfer.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 1991-2010 OpenCFD Ltd.
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::Xfer
26 
27 Description
28  A simple container for copying or transferring objects of type <T>.
29 
30  The wrapped object of type <T> must implement a transfer() method and
31  an operator=() copy method.
32 
33  Since it is decided upon construction of the Xfer object whether the
34  parameter is to be copied or transferred, the contents of the resulting
35  Xfer object can be transferred unconditionally. This greatly simplifies
36  defining constructors or methods in other classes with mixed
37  transfer/copy semantics without requiring 2^N different versions.
38 
39  When transferring between dissimilar types, the xferCopyTo() and
40  xferMoveTo() functions can prove useful. An example is transferring
41  from a DynamicList to a List. Since the
42  List<T>::transfer(List<T>&) method could result in some allocated
43  memory becoming inaccessible, the xferMoveTo() function should be used to
44  invoke the correct List<T>::transfer(DynamicList<T>&) method.
45 
46  @code
47  DynamicList<label> dynLst;
48  ...
49  labelList plainLst( xferMoveTo<labelList>(dynLst) );
50  @endcode
51 
52  Of course, since this example is a very common operation, the
53  DynamicList::xfer() method transfers to a plain List anyhow.
54  It would thus be simpler (and clearer) just to use the following code:
55 
56  @code
57  DynamicList<label> dynLst;
58  ...
59  labelList plainLst(dynLst.xfer());
60  @endcode
61 
62 SeeAlso
63  xferCopy, xferCopyTo, xferMove, xferMoveTo, xferTmp
64 
65 SourceFiles
66  XferI.H
67 
68 \*---------------------------------------------------------------------------*/
69 
70 #ifndef Xfer_H
71 #define Xfer_H
72 
73 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
74 
75 namespace Foam
76 {
77 
78 // Forward declaration of classes
79 template<class T> class tmp;
80 
81 /*---------------------------------------------------------------------------*\
82  Class Xfer Declaration
83 \*---------------------------------------------------------------------------*/
84 
85 template<class T>
86 class Xfer
87 {
88  // Private data
89 
90  //- Pointer to underlying datatype
91  mutable T* ptr_;
92 
93 public:
94 
95  // Constructors
96 
97  //- Store object pointer and manage its deletion
98  // Can also be used later to transfer by assignment
99  inline explicit Xfer(T* = 0);
100 
101  //- Construct by copying or by transferring the parameter contents
102  inline explicit Xfer(T&, bool allowTransfer=false);
103 
104  //- Construct by copying the parameter contents
105  inline explicit Xfer(const T&);
106 
107  //- Construct by transferring the contents
108  inline Xfer(const Xfer<T>&);
109 
110  // Destructor
111 
112  inline ~Xfer();
113 
114  // Member Functions
115 
116  //- Return a null object reference
117  inline static const Xfer<T>& null();
118 
119  // Member Operators
120 
121  //- Transfer the contents into the object
122  inline void operator=(T&);
123 
124  //- Transfer the contents into the object
125  inline void operator=(const Xfer<T>&);
126 
127  //- Reference to the underlying datatype
128  inline T& operator()() const;
129 
130  //- Pointer to the underlying datatype
131  inline T* operator->() const;
132 
133 };
134 
135 
136 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
137 
143 template<class T>
144 inline Xfer<T> xferCopy(const T&);
145 
151 template<class T>
152 inline Xfer<T> xferMove(T&);
153 
154 
160 template<class T>
161 inline Xfer<T> xferTmp(Foam::tmp<T>&);
162 
163 
170 template<class To, class From>
171 inline Xfer<To> xferCopyTo(const From&);
172 
173 
187 template<class To, class From>
188 inline Xfer<To> xferMoveTo(From&);
189 
190 
191 } // End namespace Foam
192 
193 
194 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
195 
196 #include "XferI.H"
197 
198 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
199 
200 #endif
201 
202 // ************************ vim: set sw=4 sts=4 et: ************************ //