1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="appendix.porting.api" xreflabel="api">
3 <?dbhtml filename="api.html"?>
5 <info><title>API Evolution and Deprecation History</title>
7 <keyword>ISO C++</keyword>
9 <keyword>evolution</keyword>
10 <keyword>deprecation</keyword>
11 <keyword>history</keyword>
18 A list of user-visible changes, in chronological order
21 <section xml:id="api.rel_300"><info><title><constant>3.0</constant></title></info>
25 Extensions moved to <filename class="directory">include/ext</filename>.
29 Include files from the SGI/HP sources that pre-date the ISO standard
30 are added. These files are placed into
31 the <filename class="directory">include/backward</filename> directory and a deprecated warning
32 is added that notifies on inclusion (<literal>-Wno-deprecated</literal>
33 deactivates the warning.)
36 <para>Deprecated include <filename class="headerfile">backward/strstream</filename> added.</para>
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>.
45 <section xml:id="api.rel_310"><info><title><constant>3.1</constant></title></info>
51 Extensions from SGI/HP moved from <code>namespace std</code>
52 to <code>namespace __gnu_cxx</code>. As part of this, the following
54 added: <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>.
58 Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
62 Extensions to tree data structures added in <filename class="headerfile">ext/rb_tree</filename>.
66 Removal of <filename class="headerfile">ext/tree</filename>, moved to <filename class="headerfile">backward/tree.h</filename>.
71 <section xml:id="api.rel_320"><info><title><constant>3.2</constant></title></info>
75 <para>Symbol versioning introduced for shared library.</para>
77 <para>Removal of include <filename class="headerfile">backward/strstream.h</filename>.</para>
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>
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>
93 <para>Error handling in iostreams cleaned up, made consistent. </para>
98 <section xml:id="api.rel_330"><info><title><constant>3.3</constant></title></info>
104 <section xml:id="api.rel_340"><info><title><constant>3.4</constant></title></info>
112 <para> Extensions for generic characters and <code>char_traits</code> added in <filename class="headerfile">ext/pod_char_traits.h</filename>.
116 Support 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.
120 Support for <code>char_traits</code> beyond builtin types.
124 Conformant <code>allocator</code> class and usage in containers. As
125 part of this, the following extensions are
126 added: <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>.
130 This is a change from all previous versions, and may require
131 source-level changes due to allocator-related changes to structures
132 names and template parameters, filenames, and file locations. Some,
133 like <code>__simple_alloc, __allocator, __alloc, </code> and <code>
134 _Alloc_traits</code> have been removed.
137 <para>Default behavior of <code>std::allocator</code> has changed.</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>.
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<T,A></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<T,A></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<T, __alloc></code> is thus the same as
159 <code>allocator<T></code>.
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.
168 <table frame="all" xml:id="table.extension_allocators">
169 <title>Extension Allocators</title>
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"/>
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>
188 <entry><classname>__gnu_cxx::new_allocator<T></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>
194 <entry><classname>__gnu_cxx::malloc_allocator<T></classname></entry>
195 <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
196 <entry><classname>std::__malloc_alloc_template<int></classname></entry>
197 <entry><filename class="headerfile">memory</filename></entry>
200 <entry><classname>__gnu_cxx::debug_allocator<T></classname></entry>
201 <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
202 <entry><classname>std::debug_alloc<T></classname></entry>
203 <entry><filename class="headerfile">memory</filename></entry>
206 <entry><classname>__gnu_cxx::__pool_alloc<T></classname></entry>
207 <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
208 <entry><classname>std::__default_alloc_template<bool,int></classname></entry>
209 <entry><filename class="headerfile">memory</filename></entry>
212 <entry><classname>__gnu_cxx::__mt_alloc<T></classname></entry>
213 <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
218 <entry><classname>__gnu_cxx::bitmap_allocator<T></classname></entry>
219 <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
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.
233 <table frame="all" xml:id="table.extension_allocators2">
234 <title>Extension Allocators Continued</title>
236 <tgroup cols="3" align="left" colsep="1" rowsep="1">
237 <colspec colname="c1"/>
238 <colspec colname="c2"/>
239 <colspec colname="c3"/>
243 <entry>Allocator</entry>
244 <entry>Include</entry>
245 <entry>Version</entry>
251 <entry><classname>__gnu_cxx::array_allocator<T></classname></entry>
252 <entry><filename class="headerfile">ext/array_allocator.h</filename></entry>
256 <entry><classname>__gnu_cxx::throw_allocator<T></classname></entry>
257 <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
266 Debug mode first appears.
270 Precompiled header support <acronym>PCH</acronym> support.
274 Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>.
278 Extension <filename class="headerfile">ext/stdio_sync_filebuf.h</filename> added.
282 Extension <filename class="headerfile">ext/demangle.h</filename> added.
288 <section xml:id="api.rel_400"><info><title><constant>4.0</constant></title></info>
293 TR1 features first appear.
297 Extension allocator <filename class="headerfile">ext/array_allocator.h</filename> added.
301 Extension <code>codecvt</code> specializations moved to <filename class="headerfile">ext/codecvt_specializations.h</filename>.
305 Removal of <filename class="headerfile">ext/demangle.h</filename>.
311 <section xml:id="api.rel_410"><info><title><constant>4.1</constant></title></info>
318 Removal of <filename class="headerfile">cassert</filename> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls.
321 <para> Extensions for policy-based data structures first added. New includes,
322 types, namespace <code>pb_assoc</code>.
327 <para> Extensions for typelists added in <filename class="headerfile">ext/typelist.h</filename>.
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>.
335 <section xml:id="api.rel_420"><info><title><constant>4.2</constant></title></info>
341 <para> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>.
344 <para>TR1 <filename class="headerfile">random</filename>, <filename class="headerfile">complex</filename>, and C compatibility headers added.</para>
346 <para> Extensions for concurrent programming consolidated
347 into <filename class="headerfile">ext/concurrence.h</filename> and <filename class="headerfile">ext/atomicity.h</filename>,
348 including change of namespace to <code>__gnu_cxx</code> in some
350 include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</para>
352 <para> Extensions for type traits consolidated
353 into <filename class="headerfile">ext/type_traits.h</filename>. Additional traits are added
354 (<code>__conditional_type</code>, <code>__enable_if</code>, others.)
357 <para> Extensions for policy-based data structures revised. New includes,
358 types, namespace moved to <code>__pb_ds</code>.
361 <para> Extensions for debug mode modified: now nested in <code>namespace
362 std::__debug</code> and extensions in <code>namespace
363 __gnu_cxx::__debug</code>.</para>
365 <para> Extensions added: <filename class="headerfile">ext/typelist.h</filename>
366 and <filename class="headerfile">ext/throw_allocator.h</filename>.
371 <section xml:id="api.rel_430"><info><title><constant>4.3</constant></title></info>
378 C++0X features first appear.
381 <para>TR1 <filename class="headerfile">regex</filename> and <filename class="headerfile">cmath</filename>'s mathematical special function added.
385 Backward include edit.
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>
401 <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename>
405 <para>Added in C++11</para>
407 <filename class="headerfile">auto_ptr.h</filename> and <filename class="headerfile">binders.h</filename>
414 Header dependency streamlining.
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>
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>
432 Debug mode for <filename class="headerfile">unordered_map</filename> and <filename class="headerfile">unordered_set</filename>.
436 Parallel mode first appears.
439 <para>Variadic template implementations of items in <filename class="headerfile">tuple</filename> and
440 <filename class="headerfile">functional</filename>.
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>.
450 PCH binary files no longer installed. Instead, the source files are installed.
454 Namespace pb_ds moved to __gnu_pb_ds.
460 <section xml:id="api.rel_440"><info><title><constant>4.4</constant></title></info>
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>
488 Updated and improved.
491 <filename class="headerfile">algorithm</filename>,
492 <filename class="headerfile">system_error</filename>,
493 <filename class="headerfile">type_traits</filename>
499 Use of the GNU extension namespace association converted to inline namespaces.
505 Preliminary support for <classname>initializer_list</classname>
506 and defaulted and deleted constructors in container classes.
512 <classname>unique_ptr</classname>.
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.
527 Support for string conversions <function>to_string</function>
528 and <function>to_wstring</function>.
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>.
542 Exception propagation support,
543 including <classname>exception_ptr</classname>, <function>current_exception</function>, <function>copy_exception</function>,
544 and <function>rethrow_exception</function>.
551 Uglification of <literal>try</literal> to <literal>__try</literal>
552 and <literal>catch</literal> to <literal>__catch</literal>.
556 Audit of internal mutex usage, conversion to functions returning static
561 added: <filename class="headerfile">ext/pointer.h</filename>
562 and <filename class="headerfile">ext/extptr_allocator.h</filename>. Support
563 for non-standard pointer types has been added
564 to <classname>vector</classname>
565 and <classname>forward_list</classname>.
569 <section xml:id="api.rel_450"><info><title><constant>4.5</constant></title></info>
584 <filename class="headerfile">functional</filename>,
585 <filename class="headerfile">future</filename>,
586 <filename class="headerfile">random</filename>
592 Updated and improved.
595 <filename class="headerfile">atomic</filename>,
596 <filename class="headerfile">system_error</filename>,
597 <filename class="headerfile">type_traits</filename>
603 Add support for explicit operators and standard layout types.
609 Profile mode first appears.
613 Support for decimal floating-point arithmetic, including <classname>decimal32</classname>, <classname>decimal64</classname>, and <classname>decimal128</classname>.
617 Python pretty-printers are added for use with appropriately-advanced versions of <command>gdb</command>.
621 Audit for application of function attributes nothrow, const, pure, and noreturn.
625 The default behavior for comparing typeinfo names changed, so
626 in <filename class="headerfile">typeinfo</filename>, <literal>__GXX_MERGED_TYPEINFO_NAMES</literal>
627 now defaults to zero.
630 <para> Extensions modified: <filename class="headerfile">ext/throw_allocator.h</filename>.
634 <section xml:id="api.rel_460"><info><title><constant>4.6</constant></title></info>
637 Use constexpr and nullptr where appropriate throughout the library.
641 The library was updated to avoid including
642 <filename class="headerfile">stddef.h</filename> in order
643 to reduce namespace pollution.
646 <para>Reference-count annotations to assist data race detectors.
650 Added <function>make_exception_ptr</function> as an alias of
651 <function>copy_exception</function>.
656 <section xml:id="api.rel_470"><info><title><constant>4.7</constant></title></info>
658 <para>Use of noexcept throughout library.</para>
660 <para>Partial support for C++11 allocators first appears.</para>
663 <classname>monotonic_clock</classname> renamed to
664 <classname>steady_clock</classname> as required by the final C++11
668 <para>A new clocale model for newlib is available.</para>
671 The library was updated to avoid including
672 <filename class="headerfile">unistd.h</filename> in order
673 to reduce namespace pollution.
676 <para>Debug Mode was improved for unordered containers. </para>
680 <section xml:id="api.rel_480"><info><title><constant>4.8</constant></title></info>
683 New random number engines and distributions.
684 Optimisations for random.
687 <para>New --enable-libstdcxx-verbose configure option</para>
690 The --enable-libstdcxx-time configure option becomes unnecessary given a
691 sufficiently recent glibc.
696 <section xml:id="api.rel_490"><info><title><constant>4.9</constant></title></info>
698 <para> Implementation of <classname>regex</classname> completed. </para>
700 <para> C++14 library and TS implementations are added. </para>
702 <para> <function>copy_exception</function> deprecated. </para>
704 <para> <classname>__gnu_cxx::array_allocator</classname> deprecated. </para>
708 <section xml:id="api.rel_50"><info><title><constant>5</constant></title></info>
711 ABI transition adds new implementations of several components, using the
712 <code>abi_tag</code> attribute and the <code>__cxx11</code> inline
713 namespace to distinguish the new entities from the old ones.
719 Use of the new or old ABI can be selected per-translation unit with the
720 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro.
725 New non-reference-counted <classname>string</classname> implementation.
730 New <classname>list</classname> implementation containing a new
731 data member in order to provide O(1) <function>size()</function>.
737 C++11 support completed (movable iostreams, new I/O manipulators,
738 Unicode conversion utilities, atomic operations for
739 <classname>shared_ptr</classname>, functions for notifying condition
740 variables and making futures ready at thread exit).
744 Changed formatting of floating point types when
745 <code>ios_base::fixed|ios_base::scientific</code> is set in a stream's
749 <para> Improved C++14 support and TS implementations. </para>
751 <para> New random number engines and distributions. </para>
754 GDB Xmethods for containers and <classname>unique_ptr</classname> added.
758 <classname>has_trivial_default_constructor</classname>,
759 <classname>has_trivial_copy_constructor</classname> and
760 <classname>has_trivial_copy_assign</classname> deprecated.