<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>Boost Pointer Container Library</title>
<style type="text/css">
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
padding: 0 0.5em 0 0 ! important }
.first {
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
.subscript {
vertical-align: sub;
font-size: smaller }
.superscript {
vertical-align: super;
font-size: smaller }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
overflow: hidden;
}
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left, object.align-left, table.align-left {
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right, object.align-right, table.align-right {
clear: right ;
float: right ;
margin-left: 1em }
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
div.align-right {
text-align: inherit }
.align-top {
vertical-align: top }
.align-middle {
vertical-align: middle }
.align-bottom {
vertical-align: bottom }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
pre.code .ln { color: grey; }
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
table.docutils.booktabs {
border: 0px;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.docutils.booktabs * {
border: 0px;
}
table.docutils.booktabs th {
border-bottom: thin solid;
text-align: left;
}
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="boost-pointer-container-library">
<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
<h2 class="subtitle" id="compatible-smart-pointer-type">Compatible Smart Pointer Type</h2>
<p>When specifying parameter or return types in interfaces, the documentation
for this library uses the pseudo-type</p>
<pre class="literal-block">
<em>compatible-smart-ptr</em><T>
</pre>
<p>to indicate that the compiler C++ standard is being used to
selectively provide or remove interfaces with <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt> or
<tt class="docutils literal"><span class="pre">std::unique_ptr<T></span></tt>. The exact meaning varies depending on whether
the smart pointer type is a parameter or a return type.</p>
<p><strong>Parameter Types:</strong></p>
<p>An interface such as</p>
<pre class="literal-block">
void container::push_back( <em>compatible-smart-ptr</em><T> );
</pre>
<p>indicates that an overload of <tt class="docutils literal"><span class="pre">container::push_back</span></tt> is present for
one or both of <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt>, <tt class="docutils literal"><span class="pre">std::unique_ptr<T></span></tt>;
Boost.Pointer Container provides an overload for each type supported
by the compiler. To be completely explicit, if the compiler provides
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>, then</p>
<pre class="literal-block">
void container::push_back( std::auto_ptr<T> );
</pre>
<p>is present. If the compiler provides <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, then</p>
<pre class="literal-block">
void container::push_back( std::unique_ptr<T> );
</pre>
<p>is present. And if the compiler provides both, both overloads are
present.</p>
<p>In practice this means that C++98/03 users have access to
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> overloads, C++11/14 users have access to
overloads taking both <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> and <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, and
users of C++17 and onwards only have access to <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>
overloads.</p>
<p>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 <a class="reference external" href="reversible_ptr_container.html">class hierarchy
reference</a> will only ever refer to a
single function.</p>
<p><strong>Return Types:</strong></p>
<p>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</p>
<pre class="literal-block">
<em>compatible-smart-ptr</em><T> container::release( );
</pre>
<p>means that precisely one of <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt> or
<tt class="docutils literal"><span class="pre">std::unique_ptr<T></span></tt> is used as the return type. If the compiler
provides <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt>, then</p>
<pre class="literal-block">
std::auto_ptr<T> container::release( );
</pre>
<p>is present, even if the compiler provides <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>. For
compilers that only provide <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, the interface above
becomes</p>
<pre class="literal-block">
std::unique_ptr<T> container::release( );
</pre>
<p>In practice, this means that for users of C++98/03/11/14, such return
types are always <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>; for users of C++17 and onwards the
return type is <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>.</p>
<p><strong>Details:</strong></p>
<p>The ISO C++11 standard saw the addition of the smart pointer class template
<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, and with it the formal deprecation of
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. After spending C++11 and C++14 with deprecated
status, <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> has been formally removed as of
the ISO C++17 standard. As such, headers mentioning
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> may be unusable in standard library
implementations which disable <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> when C++17 or later
is used. Boost.Pointer Container predates the existence of
<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, and since Boost v. <tt class="docutils literal">1.34</tt> it has provided
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> overloads for its interfaces. To provide
compatibility across a range of C++ standards, macros are used for
compile-time overloading or replacement of <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> interfaces with
<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> interfaces.</p>
<p><a class="reference external" href="../../config/index.html">Boost.Config</a> defines the macro
<tt class="docutils literal">BOOST_NO_CXX11_SMART_PTR</tt> for compilers where
<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> is not available, and <tt class="docutils literal">BOOST_NO_AUTO_PTR</tt> for
compilers where <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> 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 <tt class="docutils literal">BOOST_NO_AUTO_PTR</tt> and
<tt class="docutils literal">BOOST_NO_CXX11_SMART_PTR</tt> independently of each other to provide
interfaces taking one or both of <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>,
<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> as parameters. For interfaces with smart pointer
return types, the Boost.Config macros are used first to check if
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> is available, providing <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> as the
return type only for compilers that provide <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> but
not <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>.</p>
<p>Thus, all mentions of</p>
<pre class="literal-block">
<em>compatible-smart-ptr</em><T>
</pre>
<p>shall be understood to mean that <a class="reference external" href="../../config/index.html">Boost.Config</a> has been used as outlined above to provide
a smart pointer interface that is compatible with compiler settings.</p>
<p><strong>Navigate</strong></p>
<ul class="simple">
<li><a class="reference external" href="ptr_container.html">home</a></li>
<li><a class="reference external" href="reference.html">reference</a></li>
</ul>
<hr><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">LICENSE_1_0.txt</a>).</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>
