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