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