libstdc++-v3/doc/xml/manual/evolution.xml

   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>
  17 A 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>
  24 Extensions moved to <filename class="directory">include/ext</filename>.
  25   </para>
  26
  27 <para>
  28 Include files from the SGI/HP sources that pre-date the ISO standard
  29 are added. These files are placed into
  30 the <filename class="directory">include/backward</filename> directory and a deprecated warning
  31 is added that notifies on inclusion (<literal>-Wno-deprecated</literal>
  32 deactivates 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>
  50 Extensions from SGI/HP moved from <code>namespace std</code>
  51 to <code>namespace __gnu_cxx</code>. As part of this, the following
  52 new includes are
  53 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>.
  54 </para>
  55
  56 <para>
  57 Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
  58 </para>
  59
  60 <para>
  61 Extensions to tree data structures added in <filename class="headerfile">ext/rb_tree</filename>.
  62 </para>
  63
  64 <para>
  65 Removal 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>
 105 Large 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>
 112 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.
 113 </para>
 114
 115 <para>
 116 Support for <code>char_traits</code> beyond builtin types.
 117 </para>
 118
 119 <para>
 120 Conformant <code>allocator</code> class and usage in containers. As
 121 part of this, the following extensions are
 122 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>.
 123 </para>
 124
 125 <para>
 126 This is a change from all previous versions, and may require
 127 source-level changes due to allocator-related changes to structures
 128 names and template parameters, filenames, and file locations. Some,
 129 like <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>
 260 Debug mode first appears.
 261 </para>
 262
 263 <para>
 264 Precompiled header support <acronym>PCH</acronym> support.
 265 </para>
 266
 267 <para>
 268 Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>.
 269 </para>
 270
 271 <para>
 272 Extension <filename class="headerfile">ext/stdio_sync_filebuf.h</filename> added.
 273 </para>
 274
 275 <para>
 276 Extension <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>
 287 TR1 features first appear.
 288 </para>
 289
 290 <para>
 291 Extension allocator <filename class="headerfile">ext/array_allocator.h</filename> added.
 292 </para>
 293
 294 <para>
 295 Extension <code>codecvt</code> specializations moved to <filename class="headerfile">ext/codecvt_specializations.h</filename>.
 296 </para>
 297
 298 <para>
 299 Removal 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>
 312 Removal 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,
 316 types, 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
 341 into <filename class="headerfile">ext/concurrence.h</filename> and <filename class="headerfile">ext/atomicity.h</filename>,
 342 including change of namespace to <code>__gnu_cxx</code> in some
 343 cases. Added types
 344 include <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
 347 into <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,
 352 types, namespace moved to <code>__pb_ds</code>.
 353 </para>
 354
 355 <para> Extensions for debug mode modified: now nested in <code>namespace
 356 std::__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>
 360 and <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>
 372 C++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.</para>
 376
 377 <para>
 378 Backward include edit.
 379 </para>
 380 <itemizedlist>
 381   <listitem>
 382     <para>Removed</para>
 383   <para>
 384 <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>
 385 <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>
 386 <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>
 387 <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>
 388 <filename class="headerfile">tree.h</filename> <filename class="headerfile">vector.h</filename>
 389   </para>
 390   </listitem>
 391   <listitem>
 392     <para>Added</para>
 393   <para>
 394   <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename>
 395   </para>
 396   </listitem>
 397   <listitem>
 398     <para>Added in C++0x</para>
 399   <para>
 400     <filename class="headerfile">auto_ptr.h</filename> and <filename class="headerfile">binders.h</filename>
 401   </para>
 402   </listitem>
 403
 404 </itemizedlist>
 405
 406 <para>
 407 Header dependency streamlining.
 408 </para>
 409
 410 <itemizedlist>
 411   <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>
 412   <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>
 413   <listitem><para><filename class="headerfile">functional</filename> no longer includes <filename class="headerfile">cstddef</filename></para></listitem>
 414   <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>
 415   <listitem><para><filename class="headerfile">numeric</filename> no longer includes <filename class="headerfile">iterator</filename></para></listitem>
 416   <listitem><para><filename class="headerfile">string</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">memory</filename></para></listitem>
 417
 418   <listitem><para><filename class="headerfile">valarray</filename> no longer includes <filename class="headerfile">numeric</filename> or <filename class="headerfile">cstdlib</filename></para></listitem>
 419   <listitem><para><filename class="headerfile">tr1/hashtable</filename> no longer includes <filename class="headerfile">memory</filename> or <filename class="headerfile">functional</filename></para></listitem>
 420   <listitem><para><filename class="headerfile">tr1/memory</filename> no longer includes <filename class="headerfile">algorithm</filename></para></listitem>
 421   <listitem><para><filename class="headerfile">tr1/random</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">fstream</filename></para></listitem>
 422 </itemizedlist>
 423
 424 <para>
 425 Debug mode for <filename class="headerfile">unordered_map</filename> and <filename class="headerfile">unordered_set</filename>.
 426 </para>
 427
 428 <para>
 429 Parallel mode first appears.
 430 </para>
 431
 432 <para>Variadic template implementations of items in <filename class="headerfile">tuple</filename> and
 433     <filename class="headerfile">functional</filename>.
 434 </para>
 435
 436 <para>Default <code>what</code> implementations give more elaborate
 437     exception strings for <code>bad_cast</code>,
 438     <code>bad_typeid</code>, <code>bad_exception</code>, and
 439     <code>bad_alloc</code>.
 440 </para>
 441
 442 <para>
 443 PCH binary files no longer installed. Instead, the source files are installed.
 444 </para>
 445
 446 <para>
 447 Namespace pb_ds moved to __gnu_pb_ds.
 448 </para>
 449
 450 </sect2>
 451
 452 </sect1>