xref: /netbsd-src/external/gpl3/gcc.old/dist/libstdc++-v3/doc/xml/manual/evolution.xml (revision b7b7574d3bf8eeb51a1fa3977b59142ec6434a55) 
1<sect1 id="appendix.porting.api" xreflabel="api">
2<?dbhtml filename="api.html"?>
3
4<sect1info>
5  <keywordset>
6    <keyword>ISO C++</keyword>
7    <keyword>api</keyword>
8    <keyword>evolution</keyword>
9    <keyword>deprecation</keyword>
10    <keyword>history</keyword>
11  </keywordset>
12</sect1info>
13
14<title>API Evolution and Deprecation History</title>
15
16<para>
17A list of user-visible changes, in chronological order
18</para>
19
20<sect2 id="api.rel_300">
21<title><constant>3.0</constant></title>
22
23  <para>
24Extensions moved to <filename class="directory">include/ext</filename>.
25  </para>
26
27<para>
28Include files from the SGI/HP sources that pre-date the ISO standard
29are added. These files are placed into
30the <filename class="directory">include/backward</filename> directory and a deprecated warning
31is added that notifies on inclusion (<literal>-Wno-deprecated</literal>
32deactivates the warning.)
33</para>
34
35<para>Deprecated include <filename class="headerfile">backward/strstream</filename> added.</para>
36
37<para>Removal of include <filename class="headerfile">builtinbuf.h</filename>, <filename class="headerfile">indstream.h</filename>, <filename class="headerfile">parsestream.h</filename>, <filename class="headerfile">PlotFile.h</filename>, <filename class="headerfile">SFile.h</filename>, <filename class="headerfile">stdiostream.h</filename>, and <filename class="headerfile">stream.h</filename>.
38</para>
39
40
41
42</sect2>
43
44<sect2 id="api.rel_310">
45<title><constant>3.1</constant></title>
46  <para>
47  </para>
48
49<para>
50Extensions from SGI/HP moved from <code>namespace std</code>
51to <code>namespace __gnu_cxx</code>. As part of this, the following
52new includes are
53added: <filename class="headerfile">ext/algorithm</filename>, <filename class="headerfile">ext/functional</filename>, <filename class="headerfile">ext/iterator</filename>, <filename class="headerfile">ext/memory</filename>, and <filename class="headerfile">ext/numeric</filename>.
54</para>
55
56<para>
57Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
58</para>
59
60<para>
61Extensions to tree data structures added in <filename class="headerfile">ext/rb_tree</filename>.
62</para>
63
64<para>
65Removal of <filename class="headerfile">ext/tree</filename>, moved to <filename class="headerfile">backward/tree.h</filename>.
66</para>
67
68</sect2>
69
70<sect2 id="api.rel_320">
71<title><constant>3.2</constant></title>
72  <para>
73  </para>
74<para>Symbol versioning introduced for shared library.</para>
75
76<para>Removal of include <filename class="headerfile">backward/strstream.h</filename>.</para>
77
78<para>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </para>
79
80   <para> For GCC releases from 2.95 through the 3.1 series, defining
81   <literal>__USE_MALLOC</literal> on the gcc command line would change the
82   default allocation strategy to instead use <code> malloc</code> and
83   <function>free</function>. (This same functionality is now spelled <literal>_GLIBCXX_FORCE_NEW</literal>, see
84   <link linkend="manual.intro.using.macros">this page</link>
85   for details.
86   </para>
87
88
89<para>Error handling in iostreams cleaned up, made consistent. </para>
90
91
92</sect2>
93
94<sect2 id="api.rel_330">
95<title><constant>3.3</constant></title>
96  <para>
97  </para>
98</sect2>
99
100<sect2 id="api.rel_340">
101<title><constant>3.4</constant></title>
102  <para>
103  </para>
104<para>
105Large file support.
106</para>
107
108<para> Extensions for generic characters and <code>char_traits</code> added in <filename class="headerfile">ext/pod_char_traits.h</filename>.
109</para>
110
111<para>
112Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality.
113</para>
114
115<para>
116Support for <code>char_traits</code> beyond builtin types.
117</para>
118
119<para>
120Conformant <code>allocator</code> class and usage in containers. As
121part of this, the following extensions are
122added: <filename class="headerfile">ext/bitmap_allocator.h</filename>, <filename class="headerfile">ext/debug_allocator.h</filename>, <filename class="headerfile">ext/mt_allocator.h</filename>, <filename class="headerfile">ext/malloc_allocator.h</filename>,<filename class="headerfile">ext/new_allocator.h</filename>, <filename class="headerfile">ext/pool_allocator.h</filename>.
123</para>
124
125<para>
126This is a change from all previous versions, and may require
127source-level changes due to allocator-related changes to structures
128names and template parameters, filenames, and file locations. Some,
129like <code>__simple_alloc, __allocator, __alloc, </code> and <code>
130_Alloc_traits</code> have been removed.
131</para>
132
133<para>Default behavior of <code>std::allocator</code> has changed.</para>
134
135<para>
136   Previous versions prior to 3.4 cache allocations in a memory
137   pool, instead of passing through to call the global allocation
138   operators (i.e., <classname>__gnu_cxx::pool_allocator</classname>).  More
139   recent versions default to the
140   simpler <classname>__gnu_cxx::new_allocator</classname>.
141</para>
142
143<para> Previously, all allocators were written to the SGI
144   style, and all STL containers expected this interface. This
145   interface had a traits class called <code>_Alloc_traits</code> that
146   attempted to provide more information for compile-time allocation
147   selection and optimization. This traits class had another allocator
148   wrapper, <code>__simple_alloc&lt;T,A&gt;</code>, which was a
149   wrapper around another allocator, A, which itself is an allocator
150   for instances of T. But wait, there's more:
151   <code>__allocator&lt;T,A&gt;</code> is another adapter.  Many of
152   the provided allocator classes were SGI style: such classes can be
153   changed to a conforming interface with this wrapper:
154   <code>__allocator&lt;T, __alloc&gt;</code> is thus the same as
155   <code>allocator&lt;T&gt;</code>.
156   </para>
157
158   <para> The class <classname>allocator</classname> used the typedef
159   <type>__alloc</type> to select an underlying allocator that
160   satisfied memory allocation requests. The selection of this
161   underlying allocator was not user-configurable.
162   </para>
163
164<table frame='all'>
165<title>Extension Allocators</title>
166<tgroup cols='4' align='left' colsep='1' rowsep='1'>
167<colspec colname='c1'></colspec>
168<colspec colname='c2'></colspec>
169<colspec colname='c3'></colspec>
170<colspec colname='c4'></colspec>
171
172  <thead>
173    <row>
174      <entry>Allocator (3.4)</entry>
175      <entry>Header (3.4)</entry>
176      <entry>Allocator (3.[0-3])</entry>
177      <entry>Header (3.[0-3])</entry>
178    </row>
179  </thead>
180
181  <tbody>
182  <row>
183    <entry><classname>__gnu_cxx::new_allocator&lt;T&gt;</classname></entry>
184    <entry><filename class="headerfile">ext/new_allocator.h</filename></entry>
185    <entry><classname>std::__new_alloc</classname></entry>
186    <entry><filename class="headerfile">memory</filename></entry>
187  </row>
188  <row>
189    <entry><classname>__gnu_cxx::malloc_allocator&lt;T&gt;</classname></entry>
190    <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
191    <entry><classname>std::__malloc_alloc_template&lt;int&gt;</classname></entry>
192    <entry><filename class="headerfile">memory</filename></entry>
193  </row>
194  <row>
195    <entry><classname>__gnu_cxx::debug_allocator&lt;T&gt;</classname></entry>
196    <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
197    <entry><classname>std::debug_alloc&lt;T&gt;</classname></entry>
198    <entry><filename class="headerfile">memory</filename></entry>
199  </row>
200  <row>
201    <entry><classname>__gnu_cxx::__pool_alloc&lt;T&gt;</classname></entry>
202    <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
203    <entry><classname>std::__default_alloc_template&lt;bool,int&gt;</classname></entry>
204    <entry><filename class="headerfile">memory</filename></entry>
205  </row>
206  <row>
207    <entry><classname>__gnu_cxx::__mt_alloc&lt;T&gt;</classname></entry>
208    <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
209    <entry> </entry>
210    <entry> </entry>
211  </row>
212  <row>
213    <entry><classname>__gnu_cxx::bitmap_allocator&lt;T&gt;</classname></entry>
214    <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
215    <entry> </entry>
216    <entry> </entry>
217  </row>
218  </tbody>
219</tgroup>
220</table>
221
222   <para> Releases after gcc-3.4 have continued to add to the collection
223   of available allocators. All of these new allocators are
224   standard-style. The following table includes details, along with
225   the first released version of GCC that included the extension allocator.
226   </para>
227
228<table frame='all'>
229<title>Extension Allocators Continued</title>
230<tgroup cols='3' align='left' colsep='1' rowsep='1'>
231<colspec colname='c1'></colspec>
232<colspec colname='c2'></colspec>
233<colspec colname='c3'></colspec>
234
235<thead>
236  <row>
237    <entry>Allocator</entry>
238    <entry>Include</entry>
239    <entry>Version</entry>
240  </row>
241</thead>
242
243<tbody>
244  <row>
245    <entry><classname>__gnu_cxx::array_allocator&lt;T&gt;</classname></entry>
246    <entry><filename class="headerfile">ext/array_allocator.h</filename></entry>
247    <entry>4.0.0</entry>
248  </row>
249  <row>
250    <entry><classname>__gnu_cxx::throw_allocator&lt;T&gt;</classname></entry>
251    <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
252    <entry>4.2.0</entry>
253  </row>
254</tbody>
255</tgroup>
256</table>
257
258
259<para>
260Debug mode first appears.
261</para>
262
263<para>
264Precompiled header support <acronym>PCH</acronym> support.
265</para>
266
267<para>
268Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>.
269</para>
270
271<para>
272Extension <filename class="headerfile">ext/stdio_sync_filebuf.h</filename> added.
273</para>
274
275<para>
276Extension <filename class="headerfile">ext/demangle.h</filename> added.
277</para>
278
279
280</sect2>
281
282<sect2 id="api.rel_400">
283<title><constant>4.0</constant></title>
284  <para>
285  </para>
286<para>
287TR1 features first appear.
288</para>
289
290<para>
291Extension allocator <filename class="headerfile">ext/array_allocator.h</filename> added.
292</para>
293
294<para>
295Extension <code>codecvt</code> specializations moved to <filename class="headerfile">ext/codecvt_specializations.h</filename>.
296</para>
297
298<para>
299Removal of <filename class="headerfile">ext/demangle.h</filename>.
300</para>
301
302
303</sect2>
304
305<sect2 id="api.rel_410">
306<title><constant>4.1</constant></title>
307  <para>
308  </para>
309
310
311<para>
312Removal of <filename class="headerfile">cassert</filename> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls.
313</para>
314
315<para> Extensions for policy-based data structures first added. New includes,
316types, namespace <code>pb_assoc</code>.
317</para>
318
319
320
321<para> Extensions for typelists added in <filename class="headerfile">ext/typelist.h</filename>.
322</para>
323
324<para> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <filename class="headerfile">ext/vstring.h</filename>.
325</para>
326
327</sect2>
328
329<sect2 id="api.rel_420">
330<title><constant>4.2</constant></title>
331  <para>
332  </para>
333
334
335<para> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>.
336</para>
337
338<para>TR1 <filename class="headerfile">random</filename>, <filename class="headerfile">complex</filename>, and C compatibility headers added.</para>
339
340<para> Extensions for concurrent programming consolidated
341into <filename class="headerfile">ext/concurrence.h</filename> and <filename class="headerfile">ext/atomicity.h</filename>,
342including change of namespace to <code>__gnu_cxx</code> in some
343cases. Added types
344include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</para>
345
346<para> Extensions for type traits consolidated
347into <filename class="headerfile">ext/type_traits.h</filename>. Additional traits are added
348(<code>__conditional_type</code>, <code>__enable_if</code>, others.)
349</para>
350
351<para> Extensions for policy-based data structures revised. New includes,
352types, namespace moved to <code>__pb_ds</code>.
353</para>
354
355<para> Extensions for debug mode modified: now nested in <code>namespace
356std::__debug</code> and extensions in <code>namespace
357__gnu_cxx::__debug</code>.</para>
358
359<para> Extensions added: <filename class="headerfile">ext/typelist.h</filename>
360and <filename class="headerfile">ext/throw_allocator.h</filename>.
361</para>
362
363</sect2>
364
365<sect2 id="api.rel_430">
366<title><constant>4.3</constant></title>
367  <para>
368  </para>
369
370
371<para>
372C++0X features first appear.
373</para>
374
375<para>TR1 <filename class="headerfile">regex</filename> and <filename class="headerfile">cmath</filename>'s mathematical special function added.
376</para>
377
378<para>
379Backward include edit.
380</para>
381<itemizedlist>
382  <listitem>
383    <para>Removed</para>
384  <para>
385<filename class="headerfile">algobase.h</filename> <filename class="headerfile">algo.h</filename> <filename class="headerfile">alloc.h</filename> <filename class="headerfile">bvector.h</filename> <filename class="headerfile">complex.h</filename>
386<filename class="headerfile">defalloc.h</filename> <filename class="headerfile">deque.h</filename> <filename class="headerfile">fstream.h</filename> <filename class="headerfile">function.h</filename> <filename class="headerfile">hash_map.h</filename> <filename class="headerfile">hash_set.h</filename>
387<filename class="headerfile">hashtable.h</filename> <filename class="headerfile">heap.h</filename> <filename class="headerfile">iomanip.h</filename> <filename class="headerfile">iostream.h</filename> <filename class="headerfile">istream.h</filename> <filename class="headerfile">iterator.h</filename>
388<filename class="headerfile">list.h</filename> <filename class="headerfile">map.h</filename> <filename class="headerfile">multimap.h</filename> <filename class="headerfile">multiset.h</filename> <filename class="headerfile">new.h</filename> <filename class="headerfile">ostream.h</filename> <filename class="headerfile">pair.h</filename> <filename class="headerfile">queue.h</filename> <filename class="headerfile">rope.h</filename> <filename class="headerfile">set.h</filename> <filename class="headerfile">slist.h</filename> <filename class="headerfile">stack.h</filename> <filename class="headerfile">streambuf.h</filename> <filename class="headerfile">stream.h</filename> <filename class="headerfile">tempbuf.h</filename>
389<filename class="headerfile">tree.h</filename> <filename class="headerfile">vector.h</filename>
390  </para>
391  </listitem>
392  <listitem>
393    <para>Added</para>
394  <para>
395  <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename>
396  </para>
397  </listitem>
398  <listitem>
399    <para>Added in C++0x</para>
400  <para>
401    <filename class="headerfile">auto_ptr.h</filename> and <filename class="headerfile">binders.h</filename>
402  </para>
403  </listitem>
404
405</itemizedlist>
406
407<para>
408Header dependency streamlining.
409</para>
410
411<itemizedlist>
412  <listitem><para><filename class="headerfile">algorithm</filename> no longer includes <filename class="headerfile">climits</filename>, <filename class="headerfile">cstring</filename>, or <filename class="headerfile">iosfwd</filename> </para></listitem>
413  <listitem><para><filename class="headerfile">bitset</filename> no longer includes <filename class="headerfile">istream</filename> or <filename class="headerfile">ostream</filename>, adds <filename class="headerfile">iosfwd</filename> </para></listitem>
414  <listitem><para><filename class="headerfile">functional</filename> no longer includes <filename class="headerfile">cstddef</filename></para></listitem>
415  <listitem><para><filename class="headerfile">iomanip</filename> no longer includes <filename class="headerfile">istream</filename>, <filename class="headerfile">istream</filename>, or <filename class="headerfile">functional</filename>, adds <filename class="headerfile">ioswd</filename> </para></listitem>
416  <listitem><para><filename class="headerfile">numeric</filename> no longer includes <filename class="headerfile">iterator</filename></para></listitem>
417  <listitem><para><filename class="headerfile">string</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">memory</filename></para></listitem>
418
419  <listitem><para><filename class="headerfile">valarray</filename> no longer includes <filename class="headerfile">numeric</filename> or <filename class="headerfile">cstdlib</filename></para></listitem>
420  <listitem><para><filename class="headerfile">tr1/hashtable</filename> no longer includes <filename class="headerfile">memory</filename> or <filename class="headerfile">functional</filename></para></listitem>
421  <listitem><para><filename class="headerfile">tr1/memory</filename> no longer includes <filename class="headerfile">algorithm</filename></para></listitem>
422  <listitem><para><filename class="headerfile">tr1/random</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">fstream</filename></para></listitem>
423</itemizedlist>
424
425<para>
426Debug mode for <filename class="headerfile">unordered_map</filename> and <filename class="headerfile">unordered_set</filename>.
427</para>
428
429<para>
430Parallel mode first appears.
431</para>
432
433<para>Variadic template implementations of items in <filename class="headerfile">tuple</filename> and
434    <filename class="headerfile">functional</filename>.
435</para>
436
437<para>Default <code>what</code> implementations give more elaborate
438    exception strings for <code>bad_cast</code>,
439    <code>bad_typeid</code>, <code>bad_exception</code>, and
440    <code>bad_alloc</code>.
441</para>
442
443<para>
444PCH binary files no longer installed. Instead, the source files are installed.
445</para>
446
447<para>
448Namespace pb_ds moved to __gnu_pb_ds.
449</para>
450
451</sect2>
452
453
454<sect2 id="api.rel_440">
455<title><constant>4.4</constant></title>
456  <para>
457  </para>
458
459<para>
460C++0X features.
461</para>
462
463<itemizedlist>
464<listitem>
465  <para>
466    Added.
467  </para>
468  <para>
469    <filename class="headerfile">atomic</filename>,
470    <filename class="headerfile">chrono</filename>,
471    <filename class="headerfile">condition_variable</filename>,
472    <filename class="headerfile">forward_list</filename>,
473    <filename class="headerfile">initializer_list</filename>,
474    <filename class="headerfile">mutex</filename>,
475    <filename class="headerfile">ratio</filename>,
476    <filename class="headerfile">thread</filename>
477  </para>
478</listitem>
479
480<listitem>
481  <para>
482    Updated and improved.
483  </para>
484  <para>
485    <filename class="headerfile">algorithm</filename>,
486    <filename class="headerfile">system_error</filename>,
487    <filename class="headerfile">type_traits</filename>
488  </para>
489</listitem>
490
491<listitem>
492  <para>
493    Use of the GNU extension namespace association converted to inline namespaces.
494  </para>
495</listitem>
496
497<listitem>
498  <para>
499    Preliminary support for <classname>initializer_list</classname>
500    and defaulted and deleted constructors in container classes.
501  </para>
502</listitem>
503
504<listitem>
505  <para>
506    <classname>unique_ptr</classname>.
507  </para>
508</listitem>
509
510<listitem>
511  <para>
512    Support for new character types <type>char16_t</type>
513    and <type>char32_t</type> added
514    to <classname>char_traits</classname>, <classname>basic_string</classname>, <classname>numeric_limits</classname>,
515    and assorted compile-time type traits.
516  </para>
517</listitem>
518
519<listitem>
520  <para>
521    Support for string conversions <function>to_string</function>
522    and <function>to_wstring</function>.
523  </para>
524</listitem>
525
526<listitem>
527  <para>
528    Member functions taking string arguments were added to iostreams
529    including <classname>basic_filebuf</classname>, <classname>basic_ofstream</classname>,
530    and <classname>basic_ifstream</classname>.
531  </para>
532</listitem>
533
534<listitem>
535  <para>
536    Exception propagation support,
537    including <classname>exception_ptr</classname>, <function>current_exception</function>, <function>copy_exception</function>,
538    and <function>rethrow_exception</function>.
539  </para>
540</listitem>
541</itemizedlist>
542
543
544  <para>
545Uglification of <literal>try</literal> to <literal>__try</literal>
546and <literal>catch</literal> to <literal>__catch</literal>.
547  </para>
548
549  <para>
550Audit of internal mutex usage, conversion to functions returning static
551local mutex.
552  </para>
553
554<para> Extensions
555added: <filename class="headerfile">ext/pointer.h</filename>
556and <filename class="headerfile">ext/extptr_allocator.h</filename>. Support
557for non-standard pointer types has been added
558to <classname>vector</classname>
559and <classname>forward_list</classname>.
560</para>
561</sect2>
562
563<sect2 id="api.rel_450">
564<title><constant>4.5</constant></title>
565  <para>
566  </para>
567
568<para>
569C++0X features.
570</para>
571
572<itemizedlist>
573<listitem>
574  <para>
575    Added.
576  </para>
577  <para>
578    <filename class="headerfile">functional</filename>,
579    <filename class="headerfile">future</filename>,
580    <filename class="headerfile">random</filename>
581  </para>
582</listitem>
583
584<listitem>
585  <para>
586    Updated and improved.
587  </para>
588  <para>
589    <filename class="headerfile">atomic</filename>,
590    <filename class="headerfile">system_error</filename>,
591    <filename class="headerfile">type_traits</filename>
592  </para>
593</listitem>
594
595<listitem>
596  <para>
597    Add support for explicit operators and standard layout types.
598  </para>
599</listitem>
600</itemizedlist>
601
602<para>
603Profile mode first appears.
604</para>
605
606<para>
607Support for decimal floating-point arithmetic, including <classname>decimal32</classname>, <classname>decimal64</classname>, and <classname>decimal128</classname>.
608</para>
609
610<para>
611Python pretty-printers are added for use with appropriately-advanced versions of <command>gdb</command>.
612</para>
613
614<para>
615Audit for application of function attributes notrow, const, pure, and noreturn.
616</para>
617
618<para>
619The default behavior for comparing typeinfo names changed, so
620in <filename class="headerfile">typeinfo</filename>, <literal>__GXX_MERGED_TYPEINFO_NAMES</literal>
621now defaults to zero.
622</para>
623
624<para> Extensions modified: <filename class="headerfile">ext/throw_allocator.h</filename>.
625</para>
626</sect2>
627
628</sect1>
629