1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" /> 7<title>Boost Pointer Container Library</title> 8<style type="text/css"> 9 10/* 11:Author: David Goodger (goodger@python.org) 12:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ 13:Copyright: This stylesheet has been placed in the public domain. 14 15Default cascading style sheet for the HTML output of Docutils. 16 17See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to 18customize this style sheet. 19*/ 20 21/* used to remove borders from tables and images */ 22.borderless, table.borderless td, table.borderless th { 23 border: 0 } 24 25table.borderless td, table.borderless th { 26 /* Override padding for "table.docutils td" with "! important". 27 The right padding separates the table cells. */ 28 padding: 0 0.5em 0 0 ! important } 29 30.first { 31 /* Override more specific margin styles with "! important". */ 32 margin-top: 0 ! important } 33 34.last, .with-subtitle { 35 margin-bottom: 0 ! important } 36 37.hidden { 38 display: none } 39 40.subscript { 41 vertical-align: sub; 42 font-size: smaller } 43 44.superscript { 45 vertical-align: super; 46 font-size: smaller } 47 48a.toc-backref { 49 text-decoration: none ; 50 color: black } 51 52blockquote.epigraph { 53 margin: 2em 5em ; } 54 55dl.docutils dd { 56 margin-bottom: 0.5em } 57 58object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { 59 overflow: hidden; 60} 61 62/* Uncomment (and remove this text!) to get bold-faced definition list terms 63dl.docutils dt { 64 font-weight: bold } 65*/ 66 67div.abstract { 68 margin: 2em 5em } 69 70div.abstract p.topic-title { 71 font-weight: bold ; 72 text-align: center } 73 74div.admonition, div.attention, div.caution, div.danger, div.error, 75div.hint, div.important, div.note, div.tip, div.warning { 76 margin: 2em ; 77 border: medium outset ; 78 padding: 1em } 79 80div.admonition p.admonition-title, div.hint p.admonition-title, 81div.important p.admonition-title, div.note p.admonition-title, 82div.tip p.admonition-title { 83 font-weight: bold ; 84 font-family: sans-serif } 85 86div.attention p.admonition-title, div.caution p.admonition-title, 87div.danger p.admonition-title, div.error p.admonition-title, 88div.warning p.admonition-title, .code .error { 89 color: red ; 90 font-weight: bold ; 91 font-family: sans-serif } 92 93/* Uncomment (and remove this text!) to get reduced vertical space in 94 compound paragraphs. 95div.compound .compound-first, div.compound .compound-middle { 96 margin-bottom: 0.5em } 97 98div.compound .compound-last, div.compound .compound-middle { 99 margin-top: 0.5em } 100*/ 101 102div.dedication { 103 margin: 2em 5em ; 104 text-align: center ; 105 font-style: italic } 106 107div.dedication p.topic-title { 108 font-weight: bold ; 109 font-style: normal } 110 111div.figure { 112 margin-left: 2em ; 113 margin-right: 2em } 114 115div.footer, div.header { 116 clear: both; 117 font-size: smaller } 118 119div.line-block { 120 display: block ; 121 margin-top: 1em ; 122 margin-bottom: 1em } 123 124div.line-block div.line-block { 125 margin-top: 0 ; 126 margin-bottom: 0 ; 127 margin-left: 1.5em } 128 129div.sidebar { 130 margin: 0 0 0.5em 1em ; 131 border: medium outset ; 132 padding: 1em ; 133 background-color: #ffffee ; 134 width: 40% ; 135 float: right ; 136 clear: right } 137 138div.sidebar p.rubric { 139 font-family: sans-serif ; 140 font-size: medium } 141 142div.system-messages { 143 margin: 5em } 144 145div.system-messages h1 { 146 color: red } 147 148div.system-message { 149 border: medium outset ; 150 padding: 1em } 151 152div.system-message p.system-message-title { 153 color: red ; 154 font-weight: bold } 155 156div.topic { 157 margin: 2em } 158 159h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, 160h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { 161 margin-top: 0.4em } 162 163h1.title { 164 text-align: center } 165 166h2.subtitle { 167 text-align: center } 168 169hr.docutils { 170 width: 75% } 171 172img.align-left, .figure.align-left, object.align-left, table.align-left { 173 clear: left ; 174 float: left ; 175 margin-right: 1em } 176 177img.align-right, .figure.align-right, object.align-right, table.align-right { 178 clear: right ; 179 float: right ; 180 margin-left: 1em } 181 182img.align-center, .figure.align-center, object.align-center { 183 display: block; 184 margin-left: auto; 185 margin-right: auto; 186} 187 188table.align-center { 189 margin-left: auto; 190 margin-right: auto; 191} 192 193.align-left { 194 text-align: left } 195 196.align-center { 197 clear: both ; 198 text-align: center } 199 200.align-right { 201 text-align: right } 202 203/* reset inner alignment in figures */ 204div.align-right { 205 text-align: inherit } 206 207/* div.align-center * { */ 208/* text-align: left } */ 209 210.align-top { 211 vertical-align: top } 212 213.align-middle { 214 vertical-align: middle } 215 216.align-bottom { 217 vertical-align: bottom } 218 219ol.simple, ul.simple { 220 margin-bottom: 1em } 221 222ol.arabic { 223 list-style: decimal } 224 225ol.loweralpha { 226 list-style: lower-alpha } 227 228ol.upperalpha { 229 list-style: upper-alpha } 230 231ol.lowerroman { 232 list-style: lower-roman } 233 234ol.upperroman { 235 list-style: upper-roman } 236 237p.attribution { 238 text-align: right ; 239 margin-left: 50% } 240 241p.caption { 242 font-style: italic } 243 244p.credits { 245 font-style: italic ; 246 font-size: smaller } 247 248p.label { 249 white-space: nowrap } 250 251p.rubric { 252 font-weight: bold ; 253 font-size: larger ; 254 color: maroon ; 255 text-align: center } 256 257p.sidebar-title { 258 font-family: sans-serif ; 259 font-weight: bold ; 260 font-size: larger } 261 262p.sidebar-subtitle { 263 font-family: sans-serif ; 264 font-weight: bold } 265 266p.topic-title { 267 font-weight: bold } 268 269pre.address { 270 margin-bottom: 0 ; 271 margin-top: 0 ; 272 font: inherit } 273 274pre.literal-block, pre.doctest-block, pre.math, pre.code { 275 margin-left: 2em ; 276 margin-right: 2em } 277 278pre.code .ln { color: grey; } /* line numbers */ 279pre.code, code { background-color: #eeeeee } 280pre.code .comment, code .comment { color: #5C6576 } 281pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } 282pre.code .literal.string, code .literal.string { color: #0C5404 } 283pre.code .name.builtin, code .name.builtin { color: #352B84 } 284pre.code .deleted, code .deleted { background-color: #DEB0A1} 285pre.code .inserted, code .inserted { background-color: #A3D289} 286 287span.classifier { 288 font-family: sans-serif ; 289 font-style: oblique } 290 291span.classifier-delimiter { 292 font-family: sans-serif ; 293 font-weight: bold } 294 295span.interpreted { 296 font-family: sans-serif } 297 298span.option { 299 white-space: nowrap } 300 301span.pre { 302 white-space: pre } 303 304span.problematic { 305 color: red } 306 307span.section-subtitle { 308 /* font-size relative to parent (h1..h6 element) */ 309 font-size: 80% } 310 311table.citation { 312 border-left: solid 1px gray; 313 margin-left: 1px } 314 315table.docinfo { 316 margin: 2em 4em } 317 318table.docutils { 319 margin-top: 0.5em ; 320 margin-bottom: 0.5em } 321 322table.footnote { 323 border-left: solid 1px black; 324 margin-left: 1px } 325 326table.docutils td, table.docutils th, 327table.docinfo td, table.docinfo th { 328 padding-left: 0.5em ; 329 padding-right: 0.5em ; 330 vertical-align: top } 331 332table.docutils th.field-name, table.docinfo th.docinfo-name { 333 font-weight: bold ; 334 text-align: left ; 335 white-space: nowrap ; 336 padding-left: 0 } 337 338/* "booktabs" style (no vertical lines) */ 339table.docutils.booktabs { 340 border: 0px; 341 border-top: 2px solid; 342 border-bottom: 2px solid; 343 border-collapse: collapse; 344} 345table.docutils.booktabs * { 346 border: 0px; 347} 348table.docutils.booktabs th { 349 border-bottom: thin solid; 350 text-align: left; 351} 352 353h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, 354h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { 355 font-size: 100% } 356 357ul.auto-toc { 358 list-style-type: none } 359 360</style> 361</head> 362<body> 363<div class="document" id="boost-pointer-container-library"> 364<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1> 365<h2 class="subtitle" id="compatible-smart-pointer-type">Compatible Smart Pointer Type</h2> 366 367<p>When specifying parameter or return types in interfaces, the documentation 368for this library uses the pseudo-type</p> 369<pre class="literal-block"> 370<em>compatible-smart-ptr</em><T> 371</pre> 372<p>to indicate that the compiler C++ standard is being used to 373selectively provide or remove interfaces with <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt> or 374<tt class="docutils literal"><span class="pre">std::unique_ptr<T></span></tt>. The exact meaning varies depending on whether 375the smart pointer type is a parameter or a return type.</p> 376<p><strong>Parameter Types:</strong></p> 377<p>An interface such as</p> 378<pre class="literal-block"> 379void container::push_back( <em>compatible-smart-ptr</em><T> ); 380</pre> 381<p>indicates that an overload of <tt class="docutils literal"><span class="pre">container::push_back</span></tt> is present for 382one 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>; 383Boost.Pointer Container provides an overload for each type supported 384by the compiler. To be completely explicit, if the compiler provides 385<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>, then</p> 386<pre class="literal-block"> 387void container::push_back( std::auto_ptr<T> ); 388</pre> 389<p>is present. If the compiler provides <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, then</p> 390<pre class="literal-block"> 391void container::push_back( std::unique_ptr<T> ); 392</pre> 393<p>is present. And if the compiler provides both, both overloads are 394present.</p> 395<p>In practice this means that C++98/03 users have access to 396<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> overloads, C++11/14 users have access to 397overloads 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 398users of C++17 and onwards only have access to <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> 399overloads.</p> 400<p>The convention outlined above implies that in certain cases the 401documentation will make reference to a single function taking the 402compatible smart pointer pseudo parameter, when in fact two distinct 403overloaded functions are present. Of course the actual interface 404depends on compiler settings, so for clarity the <a class="reference external" href="reversible_ptr_container.html">class hierarchy 405reference</a> will only ever refer to a 406single function.</p> 407<p><strong>Return Types:</strong></p> 408<p>The case of return types is handled along the same lines as parameter 409types, subject of course to the restriction that C++ functions cannot 410be overloaded by return type. Thus, an interface such as</p> 411<pre class="literal-block"> 412<em>compatible-smart-ptr</em><T> container::release( ); 413</pre> 414<p>means that precisely one of <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt> or 415<tt class="docutils literal"><span class="pre">std::unique_ptr<T></span></tt> is used as the return type. If the compiler 416provides <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt>, then</p> 417<pre class="literal-block"> 418std::auto_ptr<T> container::release( ); 419</pre> 420<p>is present, even if the compiler provides <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>. For 421compilers that only provide <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, the interface above 422becomes</p> 423<pre class="literal-block"> 424std::unique_ptr<T> container::release( ); 425</pre> 426<p>In practice, this means that for users of C++98/03/11/14, such return 427types are always <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>; for users of C++17 and onwards the 428return type is <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>.</p> 429<p><strong>Details:</strong></p> 430<p>The ISO C++11 standard saw the addition of the smart pointer class template 431<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt>, and with it the formal deprecation of 432<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. After spending C++11 and C++14 with deprecated 433status, <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> has been formally removed as of 434the ISO C++17 standard. As such, headers mentioning 435<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> may be unusable in standard library 436implementations which disable <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> when C++17 or later 437is used. Boost.Pointer Container predates the existence of 438<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 439<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> overloads for its interfaces. To provide 440compatibility across a range of C++ standards, macros are used for 441compile-time overloading or replacement of <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> interfaces with 442<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> interfaces.</p> 443<p><a class="reference external" href="../../config/index.html">Boost.Config</a> defines the macro 444<tt class="docutils literal">BOOST_NO_CXX11_SMART_PTR</tt> for compilers where 445<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 446compilers where <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> is removed (or is defective). These 447macros are used for compile-time selection of interfaces depending on 448parameter and return type. For interfaces that take smart pointer 449parameters, Boost.Pointer Container uses <tt class="docutils literal">BOOST_NO_AUTO_PTR</tt> and 450<tt class="docutils literal">BOOST_NO_CXX11_SMART_PTR</tt> independently of each other to provide 451interfaces taking one or both of <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>, 452<tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> as parameters. For interfaces with smart pointer 453return types, the Boost.Config macros are used first to check if 454<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 455return type only for compilers that provide <tt class="docutils literal"><span class="pre">std::unique_ptr</span></tt> but 456not <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>.</p> 457<p>Thus, all mentions of</p> 458<pre class="literal-block"> 459<em>compatible-smart-ptr</em><T> 460</pre> 461<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 462a smart pointer interface that is compatible with compiler settings.</p> 463<p><strong>Navigate</strong></p> 464<ul class="simple"> 465<li><a class="reference external" href="ptr_container.html">home</a></li> 466<li><a class="reference external" href="reference.html">reference</a></li> 467</ul> 468<hr><table class="docutils field-list" frame="void" rules="none"> 469<col class="field-name" /> 470<col class="field-body" /> 471<tbody valign="top"> 472<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> 473</tr> 474</tbody> 475</table> 476</div> 477</body> 478</html> 479
