Pointer Container Library

Compatible Smart Pointer Type

When specifying parameter or return types in interfaces, the documentation for this library uses the pseudo-type

compatible-smart-ptr<T>

to indicate that the compiler C++ standard is being used to selectively provide or remove interfaces with std::auto_ptr<T> or std::unique_ptr<T>. The exact meaning varies depending on whether the smart pointer type is a parameter or a return type.

Parameter Types:

An interface such as

void container::push_back( compatible-smart-ptr<T> );

indicates that an overload of container::push_back is present for one or both of std::auto_ptr<T>, std::unique_ptr<T>; Boost.Pointer Container provides an overload for each type supported by the compiler. To be completely explicit, if the compiler provides std::auto_ptr, then

void container::push_back( std::auto_ptr<T> );

is present. If the compiler provides std::unique_ptr, then

void container::push_back( std::unique_ptr<T> );

is present. And if the compiler provides both, both overloads are present.

In practice this means that C++98/03 users have access to std::auto_ptr overloads, C++11/14 users have access to overloads taking both std::auto_ptr and std::unique_ptr, and users of C++17 and onwards only have access to std::unique_ptr overloads.

The convention outlined above implies that in certain cases the documentation will make reference to a single function taking the compatible smart pointer pseudo parameter, when in fact two distinct overloaded functions are present. Of course the actual interface depends on compiler settings, so for clarity the class hierarchy reference will only ever refer to a single function.

Return Types:

The case of return types is handled along the same lines as parameter types, subject of course to the restriction that C++ functions cannot be overloaded by return type. Thus, an interface such as

compatible-smart-ptr<T> container::release( );

means that precisely one of std::auto_ptr<T> or std::unique_ptr<T> is used as the return type. If the compiler provides std::auto_ptr<T>, then

std::auto_ptr<T> container::release( );

is present, even if the compiler provides std::unique_ptr. For compilers that only provide std::unique_ptr, the interface above becomes

std::unique_ptr<T> container::release( );

In practice, this means that for users of C++98/03/11/14, such return types are always std::auto_ptr; for users of C++17 and onwards the return type is std::unique_ptr.

Details:

The ISO C++11 standard saw the addition of the smart pointer class template std::unique_ptr, and with it the formal deprecation of std::auto_ptr. After spending C++11 and C++14 with deprecated status, std::auto_ptr has been formally removed as of the ISO C++17 standard. As such, headers mentioning std::auto_ptr may be unusable in standard library implementations which disable std::auto_ptr when C++17 or later is used. Boost.Pointer Container predates the existence of std::unique_ptr, and since Boost v. 1.34 it has provided std::auto_ptr overloads for its interfaces. To provide compatibility across a range of C++ standards, macros are used for compile-time overloading or replacement of std::auto_ptr interfaces with std::unique_ptr interfaces.

Boost.Config defines the macro BOOST_NO_CXX11_SMART_PTR for compilers where std::unique_ptr is not available, and BOOST_NO_AUTO_PTR for compilers where std::auto_ptr is removed (or is defective). These macros are used for compile-time selection of interfaces depending on parameter and return type. For interfaces that take smart pointer parameters, Boost.Pointer Container uses BOOST_NO_AUTO_PTR and BOOST_NO_CXX11_SMART_PTR independently of each other to provide interfaces taking one or both of std::auto_ptr, std::unique_ptr as parameters. For interfaces with smart pointer return types, the Boost.Config macros are used first to check if std::auto_ptr is available, providing std::unique_ptr as the return type only for compilers that provide std::unique_ptr but not std::auto_ptr.

Thus, all mentions of

compatible-smart-ptr<T>

shall be understood to mean that Boost.Config has been used as outlined above to provide a smart pointer interface that is compatible with compiler settings.

Navigate

• home
• reference

---

Copyright:	Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt).