include/rtl/ref.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 INCLUDED_RTL_REF_HXX
  21 #define INCLUDED_RTL_REF_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <cassert>
  26
  27 #include <sal/types.h>
  28
  29 namespace rtl
  30 {
  31
  32 /** Template reference class for reference type.
  33 */
  34 template <class reference_type>
  35 class Reference
  36 {
  37     /** The <b>reference_type</b> body pointer.
  38      */
  39     reference_type * m_pBody;
  40
  41
  42 public:
  43     /** Constructor...
  44      */
  45     inline Reference()
  46         : m_pBody (NULL)
  47     {}
  48
  49
  50     /** Constructor...
  51      */
  52     inline Reference (reference_type * pBody, __sal_NoAcquire)
  53         : m_pBody (pBody)
  54     {
  55     }
  56
  57     /** Constructor...
  58      */
  59     inline Reference (reference_type * pBody)
  60         : m_pBody (pBody)
  61     {
  62         if (m_pBody)
  63             m_pBody->acquire();
  64     }
  65
  66     /** Copy constructor...
  67      */
  68     inline Reference (const Reference<reference_type> & handle)
  69         : m_pBody (handle.m_pBody)
  70     {
  71         if (m_pBody)
  72             m_pBody->acquire();
  73     }
  74
  75 #ifdef LIBO_INTERNAL_ONLY
  76     /** Move constructor...
  77      */
  78     inline Reference (Reference<reference_type> && handle)
  79         : m_pBody (handle.m_pBody)
  80     {
  81         handle.m_pBody = nullptr;
  82     }
  83 #endif
  84
  85     /** Destructor...
  86      */
  87     inline ~Reference()
  88     {
  89         if (m_pBody)
  90             m_pBody->release();
  91     }
  92
  93     /** Set...
  94          Similar to assignment.
  95      */
  96     inline Reference<reference_type> &
  97     SAL_CALL set (reference_type * pBody)
  98     {
  99         if (pBody)
 100             pBody->acquire();
 101         reference_type * const pOld = m_pBody;
 102         m_pBody = pBody;
 103         if (pOld)
 104             pOld->release();
 105         return *this;
 106     }
 107
 108     /** Assignment.
 109          Unbinds this instance from its body (if bound) and
 110          bind it to the body represented by the handle.
 111      */
 112     inline Reference<reference_type> &
 113     SAL_CALL operator= (const Reference<reference_type> & handle)
 114     {
 115         return set( handle.m_pBody );
 116     }
 117
 118 #ifdef LIBO_INTERNAL_ONLY
 119     /** Assignment.
 120      *   Unbinds this instance from its body (if bound),
 121      *   bind it to the body represented by the handle, and
 122      *   set the body represented by the handle to nullptr.
 123      */
 124     inline Reference<reference_type> &
 125     operator= (Reference<reference_type> && handle)
 126     {
 127         // self-movement guts ourself
 128         if (m_pBody)
 129             m_pBody->release();
 130         m_pBody = handle.m_pBody;
 131         handle.m_pBody = nullptr;
 132         return *this;
 133     }
 134 #endif
 135
 136     /** Assignment...
 137      */
 138     inline Reference<reference_type> &
 139     SAL_CALL operator= (reference_type * pBody)
 140     {
 141         return set( pBody );
 142     }
 143
 144     /** Unbind the body from this handle.
 145          Note that for a handle representing a large body,
 146          "handle.clear().set(new body());" _might_
 147          perform a little bit better than "handle.set(new body());",
 148          since in the second case two large objects exist in memory
 149          (the old body and the new body).
 150      */
 151     inline Reference<reference_type> & SAL_CALL clear()
 152     {
 153         if (m_pBody)
 154         {
 155             reference_type * const pOld = m_pBody;
 156             m_pBody = NULL;
 157             pOld->release();
 158         }
 159         return *this;
 160     }
 161
 162
 163     /** Get the body. Can be used instead of operator->().
 164          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 165          are the same.
 166      */
 167     inline reference_type * SAL_CALL get() const
 168     {
 169         return m_pBody;
 170     }
 171
 172
 173     /** Probably most common used: handle->someBodyOp().
 174      */
 175     inline reference_type * SAL_CALL operator->() const
 176     {
 177         assert(m_pBody != NULL);
 178         return m_pBody;
 179     }
 180
 181
 182     /** Allows (*handle).someBodyOp().
 183     */
 184     inline reference_type & SAL_CALL operator*() const
 185     {
 186         assert(m_pBody != NULL);
 187         return *m_pBody;
 188     }
 189
 190
 191     /** Returns True if the handle does point to a valid body.
 192      */
 193     inline bool SAL_CALL is() const
 194     {
 195         return (m_pBody != NULL);
 196     }
 197
 198
 199     /** Returns True if this points to pBody.
 200      */
 201     inline bool SAL_CALL operator== (const reference_type * pBody) const
 202     {
 203         return (m_pBody == pBody);
 204     }
 205
 206
 207     /** Returns True if handle points to the same body.
 208      */
 209     inline bool
 210     SAL_CALL operator== (const Reference<reference_type> & handle) const
 211     {
 212         return (m_pBody == handle.m_pBody);
 213     }
 214
 215
 216     /** Needed to place References into STL collection.
 217      */
 218     inline bool
 219     SAL_CALL operator!= (const Reference<reference_type> & handle) const
 220     {
 221         return (m_pBody != handle.m_pBody);
 222     }
 223
 224
 225     /** Needed to place References into STL collection.
 226      */
 227     inline bool
 228     SAL_CALL operator< (const Reference<reference_type> & handle) const
 229     {
 230         return (m_pBody < handle.m_pBody);
 231     }
 232
 233
 234     /** Needed to place References into STL collection.
 235      */
 236     inline bool
 237     SAL_CALL operator> (const Reference<reference_type> & handle) const
 238     {
 239         return (m_pBody > handle.m_pBody);
 240     }
 241 };
 242
 243 } // namespace rtl
 244
 245 #endif /* ! INCLUDED_RTL_REF_HXX */
 246
 247 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */