File: temporary_buffer.html

package info (click to toggle)
stl-manual 3.30-6
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k
  • size: 4,092 kB
  • ctags: 4,448
  • sloc: cpp: 17,845; ansic: 2,842; makefile: 41
file content (254 lines) | stat: -rw-r--r-- 8,650 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
<HTML>
<!--
  -- Copyright (c) 1996-1999
  -- Silicon Graphics Computer Systems, Inc.
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Silicon Graphics makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -- Copyright (c) 1994
  -- Hewlett-Packard Company
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Hewlett-Packard Company makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -->
<Head>
<Title>temporary_buffer&lt;ForwardIterator, T&gt;</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
	ALINK="#ff0000"> 
<IMG SRC="CorpID.gif" 
     ALT="SGI" HEIGHT="43" WIDTH="151"> 
<!--end header-->
<BR Clear>
<H1>temporary_buffer&lt;ForwardIterator, T&gt;</H1>

<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "allocators.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
<TD Align=right><Img src = "type.gif" Alt=""   WIDTH = "194"  HEIGHT = "39" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: allocators</TD>
<TD Align=right VAlign=top><b>Component type</b>: type</TD>
</TR>
</Table>

<h3>Description</h3>
Some algorithms, such as <tt><A href="stable_sort.html">stable_sort</A></tt> and <tt><A href="inplace_merge.html">inplace_merge</A></tt>,
are <i>adaptive</i>: they attempt to use extra temporary memory to store
intermediate results, and their run-time complexity is better if that
extra memory is available.  These algorithms use <tt>temporary_buffer</tt>
to allocate that extra memory.
<P>
<tt>temporary_buffer</tt>'s constructor takes two arguments, <tt>first</tt> and
<tt>last</tt>, of type <tt>ForwardIterator</tt>; the constructor allocates
a buffer that is large enough to contain <tt>N</tt> objects of type <tt>T</tt>,
where <tt>0 &lt;= N &lt;= last - first</tt> <A href="#1">[1]</A>, and it fills the buffer with 
objects of type <tt>T</tt>.  The member functions <tt>begin()</tt> and 
<tt>end()</tt> return iterators that point to the beginning and the end
of the buffer.
<P>
Note that the elements in the buffer are guaranteed to be 
initialized; that is, <tt>begin()</tt> points to an object of type
<tt>T</tt>, not to raw memory.   However, the initial values of
the buffer's elements are unspecified.  You should not rely
on them to be initialized to any particular value.
<P>
<tt>temporary_buffer</tt> does not have a copy constructor, or an assignment
operator.  Those operations would have complicated, and not terribly
useful, semantics.
<P>
(Earlier versions of the STL used <tt><A href="get_temporary_buffer.html">get_temporary_buffer</A></tt> and
<tt><A href="return_temporary_buffer.html">return_temporary_buffer</A></tt> instead of <tt>temporary_buffer</tt>.  
<tt>temporary_buffer</tt> is more convenient, because it does not require
using <tt><A href="uninitialized_copy.html">uninitialized_copy</A></tt>, and in some cases it is also more
efficient.  Additionally, it is much easier to write exception-safe
code with <tt>temporary_buffer</tt> than with <tt><A href="get_temporary_buffer.html">get_temporary_buffer</A></tt> and
<tt><A href="return_temporary_buffer.html">return_temporary_buffer</A></tt>.)
<h3>Example</h3>
<pre>
int main()
{
  vector&lt;int&gt; V(50);
  iota(V.begin(), V.end(), 1);

  temporary_buffer&lt;vector&lt;int&gt;::iterator, int&gt; buf(V.begin(), V.end());
  copy(V.rbegin(), V.rbegin() + buf.size(), buf.begin());
  copy(buf.begin(), buf.end(), ostream_iterator&lt;int&gt;(cout, &quot;\n&quot;));
}
</pre>
<h3>Definition</h3>
Defined in the standard header <A href="memory">memory</A>, and in the nonstandard
backward-compatibility header <A href="algo.h">algo.h</A>.
This class is an SGI extension; it is not part of the C++
standard.
<h3>Template parameters</h3>
<Table border>
<TR>
<TH>
Parameter
</TH>
<TH>
Description
</TH>
<TH>
Default
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>ForwardIterator</tt>
</TD>
<TD VAlign=top>
The type of the iterators passed as arguments to
   <tt>temporary_buffer</tt>'s constructor.
</TD>
<TD VAlign=top>
&nbsp;
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>T</tt>
</TD>
<TD VAlign=top>
The type of object stored in the temporary buffer.
</TD>
<TD VAlign=top>
<tt><A href="iterator_traits.html">iterator_traits</A>&lt;ForwardIterator&gt;::value_type</tt> <A href="#2">[2]</A>
</TD>
</tr>
</table>
<h3>Model of</h3>
None.  <tt>temporary_buffer</tt> is vaguely similar to a <A href="Container.html">Container</A>, 
but it does not provide the entire <A href="Container.html">Container</A> interface.  In
particular, it is not a model of <A href="DefaultConstructible.html">DefaultConstructible</A> or
<A href="Assignable.html">Assignable</A>.
<h3>Type requirements</h3>
<UL>
<LI>
<tt>ForwardIterator</tt> is a model of <A href="ForwardIterator.html">Forward Iterator</A>
<LI>
<tt>ForwardIterator</tt> is mutable.
<LI>
<tt>T</tt> has a constructor that can take a single argument of
   <tt>ForwardIterator</tt>'s value type.
</UL>
<h3>Public base classes</h3>
None.
<h3>Members</h3>
<Table border>
<TR>
<TH>
Member
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<pre>
<b>temporary_buffer</b>(ForwardIterator first, 
                 ForwardIterator last)
</pre>
</TD>
<TD VAlign=top>
Allocates a temporary buffer that holds at most <tt>last - first</tt> elements
of type <tt>T</tt>, and constructs those elements.  The initial values of
the elements are unspecified.  Precondition: <tt>[first, last)</tt> is a
valid range.
</TD>
</TR>
<TR>
<TD VAlign=top>
<b><tt>~temporary_buffer</b>()</tt>
</TD>
<TD VAlign=top>
Destroys the elements in the temporary buffer, and deallocates
the buffer itself.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>T* <b>begin</b>()</tt>
</TD>
<TD VAlign=top>
Returns a pointer to the first element in the buffer.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>T* <b>end</b>()</tt>
</TD>
<TD VAlign=top>
Returns a pointer that points one past the last element
in the buffer.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>ptrdiff_t <b>requested_size</b>() const</tt>
</TD>
<TD VAlign=top>
Returns the value <tt>last - first</tt>, where <tt>first</tt> and <tt>last</tt> are
the arguments that were passed to the constructor.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>ptrdiff_t <b>size</b>() const</tt>
</TD>
<TD VAlign=top>
Returns the number of elements in the temporary buffer,
<b><tt>end</b>()- <b>begin</b>()</tt>.  The return value satisfies the constraint
<tt>0&lt;= <b>size</b>() &lt;= requested_size()</tt>. 
</TD>
</tr>
</table>
<h3>New members</h3>
<h3>Notes</h3>
<P><A name="1">[1]</A>
The <i>requested size</i> is <tt>last - first</tt>.  The size of the
temporary buffer is never larger than the requested size, but it might
well be smaller; the size might even be zero.  The intention is that
<tt>temporary_buffer</tt> will allocate as large a buffer as is possible
without hurting performance.  Note that determining this maximum size
is quite difficult: it depends on cache size, physical versus virtual
memory, heap fragmentation, and so on.  A good implementation of
<tt>temporary_buffer</tt> must be nonportable.
<P><A name="2">[2]</A>
The <A href="iterator_traits.html">iterator_traits</A> mechanism relies on partial
specialization of templates.  If your compiler does not yet
implement this features, then you will not be able to use this
default parameter; you will have to provide both template arguments.
<h3>See also</h3>

<!--start footer--> 
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54" 
        ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif" 
        HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright &copy; 
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML>