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