include/cosv/tpl/dyn.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef CSV_DYN_HXX
  21 #define CSV_DYN_HXX
  22
  23
  24
  25
  26 namespace csv
  27 {
  28
  29
  30 /** Dyn owns an object on the heap, which will be automatically
  31     deleted in its D'tor.
  32
  33     Dyn's main purpose is for class members on the heap:
  34     You can't forget to delete them in the D'tor. Constness will be transfered
  35     to the hold object.
  36
  37     Dyn forbids the CopyC'tor and operator=(). So you can't incidentally
  38     run into problems with compiler defined CopyC'tor or operator=() of the
  39     owning class. If you need those, you have to define them explicitly - as
  40     you should do anyway with all classes, that own members on the heap.
  41
  42     Dyn also works with incomplete types.
  43     You only need to write
  44     class DX;
  45     but needn't include  #include <DX>.hxx.
  46     This is a difference to std::auto_ptr, where it is not absolutely clear
  47     if it is allowed to use it with incomplete types.
  48
  49     You can also use Dyn within function bodies, to make them exception safe.
  50
  51     @attention
  52     If you use Dyn with an incomplete type, the owning class needs to
  53     define a non-inline D'tor. Else the compiler will complain.
  54 */
  55 template <class DX>
  56 class Dyn
  57 {
  58   public:
  59     // LIFECYCLE
  60     /// From now on, let_dpObject is owned by this Dyn-object.
  61     explicit            Dyn(
  62                             DX *                let_dpObject = 0);
  63                         ~Dyn();
  64     // OPERATORS
  65     /** This deletes a prevoiusly existing dpObject!
  66         From now on, let_dpObject is owned by this Dyn-object.
  67     */
  68     Dyn<DX> &           operator=(
  69                             DX *                let_dpObject);
  70     /// @return true, if any valid object is hold, false else.
  71                         operator bool() const;
  72
  73     const DX *          operator->() const;
  74     DX *                operator->();
  75
  76     const DX &          operator*() const;
  77     DX &                operator*();
  78
  79     // OPERATIONS
  80     /** @return The hold object on the heap.
  81
  82         @ATTENTION
  83         The caller of the function is responsible to delete
  84         the returned object
  85
  86         @postcond
  87         this->dpObject == 0.
  88     */
  89     DX *                Release();
  90
  91     // INQUIRY
  92     /// Shorthand for operator->(), if implicit overloading of -> can not be used.
  93     const DX *          Ptr() const;
  94
  95     // ACCESS
  96     /// Shorthand for operator->(), if implicit overloading of -> can not be used.
  97     DX *                Ptr();
  98     /// So const objects can return mutable pointers to the owned object.
  99     DX *                MutablePtr() const;
 100
 101   private:
 102       /*  Does NOT set dpObject to zero! Because it is only used
 103           internally in situations where dpObject is set immediately
 104           after.
 105       */
 106       void              Delete();
 107
 108       /**   Forbidden function!
 109           -------------------
 110           Help ensure, that classes with
 111           dynamic pointers use a selfdefined copy constructor
 112           and operator=(). If the default versions of these
 113           functions are used, the compiler will throw an error.
 114       **/
 115                           Dyn( const Dyn<DX> & );
 116       /**   Forbidden function!
 117           -------------------
 118           Help ensure, that classes with
 119           dynamic pointers use a selfdefined copy constructor
 120           and operator=(). If the default versions of these
 121           functions are used, the compiler will throw an error.
 122       **/
 123     Dyn<DX> &           operator=( const Dyn<DX> & );
 124
 125     // DATA
 126     /// An owned heap object. Needs to be deleted by this class.
 127     DX *                dpObject;
 128 };
 129
 130
 131
 132
 133 // IMPLEMENTATION
 134 template <class DX>
 135 void
 136 Dyn<DX>::Delete()
 137 {
 138     if (dpObject != 0)
 139         delete dpObject;
 140 }
 141
 142 template <class DX>
 143 inline
 144 Dyn<DX>::Dyn( DX * let_dpObject )
 145     : dpObject(let_dpObject) {}
 146
 147 template <class DX>
 148 inline
 149 Dyn<DX>::~Dyn()
 150 { Delete(); }
 151
 152
 153 template <class DX>
 154 inline Dyn<DX> &
 155 Dyn<DX>::operator=( DX * let_dpObject )
 156 {
 157     if ( dpObject == let_dpObject )
 158         return *this;
 159
 160     Delete();
 161     dpObject = let_dpObject;
 162     return *this;
 163 }
 164
 165 template <class DX>
 166 inline
 167 Dyn<DX>::operator bool() const
 168 { return dpObject != 0; }
 169
 170 template <class DX>
 171 inline
 172 const DX *
 173 Dyn<DX>::operator->() const
 174 { return dpObject; }
 175
 176 template <class DX>
 177 inline DX *
 178 Dyn<DX>::operator->()
 179 { return dpObject; }
 180
 181 template <class DX>
 182 inline const DX &
 183 Dyn<DX>::operator*() const
 184 { csv_assert(dpObject != 0);
 185   return *dpObject;
 186 }
 187
 188 template <class DX>
 189 inline DX &
 190 Dyn<DX>::operator*()
 191 { csv_assert(dpObject != 0);
 192   return *dpObject;
 193 }
 194
 195 template <class DX>
 196 inline DX *
 197 Dyn<DX>::Release()
 198 { DX * ret = dpObject;
 199   dpObject = 0;
 200   return ret;
 201 }
 202
 203 template <class DX>
 204 inline const DX *
 205 Dyn<DX>::Ptr() const
 206 { return dpObject; }
 207
 208 template <class DX>
 209 inline DX *
 210 Dyn<DX>::Ptr()
 211 { return dpObject; }
 212
 213 template <class DX>
 214 inline DX *
 215 Dyn<DX>::MutablePtr() const
 216 { return dpObject; }
 217
 218 }   // namespace csv
 219
 220
 221
 222
 223 #ifndef CSV_HIDE_DYN
 224 #define Dyn ::csv::Dyn
 225 #endif
 226
 227
 228
 229
 230 #endif
 231
 232 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */