1++++++++++++++++++++++++++++++++++ 2 |Boost| Pointer Container Library 3++++++++++++++++++++++++++++++++++ 4 5.. |Boost| image:: boost.png 6 7Compatible Smart Pointer Type 8----------------------------- 9 10When specifying parameter or return types in interfaces, the documentation 11for this library uses the pseudo-type 12 13.. parsed-literal:: 14 *compatible-smart-ptr*\ <T> 15 16to indicate that the compiler C++ standard is being used to 17selectively provide or remove interfaces with ``std::auto_ptr<T>`` or 18``std::unique_ptr<T>``. The exact meaning varies depending on whether 19the smart pointer type is a parameter or a return type. 20 21**Parameter Types:** 22 23An interface such as 24 25.. parsed-literal:: 26 void container::push_back( *compatible-smart-ptr*\ <T> ); 27 28indicates that an overload of ``container::push_back`` is present for 29one or both of ``std::auto_ptr<T>``, ``std::unique_ptr<T>``: 30Boost.Pointer Container provides an overload for each type supported 31by the compiler. To be completely explicit, if the compiler provides 32``std::auto_ptr``, then 33 34.. parsed-literal:: 35 void container::push_back( std::auto_ptr<T> ); 36 37is present. If the compiler provides ``std::unique_ptr``, then 38 39.. parsed-literal:: 40 void container::push_back( std::unique_ptr<T> ); 41 42is present. And if the compiler provides both, both overloads are 43present. 44 45In practice this means that C++98/03 users have access to 46``std::auto_ptr`` overloads, C++11/14 users have access to 47overloads taking both ``std::auto_ptr`` and ``std::unique_ptr``, and 48users of C++17 and onwards only have access to ``std::unique_ptr`` 49overloads. 50 51The convention outlined above implies that in certain cases the 52documentation will make reference to a single function taking the 53compatible smart pointer pseudo parameter, when in fact two distinct 54overloaded functions are present. Of course the actual interface 55depends on compiler settings, so for clarity the `class hierarchy 56reference <reversible_ptr_container.html>`_ will only ever refer to a 57single function. 58 59**Return Types:** 60 61The case of return types is handled along the same lines as parameter 62types, subject of course to the restriction that C++ functions cannot 63be overloaded by return type. Thus, an interface such as 64 65.. parsed-literal:: 66 *compatible-smart-ptr*\ <T> container::release( ); 67 68means that precisely one of ``std::auto_ptr<T>`` or 69``std::unique_ptr<T>`` is used as the return type. If the compiler 70provides ``std::auto_ptr<T>``, then 71 72.. parsed-literal:: 73 std::auto_ptr<T> container::release( ); 74 75is present, even if the compiler provides ``std::unique_ptr``. For 76compilers that only provide ``std::unique_ptr``, the interface above 77becomes 78 79.. parsed-literal:: 80 std::unique_ptr<T> container::release( ); 81 82In practice, this means that for users of C++98/03/11/14, such return 83types are always ``std::auto_ptr``; for users of C++17 and onwards the 84return type is ``std::unique_ptr``. 85 86**Details:** 87 88The ISO C++11 standard saw the addition of the smart pointer class template 89``std::unique_ptr``, and with it the formal deprecation of 90``std::auto_ptr``. After spending C++11 and C++14 with deprecated 91status, ``std::auto_ptr`` has been formally removed as of 92the ISO C++17 standard. As such, headers mentioning 93``std::auto_ptr`` may be unusable in standard library 94implementations which disable ``std::auto_ptr`` when C++17 or later 95is used. Boost.Pointer Container predates the existence of 96``std::unique_ptr``, and since Boost v. ``1.34`` it has provided 97``std::auto_ptr`` overloads for its interfaces. To provide 98compatibility across a range of C++ standards, macros are used for 99compile-time overloading or replacement of ``std::auto_ptr`` interfaces with 100``std::unique_ptr`` interfaces. 101 102`Boost.Config <../../config/index.html>`_ defines the macro 103``BOOST_NO_CXX11_SMART_PTR`` for compilers where 104``std::unique_ptr`` is not available, and ``BOOST_NO_AUTO_PTR`` for 105compilers where ``std::auto_ptr`` is removed (or is defective). These 106macros are used for compile-time selection of interfaces depending on 107parameter and return type. For interfaces that take smart pointer 108parameters, Boost.Pointer Container uses ``BOOST_NO_AUTO_PTR`` and 109``BOOST_NO_CXX11_SMART_PTR`` independently of each other to provide 110interfaces taking one or both of ``std::auto_ptr``, 111``std::unique_ptr`` as parameters. For interfaces with smart pointer 112return types, the Boost.Config macros are used first to check if 113``std::auto_ptr`` is available, providing ``std::unique_ptr`` as the 114return type only for compilers that provide ``std::unique_ptr`` but 115not ``std::auto_ptr``. 116 117Thus, all mentions of 118 119.. parsed-literal:: 120 *compatible-smart-ptr*\ <T> 121 122shall be understood to mean that `Boost.Config 123<../../config/index.html>`_ has been used as outlined above to provide 124a smart pointer interface that is compatible with compiler settings. 125 126**Navigate** 127 128- `home <ptr_container.html>`_ 129- `reference <reference.html>`_ 130 131.. raw:: html 132 133 <hr> 134 135:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). 136 137__ http://www.boost.org/LICENSE_1_0.txt 138 139
