ceph/src/boost/libs/ptr_container/doc/ptr_sequence_adapter.html

   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.3.10: http://docutils.sourceforge.net/" />
   7 <title>Boost Pointer Container Library</title>
   8 <style type="text/css">
   9
  10 /*
  11 :Author: David Goodger
  12 :Contact: goodger@users.sourceforge.net
  13 :Date: $Date$
  14 :Revision: $Revision$
  15 :Copyright: This stylesheet has been placed in the public domain.
  16
  17 Default cascading style sheet for the HTML output of Docutils.
  18
  19 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  20 customize this style sheet.
  21 */
  22
  23 /* "! important" is used here to override other ``margin-top`` and
  24    ``margin-bottom`` styles that are later in the stylesheet or
  25    more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
  26 .first {
  27   margin-top: 0 ! important }
  28
  29 .last, .with-subtitle {
  30   margin-bottom: 0 ! important }
  31
  32 .hidden {
  33   display: none }
  34
  35 a.toc-backref {
  36   text-decoration: none ;
  37   color: black }
  38
  39 blockquote.epigraph {
  40   margin: 2em 5em ; }
  41
  42 dl.docutils dd {
  43   margin-bottom: 0.5em }
  44
  45 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  46 dl.docutils dt {
  47   font-weight: bold }
  48 */
  49
  50 div.abstract {
  51   margin: 2em 5em }
  52
  53 div.abstract p.topic-title {
  54   font-weight: bold ;
  55   text-align: center }
  56
  57 div.admonition, div.attention, div.caution, div.danger, div.error,
  58 div.hint, div.important, div.note, div.tip, div.warning {
  59   margin: 2em ;
  60   border: medium outset ;
  61   padding: 1em }
  62
  63 div.admonition p.admonition-title, div.hint p.admonition-title,
  64 div.important p.admonition-title, div.note p.admonition-title,
  65 div.tip p.admonition-title {
  66   font-weight: bold ;
  67   font-family: sans-serif }
  68
  69 div.attention p.admonition-title, div.caution p.admonition-title,
  70 div.danger p.admonition-title, div.error p.admonition-title,
  71 div.warning p.admonition-title {
  72   color: red ;
  73   font-weight: bold ;
  74   font-family: sans-serif }
  75
  76 /* Uncomment (and remove this text!) to get reduced vertical space in
  77    compound paragraphs.
  78 div.compound .compound-first, div.compound .compound-middle {
  79   margin-bottom: 0.5em }
  80
  81 div.compound .compound-last, div.compound .compound-middle {
  82   margin-top: 0.5em }
  83 */
  84
  85 div.dedication {
  86   margin: 2em 5em ;
  87   text-align: center ;
  88   font-style: italic }
  89
  90 div.dedication p.topic-title {
  91   font-weight: bold ;
  92   font-style: normal }
  93
  94 div.figure {
  95   margin-left: 2em }
  96
  97 div.footer, div.header {
  98   clear: both;
  99   font-size: smaller }
 100
 101 div.line-block {
 102   display: block ;
 103   margin-top: 1em ;
 104   margin-bottom: 1em }
 105
 106 div.line-block div.line-block {
 107   margin-top: 0 ;
 108   margin-bottom: 0 ;
 109   margin-left: 1.5em }
 110
 111 div.sidebar {
 112   margin-left: 1em ;
 113   border: medium outset ;
 114   padding: 1em ;
 115   background-color: #ffffee ;
 116   width: 40% ;
 117   float: right ;
 118   clear: right }
 119
 120 div.sidebar p.rubric {
 121   font-family: sans-serif ;
 122   font-size: medium }
 123
 124 div.system-messages {
 125   margin: 5em }
 126
 127 div.system-messages h1 {
 128   color: red }
 129
 130 div.system-message {
 131   border: medium outset ;
 132   padding: 1em }
 133
 134 div.system-message p.system-message-title {
 135   color: red ;
 136   font-weight: bold }
 137
 138 div.topic {
 139   margin: 2em }
 140
 141 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 142 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 143   margin-top: 0.4em }
 144
 145 h1.title {
 146   text-align: center }
 147
 148 h2.subtitle {
 149   text-align: center }
 150
 151 hr.docutils {
 152   width: 75% }
 153
 154 img.align-left {
 155   clear: left }
 156
 157 img.align-right {
 158   clear: right }
 159
 160 img.borderless {
 161   border: 0 }
 162
 163 ol.simple, ul.simple {
 164   margin-bottom: 1em }
 165
 166 ol.arabic {
 167   list-style: decimal }
 168
 169 ol.loweralpha {
 170   list-style: lower-alpha }
 171
 172 ol.upperalpha {
 173   list-style: upper-alpha }
 174
 175 ol.lowerroman {
 176   list-style: lower-roman }
 177
 178 ol.upperroman {
 179   list-style: upper-roman }
 180
 181 p.attribution {
 182   text-align: right ;
 183   margin-left: 50% }
 184
 185 p.caption {
 186   font-style: italic }
 187
 188 p.credits {
 189   font-style: italic ;
 190   font-size: smaller }
 191
 192 p.label {
 193   white-space: nowrap }
 194
 195 p.rubric {
 196   font-weight: bold ;
 197   font-size: larger ;
 198   color: maroon ;
 199   text-align: center }
 200
 201 p.sidebar-title {
 202   font-family: sans-serif ;
 203   font-weight: bold ;
 204   font-size: larger }
 205
 206 p.sidebar-subtitle {
 207   font-family: sans-serif ;
 208   font-weight: bold }
 209
 210 p.topic-title {
 211   font-weight: bold }
 212
 213 pre.address {
 214   margin-bottom: 0 ;
 215   margin-top: 0 ;
 216   font-family: serif ;
 217   font-size: 100% }
 218
 219 pre.line-block {
 220   font-family: serif ;
 221   font-size: 100% }
 222
 223 pre.literal-block, pre.doctest-block {
 224   margin-left: 2em ;
 225   margin-right: 2em ;
 226   background-color: #eeeeee }
 227
 228 span.classifier {
 229   font-family: sans-serif ;
 230   font-style: oblique }
 231
 232 span.classifier-delimiter {
 233   font-family: sans-serif ;
 234   font-weight: bold }
 235
 236 span.interpreted {
 237   font-family: sans-serif }
 238
 239 span.option {
 240   white-space: nowrap }
 241
 242 span.pre {
 243   white-space: pre }
 244
 245 span.problematic {
 246   color: red }
 247
 248 span.section-subtitle {
 249   /* font-size relative to parent (h1..h6 element) */
 250   font-size: 80% }
 251
 252 table.citation {
 253   border-left: solid thin gray }
 254
 255 table.docinfo {
 256   margin: 2em 4em }
 257
 258 table.docutils {
 259   margin-top: 0.5em ;
 260   margin-bottom: 0.5em }
 261
 262 table.footnote {
 263   border-left: solid thin black }
 264
 265 table.docutils td, table.docutils th,
 266 table.docinfo td, table.docinfo th {
 267   padding-left: 0.5em ;
 268   padding-right: 0.5em ;
 269   vertical-align: top }
 270
 271 table.docutils th.field-name, table.docinfo th.docinfo-name {
 272   font-weight: bold ;
 273   text-align: left ;
 274   white-space: nowrap ;
 275   padding-left: 0 }
 276
 277 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 278 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 279   font-size: 100% }
 280
 281 tt.docutils {
 282   background-color: #eeeeee }
 283
 284 ul.auto-toc {
 285   list-style-type: none }
 286
 287 </style>
 288 </head>
 289 <body>
 290 <div class="document" id="boost-pointer-container-library">
 291 <h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
 292 <div class="section">
 293 <h1><a id="class-ptr-sequence-adapter" name="class-ptr-sequence-adapter">Class <tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt></a></h1>
 294 <p>This section describes all the common operations for all the pointer
 295 sequences:</p>
 296 <ul class="simple">
 297 <li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
 298 <li><a class="reference" href="ptr_list.html">ptr_list</a></li>
 299 <li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
 300 </ul>
 301 <p>The <tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt> is also a concrete class that you can use to create custom pointer
 302 containers from.</p>
 303 <p><strong>Hierarchy:</strong></p>
 304 <ul class="simple">
 305 <li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul>
 306 <li><tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt><ul>
 307 <li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
 308 <li><a class="reference" href="ptr_list.html">ptr_list</a></li>
 309 <li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
 310 <li><a class="reference" href="ptr_array.html">ptr_array</a></li>
 311 </ul>
 312 </li>
 313 </ul>
 314 </li>
 315 </ul>
 316 <p><strong>Navigate:</strong></p>
 317 <ul class="simple">
 318 <li><a class="reference" href="ptr_container.html">home</a></li>
 319 <li><a class="reference" href="reference.html">reference</a></li>
 320 </ul>
 321 <p><strong>Synopsis:</strong></p>
 322 <pre class="literal-block">
 323 namespace boost
 324 {
 325
 326     template
 327     &lt;
 328         class T,
 329         class VoidPtrSeq,
 330         class CloneAllocator = heap_clone_allocator
 331     &gt;
 332     class ptr_sequence_adapter
 333     {
 334     public: // <a class="reference" href="#construct-copy-destroy">construct/copy/destroy</a>
 335         template&lt; class InputIterator &gt;
 336         assign( InputIterator first, InputIterator last );
 337         template&lt; class InputRange &gt;
 338         assign( const InputRange&amp; e );
 339
 340     public: // <a class="reference" href="#element-access">element access</a>
 341         T&amp;        front();
 342         const T&amp;  front() const;
 343         T&amp;        back();
 344         const T&amp;  back() const;
 345
 346     public: // <a class="reference" href="#modifiers">modifiers</a>
 347         void      push_back( T* x );
 348         template&lt; class U &gt;
 349         void      push_back( std::auto_ptr&lt;U&gt; x );
 350         auto_type pop_back();
 351         iterator  insert( iterator position, T* x );
 352         template&lt; class U &gt;
 353         iterator  insert( iterator position, std::auto_ptr&lt;U&gt; x );
 354         template&lt; class InputIterator &gt;
 355         void      insert( iterator position, InputIterator first, InputIterator last );
 356         template&lt; class InputRange &gt;
 357         void      insert( iterator position, const InputRange&amp; r );
 358         iterator  erase( iterator position );
 359         iterator  erase( iterator first, iterator last );
 360         template&lt; class Range &gt;
 361         iterator  erase( const Range&amp; r );
 362         void      resize( size_type size );
 363         void      resize( size_type size, T* to_clone );
 364
 365     public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a>
 366         template&lt; class PtrSequence &gt;
 367         void transfer( iterator before, typename PtrSequence::iterator object,
 368                        PtrSequence&amp; from );
 369         template&lt; class PtrSequence &gt;
 370         void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last,
 371                        PtrSequence&amp; from );
 372         void template&lt; class PtrSequence, class Range &gt;
 373         void transfer( iterator before, const Range&amp; r, PtrSequence&amp; from );
 374         template&lt; class PtrSequence &gt;
 375         void transfer( iterator before, PtrSequence&amp; from );
 376
 377     public: // <a class="reference" href="#algorithms">algorithms</a>
 378
 379         void sort();
 380         void sort( iterator first, iterator last );
 381         template&lt; class Compare &gt;
 382         void sort( Compare comp );
 383         template&lt; class Compare &gt;
 384         void sort( iterator begin, iterator end, Compare comp );
 385
 386         void unique();
 387         void unique( iterator first, iterator last );
 388         template&lt; class Compare &gt;
 389         void unique( Compare comp );
 390         template&lt; class Compare &gt;
 391         void unique( iterator begin, iterator end, Compare comp );
 392
 393         template&lt; class Pred &gt;
 394         void erase_if( Pred pred );
 395         template&lt; class Pred &gt;
 396         void erase_if( iterator begin, iterator end, Pred pred );
 397
 398         void merge( ptr_sequence_adapter&amp; r );
 399         template&lt; class Compare &gt;
 400         void merge( ptr_sequence_adapter&amp; r, Compare comp );
 401         void merge( iterator first, iterator last, ptr_sequence_adapter&amp; from );
 402         template&lt; class Compare &gt;
 403         void merge( iterator first, iterator last, ptr_sequence_adapter&amp; from, Compare comp );
 404
 405     public: // <a class="reference" href="ptr_list.html">ptr_list interface</a>
 406
 407     public: // <a class="reference" href="ptr_vector.html">ptr_vector interface</a>
 408
 409     public: // <a class="reference" href="ptr_deque.html">ptr_deque interface</a>
 410
 411     }; //  class 'ptr_sequence_adapter'
 412
 413 } // namespace 'boost'
 414 </pre>
 415 </div>
 416 <div class="section">
 417 <h1><a id="semantics" name="semantics">Semantics</a></h1>
 418 <div class="section">
 419 <h2><a id="semantics-construct-copy-destroy" name="semantics-construct-copy-destroy"><span id="construct-copy-destroy"></span>Semantics: construct/copy/destroy</a></h2>
 420 <ul>
 421 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">&gt;</span>
 422 <span class="pre">void</span> <span class="pre">assign(</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p>
 423 <blockquote>
 424 <ul class="simple">
 425 <li>Requirements: <tt class="docutils literal"><span class="pre">(first,last]</span></tt> is a valid range</li>
 426 <li>Effects: <tt class="docutils literal"><span class="pre">clear();</span> <span class="pre">insert(</span> <span class="pre">first,</span> <span class="pre">last</span> <span class="pre">);</span></tt></li>
 427 <li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">std::distance(</span> <span class="pre">first,</span> <span class="pre">last</span> <span class="pre">);</span></tt></li>
 428 <li>Exception safety: strong guarantee</li>
 429 </ul>
 430 </blockquote>
 431 </li>
 432 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">InputRange</span> <span class="pre">&gt;</span>
 433 <span class="pre">void</span> <span class="pre">assign(</span> <span class="pre">const</span> <span class="pre">InputRange&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
 434 <blockquote>
 435 <ul class="simple">
 436 <li>Effects: <tt class="docutils literal"><span class="pre">assign(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li>
 437 </ul>
 438 </blockquote>
 439 </li>
 440 </ul>
 441 <!-- - ``assign( size_type n, const T& u )``
 442
 443 - Effects: ``clear(); insert( begin(), n, u );``
 444
 445 - Postconditions: ``size() == n``
 446
 447 - Exception safety: Strong guarantee -->
 448 <!-- void resize( size_type sz, const T& x );
 449 Effects:
 450
 451 if ( sz > size() )
 452     insert( end(), sz-size(), x );
 453     else if ( sz < size() )
 454     erase( begin()+sz, end() );
 455     else
 456     ; //do nothing
 457
 458 Postconditions: size() == sz
 459
 460 Exception safety: Strong guarantee -->
 461 </div>
 462 <div class="section">
 463 <h2><a id="semantics-element-access" name="semantics-element-access"><span id="element-access"></span>Semantics: element access</a></h2>
 464 <ul>
 465 <li><p class="first"><tt class="docutils literal"><span class="pre">T&amp;</span> <span class="pre">front();</span></tt></p>
 466 <blockquote>
 467 <ul class="simple">
 468 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li>
 469 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*begin();</span></tt></li>
 470 </ul>
 471 </blockquote>
 472 </li>
 473 <li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">front()</span> <span class="pre">const;</span></tt></p>
 474 <blockquote>
 475 <ul class="simple">
 476 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li>
 477 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*begin();</span></tt></li>
 478 </ul>
 479 </blockquote>
 480 </li>
 481 <li><p class="first"><tt class="docutils literal"><span class="pre">T&amp;</span> <span class="pre">back();</span></tt></p>
 482 <blockquote>
 483 <ul class="simple">
 484 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li>
 485 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*--end();</span></tt></li>
 486 </ul>
 487 </blockquote>
 488 </li>
 489 <li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">back()</span> <span class="pre">const;</span></tt></p>
 490 <blockquote>
 491 <ul class="simple">
 492 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li>
 493 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*--end();</span></tt></li>
 494 </ul>
 495 </blockquote>
 496 </li>
 497 </ul>
 498 </div>
 499 <div class="section">
 500 <h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2>
 501 <ul>
 502 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">push_back(</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
 503 <blockquote>
 504 <ul class="simple">
 505 <li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li>
 506 <li>Effects: Inserts the pointer into container and takes ownership of it</li>
 507 <li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li>
 508 <li>Exception safety: Strong guarantee</li>
 509 </ul>
 510 </blockquote>
 511 </li>
 512 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">push_back(</span> <span class="pre">std::auto_ptr&lt;U&gt;</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
 513 <blockquote>
 514 <ul class="simple">
 515 <li>Effects: <tt class="docutils literal"><span class="pre">push_back(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li>
 516 </ul>
 517 </blockquote>
 518 </li>
 519 </ul>
 520 <!-- - ``void push_back( const T& x );``
 521
 522 - Effects: ``push_back( CloneAllocator::clone( x ) );``
 523
 524 - Exception safety: Strong guarantee -->
 525 <ul>
 526 <li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">pop_back();</span></tt></p>
 527 <blockquote>
 528 <ul class="simple">
 529 <li>Requirements:<tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty()</span></tt></li>
 530 <li>Effects: Removes the last element in the container</li>
 531 <li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one less</li>
 532 <li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li>
 533 <li>Exception safety: Strong guarantee</li>
 534 </ul>
 535 </blockquote>
 536 </li>
 537 <li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
 538 <blockquote>
 539 <ul class="simple">
 540 <li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container and
 541 <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li>
 542 <li>Effects: Inserts <tt class="docutils literal"><span class="pre">x</span></tt> before <tt class="docutils literal"><span class="pre">position</span></tt> and returns an iterator pointing to it</li>
 543 <li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li>
 544 <li>Exception safety: Strong guarantee</li>
 545 </ul>
 546 </blockquote>
 547 </li>
 548 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">&gt;</span> <span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">std::auto_ptr&lt;U&gt;</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
 549 <blockquote>
 550 <ul class="simple">
 551 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">position,</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li>
 552 </ul>
 553 </blockquote>
 554 </li>
 555 </ul>
 556 <!-- - ``iterator insert( iterator position, const T& x );``
 557
 558 - Requirements: ``position`` is a valid iterator from the container
 559
 560 - Effects: ``return insert( position, CloneAllocator::clone( x ) );``
 561
 562 - Exception safety: Strong guarantee
 563
 564 - ``void insert( iterator position, size_type n, const T& x );``
 565
 566 - Requirements: ``position`` is a valid iterator from the container
 567
 568 - Effects: Inserts ``n`` clones of ``x`` before position into the container
 569
 570 - Exception safety: Strong guarantee -->
 571 <ul>
 572 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">&gt;</span>
 573 <span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p>
 574 <blockquote>
 575 <ul class="simple">
 576 <li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container</li>
 577 <li>Effects: Inserts a cloned range before <tt class="docutils literal"><span class="pre">position</span></tt></li>
 578 <li>Exception safety: Strong guarantee</li>
 579 </ul>
 580 </blockquote>
 581 </li>
 582 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">InputRange</span> <span class="pre">&gt;</span>
 583 <span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">const</span> <span class="pre">InputRange&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
 584 <blockquote>
 585 <ul class="simple">
 586 <li>Effects: <tt class="docutils literal"><span class="pre">insert(</span> <span class="pre">position,</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li>
 587 </ul>
 588 </blockquote>
 589 </li>
 590 <li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">position</span> <span class="pre">);</span></tt></p>
 591 <blockquote>
 592 <ul class="simple">
 593 <li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container</li>
 594 <li>Effects: Removes the element defined by <tt class="docutils literal"><span class="pre">position</span></tt> and returns an iterator to the following element</li>
 595 <li>Throws: Nothing</li>
 596 </ul>
 597 </blockquote>
 598 </li>
 599 <li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p>
 600 <blockquote>
 601 <ul class="simple">
 602 <li>Requirements: <tt class="docutils literal"><span class="pre">[first,last)</span></tt> is a valid range</li>
 603 <li>Effects: Removes the range of element defined by <tt class="docutils literal"><span class="pre">[first,last)</span></tt> and returns an iterator to the following element</li>
 604 <li>Throws: Nothing</li>
 605 </ul>
 606 </blockquote>
 607 </li>
 608 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">&gt;</span>
 609 <span class="pre">void</span> <span class="pre">erase(</span> <span class="pre">const</span> <span class="pre">Range&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
 610 <blockquote>
 611 <ul class="simple">
 612 <li>Effects: <tt class="docutils literal"><span class="pre">erase(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li>
 613 </ul>
 614 </blockquote>
 615 </li>
 616 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">resize(</span> <span class="pre">size_type</span> <span class="pre">size</span> <span class="pre">);</span></tt></p>
 617 <blockquote>
 618 <ul class="simple">
 619 <li>Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.</li>
 620 <li>Requirements: <tt class="docutils literal"><span class="pre">T</span></tt> is default constructible</li>
 621 <li>Postcondition: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">size;</span></tt></li>
 622 <li>Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise</li>
 623 </ul>
 624 </blockquote>
 625 </li>
 626 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">resize(</span> <span class="pre">size_type</span> <span class="pre">size,</span> <span class="pre">T*</span> <span class="pre">to_clone</span> <span class="pre">);</span></tt></p>
 627 <blockquote>
 628 <ul class="simple">
 629 <li>Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of <tt class="docutils literal"><span class="pre">*to_clone</span></tt> are inserted at the back.</li>
 630 <li>Postcondition: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">size;</span></tt></li>
 631 <li>Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise</li>
 632 <li>Remarks: <tt class="docutils literal"><span class="pre">to_clone</span> <span class="pre">==</span> <span class="pre">0</span></tt> is valid if the container supports nulls. The container does not take ownership of <tt class="docutils literal"><span class="pre">to_clone</span></tt>.</li>
 633 </ul>
 634 </blockquote>
 635 </li>
 636 </ul>
 637 </div>
 638 <div class="section">
 639 <h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2>
 640 <p>You can use <tt class="docutils literal"><span class="pre">transfer()</span></tt> to move elements between two containers of the same type. Furthermore,
 641 you can also move elements from a container of type <tt class="docutils literal"><span class="pre">T</span></tt> to a container of type <tt class="docutils literal"><span class="pre">U</span></tt> as long as
 642 <tt class="docutils literal"><span class="pre">T::value_type</span></tt> is convertible to <tt class="docutils literal"><span class="pre">U::value_type</span></tt>. An example would be transferring from <tt class="docutils literal"><span class="pre">boost::ptr_vector&lt;Derived&gt;</span></tt>
 643 to <tt class="docutils literal"><span class="pre">boost::ptr_deque&lt;Base&gt;</span></tt>.</p>
 644 <p>(<strong>Remark:</strong> <em>When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.</em>
 645 <em>The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.</em>)</p>
 646 <!--  -->
 647 <ul>
 648 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">PtrSequence</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">object,</span> <span class="pre">PtrSequence&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 649 <blockquote>
 650 <ul class="simple">
 651 <li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.
 652 Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li>
 653 <li>Postconditions: If <tt class="docutils literal"><span class="pre">from.empty()</span></tt>, nothing happens. Otherwise
 654 <tt class="docutils literal"><span class="pre">size()</span></tt> is one more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is one less.</li>
 655 <li>Exception safety: Strong guarantee</li>
 656 </ul>
 657 </blockquote>
 658 </li>
 659 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">PtrSequence</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">first,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">last,</span> <span class="pre">PtrSequence&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 660 <blockquote>
 661 <ul class="simple">
 662 <li>Requirements: <tt class="docutils literal"><span class="pre">from.size()</span> <span class="pre">&gt;=</span> <span class="pre">std::distance(first,last)</span></tt></li>
 663 <li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.
 664 Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li>
 665 <li>Postconditions: If <tt class="docutils literal"><span class="pre">from.empty()</span></tt>, nothing happens. Otherwise,
 666 let <tt class="docutils literal"><span class="pre">N</span> <span class="pre">==</span> <span class="pre">std::distance(first,last);</span></tt> then <tt class="docutils literal"><span class="pre">size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> less.</li>
 667 <li>Exception safety: Strong guarantee</li>
 668 <li>Complexity: Linear or better</li>
 669 </ul>
 670 </blockquote>
 671 </li>
 672 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">PtrSequence,</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">const</span> <span class="pre">Range&amp;</span> <span class="pre">r,</span> <span class="pre">PtrSequence&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 673 <blockquote>
 674 <ul class="simple">
 675 <li>Effects: <tt class="docutils literal"><span class="pre">transfer(before,</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from);</span></tt></li>
 676 </ul>
 677 </blockquote>
 678 </li>
 679 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">PtrSequence&gt;</span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">PtrSequence&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 680 <blockquote>
 681 <ul class="simple">
 682 <li>Effects: <tt class="docutils literal"><span class="pre">transfer(before,</span> <span class="pre">from,</span> <span class="pre">from);</span></tt></li>
 683 </ul>
 684 </blockquote>
 685 </li>
 686 </ul>
 687 </div>
 688 <div class="section">
 689 <h2><a id="semantics-algorithms" name="semantics-algorithms"><span id="algorithms"></span>Semantics: algorithms</a></h2>
 690 <p>The general requirement for these algorithms is that the container <em>does not
 691 contain any nulls</em>.</p>
 692 <ul>
 693 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">sort();</span></tt></p>
 694 </li>
 695 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p>
 696 </li>
 697 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 698 </li>
 699 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 700 <blockquote>
 701 <ul class="simple">
 702 <li>Requirements: (versions without <tt class="docutils literal"><span class="pre">Compare</span></tt>) <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">operator&lt;(</span> <span class="pre">const</span> <span class="pre">T&amp;,</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">)</span></tt> is defined</li>
 703 <li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> arguments</li>
 704 <li>Effects: sorts the entire container or the specified range</li>
 705 <li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li>
 706 <li>Remarks: The versions of <tt class="docutils literal"><span class="pre">sort()</span></tt> that take two iterators are not available for <tt class="docutils literal"><span class="pre">ptr_list</span></tt></li>
 707 </ul>
 708 </blockquote>
 709 </li>
 710 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">unique();</span></tt></p>
 711 </li>
 712 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p>
 713 </li>
 714 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 715 </li>
 716 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 717 <blockquote>
 718 <ul class="simple">
 719 <li>Requirements: (versions without <tt class="docutils literal"><span class="pre">Compare</span></tt>) <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">operator==(</span> <span class="pre">const</span> <span class="pre">T&amp;,</span> <span class="pre">const</span> <span class="pre">T&amp;</span> <span class="pre">)</span></tt> is defined</li>
 720 <li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> arguments</li>
 721 <li>Effects: removes adjacent and equal objects from the entire container or the specified range</li>
 722 <li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li>
 723 </ul>
 724 </blockquote>
 725 </li>
 726 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Pred</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">erase_if(</span> <span class="pre">Pred</span> <span class="pre">pred</span> <span class="pre">);</span></tt></p>
 727 </li>
 728 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Pred</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">erase_if(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Pred</span> <span class="pre">pred</span> <span class="pre">);</span></tt></p>
 729 <blockquote>
 730 <ul class="simple">
 731 <li>Requirements: <tt class="docutils literal"><span class="pre">Pred</span></tt> must take an <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> argument</li>
 732 <li>Effects: removes all elements <tt class="docutils literal"><span class="pre">t</span></tt> for which <tt class="docutils literal"><span class="pre">pred(t)</span></tt> returns <tt class="docutils literal"><span class="pre">true</span></tt> from the entire container or the specified range</li>
 733 <li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li>
 734 </ul>
 735 </blockquote>
 736 </li>
 737 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">ptr_sequence_adapter&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
 738 </li>
 739 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">ptr_sequence_adapter&amp;</span> <span class="pre">r,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 740 </li>
 741 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_sequence_adapter&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 742 </li>
 743 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">&gt;</span> <span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_sequence_adapter&amp;</span> <span class="pre">from,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p>
 744 <blockquote>
 745 <ul class="simple">
 746 <li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> arguments</li>
 747 <li>Requirements: both sequences are sorted wrt. the same predicate</li>
 748 <li>Effects: transfers the entire container or the specified sequence to the container while
 749 ensuring the new sequence is also sorted</li>
 750 <li>Postconditions: (Container versions) <tt class="docutils literal"><span class="pre">r.empty()</span></tt></li>
 751 <li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li>
 752 </ul>
 753 </blockquote>
 754 </li>
 755 </ul>
 756 <hr><table class="docutils field-list" frame="void" rules="none">
 757 <col class="field-name" />
 758 <col class="field-body" />
 759 <tbody valign="top">
 760 <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" href="http://www.boost.org/LICENSE_1_0.txt">LICENSE_1_0.txt</a>).</td>
 761 </tr>
 762 </tbody>
 763 </table>
 764 </div>
 765 </div>
 766 </div>
 767 </body>
 768 </html>