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