← Back to branch summary

~ubuntu-branches/debian/sid/boost1.49/sid

« back to all changes in this revision

Viewing changes to doc/html/move/move_inserters.html

  • Committer: Package Import Robot
  • Author(s): Steve M. Robbins
  • Date: 2012-02-26 00:31:44 UTC
  • Revision ID: package-import@ubuntu.com-20120226003144-eaytp12cbf6ubpms
Tags: upstream-1.49.0
Import upstream version 1.49.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/html/move/move_inserters.html
 
1
<html>
 
2
<head>
 
3
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 
4
<title>Move inserters</title>
 
5
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
 
6
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
 
7
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
 
8
<link rel="up" href="../move.html" title="Chapter&#160;16.&#160;Boost.Move">
 
9
<link rel="prev" href="move_iterator.html" title="Move iterators">
 
10
<link rel="next" href="move_algorithms.html" title="Move algorithms">
 
11
</head>
 
12
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 
13
<table cellpadding="2" width="100%"><tr>
 
14
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
 
15
<td align="center"><a href="../../../index.html">Home</a></td>
 
16
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
 
17
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
 
18
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
 
19
<td align="center"><a href="../../../more/index.htm">More</a></td>
 
20
</tr></table>
 
21
<hr>
 
22
<div class="spirit-nav">
 
23
<a accesskey="p" href="move_iterator.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../move.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="move_algorithms.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 
24
</div>
 
25
<div class="section">
 
26
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
 
27
<a name="move.move_inserters"></a><a class="link" href="move_inserters.html" title="Move inserters">Move inserters</a>
 
28
</h2></div></div></div>
 
29
<p>
 
30
      Similar to standard insert iterators, it's possible to deal with move insertion
 
31
      in the same way as writing into an array. A special kind of iterator adaptors,
 
32
      called move insert iterators, are provided with this library. With regular
 
33
      iterator classes,
 
34
    </p>
 
35
<pre class="programlisting"><span class="keyword">while</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="special">*</span><span class="identifier">result</span><span class="special">++</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">first</span><span class="special">++;</span>
 
36
</pre>
 
37
<p>
 
38
      causes a range [first,last) to be copied into a range starting with result.
 
39
      The same code with result being an move insert iterator will move insert corresponding
 
40
      elements into the container. This device allows all of the copying algorithms
 
41
      in the library to work in the move insert mode instead of the regular overwrite
 
42
      mode. This library offers 3 move insert iterators and their helper functions:
 
43
    </p>
 
44
<pre class="programlisting"><span class="comment">// Note: C models Container</span>
 
45
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
46
<span class="keyword">class</span> <span class="identifier">back_move_insert_iterator</span><span class="special">;</span>
 
47
 
 
48
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
49
<span class="identifier">back_move_insert_iterator</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">&gt;</span> <span class="identifier">back_move_inserter</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
 
50
 
 
51
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
52
<span class="keyword">class</span> <span class="identifier">front_move_insert_iterator</span><span class="special">;</span>
 
53
 
 
54
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
55
<span class="identifier">front_move_insert_iterator</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">&gt;</span> <span class="identifier">front_move_inserter</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
 
56
 
 
57
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
58
<span class="keyword">class</span> <span class="identifier">move_insert_iterator</span><span class="special">;</span>
 
59
 
 
60
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
 
61
<span class="identifier">move_insert_iterator</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">&gt;</span> <span class="identifier">move_inserter</span><span class="special">(</span><span class="identifier">C</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">it</span><span class="special">);</span>
 
62
</pre>
 
63
<p>
 
64
      A move insert iterator is constructed from a container and possibly one of
 
65
      its iterators pointing to where insertion takes place if it is neither at the
 
66
      beginning nor at the end of the container. Insert iterators satisfy the requirements
 
67
      of output iterators. <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> returns the move insert iterator itself. The
 
68
      assignment <code class="computeroutput"><span class="keyword">operator</span><span class="special">=(</span><span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span></code> is defined on insert iterators to allow writing
 
69
      into them, it inserts x right before where the insert iterator is pointing.
 
70
      In other words, an <code class="computeroutput"><span class="identifier">insert</span> <span class="identifier">iterator</span></code> is like a cursor pointing into the
 
71
      container where the insertion takes place. <code class="computeroutput"><span class="identifier">back_move_iterator</span></code>
 
72
      move inserts elements at the end of a container, <code class="computeroutput"><span class="identifier">front_insert_iterator</span></code>
 
73
      move inserts elements at the beginning of a container, and <code class="computeroutput"><span class="identifier">move_insert_iterator</span></code>
 
74
      move inserts elements where the iterator points to in a container. <code class="computeroutput"><span class="identifier">back_move_inserter</span></code>, <code class="computeroutput"><span class="identifier">front_move_inserter</span></code>,
 
75
      and <code class="computeroutput"><span class="identifier">move_inserter</span></code> are three
 
76
      functions making the insert iterators out of a container. Here's an example
 
77
      of how to use them:
 
78
    </p>
 
79
<p>
 
80
</p>
 
81
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 
82
<span class="preprocessor">#include</span> <span class="string">"movable.hpp"</span>
 
83
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 
84
 
 
85
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span>
 
86
 
 
87
<span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">movable</span><span class="special">&gt;</span> <span class="identifier">list_t</span><span class="special">;</span>
 
88
<span class="keyword">typedef</span> <span class="identifier">list_t</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">l_iterator</span><span class="special">;</span>
 
89
 
 
90
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">MoveInsertIterator</span><span class="special">&gt;</span>
 
91
<span class="keyword">void</span> <span class="identifier">test_move_inserter</span><span class="special">(</span><span class="identifier">list_t</span> <span class="special">&amp;</span><span class="identifier">l2</span><span class="special">,</span> <span class="identifier">MoveInsertIterator</span> <span class="identifier">mit</span><span class="special">)</span>
 
92
<span class="special">{</span>
 
93
   <span class="comment">//Create a list with 10 default constructed objects</span>
 
94
   <span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">movable</span><span class="special">&gt;</span> <span class="identifier">l</span><span class="special">(</span><span class="number">10</span><span class="special">);</span>
 
95
   <span class="identifier">assert</span><span class="special">(!</span><span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()-&gt;</span><span class="identifier">moved</span><span class="special">());</span>
 
96
   <span class="identifier">l2</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
 
97
 
 
98
   <span class="comment">//Move construct</span>
 
99
   <span class="keyword">for</span><span class="special">(</span><span class="identifier">l_iterator</span> <span class="identifier">itbeg</span> <span class="special">=</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">itend</span> <span class="special">=</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="identifier">itbeg</span> <span class="special">!=</span> <span class="identifier">itend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">itbeg</span><span class="special">){</span>
 
100
      <span class="special">*</span><span class="identifier">mit</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">itbeg</span><span class="special">;</span>
 
101
   <span class="special">}</span>
 
102
   <span class="comment">//Check size and status</span>
 
103
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">l2</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
 
104
   <span class="identifier">assert</span><span class="special">(</span><span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()-&gt;</span><span class="identifier">moved</span><span class="special">());</span>
 
105
   <span class="identifier">assert</span><span class="special">(!</span><span class="identifier">l2</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()-&gt;</span><span class="identifier">moved</span><span class="special">());</span>
 
106
<span class="special">}</span>
 
107
 
 
108
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 
109
<span class="special">{</span>
 
110
   <span class="identifier">list_t</span> <span class="identifier">l2</span><span class="special">;</span>
 
111
   <span class="identifier">test_move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">back_move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">));</span>
 
112
   <span class="identifier">test_move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">front_move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">));</span>
 
113
   <span class="identifier">test_move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">move_inserter</span><span class="special">(</span><span class="identifier">l2</span><span class="special">,</span> <span class="identifier">l2</span><span class="special">.</span><span class="identifier">end</span><span class="special">()));</span>
 
114
   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 
115
<span class="special">}</span>
 
116
</pre>
 
117
<p>
 
118
    </p>
 
119
</div>
 
120
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 
121
<td align="left"></td>
 
122
<td align="right"><div class="copyright-footer">Copyright &#169; 2008-2010 Ion Gaztanaga<p>
 
123
        Distributed under the Boost Software License, Version 1.0. (See accompanying
 
124
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 
125
      </p>
 
126
</div></td>
 
127
</tr></table>
 
128
<hr>
 
129
<div class="spirit-nav">
 
130
<a accesskey="p" href="move_iterator.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../move.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="move_algorithms.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 
131
</div>
 
132
</body>
 
133
</html>