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     /** Move constructor...
  87      */
  88     Reference (Reference<reference_type> && handle) noexcept
  89         : m_pBody (handle.m_pBody)
  90     {
  91         handle.m_pBody = nullptr;
  92     }
  93 #endif
  94
  95 #if defined LIBO_INTERNAL_ONLY
  96     /** Up-casting conversion constructor: Copies interface reference.
  97
  98         Does not work for up-casts to ambiguous bases.
  99
 100         @param rRef another reference
 101     */
 102     template< class derived_type >
 103     inline Reference(
 104         const Reference< derived_type > & rRef,
 105         std::enable_if_t<std::is_base_of_v<reference_type, derived_type>, int> = 0 )
 106         : m_pBody (rRef.get())
 107     {
 108         if (m_pBody)
 109             m_pBody->acquire();
 110     }
 111
 112     /** Up-casting conversion operator to convert to css::uno::Interface
 113
 114         Does not work for up-casts to ambiguous bases.
 115     */
 116     template< class super_type,
 117         std::enable_if_t<std::is_base_of_v<super_type, reference_type>, int> = 0 >
 118     inline operator css::uno::Reference<super_type>() const
 119     {
 120         return css::uno::Reference<super_type>(m_pBody);
 121     }
 122 #endif
 123
 124     /** Destructor...
 125      */
 126     ~Reference() COVERITY_NOEXCEPT_FALSE
 127     {
 128         if (m_pBody)
 129             m_pBody->release();
 130     }
 131
 132     /** Set...
 133          Similar to assignment.
 134      */
 135     Reference<reference_type> &
 136     SAL_CALL set (reference_type * pBody)
 137     {
 138         if (pBody)
 139             pBody->acquire();
 140         reference_type * const pOld = m_pBody;
 141         m_pBody = pBody;
 142         if (pOld)
 143             pOld->release();
 144         return *this;
 145     }
 146
 147     /** Assignment.
 148          Unbinds this instance from its body (if bound) and
 149          bind it to the body represented by the handle.
 150      */
 151     Reference<reference_type> &
 152     SAL_CALL operator= (const Reference<reference_type> & handle)
 153     {
 154         return set( handle.m_pBody );
 155     }
 156
 157 #ifdef LIBO_INTERNAL_ONLY
 158     /** Assignment.
 159      *   Unbinds this instance from its body (if bound),
 160      *   bind it to the body represented by the handle, and
 161      *   set the body represented by the handle to nullptr.
 162      */
 163     Reference<reference_type> &
 164     operator= (Reference<reference_type> && handle)
 165     {
 166         // self-movement guts ourself
 167         if (m_pBody)
 168             m_pBody->release();
 169         m_pBody = handle.m_pBody;
 170         handle.m_pBody = nullptr;
 171         return *this;
 172     }
 173 #endif
 174
 175     /** Assignment...
 176      */
 177     Reference<reference_type> &
 178     SAL_CALL operator= (reference_type * pBody)
 179     {
 180         return set( pBody );
 181     }
 182
 183     /** Unbind the body from this handle.
 184          Note that for a handle representing a large body,
 185          "handle.clear().set(new body());" _might_
 186          perform a little bit better than "handle.set(new body());",
 187          since in the second case two large objects exist in memory
 188          (the old body and the new body).
 189      */
 190     Reference<reference_type> & SAL_CALL clear()
 191     {
 192         if (m_pBody)
 193         {
 194             reference_type * const pOld = m_pBody;
 195             m_pBody = NULL;
 196             pOld->release();
 197         }
 198         return *this;
 199     }
 200
 201
 202     /** Get the body. Can be used instead of operator->().
 203          I.e. handle->someBodyOp() and handle.get()->someBodyOp()
 204          are the same.
 205      */
 206     reference_type * SAL_CALL get() const
 207     {
 208         return m_pBody;
 209     }
 210
 211
 212     /** Probably most common used: handle->someBodyOp().
 213      */
 214     reference_type * SAL_CALL operator->() const
 215     {
 216         assert(m_pBody != NULL);
 217         return m_pBody;
 218     }
 219
 220
 221     /** Allows (*handle).someBodyOp().
 222     */
 223     reference_type & SAL_CALL operator*() const
 224     {
 225         assert(m_pBody != NULL);
 226         return *m_pBody;
 227     }
 228
 229
 230     /** Returns True if the handle does point to a valid body.
 231      */
 232     bool SAL_CALL is() const
 233     {
 234         return (m_pBody != NULL);
 235     }
 236
 237 #if defined LIBO_INTERNAL_ONLY
 238     /** Returns True if the handle does point to a valid body.
 239      */
 240     explicit operator bool() const
 241     {
 242         return is();
 243     }
 244 #endif
 245
 246     /** Returns True if this points to pBody.
 247      */
 248     bool SAL_CALL operator== (const reference_type * pBody) const
 249     {
 250         return (m_pBody == pBody);
 251     }
 252
 253
 254     /** Returns True if handle points to the same body.
 255      */
 256     bool
 257     SAL_CALL operator== (const Reference<reference_type> & handle) const
 258     {
 259         return (m_pBody == handle.m_pBody);
 260     }
 261
 262
 263     /** Needed to place References into STL collection.
 264      */
 265     bool
 266     SAL_CALL operator!= (const Reference<reference_type> & handle) const
 267     {
 268         return (m_pBody != handle.m_pBody);
 269     }
 270
 271
 272     /** Needed to place References into STL collection.
 273      */
 274     bool
 275     SAL_CALL operator< (const Reference<reference_type> & handle) const
 276     {
 277         return (m_pBody < handle.m_pBody);
 278     }
 279
 280
 281     /** Needed to place References into STL collection.
 282      */
 283     bool
 284     SAL_CALL operator> (const Reference<reference_type> & handle) const
 285     {
 286         return (m_pBody > handle.m_pBody);
 287     }
 288 };
 289
 290 } // namespace rtl
 291
 292 #if defined LIBO_INTERNAL_ONLY
 293 namespace std
 294 {
 295
 296 /// @cond INTERNAL
 297 /**
 298   Make rtl::Reference hashable by default for use in STL containers.
 299
 300   @since LibreOffice 6.3
 301 */
 302 template<typename T>
 303 struct hash<::rtl::Reference<T>>
 304 {
 305     std::size_t operator()(::rtl::Reference<T> const & s) const
 306     { return std::size_t(s.get()); }
 307 };
 308 /// @endcond
 309
 310 }
 311
 312 #endif
 313
 314 #endif /* ! INCLUDED_RTL_REF_HXX */
 315
 316 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */