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) 2011-2016 OpenFOAM Foundation
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 See also
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 
94 public:
95 
96  // Constructors
97 
98  //- Store object pointer and manage its deletion
99  // Can also be used later to transfer by assignment
100  inline explicit Xfer(T* = 0);
101 
102  //- Construct by copying or by transferring the parameter contents
103  inline explicit Xfer(T&, bool allowTransfer=false);
104 
105  //- Construct by copying the parameter contents
106  inline explicit Xfer(const T&);
107 
108  //- Construct by transferring the contents
109  inline Xfer(const Xfer<T>&);
110 
111 
112  //- Destructor
113  inline ~Xfer();
114 
115 
116  // Member Functions
117 
118  //- Return a null object reference
119  inline static const Xfer<T>& null();
120 
121 
122  // Member Operators
123 
124  //- Transfer the contents into the object
125  inline void operator=(T&);
126 
127  //- Transfer the contents into the object
128  inline void operator=(const Xfer<T>&);
129 
130  //- Reference to the underlying datatype
131  inline T& operator()() const;
132 
133  //- Pointer to the underlying datatype
134  inline T* operator->() const;
135 };
136 
137 
138 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
139 
140 //- Construct by copying the contents of the \a arg
141 //
142 // \sa xferCopyTo, xferMove, xferMoveTo, xferTmp and Foam::Xfer
143 template<class T>
144 inline Xfer<T> xferCopy(const T&);
145 
146 //- Construct by transferring the contents of the \a arg
147 //
148 // \sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
149 template<class T>
150 inline Xfer<T> xferMove(T&);
151 
152 
153 //- Construct by transferring the contents of the \a arg
154 //
155 // \sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
156 template<class T>
157 inline Xfer<T> xferTmp(Foam::tmp<T>&);
158 
159 
160 //- Construct by copying the contents of the \a arg
161 // between dissimilar types
162 //
163 // \sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
164 template<class To, class From>
165 inline Xfer<To> xferCopyTo(const From&);
166 
167 
168 //- Construct by transferring the contents of the \a arg
169 // between dissimilar types
170 //
171 // \par Example Use
172 // \code
173 // DynamicList<label> dynLst;
174 // ...
175 // labelList plainLst( xferMoveTo<labelList>(dynLst) );
176 // \endcode
177 //
178 // \sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
179 template<class To, class From>
180 inline Xfer<To> xferMoveTo(From&);
181 
182 
183 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
184 
185 } // End namespace Foam
186 
187 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
188 
189 #include "XferI.H"
190 
191 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
192 
193 #endif
194 
195 // ************************************************************************* //
A simple container for copying or transferring objects of type <T>.
Definition: Xfer.H:85
Xfer< T > xferCopy(const T &)
Construct by copying the contents of the arg.
void operator=(T &)
Transfer the contents into the object.
Definition: XferI.H:96
Xfer< To > xferCopyTo(const From &)
Construct by copying the contents of the arg.
Xfer< T > xferMove(T &)
Construct by transferring the contents of the arg.
T & operator()() const
Reference to the underlying datatype.
Definition: XferI.H:114
static const Xfer< T > & null()
Return a null object reference.
Definition: XferI.H:31
~Xfer()
Destructor.
Definition: XferI.H:83
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
T * operator->() const
Pointer to the underlying datatype.
Definition: XferI.H:121
Xfer< T > xferTmp(Foam::tmp< T > &)
Construct by transferring the contents of the arg.
Xfer< To > xferMoveTo(From &)
Construct by transferring the contents of the arg.
A class for managing temporary objects.
Definition: PtrList.H:54
Xfer(T *=0)
Store object pointer and manage its deletion.
Definition: XferI.H:40
Namespace for OpenFOAM.