src/OpenFOAM/memory/Xfer/Xfer.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright held by original author
   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 the
  13     Free Software Foundation; either version 2 of the License, or (at your
  14     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, write to the Free Software Foundation,
  23     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  24
  25 Class
  26     Foam::Xfer
  27
  28 Description
  29     A simple container for copying or transferring objects of type \<T\>.
  30
  31     The wrapped object of type \<T\> must implement a transfer() method and
  32     an operator=() copy method.
  33
  34     Since it is decided upon construction of the Xfer object whether the
  35     parameter is to be copied or transferred, the contents of the resulting
  36     Xfer object can be transferred unconditionally. This greatly simplifies
  37     defining constructors or methods in other classes with mixed
  38     transfer/copy semantics without requiring 2^N different versions.
  39
  40     When transferring between dissimilar types, the xferCopyTo() and
  41     xferMoveTo() functions can prove useful. An example is transferring
  42     from a DynamicList to a List.  Since the
  43     List\<T\>::transfer(List\<T\>&) method could result in some allocated
  44     memory becoming inaccessible, the xferMoveTo() function should be used to
  45     invoke the correct List\<T\>::transfer(DynamicList\<T\>&) method.
  46
  47     @code
  48         DynamicList<label> dynLst;
  49         ...
  50         labelList plainLst( xferMoveTo<labelList>(dynLst) );
  51     @endcode
  52
  53     Of course, since this example is a very common operation, the
  54     DynamicList::xfer() method transfers to a plain List anyhow.
  55     It would thus be simpler (and clearer) just to use the following code:
  56
  57     @code
  58         DynamicList<label> dynLst;
  59         ...
  60         labelList plainLst(dynLst.xfer());
  61     @endcode
  62
  63 SeeAlso
  64     xferCopy, xferCopyTo, xferMove, xferMoveTo, xferTmp
  65
  66 SourceFiles
  67     XferI.H
  68
  69 \*---------------------------------------------------------------------------*/
  70
  71 #ifndef Xfer_H
  72 #define Xfer_H
  73
  74 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  75
  76 namespace Foam
  77 {
  78
  79 // Forward declaration of classes
  80 template<class T> class tmp;
  81
  82 /*---------------------------------------------------------------------------*\
  83                            Class Xfer Declaration
  84 \*---------------------------------------------------------------------------*/
  85
  86 template<class T>
  87 class Xfer
  88 {
  89     // Private data
  90
  91         //- Pointer to underlying datatype
  92         mutable T* ptr_;
  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     // Destructor
 112
 113         inline ~Xfer();
 114
 115     // Member Functions
 116
 117         //- Return a null object reference
 118         inline static const Xfer<T>& null();
 119
 120     // Member Operators
 121
 122         //- Transfer the contents into the object
 123         inline void operator=(T&);
 124
 125         //- Transfer the contents into the object
 126         inline void operator=(const Xfer<T>&);
 127
 128         //- Reference to the underlying datatype
 129         inline T& operator()() const;
 130
 131         //- Pointer to the underlying datatype
 132         inline T* operator->() const;
 133
 134 };
 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 */
 144 template<class T>
 145 inline Xfer<T> xferCopy(const T&);
 146
 147 /**
 148  * Construct by transferring the contents of the @a arg
 149  *
 150  * @sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
 151 */
 152 template<class T>
 153 inline Xfer<T> xferMove(T&);
 154
 155
 156 /**
 157  * Construct by transferring the contents of the @a arg
 158  *
 159  * @sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
 160 */
 161 template<class T>
 162 inline Xfer<T> xferTmp(Foam::tmp<T>&);
 163
 164
 165 /**
 166  * Construct by copying the contents of the @a arg
 167  * between dissimilar types
 168  *
 169  * @sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
 170 */
 171 template<class To, class From>
 172 inline Xfer<To> xferCopyTo(const From&);
 173
 174
 175 /**
 176  * Construct by transferring the contents of the @a arg
 177  * between dissimilar types
 178  *
 179  * @par Example Use
 180  * @code
 181  *     DynamicList<label> dynLst;
 182  *     ...
 183  *     labelList plainLst( xferMoveTo<labelList>(dynLst) );
 184  * @endcode
 185  *
 186  * @sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
 187 */
 188 template<class To, class From>
 189 inline Xfer<To> xferMoveTo(From&);
 190
 191
 192 } // End namespace Foam
 193
 194
 195 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 196
 197 #include "XferI.H"
 198
 199 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 200
 201 #endif
 202
 203 // ************************************************************************* //