src/OpenFOAM/memory/Xfer/Xfer.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright (C) 2011 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 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     inline ~Xfer();
 112
 113     // Member Functions
 114
 115         //- Return a null object reference
 116         inline static const Xfer<T>& null();
 117
 118     // Member Operators
 119
 120         //- Transfer the contents into the object
 121         inline void operator=(T&);
 122
 123         //- Transfer the contents into the object
 124         inline void operator=(const Xfer<T>&);
 125
 126         //- Reference to the underlying datatype
 127         inline T& operator()() const;
 128
 129         //- Pointer to the underlying datatype
 130         inline T* operator->() const;
 131
 132 };
 133
 134
 135 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 136
 137 /**
 138  * Construct by copying the contents of the \a arg
 139  *
 140  * \sa xferCopyTo, xferMove, xferMoveTo, xferTmp and Foam::Xfer
 141 */
 142 template<class T>
 143 inline Xfer<T> xferCopy(const T&);
 144
 145 /**
 146  * Construct by transferring the contents of the \a arg
 147  *
 148  * \sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
 149 */
 150 template<class T>
 151 inline Xfer<T> xferMove(T&);
 152
 153
 154 /**
 155  * Construct by transferring the contents of the \a arg
 156  *
 157  * \sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
 158 */
 159 template<class T>
 160 inline Xfer<T> xferTmp(Foam::tmp<T>&);
 161
 162
 163 /**
 164  * Construct by copying the contents of the \a arg
 165  * between dissimilar types
 166  *
 167  * \sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
 168 */
 169 template<class To, class From>
 170 inline Xfer<To> xferCopyTo(const From&);
 171
 172
 173 /**
 174  * Construct by transferring the contents of the \a arg
 175  * between dissimilar types
 176  *
 177  * \par Example Use
 178  * \code
 179  *     DynamicList<label> dynLst;
 180  *     ...
 181  *     labelList plainLst( xferMoveTo<labelList>(dynLst) );
 182  * \endcode
 183  *
 184  * \sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
 185 */
 186 template<class To, class From>
 187 inline Xfer<To> xferMoveTo(From&);
 188
 189
 190 } // End namespace Foam
 191
 192
 193 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 194
 195 #include "XferI.H"
 196
 197 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 198
 199 #endif
 200
 201 // ************************************************************************* //