<book xmlns="http://docbook.org/ns/docbook" version="5.0" xreflabel="Manual" xml:id="manual"><?dbhtml dir="manual"?><?dbhtml filename="index.html"?><title>The GNU C++ Library Manual</title><info><copyright><year>2000</year><year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year><year>2009</year><year>2010</year><year>2011</year><year>2012</year><year>2013</year><year>2014</year><year>2015</year><year>2016</year><year>2017</year><year>2018</year><year>2019</year><year>2020</year><holder><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.fsf.org">FSF</link></holder></copyright><authorgroup version="5.0"><!--
  <author>
    <firstname>Benjamin</firstname>
    <surname>Kosnik</surname>

    <affiliation>
      <shortaffil>Red Hat</shortaffil>
      <orgname>Red Hat, Inc.</orgname>
      <address>
	<email>libstdc++@gcc.gnu.org</email>
      </address>
    </affiliation>

    <personblurb>
      <para>
      </para>
    </personblurb>
  </author>
--><author><personname><firstname>Paolo</firstname><surname>Carlini</surname></personname><personblurb><para>
	TR1, LWG Active, Closed, Defects lists.
      </para></personblurb></author><author><personname><firstname>Phil</firstname><surname>Edwards</surname></personname><personblurb><para>
	Originating author, started HOWTO and FAQ, worked on sections
	Demangling, Macros, Strings, Iterators, Backwards
	Compatibility, SGI Extensions, Configure, Build, Install.
      </para></personblurb></author><author><personname><firstname>Doug</firstname><surname>Gregor</surname></personname><personblurb><para>
	Debug Mode, TR1 function objects
      </para></personblurb></author><author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname><personblurb><para>
	Allocators, ABI, API evolution and deprecation history,
	Backwards Compatibility, Thread, Debug Support, Locales,
	Facets, Parallel Mode, Headers, Namespaces, Construction and
	Structure, Using Exceptions, DocBook conversion and layout.
      </para></personblurb></author><author><personname><firstname>Dhruv</firstname><surname>Matani</surname></personname><personblurb><para>
	bitmap_allocator
      </para></personblurb></author><author><personname><firstname>Jason</firstname><surname>Merrill</surname></personname><personblurb><para>
	License, __verbose_terminate_handler
      </para></personblurb></author><author><personname><firstname>Mark</firstname><surname>Mitchell</surname></personname><personblurb><para>
	Porting
      </para></personblurb></author><author><personname><firstname>Nathan</firstname><surname>Myers</surname></personname><personblurb><para>
	Referenced counted string, C++1998 implementation status.
      </para></personblurb></author><author><personname><firstname>Felix</firstname><surname>Natter</surname></personname><personblurb><para>
	Namespace composition, Backwards Compatibility.
      </para></personblurb></author><author><personname><firstname>Stefan</firstname><surname>Olsson</surname></personname><personblurb><para>
	mt_allocator
      </para></personblurb></author><author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname><personblurb><para>
	Parallel mode
      </para></personblurb></author><author><personname><firstname>Ami</firstname><surname>Tavory</surname></personname><personblurb><para>
	Policy Based Data Structures, Associative Containers, Unordered
	Containers.
      </para></personblurb></author><author><personname><firstname>Jonathan</firstname><surname>Wakely</surname></personname><personblurb><para>
	Implementation Status, Dual ABI, Linking, shared_ptr,
        markup editing and styling.
      </para></personblurb></author></authorgroup></info><!-- Part 01 : Intro --><part version="5.0" xreflabel="Introduction" xml:id="manual.intro"><?dbhtml filename="intro.html"?><info><title>
  Introduction
  <indexterm><primary>Introduction</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Chapter 01 : Status --><chapter xreflabel="Status" xml:id="manual.intro.status"><info><title>Status</title></info><?dbhtml filename="status.html"?><!-- Section 01 : Implementation Status --><section xreflabel="Status" xml:id="manual.intro.status.iso"><info><title>Implementation Status</title></info><!-- Section 01.1 : Status C++ 1998 --><section version="5.0" xreflabel="ISO C++ 1998" xml:id="status.iso.1998"><?dbhtml filename="status_iso_cxx1998.html"?><info><title>C++ 1998/2003</title><keywordset><keyword>ISO C++</keyword><keyword>1998</keyword></keywordset></info><section xreflabel="Implementation Status" xml:id="iso.1998.status"><info><title>Implementation Status</title></info><para>
This status table is based on the table of contents of ISO/IEC 14882:2003.
</para><para>
This section describes the C++ support in
mainline GCC, not in any particular release.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.cxx98_status"><title>C++ 1998/2003 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>18</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Language support</emphasis></entry></row><row><entry>18.1</entry><entry>Types</entry><entry>Y</entry><entry></entry></row><row><entry>18.2</entry><entry>Implementation properties</entry><entry>Y</entry><entry></entry></row><row><entry>18.2.1</entry><entry>Numeric Limits</entry><entry></entry><entry></entry></row><row><entry>18.2.1.1</entry><entry>Class template <code>numeric_limits</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.2.1.2</entry><entry><code>numeric_limits</code> members</entry><entry>Y</entry></row><row><entry>18.2.1.3</entry><entry><code>float_round_style</code></entry><entry>Y</entry></row><row><entry>18.2.1.4</entry><entry><code>float_denorm_style</code></entry><entry>Y</entry></row><row><entry>18.2.1.5</entry><entry><code>numeric_limits</code> specializations</entry><entry>Y</entry><entry></entry></row><row><entry>18.2.2</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry>18.3</entry><entry>Start and termination</entry><entry>Y</entry><entry></entry></row><row><entry>18.4</entry><entry>Dynamic memory management</entry><entry>Y</entry><entry></entry></row><row><entry>18.5</entry><entry>Type identification</entry><entry></entry><entry></entry></row><row><entry>18.5.1</entry><entry>Class type_info</entry><entry>Y</entry><entry></entry></row><row><entry>18.5.2</entry><entry>Class bad_cast</entry><entry>Y</entry><entry></entry></row><row><entry>18.5.3</entry><entry>Class bad_typeid</entry><entry>Y</entry><entry></entry></row><row><entry>18.6</entry><entry>Exception handling</entry><entry></entry><entry></entry></row><row><entry>18.6.1</entry><entry>Class exception</entry><entry>Y</entry><entry></entry></row><row><entry>18.6.2</entry><entry>Violation exception-specifications</entry><entry>Y</entry><entry></entry></row><row><entry>18.6.3</entry><entry>Abnormal termination</entry><entry>Y</entry><entry></entry></row><row><entry>18.6.4</entry><entry><code>uncaught_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7</entry><entry>Other runtime support</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>19</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Diagnostics</emphasis></entry></row><row><entry>19.1</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>19.2</entry><entry>Assertions</entry><entry>Y</entry><entry></entry></row><row><entry>19.3</entry><entry>Error numbers</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>20</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General utilities</emphasis></entry></row><row><entry>20.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.2</entry><entry>Utility components</entry><entry></entry><entry></entry></row><row><entry>20.2.1</entry><entry>Operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.2</entry><entry><code>pair</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.3</entry><entry>Function objects</entry><entry></entry><entry></entry></row><row><entry>20.3.1</entry><entry>Base</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.2</entry><entry>Arithmetic operation</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.3</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.4</entry><entry>Logical operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.5</entry><entry>Negators</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.6</entry><entry>Binders</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.7</entry><entry>Adaptors for pointers to functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.8</entry><entry>Adaptors for pointers to members</entry><entry>Y</entry><entry></entry></row><row><entry>20.4</entry><entry>Memory</entry><entry></entry><entry></entry></row><row><entry>20.4.1</entry><entry>The default allocator</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2</entry><entry>Raw storage iterator</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.3</entry><entry>Temporary buffers</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.4</entry><entry>Specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.4.1</entry><entry><code>uninitialized_copy</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.4.4.2</entry><entry><code>uninitialized_fill</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.4.4.3</entry><entry><code>uninitialized_fill_n</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.4.5</entry><entry>Class template <code>auto_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.4.6</entry><entry>C library</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>21</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Strings</emphasis></entry></row><row><entry>21.1</entry><entry>Character traits</entry><entry></entry><entry></entry></row><row><entry>21.1.1</entry><entry>Character traits requirements</entry><entry>Y</entry><entry></entry></row><row><entry>21.1.2</entry><entry>traits typedef</entry><entry>Y</entry><entry></entry></row><row><entry>21.1.3</entry><entry><code>char_traits</code> specializations</entry><entry></entry><entry></entry></row><row><entry>21.1.3.1</entry><entry>struct <code>char_traits&lt;char&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.1.3.2</entry><entry>struct <code>char_traits&lt;wchar_t&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.2</entry><entry>String classes</entry><entry>Y</entry><entry></entry></row><row><entry>21.3</entry><entry>Class template <code>basic_string</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.4</entry><entry>Null-terminated sequence utilities</entry><entry>Y</entry><entry>C library dependency</entry></row><row><entry><emphasis>22</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Localization</emphasis></entry></row><row><entry>22.1</entry><entry>Locales</entry><entry></entry><entry></entry></row><row><entry>22.1.1</entry><entry>Class <code>locale</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.1.2</entry><entry><code>locale</code> globals</entry><entry>Y</entry><entry></entry></row><row><entry>22.1.3</entry><entry>Convenience interfaces</entry><entry></entry><entry></entry></row><row><entry>22.1.3.1</entry><entry>Character classification</entry><entry>Y</entry><entry></entry></row><row><entry>22.1.3.2</entry><entry>Character conversions</entry><entry>Y</entry><entry></entry></row><row><entry>22.2</entry><entry>Standard locale categories</entry><entry></entry><entry></entry></row><row><entry>22.2.1</entry><entry><code>ctype</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.2</entry><entry>Numeric</entry><entry></entry><entry></entry></row><row><entry>22.2.2.1</entry><entry><code>num_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.2.2</entry><entry><code>num_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.3</entry><entry><code>num_punct</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.4</entry><entry><code>collate</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.5</entry><entry>Time</entry><entry></entry><entry></entry></row><row><entry>22.2.5.1</entry><entry><code>time_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.5.2</entry><entry><code>time_get_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.5.3</entry><entry><code>time_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.5.3</entry><entry><code>time_put_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.6</entry><entry>Monetary</entry><entry></entry><entry></entry></row><row><entry>22.2.6.1</entry><entry><code>money_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.6.2</entry><entry><code>money_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.6.3</entry><entry><code>money_punct</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.6.4</entry><entry><code>money_punct_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.7</entry><entry><code>messages</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.2.8</entry><entry>Program-defined facets</entry><entry>Y</entry><entry></entry></row><row><entry>22.3</entry><entry>C Library Locales</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>23</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers</emphasis></entry></row><row><entry>23.1</entry><entry>Container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.2</entry><entry>Sequence containers</entry><entry></entry><entry></entry></row><row><entry>23.2.1</entry><entry>Class template <code>deque</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.2</entry><entry>Class template <code>list</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.3</entry><entry>Adaptors</entry><entry></entry><entry></entry></row><row><entry>23.2.3.1</entry><entry>Class template <code>queue</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.3.2</entry><entry>Class template <code>priority_queue</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.3.3</entry><entry>Class template <code>stack</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.4</entry><entry>Class template <code>vector</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.5</entry><entry>Class <code>vector&lt;bool&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3</entry><entry>Associative containers</entry><entry></entry><entry></entry></row><row><entry>23.3.1</entry><entry>Class template <code>map</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.2</entry><entry>Class template <code>multimap</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.3</entry><entry>Class template <code>set</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.4</entry><entry>Class template <code>multiset</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>24</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Iterators</emphasis></entry></row><row><entry>24.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>24.2</entry><entry>Header <code>&lt;iterator&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>24.3</entry><entry>Iterator primitives</entry><entry>Y</entry><entry></entry></row><row><entry>24.4</entry><entry>Predefined iterators and Iterator adaptors</entry><entry></entry><entry></entry></row><row><entry>24.4.1</entry><entry>Reverse iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.2</entry><entry>Insert iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.5</entry><entry>Stream iterators</entry><entry></entry><entry></entry></row><row><entry>24.5.1</entry><entry>Class template <code>istream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.5.2</entry><entry>Class template <code>ostream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.5.3</entry><entry>Class template <code>istreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.5.4</entry><entry>Class template <code>ostreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>25</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Algorithms</emphasis></entry></row><row><entry>25.1</entry><entry>Non-modifying sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.2</entry><entry>Mutating sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.3</entry><entry>Sorting and related operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.4</entry><entry>C library algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>26</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerics</emphasis></entry></row><row><entry>26.1</entry><entry>Numeric type requirements</entry><entry>Y</entry><entry></entry></row><row><entry>26.2</entry><entry>Complex numbers</entry><entry>Y</entry><entry></entry></row><row><entry>26.3</entry><entry>Numeric arrays</entry><entry></entry><entry></entry></row><row><entry>26.3.1</entry><entry>Header <code>&lt;valarray&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>26.3.2</entry><entry>Class template <code>valarray</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.3</entry><entry><code>valarray</code> non-member operations</entry><entry>Y</entry><entry></entry></row><row><entry>26.3.4</entry><entry>Class <code>slice</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.5</entry><entry>Class template <code>slice_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.6</entry><entry>Class <code>gslice</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.7</entry><entry>Class template <code>gslice_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.8</entry><entry>Class template <code>mask_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.3.9</entry><entry>Class template <code>indirect_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.4</entry><entry>Generalized numeric operations</entry><entry></entry><entry></entry></row><row><entry>26.4.1</entry><entry><code>accumulate</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.4.2</entry><entry><code>inner_product</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.4.3</entry><entry><code>partial_sum</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.4.4</entry><entry><code>adjacent_difference</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.4.5</entry><entry>iota</entry><entry>Y</entry><entry></entry></row><row><entry>26.5</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>27</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Input/output</emphasis></entry></row><row><entry>27.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>27.2</entry><entry>Forward declarations</entry><entry>Y</entry><entry></entry></row><row><entry>27.3</entry><entry>Standard iostream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.3.1</entry><entry>Narrow stream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.3.2</entry><entry>Wide stream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.4</entry><entry>Iostreams base classes</entry><entry>Y</entry><entry></entry></row><row><entry>27.5</entry><entry>Stream buffers</entry><entry>Y</entry><entry></entry></row><row><entry>27.6</entry><entry>Formatting and manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>27.7</entry><entry>String-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>27.8</entry><entry>File-based streams</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>Appendix D</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Compatibility features</emphasis></entry></row><row><entry>D.1</entry><entry>Increment operator with bool operand</entry><entry></entry><entry></entry></row><row><entry>D.2</entry><entry><code>static</code> keyword</entry><entry></entry><entry></entry></row><row><entry>D.3</entry><entry>Access declarations</entry><entry></entry><entry></entry></row><row><entry>D.4</entry><entry>Implicit conversion from const strings</entry><entry></entry><entry></entry></row><row><entry>D.5</entry><entry>C standard library headers</entry><entry></entry><entry></entry></row><row><entry>D.6</entry><entry>Old iostreams members</entry><entry></entry><entry></entry></row><row><entry>D.7</entry><entry>char* streams</entry><entry></entry><entry></entry></row></tbody></tgroup></table></section><section xreflabel="Implementation Specific" xml:id="iso.1998.specific"><info><title>Implementation Specific Behavior</title></info><para>
     The ISO standard defines the following phrase:
   </para><blockquote><variablelist><varlistentry><term><code>[1.3.5] implementation-defined behavior</code></term><listitem><para>
	 Behavior, for a well-formed program construct and correct data, that
	 depends on the implementation <emphasis>and that each implementation
	 shall document</emphasis>.
	 </para></listitem></varlistentry></variablelist></blockquote><para>
     We do so here, for the C++ library only.  Behavior of the
     compiler, linker, runtime loader, and other elements of "the
     implementation" are documented elsewhere.  Everything listed
     in Annex B, Implementation Qualities, are also part of the
     compiler, not the library.
   </para><para>
     For each entry, we give the section number of the standard, when
     applicable.  This list is probably incomplet and inkorrekt.
   </para><para><emphasis>1.9 [intro.execution]/11 #3</emphasis> If <code>isatty(3)</code>
     is true, then interactive stream support is implied.
   </para><para><emphasis>17.4.4.5 [lib.reentrancy]</emphasis> Non-reentrant functions are
     probably best discussed in the various sections on multithreading (see above).
   </para><!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
	can throw whatever we want; see also its footnote.  Let's list those
	in the sections where the function itself occurs.
   --><para><emphasis>18.1 [lib.support.types]/4</emphasis> The type of
      <code>NULL</code> is described under
      <link linkend="std.support.types.null">Support</link>.
   </para><para><emphasis>18.3 [lib.support.start.term]/8</emphasis> Even though it's
      listed in the library sections, libstdc++ has zero control over what the
      cleanup code hands back to the runtime loader.  Talk to the compiler people.
      :-)
   </para><para><emphasis>18.4.2.1 [lib.bad.alloc]/5</emphasis> (bad_alloc),
      <emphasis>18.5.2 [lib.bad.cast]/5</emphasis> (bad_cast),
      <emphasis>18.5.3 [lib.bad.typeid]/5</emphasis> (bad_typeid),
      <emphasis>18.6.1 [lib.exception]/8</emphasis> (exception),
      <emphasis>18.6.2.1 [lib.bad.exception]/5</emphasis> (bad_exception):
      The <code>what()</code> member function of class <code>std::exception</code>,
      and these other classes publicly derived from it, returns the name of the
      class, e.g. <literal>"std::bad_alloc"</literal>.
   </para><para><emphasis>18.5.1 [lib.type.info]/7</emphasis> The return value of
      <code>std::type_info::name()</code> is the mangled type name.
      You will need to call <code>c++filt</code> and pass the names as
      command-line parameters to demangle them, or call a
      <link linkend="manual.ext.demangle">runtime demangler function</link>.
   </para><para><emphasis>20.1.5 [lib.allocator.requirements]/5</emphasis><emphasis>"Implementors are encouraged to supply libraries that can
      accept allocators that encapsulate more general memory models and that
      support non-equal instances.  In such implementations, any requirements
      imposed on allocators by containers beyond those requirements that appear
      in Table 32, and the semantics of containers and algorithms when allocator
      instances compare non-equal, are implementation-defined."</emphasis>
      There is experimental support for non-equal allocators in the standard
      containers in C++98  mode. There are no additional requirements on
      allocators. It is undefined behaviour to swap two containers if their
      allocators are not equal.
   </para><para><emphasis>21.1.3.1 [lib.char.traits.specializations.char]/3,4</emphasis>,
      <emphasis>21.1.3.2 [lib.char.traits.specializations.wchar.t]/2</emphasis>,
      <emphasis>21.3 [lib.basic.string]/6 basic_string::iterator,
      basic_string::const_iterator</emphasis>,
      <emphasis>23.* [lib.containers]'s foo::iterator</emphasis>,
      <emphasis>27.* [lib.input.output]'s foo::*_type</emphasis>,
      <emphasis>others...</emphasis>
      Nope, these types are called implementation-defined because you
      shouldn't be taking advantage of their underlying types.  Listing them
      here would defeat the purpose.  :-)
   </para><para><emphasis>21.1.3.1 [lib.char.traits.specializations.char]/5</emphasis>
      I don't really know about the <type>mbstate_t</type> stuff... see
      the <link linkend="std.localization.facet.codecvt"><code>codecvt</code>
      notes</link> for what does exist.
   </para><para><emphasis>22.* [lib.localization]</emphasis> Anything and everything
      we have on locale implementation will be described under
      <link linkend="std.localization.locales.locale">Localization</link>.
   </para><para><emphasis>23.* [lib.containers]</emphasis> All of the containers in
     this clause define <type>size_type</type> as <type>std::size_t</type> and
     <type>difference_type</type> as <type>std::ptrdiff_t</type>.
   </para><para><emphasis>26.2.8 [lib.complex.transcendentals/9</emphasis> I have no
      idea what <code>complex&lt;T&gt;</code>'s <code>pow(0,0)</code> returns.
   </para><para><emphasis>27.4.2.4 [lib.ios.members.static/2</emphasis> Calling
      <code>std::ios_base::sync_with_stdio</code> after I/O has already been
      performed on the standard stream objects will
      flush the buffers, and <!-- this line might go away -->
      destroy and recreate the underlying buffer instances.  Whether or not
      the previously-written I/O is destroyed in this process depends mostly
      on the <code>--enable-libio</code> choice:  for stdio, if the written
      data is already in the stdio buffer, the data may be completely safe!
   </para><para><emphasis>27.6.1.1.2 [lib.istream::sentry]</emphasis>,
      <emphasis>27.6.2.3 [lib.ostream::sentry]</emphasis> The I/O sentry ctor
      and dtor can perform additional work than the minimum required. We are
      not currently taking  advantage of this yet.
   </para><para><emphasis>27.7.1.3 [lib.stringbuf.virtuals]/16</emphasis>,
      <emphasis>27.8.1.4 [lib.filebuf.virtuals]/10</emphasis>
      The effects of <code>pubsetbuf/setbuf</code> are described in the
      <link linkend="std.io">Input and Output</link> chapter.
   </para><para><emphasis>27.8.1.4 [lib.filebuf.virtuals]/16</emphasis> Calling
      <code>fstream::sync</code> when a get area exists will... whatever
      <code>fflush()</code> does, I think.
   </para></section></section><!-- Section 01.2 : Status C++ 2011 --><section version="5.0" xreflabel="Status C++ 2011" xml:id="status.iso.2011"><?dbhtml filename="status_iso_cxx2011.html"?><info><title>C++ 2011</title><keywordset><keyword>ISO C++</keyword><keyword>2011</keyword></keywordset></info><para><anchor xml:id="status.iso.200x"></anchor><!-- preserve links to old section ID -->
This table is based on the table of contents of ISO/IEC
JTC1 SC22 WG21 Doc No: N3290 Date: 2011-04-11
Final Draft International Standard, Standard for Programming Language C++
</para><para>
In this implementation the <literal>-std=gnu++11</literal> or
<literal>-std=c++11</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
<constant>__cplusplus</constant> is used to check for the
presence of the required flag.
GCC 5.1 was the first release with non-experimental C++11 support,
so the API and ABI of features added in C++11 is only stable
since that release.
</para><para>
This status table is based on the table of contents of ISO/IEC 14882:2011.
</para><para>
This section describes the C++11 support in
mainline GCC, not in any particular release.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.cxx11_status"><title>C++ 2011 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>18</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Language support</emphasis></entry></row><row><entry>18.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.2</entry><entry>Types</entry><entry>Y</entry><entry></entry></row><row><entry>18.3</entry><entry>Implementation properties</entry><entry></entry><entry></entry></row><row><entry>18.3.2</entry><entry>Numeric Limits</entry><entry></entry><entry></entry></row><row><entry>18.3.2.3</entry><entry>Class template <code>numeric_limits</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.3.2.4</entry><entry><code>numeric_limits</code> members</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>18.3.2.5</entry><entry><code>float_round_style</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>18.3.2.6</entry><entry><code>float_denorm_style</code></entry><entry>N</entry><entry></entry></row><row><entry>18.3.2.7</entry><entry><code>numeric_limits</code> specializations</entry><entry>Y</entry><entry></entry></row><row><entry>18.3.3</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry>18.4</entry><entry>Integer types</entry><entry></entry><entry></entry></row><row><entry>18.4.1</entry><entry>Header <code>&lt;cstdint&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>18.5</entry><entry>Start and termination</entry><entry>Partial</entry><entry>C library dependency for quick_exit, at_quick_exit</entry></row><row><entry>18.6</entry><entry>Dynamic memory management</entry><entry>Y</entry><entry></entry></row><row><entry>18.7</entry><entry>Type identification</entry><entry></entry><entry></entry></row><row><entry>18.7.1</entry><entry>Class type_info</entry><entry>Y</entry><entry></entry></row><row><entry>18.7.2</entry><entry>Class bad_cast</entry><entry>Y</entry><entry></entry></row><row><entry>18.7.3</entry><entry>Class bad_typeid</entry><entry>Y</entry><entry></entry></row><row><entry>18.8</entry><entry>Exception handling</entry><entry></entry><entry></entry></row><row><entry>18.8.1</entry><entry>Class exception</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.2</entry><entry>Class bad_exception</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.3</entry><entry>Abnormal termination</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.4</entry><entry><code>uncaught_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.8.5</entry><entry>Exception Propagation</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.6</entry><entry><code>nested_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.9</entry><entry>Initializer lists</entry><entry></entry><entry></entry></row><row><entry>18.9.1</entry><entry>Initializer list constructors</entry><entry>Y</entry><entry></entry></row><row><entry>18.9.2</entry><entry>Initializer list access</entry><entry>Y</entry><entry></entry></row><row><entry>18.9.3</entry><entry>Initializer list range access</entry><entry>Y</entry><entry></entry></row><row><entry>18.10</entry><entry>Other runtime support</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>19</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Diagnostics</emphasis></entry></row><row><entry>19.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>19.2</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>19.3</entry><entry>Assertions</entry><entry>Y</entry><entry></entry></row><row><entry>19.4</entry><entry>Error numbers</entry><entry>Y</entry><entry></entry></row><row><entry>19.5</entry><entry>System error support</entry><entry></entry><entry></entry></row><row><entry>19.5.1</entry><entry>Class <code>error_category</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.2</entry><entry>Class <code>error_code</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.3</entry><entry>Class <code>error_condition</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.4</entry><entry>Comparison operators</entry><entry>Y</entry><entry></entry></row><row><entry>19.5.5</entry><entry>Class <code>system_error</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>20</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General utilities</emphasis></entry></row><row><entry>20.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.2</entry><entry>Utility components</entry><entry></entry><entry></entry></row><row><entry>20.2.1</entry><entry>Operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.2</entry><entry>swap</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.3</entry><entry>forward/move helpers</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.4</entry><entry>Function template <code>declval</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.3</entry><entry>Pairs</entry><entry></entry><entry></entry></row><row><entry>20.3.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>20.3.2</entry><entry>Class template <code>pair</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.3.3</entry><entry>Specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>20.3.4</entry><entry>Tuple-like access to <code>pair</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.3.5</entry><entry>Piecewise construction</entry><entry>Y</entry><entry></entry></row><row><entry>20.4</entry><entry>Tuples</entry><entry></entry><entry></entry></row><row><entry>20.4.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>20.4.2</entry><entry>Class template <code>tuple</code></entry><entry></entry><entry></entry></row><row><entry>20.4.2.1</entry><entry>Construction</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.2</entry><entry>Assignment</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.3</entry><entry>Swap</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.4</entry><entry>Tuple creation functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.5</entry><entry>Tuple helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.6</entry><entry>Element access</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.7</entry><entry>Relational operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.8</entry><entry>Tuple traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.4.2.9</entry><entry>Tuple specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>20.5</entry><entry>Class template <code>bitset</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.5.1</entry><entry><code>bitset</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>20.5.2</entry><entry><code>bitset</code> members</entry><entry>Y</entry><entry></entry></row><row><entry>20.5.3</entry><entry><code>bitset</code> hash support</entry><entry>Y</entry><entry></entry></row><row><entry>20.5.4</entry><entry><code>bitset</code> operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.6</entry><entry>Memory</entry><entry></entry><entry></entry></row><row><entry>20.6.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>20.6.2</entry><entry>Header <code>&lt;memory&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>20.6.3</entry><entry>Pointer traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.4</entry><entry>Pointer safety</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.5</entry><entry>Align</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.6</entry><entry>Allocator argument tag</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.7</entry><entry><code>uses_allocator</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6.8</entry><entry>Allocator traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.9</entry><entry>The default allocator</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.10</entry><entry>Raw storage iterator</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.11</entry><entry>Temporary buffers</entry><entry>Y</entry><entry></entry></row><row><entry>20.6.12</entry><entry>Specialized algorithms</entry><entry></entry><entry></entry></row><row><entry>20.6.12.1</entry><entry><code>addressof</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6.12.2</entry><entry><code>uninitialized_copy</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6.12.3</entry><entry><code>uninitialized_fill</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6.12.4</entry><entry><code>uninitialized_fill_n</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6.13</entry><entry>C library</entry><entry>Y</entry><entry></entry></row><row><entry>20.7</entry><entry>Smart pointers</entry><entry></entry><entry></entry></row><row><entry>20.7.1</entry><entry>Class template <code>unique_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.7.2</entry><entry>Shared-ownership pointers</entry><entry></entry><entry></entry></row><row><entry>20.7.2.1</entry><entry>Class <code>bad_weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.7.2.2</entry><entry>Class template <code>shared_ptr</code></entry><entry>Y</entry><entry>
	  Uses code from
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
      </entry></row><row><entry>20.7.2.3</entry><entry>Class template <code>weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.7.2.4</entry><entry>Class template <code>enable_shared_from_this</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.7.2.5</entry><entry><code>shared_ptr</code> atomic access</entry><entry>Y</entry><entry></entry></row><row><entry>20.7.2.6</entry><entry>Smart pointer hash support</entry><entry>Y</entry><entry></entry></row><row><entry>20.8</entry><entry>Function objects</entry><entry></entry><entry></entry></row><row><entry>20.8.1</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>20.8.2</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>20.8.3</entry><entry>Class template <code>reference_wrapper</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.4</entry><entry>Arithmetic operation</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.5</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.6</entry><entry>Logical operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.7</entry><entry>Bitwise operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.8</entry><entry>Negators</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.9</entry><entry>Function template <code>bind</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.10</entry><entry>Function template <code>mem_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.11</entry><entry>Polymorphic function wrappers</entry><entry></entry><entry></entry></row><row><entry>20.8.11.1</entry><entry>Class <code>bad_function_call</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>20.8.11.2</entry><entry>Class template <code>function</code></entry><entry>Partial</entry><entry>Missing allocator support</entry></row><row><entry>20.8.12</entry><entry>Class template <code>hash</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.9</entry><entry>Metaprogramming and type traits</entry><entry></entry><entry></entry></row><row><entry>20.9.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.2</entry><entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>20.9.3</entry><entry>Helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.4</entry><entry>Unary Type Traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.4.1</entry><entry>Primary type categories</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.4.2</entry><entry>Composite type traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.4.3</entry><entry>Type properties</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.5</entry><entry>Type property queries</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.6</entry><entry>Relationships between types</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7</entry><entry>Transformations between types</entry><entry></entry><entry></entry></row><row><entry>20.9.7.1</entry><entry>Const-volatile modifications</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7.2</entry><entry>Reference modifications</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7.3</entry><entry>Sign modifications</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7.4</entry><entry>Array modifications</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7.5</entry><entry>Pointer modifications</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7.6</entry><entry>Other transformations</entry><entry>Y</entry><entry></entry></row><row><entry>20.10</entry><entry>Compile-time rational arithmetic</entry><entry></entry><entry></entry></row><row><entry>20.10.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>20.10.2</entry><entry>Header <code>&lt;ratio&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>20.10.3</entry><entry>Class template <code>ratio</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.10.4</entry><entry>Arithmetic on <code>ratio</code>s</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.5</entry><entry>Comparison of <code>ratio</code>s</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.6</entry><entry>SI types for <code>ratio</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11</entry><entry>Time utilities</entry><entry></entry><entry></entry></row><row><entry>20.11.3</entry><entry>Clock requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.11.4</entry><entry>Time-related traits</entry><entry></entry><entry></entry></row><row><entry>20.11.4.1</entry><entry><code>treat_as_floating_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.4.2</entry><entry><code>duration_values</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.4.3</entry><entry>Specializations of <code>common_type</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.5</entry><entry>Class template <code>duration</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.6</entry><entry>Class template <code>time_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.7</entry><entry>Clocks</entry><entry></entry><entry></entry></row><row><entry>20.11.7.1</entry><entry>Class <code>system_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.7.2</entry><entry>Class <code>steady_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.7.3</entry><entry>Class <code>high_resolution_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.8</entry><entry>Date and time functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.12</entry><entry>Scoped allocator adaptor</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.1</entry><entry>Header <code>&lt;scoped_allocator&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>20.12.2</entry><entry>Scoped allocator adaptor member types</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.3</entry><entry>Scoped allocator adaptor constructors</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.4</entry><entry>Scoped allocator adaptor members</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.5</entry><entry>Scoped allocator operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.13</entry><entry>Class <code>type_index</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>21</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Strings</emphasis></entry></row><row><entry>21.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>21.2</entry><entry>Character traits</entry><entry></entry><entry></entry></row><row><entry>21.2.1</entry><entry>Character traits requirements</entry><entry>Y</entry><entry></entry></row><row><entry>21.2.2</entry><entry>traits typedefs</entry><entry>Y</entry><entry></entry></row><row><entry>21.2.3</entry><entry><code>char_traits</code> specializations</entry><entry></entry><entry></entry></row><row><entry>21.2.3.1</entry><entry>struct <code>char_traits&lt;char&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.2.3.2</entry><entry>struct <code>char_traits&lt;char16_t&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.2.3.3</entry><entry>struct <code>char_traits&lt;char32_t&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.2.3.4</entry><entry>struct <code>char_traits&lt;wchar_t&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.3</entry><entry>String classes</entry><entry>Y</entry><entry></entry></row><row><entry>21.4</entry><entry>Class template <code>basic_string</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.5</entry><entry>Numeric Conversions</entry><entry>Y</entry><entry></entry></row><row><entry>21.6</entry><entry>Hash support</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>21.7</entry><entry>Null-terminated sequence utilities</entry><entry>Partial</entry><entry>C library dependency. </entry></row><row><entry><emphasis>22</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Localization</emphasis></entry></row><row><entry>22.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>22.2</entry><entry>Header <code>&lt;locale&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>22.3</entry><entry>Locales</entry><entry></entry><entry></entry></row><row><entry>22.3.1</entry><entry>Class <code>locale</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.3.2</entry><entry><code>locale</code> globals</entry><entry>Y</entry><entry></entry></row><row><entry>22.3.3</entry><entry>Convenience interfaces</entry><entry></entry><entry></entry></row><row><entry>22.3.3.1</entry><entry>Character classification</entry><entry>Y</entry><entry></entry></row><row><entry>22.3.3.2</entry><entry>Conversions</entry><entry></entry><entry></entry></row><row><entry>22.3.3.2.1</entry><entry>Character conversions</entry><entry>Y</entry><entry></entry></row><row><entry>22.3.3.2.2</entry><entry><code>string</code> conversions</entry><entry>Y</entry><entry></entry></row><row><entry>22.3.3.2.3</entry><entry>Buffer conversions</entry><entry>Y</entry><entry></entry></row><row><entry>22.4</entry><entry>Standard <code>locale</code> categories</entry><entry></entry><entry></entry></row><row><entry>22.4.1</entry><entry>The <code>ctype</code> category</entry><entry>Y</entry><entry></entry></row><row><entry>22.4.2</entry><entry>The numeric category</entry><entry></entry><entry></entry></row><row><entry>22.4.2.1</entry><entry><code>num_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.2.2</entry><entry><code>num_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.3</entry><entry>The numeric punctuation facet</entry><entry>Y</entry><entry></entry></row><row><entry>22.4.4</entry><entry>The collate category</entry><entry>Y</entry><entry></entry></row><row><entry>22.4.5</entry><entry>The time category</entry><entry></entry><entry></entry></row><row><entry>22.4.5.1</entry><entry>Class template <code>time_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.5.2</entry><entry>Class template <code>time_get_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.5.3</entry><entry>Class template <code>time_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.5.3</entry><entry>Class template <code>time_put_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.6</entry><entry>The monetary category</entry><entry></entry><entry></entry></row><row><entry>22.4.6.1</entry><entry>Class template <code>money_get</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.6.2</entry><entry>Class template <code>money_put</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.6.3</entry><entry>Class template <code>money_punct</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.6.4</entry><entry>Class template <code>money_punct_byname</code></entry><entry>Y</entry><entry></entry></row><row><entry>22.4.7</entry><entry>The message retrieval category</entry><entry>Y</entry><entry></entry></row><row><entry>22.4.8</entry><entry>Program-defined facets</entry><entry>Y</entry><entry></entry></row><row><entry>22.5</entry><entry>Standard code conversion facets</entry><entry>Y</entry><entry></entry></row><row><entry>22.6</entry><entry>C Library Locales</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>23</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers</emphasis></entry></row><row><entry>23.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.2</entry><entry>Container requirements</entry><entry></entry><entry></entry></row><row><entry>23.2.1</entry><entry>General container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.2</entry><entry>Container data races</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.3</entry><entry>Sequence containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.4</entry><entry>Associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.5</entry><entry>Unordered associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.3</entry><entry>Sequence containers</entry><entry></entry><entry></entry></row><row><entry>23.3.2</entry><entry>Class template <code>array</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.3</entry><entry>Class template <code>deque</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.4</entry><entry>Class template <code>forward_list</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.5</entry><entry>Class template <code>list</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.6</entry><entry>Class template <code>vector</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.3.7</entry><entry>Class <code>vector&lt;bool&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.4</entry><entry>Associative containers</entry><entry></entry><entry></entry></row><row><entry>23.4.4</entry><entry>Class template <code>map</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.4.5</entry><entry>Class template <code>multimap</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.4.6</entry><entry>Class template <code>set</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.4.7</entry><entry>Class template <code>multiset</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.5</entry><entry>Unordered associative containers</entry><entry></entry><entry></entry></row><row><entry>23.5.4</entry><entry>Class template <code>unordered_map</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.5.5</entry><entry>Class template <code>unordered_multimap</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.5.6</entry><entry>Class template <code>unordered_set</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.5.7</entry><entry>Class template <code>unordered_multiset</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6</entry><entry>Container adaptors</entry><entry></entry><entry></entry></row><row><entry>23.6.1</entry><entry>Class template <code>queue</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6.2</entry><entry>Class template <code>priority_queue</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6.3</entry><entry>Class template <code>stack</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>24</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Iterators</emphasis></entry></row><row><entry>24.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>24.2</entry><entry>Iterator requirements</entry><entry>Y</entry><entry></entry></row><row><entry>24.3</entry><entry>Header <code>&lt;iterator&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>24.4</entry><entry>Iterator primitives</entry><entry>Y</entry><entry></entry></row><row><entry>24.5</entry><entry>Iterator adaptors</entry><entry></entry><entry></entry></row><row><entry>24.5.1</entry><entry>Reverse iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.5.2</entry><entry>Insert iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.5.3</entry><entry>Move iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.6</entry><entry>Stream iterators</entry><entry></entry><entry></entry></row><row><entry>24.6.1</entry><entry>Class template <code>istream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.6.2</entry><entry>Class template <code>ostream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.6.3</entry><entry>Class template <code>istreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.6.4</entry><entry>Class template <code>ostreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.6.5</entry><entry>range access</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>25</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Algorithms</emphasis></entry></row><row><entry>25.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>25.2</entry><entry>Non-modifying sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.3</entry><entry>Mutating sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.4</entry><entry>Sorting and related operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.5</entry><entry>C library algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>26</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerics</emphasis></entry></row><row><entry>26.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>26.2</entry><entry>Numeric type requirements</entry><entry>Y</entry><entry></entry></row><row><entry>26.3</entry><entry>The floating-point environment</entry><entry>Y</entry><entry></entry></row><row><entry>26.4</entry><entry>Complex numbers</entry><entry>Y</entry><entry></entry></row><row><entry>26.5</entry><entry>Random number generation</entry><entry></entry><entry></entry></row><row><entry>26.5.1</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>26.5.2</entry><entry>Header <code>&lt;random&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>26.5.3</entry><entry>Random number engine class templates</entry><entry></entry><entry></entry></row><row><entry>26.5.3.1</entry><entry>Class template <code>linear_congruential_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.3.2</entry><entry>Class template <code>mersenne_twister_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.3.3</entry><entry>Class template <code>subtract_with_carry_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.4</entry><entry>Random number engine adaptor class templates</entry><entry></entry><entry></entry></row><row><entry>26.5.4.2</entry><entry>Class template <code>discard_block_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.4.3</entry><entry>Class template <code>independent_bits_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.4.4</entry><entry>Class template <code>shuffle_order_engine</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.5</entry><entry>Engines and engine adaptors with predefined parameters</entry><entry>Y</entry><entry></entry></row><row><entry>26.5.6</entry><entry>Class <code>random_device</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.7</entry><entry>Utilities</entry><entry></entry><entry></entry></row><row><entry>26.5.7.1</entry><entry>Class <code>seed_seq</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.7.2</entry><entry>Function template <code>generate_canonical</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8</entry><entry>Random number distribution class templates</entry><entry></entry><entry></entry></row><row><entry>26.5.8.2</entry><entry>Uniform distributions</entry><entry></entry><entry></entry></row><row><entry>26.5.8.2.1</entry><entry>Class template <code>uniform_int_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.2.2</entry><entry>Class template <code>uniform_real_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.3</entry><entry>Bernoulli distributions</entry><entry></entry><entry></entry></row><row><entry>26.5.8.3.1</entry><entry>Class <code>bernoulli_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.3.2</entry><entry>Class template <code>binomial_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.3.3</entry><entry>Class template <code>geometric_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.3.4</entry><entry>Class template <code>negative_binomial_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.4</entry><entry>Poisson distributions</entry><entry></entry><entry></entry></row><row><entry>26.5.8.4.1</entry><entry>Class template <code>poisson_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.4.2</entry><entry>Class template <code>exponential_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.4.3</entry><entry>Class template <code>gamma_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.4.4</entry><entry>Class template <code>weibull_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.4.5</entry><entry>Class template <code>extreme_value_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5</entry><entry>Normal distributions</entry><entry></entry><entry></entry></row><row><entry>26.5.8.5.1</entry><entry>Class template <code>normal_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5.2</entry><entry>Class template <code>lognormal_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5.3</entry><entry>Class template <code>chi_squared_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5.4</entry><entry>Class template <code>cauchy_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5.5</entry><entry>Class template <code>fisher_f_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.5.6</entry><entry>Class template <code>student_t_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.6</entry><entry>Sampling distributions</entry><entry></entry><entry></entry></row><row><entry>26.5.8.6.1</entry><entry>Class template <code>discrete_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.6.2</entry><entry>Class template <code>piecewise_constant_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.8.6.3</entry><entry>Class template <code>piecewise_linear_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6</entry><entry>Numeric arrays</entry><entry></entry><entry></entry></row><row><entry>26.6.1</entry><entry>Header <code>&lt;valarray&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>26.6.2</entry><entry>Class template <code>valarray</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.3</entry><entry><code>valarray</code> non-member operations</entry><entry>Y</entry><entry></entry></row><row><entry>26.6.4</entry><entry>Class <code>slice</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.5</entry><entry>Class template <code>slice_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.6</entry><entry>The <code>gslice</code> class</entry><entry>Y</entry><entry></entry></row><row><entry>26.6.7</entry><entry>Class template <code>gslice_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.8</entry><entry>Class template <code>mask_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.9</entry><entry>Class template <code>indirect_array</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.6.10</entry><entry><code>valarray</code> range access</entry><entry>Y</entry><entry></entry></row><row><entry>26.7</entry><entry>Generalized numeric operations</entry><entry></entry><entry></entry></row><row><entry>26.7.1</entry><entry>Header <code>&lt;numeric&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>26.7.2</entry><entry>Accumulate&gt;</entry><entry>Y</entry><entry></entry></row><row><entry>26.7.3</entry><entry>Inner product</entry><entry>Y</entry><entry></entry></row><row><entry>26.7.4</entry><entry>Partial sum</entry><entry>Y</entry><entry></entry></row><row><entry>26.7.5</entry><entry>Adjacent difference</entry><entry>Y</entry><entry></entry></row><row><entry>26.7.6</entry><entry>Iota</entry><entry>Y</entry><entry></entry></row><row><entry>26.8</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>27</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Input/output library</emphasis></entry></row><row><entry>27.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>27.2</entry><entry>Iostreams requirements</entry><entry>Y</entry><entry></entry></row><row><entry>27.2.1</entry><entry>Imbue Limitations</entry><entry>Y</entry><entry></entry></row><row><entry>27.2.2</entry><entry>Positioning Type Limitations</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>27.2.3</entry><entry>Thread safety</entry><entry>Partial</entry><entry></entry></row><row><entry>27.3</entry><entry>Forward declarations</entry><entry>Y</entry><entry></entry></row><row><entry>27.4</entry><entry>Standard iostream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.4.1</entry><entry>Overview</entry><entry>Y</entry><entry></entry></row><row><entry>27.4.2</entry><entry>Narrow stream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.4.3</entry><entry>Wide stream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.5</entry><entry>Iostreams base classes</entry><entry>Y</entry><entry></entry></row><row><entry>27.6</entry><entry>Stream buffers</entry><entry>Y</entry><entry></entry></row><row><entry>27.7</entry><entry>Formatting and manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>27.8</entry><entry>String-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>27.9</entry><entry>File-based streams</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>28</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Regular expressions</emphasis></entry></row><row><entry>28.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>28.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>28.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>28.4</entry><entry>Header <code>&lt;regex&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>28.5</entry><entry>Namespace <code>std::regex_constants</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.6</entry><entry>Class <code>regex_error</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>28.7</entry><entry>Class template <code>regex_traits</code></entry><entry>Partial</entry><entry><code>transform_primary</code> is not correctly implemented</entry></row><row><entry>28.8</entry><entry>Class template <code>basic_regex</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.9</entry><entry>Class template <code>sub_match</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.10</entry><entry>Class template <code>match_results</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.11</entry><entry>Regular expression algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>28.12</entry><entry>Regular expression Iterators</entry><entry>Y</entry><entry></entry></row><row><entry>28.13</entry><entry>Modified ECMAScript regular expression grammar</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>29</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Atomic operations</emphasis></entry></row><row><entry>29.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>29.2</entry><entry>Header <code>&lt;atomic&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>29.3</entry><entry>Order and consistency</entry><entry>Y</entry><entry></entry></row><row><entry>29.4</entry><entry>Lock-free property</entry><entry>Y</entry><entry></entry></row><row><entry>29.5</entry><entry>Atomic types</entry><entry>Y</entry><entry></entry></row><row><entry>29.6</entry><entry>Operations on atomic types</entry><entry>Y</entry><entry></entry></row><row><entry>29.7</entry><entry>Flag Type and operations</entry><entry>Y</entry><entry></entry></row><row><entry>29.8</entry><entry>Fences</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>30</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Thread support</emphasis></entry></row><row><entry>30.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>30.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>30.3</entry><entry>Threads</entry><entry></entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.3.1</entry><entry>Class <code>thread</code></entry><entry>Partial</entry><entry><code>thread::id</code> comparisons not well-defined</entry></row><row><entry>30.3.2</entry><entry>Namespace <code>this_thread</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4</entry><entry>Mutual exclusion</entry><entry></entry><entry></entry></row><row><entry>30.4.1</entry><entry>Mutex requirements</entry><entry></entry><entry></entry></row><row><entry>30.4.1.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>30.4.1.2</entry><entry>Mutex types</entry><entry></entry><entry></entry></row><row><entry>30.4.1.2.1</entry><entry>Class <code>mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.2.2</entry><entry>Class <code>recursive_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.3</entry><entry>Timed mutex types</entry><entry></entry><entry></entry></row><row><entry>30.4.1.3.1</entry><entry>Class <code>timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.3.2</entry><entry>Class <code>recursive_timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.2</entry><entry>Locks</entry><entry></entry><entry></entry></row><row><entry>30.4.2.1</entry><entry>Class template <code>lock_guard</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.2.2</entry><entry>Class template <code>unique_lock</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.3</entry><entry>Generic locking algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>30.4.4</entry><entry>Call once</entry><entry></entry><entry></entry></row><row><entry>30.4.4.1</entry><entry>Struct <code>once_flag</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.4.4.2</entry><entry>Function <code>call_once</code></entry><entry>Y</entry><entry>Exception support is broken.
	See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66146">PR
	66146</link>.
      </entry></row><row><entry>30.5</entry><entry>Condition variables</entry><entry>Y</entry><entry></entry></row><row><entry>30.5.1</entry><entry>Class <code>condition_variable</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.5.2</entry><entry>Class <code>condition_variable_any</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6</entry><entry>Futures</entry><entry></entry><entry></entry></row><row><entry>30.6.1</entry><entry>Overview</entry><entry></entry><entry></entry></row><row><entry>30.6.2</entry><entry>Error handling</entry><entry>Y</entry><entry></entry></row><row><entry>30.6.3</entry><entry>Class <code>future_error</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.4</entry><entry>Shared state</entry><entry>Y</entry><entry></entry></row><row><entry>30.6.5</entry><entry>Class template <code>promise</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.6</entry><entry>Class template <code>future</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.7</entry><entry>Class template <code>shared_future</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.8</entry><entry>Function template <code>async</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.9</entry><entry>Class template <code>packaged_task</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>Appendix D</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Compatibility features</emphasis></entry></row><row><entry>D.1</entry><entry>Increment operator with <code>bool</code> operand</entry><entry></entry><entry></entry></row><row><entry>D.2</entry><entry><code>register</code> keyword</entry><entry></entry><entry></entry></row><row><entry>D.3</entry><entry>Implicit declaration of copy functions</entry><entry></entry><entry></entry></row><row><entry>D.4</entry><entry>Dynamic exception specifications</entry><entry></entry><entry></entry></row><row><entry>D.5</entry><entry>C standard library headers</entry><entry>Y</entry><entry></entry></row><row><entry>D.6</entry><entry>Old iostreams members</entry><entry>Y</entry><entry></entry></row><row><entry>D.7</entry><entry><code>char*</code> streams</entry><entry>Y</entry><entry></entry></row><row><entry>D.8</entry><entry>Function objects</entry><entry>Y</entry><entry></entry></row><row><entry>D.9</entry><entry>Binders</entry><entry>Y</entry><entry></entry></row><row><entry>D.10</entry><entry><code>auto_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.11</entry><entry>Violating exception-specifications</entry><entry>Y</entry><entry></entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.2011.specific"><info><title>Implementation Specific Behavior</title></info><para>For behaviour which is also specified by the 1998 and 2003 standards,
      see <link linkend="iso.1998.specific">C++ 1998/2003 Implementation
      Specific Behavior</link>. This section only documents behaviour which
      is new in the 2011 standard.
   </para><para><emphasis>17.6.5.12 [res.on.exception.handling]</emphasis>
      There are no implementation-defined exception classes, only standard
      exception classes (or classes derived from them) will be thrown.
   </para><para><emphasis>17.6.5.14 [value.error.codes]</emphasis>
      The <classname>error_category</classname> for errors originating outside
      the OS, and the possible error code values for each error category,
      should be documented here.
   </para><para><emphasis>18.6.2.2 [new.badlength]</emphasis><function>what()</function> returns
      <literal>"std::bad_array_new_length"</literal>.
   </para><para><emphasis>20.6.9.1 [allocator.member]/5</emphasis>
      Over-aligned types are not supported by
      <classname>std::allocator</classname>.
   </para><para><emphasis>20.7.2.2.1 [util.smartptr.shared.const]</emphasis>
      When a <classname>shared_ptr</classname> constructor fails
      <classname>bad_alloc</classname> (or types derived from it) will
      be thrown, or when an allocator is passed to the constructor then any
      exceptions thrown by the allocator.
   </para><para><emphasis>20.7.2.0 [util.smartptr.weakptr]</emphasis><code>what()</code> returns <literal>"bad_weak_ptr"</literal>.
   </para><para><emphasis>20.8.11.1 [func.wrap.badcall]</emphasis><code>what()</code> returns <literal>"bad_function_call"</literal>.
   </para><para><emphasis>20.8.9.1.3 [func.bind.place]/1</emphasis> There are 29
      placeholders defined and the placeholder types are
      <literal>CopyAssignable</literal>.
   </para><para><emphasis>20.11.7.1 [time.clock.system]/3, /4</emphasis>
      Time point values are truncated to <code>time_t</code> values.
      There is no loss of precision for conversions in the other direction.
   </para><para><emphasis>20.15.7 [meta.trans]/2</emphasis><classname>aligned_storage</classname> does not support extended
      alignment.
   </para><para><emphasis>21.2.3.2 [char.traits.specializations.char16_t]</emphasis>,
      <emphasis>21.2.3.3 [char.traits.specializations.char32_t]</emphasis>
      The types <classname>u16streampos</classname> and
      <classname>u32streampos</classname> are both synonyms for
      <classname>fpos&lt;mbstate_t&gt;</classname>.
      The function <function>eof</function> returns <code>int_type(-1)</code>.
      <function>char_traits&lt;char16_t&gt;::to_int_type</function> will
      transform the "noncharacter" U+FFFF to U+FFFD (REPLACEMENT CHARACTER).
      This is done to ensure that <function>to_int_type</function> never
      returns the same value as <function>eof</function>, which is U+FFFF.
   </para><para><emphasis>22.3.1 [locale]</emphasis>
      There is one global locale for the whole program, not per-thread.
   </para><para><emphasis>22.4.5.1.2 [locale.time.get.virtuals]</emphasis>,
      <emphasis>22.4.5.3.2 [locale.time.put.virtuals]</emphasis>
      Additional supported formats should be documented here.
   </para><para><emphasis> 22.4.7.1.2 [locale.messages.virtuals]</emphasis>
      The mapping should be documented here.
   </para><para><emphasis>23.3.2.1 [array.overview]</emphasis><classname>array&lt;T, N&gt;::iterator</classname> is <code>T*</code> and
      <classname>array&lt;T, N&gt;::const_iterator</classname> is
      <code>const T*</code>.
   </para><para><emphasis>23.5.4.2 [unord.map.cnstr]</emphasis>,
      <emphasis>23.5.5.2 [unord.multimap.cnstr]</emphasis>,
      <emphasis>23.5.6.2 [unord.set.cnstr]</emphasis>,
      <emphasis>23.5.7.2 [unord.multiset.cnstr]</emphasis>
      The default minimal bucket count is 0 for the default constructors, range
      constructors and initializer-list constructors.
   </para><para><emphasis>25.3.12 [alg.random.shuffle]</emphasis>
      The two-argument overload of <function>random_shuffle</function>
      uses <function>rand</function> as the source of randomness.
   </para><para><emphasis>26.5.5 [rand.predef]</emphasis>
      The type <classname>default_random_engine</classname> is a synonym for
      <classname>minstd_rand0</classname>.
   </para><para><emphasis> 26.5.6 [rand.device] </emphasis>
      The <code>token</code> parameter of the
      <classname>random_device</classname> constructor can be used to select
      a specific source of random bytes. The valid token values are shown
      in the list below.
      The default constructor uses the token <literal>"default"</literal>.
      <variablelist><varlistentry><term><literal>"default"</literal></term><listitem>
          Select the first available source from the other entries below.
          This is the only token that is always valid.
        </listitem></varlistentry><varlistentry><term><literal>"rand_s"</literal></term><listitem>
          Use the MSVCRT <function>rand_s</function> function.
          This token is only valid for mingw-w64 targets.
        </listitem></varlistentry><varlistentry><term><literal>"rdseed"</literal></term><term><literal>"rdrand"</literal> or <literal>"rdrnd"</literal></term><listitem>
          Use the IA-32 <literal>RDSEED</literal> or <literal>RDRAND</literal>
          instruction to read from an on-chip hardware random number generator.
          These tokens are only valid for x86 and x86_64 targets when both
          the assembler and CPU support the corresponding instruction.
        </listitem></varlistentry><varlistentry><term><literal>"darn"</literal></term><listitem>
          Use the Power ISA-3.0 <literal>DARN</literal>
          ("Deliver A Random Number")
          instruction to read from an on-chip hardware random number generator.
          This token is only valid for 64-bit powerpc targets when both
          the assembler and CPU support the corresponding instruction.
        </listitem></varlistentry><varlistentry><term><literal>"hw"</literal></term><term><literal>"hardware"</literal></term><listitem>
          Use any available CPU
          instruction to read from an on-chip hardware random number generator.
          This is equivalent to trying each of the following and using the
          first that is supported:
          <literal>"rdseed"</literal>
          <literal>"rdrand"</literal>
          <literal>"darn"</literal>
        </listitem></varlistentry><varlistentry><term><literal>"arc4random"</literal></term><term><literal>"getentropy"</literal></term><listitem>
          Use the named C library function, if available on the target.
        </listitem></varlistentry><varlistentry><term><literal>"/dev/urandom"</literal></term><term><literal>"/dev/random"</literal></term><listitem>
          Use the named character special file to read random bytes from.
          These tokens are only valid when the device files are present
          and readable by the current user.
        </listitem></varlistentry><varlistentry><term><literal>"mt19937"</literal></term><term>seed value</term><listitem>
          When no source of nondeterministic random numbers is available a
          <classname>mersenne_twister_engine</classname> will be used.
          An integer seed value can be used as the token and will be converted
          to an <code>unsigned long</code> using <function>strtoul</function>.
          These tokens are only valid when no other source of random bytes
          is available.
        </listitem></varlistentry></variablelist>
      An exception of type <classname>runtime_error</classname> will be
      thrown if a <classname>random_device</classname> object is constructed
      with an invalid token, or if it cannot open or read from the source
      of random bytes.
   </para><para><emphasis>26.5.8.1 [rand.dist.general]</emphasis>
      The algorithms used by the distributions should be documented here.
   </para><para><emphasis>26.8 [c.math]</emphasis> Whether the
      <function>rand</function> function introduces data races depends on
      the C library as the function is not provided by libstdc++.
   </para><para><emphasis>27.8.2.1 [stringbuf.cons]</emphasis>
      Whether the sequence pointers are copied by the
      <classname>basic_stringbuf</classname> move constructor should be
      documented here.
   </para><para><emphasis>27.9.1.2 [filebuf.cons]</emphasis>
      Whether the sequence pointers are copied by the
      <classname>basic_filebuf</classname> move constructor should be
      documented here.
   </para><para><emphasis>28.5.1 [re.synopt]</emphasis>,
      <emphasis> 28.5.2 [re.matchflag] </emphasis>,
      <emphasis> 28.5.3 [re.err] </emphasis><code>syntax_option_type</code>, <code>match_flag_type</code>
      and <code>error_type</code> are unscoped enumeration types.
   </para><para><emphasis>28.7 [re.traits]</emphasis>
      The <literal>blank</literal> character class corresponds to the
      <code>ctype_base::blank</code> mask.
   </para><para><emphasis>29.4 [atomics.lockfree]</emphasis>
      The values of the <code>ATOMIC_xxx_LOCK_FREE</code> macros depend on
      the target and cannot be listed here.
   </para><para><emphasis>30.2.3 [thread.req.native]/1</emphasis><classname>native_handle_type</classname> and
      <methodname>native_handle</methodname> are provided. The handle types
      are defined in terms of the Gthreads abstraction layer, although this
      is subject to change at any time. Any use of
      <classname>native_handle</classname> is inherently non-portable and
      not guaranteed to work between major releases of GCC.
      <variablelist><varlistentry><term><classname>thread</classname></term><listitem>
            The native handle type is a typedef for <code>__gthread_t</code>
            i.e. <code>pthread_t</code> when GCC is configured with the
            <literal>posix</literal> thread model.
            The value of the native handle is undefined for a thread
            which is not joinable.
         </listitem></varlistentry><varlistentry><term><classname>mutex</classname></term><term><classname>timed_mutex</classname></term><listitem>
            The native handle type is <code>__gthread_mutex_t*</code> i.e.
            <code>pthread_mutex_t*</code> for the <literal>posix</literal>
            thread model.
         </listitem></varlistentry><varlistentry><term><classname>recursive_mutex</classname></term><term><classname>recursive_timed_mutex</classname></term><listitem>
            The native handle type is <code>__gthread_recursive_mutex_t*</code>
            i.e. <code>pthread_mutex_t*</code> for the <literal>posix</literal>
            thread model.
         </listitem></varlistentry><varlistentry><term><classname>condition_variable</classname></term><listitem>
            The native handle type is <code>__gthread_cond_t*</code> i.e.
            <code>pthread_cond_t*</code> for the <literal>posix</literal>
            thread model.
         </listitem></varlistentry></variablelist>
   </para><para><emphasis>30.6.1 [futures.overview]/2</emphasis><code>launch</code> is a scoped enumeration type with
      overloaded operators to support bitmask operations. There are no
      additional bitmask elements defined.
   </para></section></section><!-- Section 01.3 : Status C++ 2014 --><section version="5.0" xreflabel="Status C++ 2014" xml:id="status.iso.2014"><?dbhtml filename="status_iso_cxx2014.html"?><info><title>C++ 2014</title><keywordset><keyword>ISO C++</keyword><keyword>2014</keyword></keywordset></info><para>
In this implementation the <literal>-std=gnu++14</literal> or
<literal>-std=c++14</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
<constant>__cplusplus</constant> is used to check for the
presence of the required flag.
GCC 6.1 was the first release with non-experimental C++14 support,
so the API and ABI of features added in C++14 is only stable
since that release.
</para><para>
This status table is based on the table of contents of ISO/IEC 14882:2014.
Some subclauses are not shown in the table where the content is unchanged
since C++11 and the implementation is complete.
</para><para>
This section describes the C++14 and library TS support in
mainline GCC, not in any particular release.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.cxx14_status"><title>C++ 2014 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>18</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Language support</emphasis></entry></row><row><entry>18.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.2</entry><entry>Types</entry><entry>Y</entry><entry></entry></row><row><entry>18.3</entry><entry>Implementation properties</entry><entry></entry><entry></entry></row><row><entry>18.3.2</entry><entry>Numeric Limits</entry><entry></entry><entry></entry></row><row><entry>18.3.2.3</entry><entry>Class template <code>numeric_limits</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.3.2.4</entry><entry><code>numeric_limits</code> members</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>18.3.2.5</entry><entry><code>float_round_style</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>18.3.2.6</entry><entry><code>float_denorm_style</code></entry><entry>N</entry><entry></entry></row><row><entry>18.3.2.7</entry><entry><code>numeric_limits</code> specializations</entry><entry>Y</entry><entry></entry></row><row><entry>18.3.3</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry>18.4</entry><entry>Integer types</entry><entry></entry><entry></entry></row><row><entry>18.4.1</entry><entry>Header <code>&lt;cstdint&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>18.5</entry><entry>Start and termination</entry><entry>Partial</entry><entry>C library dependency for quick_exit, at_quick_exit</entry></row><row><entry>18.6</entry><entry>Dynamic memory management</entry><entry>Y</entry><entry></entry></row><row><entry>18.7</entry><entry>Type identification</entry><entry></entry><entry></entry></row><row><entry>18.7.1</entry><entry>Class type_info</entry><entry>Y</entry><entry></entry></row><row><entry>18.7.2</entry><entry>Class bad_cast</entry><entry>Y</entry><entry></entry></row><row><entry>18.7.3</entry><entry>Class bad_typeid</entry><entry>Y</entry><entry></entry></row><row><entry>18.8</entry><entry>Exception handling</entry><entry></entry><entry></entry></row><row><entry>18.8.1</entry><entry>Class exception</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.2</entry><entry>Class bad_exception</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.3</entry><entry>Abnormal termination</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.4</entry><entry><code>uncaught_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.8.5</entry><entry>Exception Propagation</entry><entry>Y</entry><entry></entry></row><row><entry>18.8.6</entry><entry><code>nested_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.9</entry><entry>Initializer lists</entry><entry></entry><entry></entry></row><row><entry>18.9.1</entry><entry>Initializer list constructors</entry><entry>Y</entry><entry></entry></row><row><entry>18.9.2</entry><entry>Initializer list access</entry><entry>Y</entry><entry></entry></row><row><entry>18.9.3</entry><entry>Initializer list range access</entry><entry>Y</entry><entry></entry></row><row><entry>18.10</entry><entry>Other runtime support</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>19</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Diagnostics</emphasis></entry></row><row><entry>19.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>19.2</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>19.3</entry><entry>Assertions</entry><entry>Y</entry><entry></entry></row><row><entry>19.4</entry><entry>Error numbers</entry><entry>Y</entry><entry></entry></row><row><entry>19.5</entry><entry>System error support</entry><entry></entry><entry></entry></row><row><entry>19.5.1</entry><entry>Class <code>error_category</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.2</entry><entry>Class <code>error_code</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.3</entry><entry>Class <code>error_condition</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.4</entry><entry>Comparison operators</entry><entry>Y</entry><entry></entry></row><row><entry>19.5.5</entry><entry>Class <code>system_error</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>20</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General utilities</emphasis></entry></row><row><entry>20.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.2</entry><entry>Utility components</entry><entry></entry><entry></entry></row><row><entry>20.2.1</entry><entry>Operators</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.2</entry><entry>swap</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.3</entry><entry>exchange</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.4</entry><entry>forward/move helpers</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.5</entry><entry>Function template <code>declval</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.3</entry><entry>Pairs</entry><entry>Y</entry><entry></entry></row><row><entry>20.4</entry><entry>Tuples</entry><entry>Y</entry><entry></entry></row><row><entry>20.5</entry><entry>Compile-time integer sequences</entry><entry></entry><entry></entry></row><row><entry>20.5.2</entry><entry>Class template <code>integer_sequence</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.5.3</entry><entry>Alias template <code>make_integer_sequence</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.6</entry><entry>Class template <code>bitset</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.7</entry><entry>Memory</entry><entry>Y</entry><entry></entry></row><row><entry>20.8</entry><entry>Smart pointers</entry><entry></entry><entry></entry></row><row><entry>20.8.1</entry><entry>Class template <code>unique_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.1.1</entry><entry>Default deleters</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.1.2</entry><entry><code>unique_ptr</code> for single objects</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.1.3</entry><entry><code>unique_ptr</code> for array objects with a runtime length</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.1.4</entry><entry><code>unique_ptr</code> creation</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.1.5</entry><entry><code>unique_ptr</code> specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2</entry><entry>Shared-ownership pointers</entry><entry></entry><entry></entry></row><row><entry>20.8.2.1</entry><entry>Class <code>bad_weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2.2</entry><entry>Class template <code>shared_ptr</code></entry><entry>Y</entry><entry>
	  Uses code from
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
      </entry></row><row><entry>20.8.2.3</entry><entry>Class template <code>weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2.4</entry><entry>Class template <code>owner_less</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2.5</entry><entry>Class template <code>enable_shared_from_this</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2.6</entry><entry><code>shared_ptr</code> atomic access</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.2.7</entry><entry>Smart pointer hash support</entry><entry>Y</entry><entry></entry></row><row><entry>20.9</entry><entry>Function objects</entry><entry></entry><entry></entry></row><row><entry>20.9.1</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>20.9.2</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>20.9.3</entry><entry>Class template <code>reference_wrapper</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.9.4</entry><entry>Arithmetic operation</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.5</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>20.8.6</entry><entry>Logical operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.7</entry><entry>Bitwise operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.8</entry><entry>Negators</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.9</entry><entry>Function object binders</entry><entry>Y</entry><entry></entry></row><row><entry>20.9.10</entry><entry>Function template <code>mem_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.9.11</entry><entry>Polymorphic function wrappers</entry><entry></entry><entry></entry></row><row><entry>20.9.11.1</entry><entry>Class <code>bad_function_call</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>20.9.11.2</entry><entry>Class template <code>function</code></entry><entry>Partial</entry><entry>Missing allocator support</entry></row><row><entry>20.9.12</entry><entry>Class template <code>hash</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.10</entry><entry>Metaprogramming and type traits</entry><entry></entry><entry></entry></row><row><entry>20.10.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.2</entry><entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>20.10.3</entry><entry>Helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.4</entry><entry>Unary Type Traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.5</entry><entry>Type property queries</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.6</entry><entry>Relationships between types</entry><entry>Y</entry><entry></entry></row><row><entry>20.10.7</entry><entry>Transformations between types</entry><entry>Y</entry><entry></entry></row><row><entry>20.11</entry><entry>Compile-time rational arithmetic</entry><entry>Y</entry><entry></entry></row><row><entry>20.12</entry><entry>Time utilities</entry><entry></entry><entry></entry></row><row><entry>20.12.3</entry><entry>Clock requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.4</entry><entry>Time-related traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.5</entry><entry>Class template <code>duration</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.12.5.8</entry><entry>Suffixes for duration literals</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.6</entry><entry>Class template <code>time_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.12.7</entry><entry>Clocks</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.8</entry><entry>Date and time functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.13</entry><entry>Scoped allocator adaptor</entry><entry>Y</entry><entry></entry></row><row><entry>20.14</entry><entry>Class <code>type_index</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>21</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Strings</emphasis></entry></row><row><entry>21.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>21.2</entry><entry>Character traits</entry><entry>Y</entry><entry></entry></row><row><entry>21.3</entry><entry>String classes</entry><entry>Y</entry><entry></entry></row><row><entry>21.4</entry><entry>Class template <code>basic_string</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.5</entry><entry>Numeric Conversions</entry><entry>Y</entry><entry></entry></row><row><entry>21.6</entry><entry>Hash support</entry><entry>Y</entry><entry></entry></row><row><entry>21.7</entry><entry>Suffixes for <code>basic_string</code> literals</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>21.7</entry><entry>Null-terminated sequence utilities</entry><entry>Partial</entry><entry>C library dependency. </entry></row><row><entry><emphasis>22</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Localization</emphasis></entry></row><row><entry>22.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>22.2</entry><entry>Header <code>&lt;locale&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>22.3</entry><entry>Locales</entry><entry>Y</entry><entry></entry></row><row><entry>22.4</entry><entry>Standard <code>locale</code> categories</entry><entry>Y</entry><entry></entry></row><row><entry>22.5</entry><entry>Standard code conversion facets</entry><entry>Y</entry><entry></entry></row><row><entry>22.6</entry><entry>C Library Locales</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>23</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers</emphasis></entry></row><row><entry>23.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.2</entry><entry>Container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.3</entry><entry>Sequence containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.4</entry><entry>Associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.5</entry><entry>Unordered associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>23.6</entry><entry>Container adaptors</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>24</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Iterators</emphasis></entry></row><row><entry>24.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>24.2</entry><entry>Iterator requirements</entry><entry>Y</entry><entry></entry></row><row><entry>24.3</entry><entry>Header <code>&lt;iterator&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>24.4</entry><entry>Iterator primitives</entry><entry>Y</entry><entry></entry></row><row><entry>24.5</entry><entry>Iterator adaptors</entry><entry>Y</entry><entry></entry></row><row><entry>24.6</entry><entry>Stream iterators</entry><entry>Y</entry><entry></entry></row><row><entry>24.7</entry><entry>range access</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>25</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Algorithms</emphasis></entry></row><row><entry>25.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>25.2</entry><entry>Non-modifying sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.3</entry><entry>Mutating sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.4</entry><entry>Sorting and related operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.5</entry><entry>C library algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>26</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerics</emphasis></entry></row><row><entry>26.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>26.2</entry><entry>Numeric type requirements</entry><entry>Y</entry><entry></entry></row><row><entry>26.3</entry><entry>The floating-point environment</entry><entry>Y</entry><entry></entry></row><row><entry>26.4</entry><entry>Complex numbers</entry><entry>Y</entry><entry></entry></row><row><entry>26.4.10</entry><entry>Suffixes for complex number literals</entry><entry>Y</entry><entry></entry></row><row><entry>26.5</entry><entry>Random number generation</entry><entry>Y</entry><entry></entry></row><row><entry>26.6</entry><entry>Numeric arrays</entry><entry>Y</entry><entry></entry></row><row><entry>26.7</entry><entry>Generalized numeric operations</entry><entry>Y</entry><entry></entry></row><row><entry>26.8</entry><entry>C Library</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>27</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Input/output library</emphasis></entry></row><row><entry>27.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>27.2</entry><entry>Iostreams requirements</entry><entry>Y</entry><entry></entry></row><row><entry>27.2.1</entry><entry>Imbue Limitations</entry><entry>Y</entry><entry></entry></row><row><entry>27.2.2</entry><entry>Positioning Type Limitations</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>27.2.3</entry><entry>Thread safety</entry><entry>Partial</entry><entry></entry></row><row><entry>27.3</entry><entry>Forward declarations</entry><entry>Y</entry><entry></entry></row><row><entry>27.4</entry><entry>Standard iostream objects</entry><entry>Y</entry><entry></entry></row><row><entry>27.5</entry><entry>Iostreams base classes</entry><entry>Y</entry><entry></entry></row><row><entry>27.6</entry><entry>Stream buffers</entry><entry>Y</entry><entry></entry></row><row><entry>27.7</entry><entry>Formatting and manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>27.7.6</entry><entry>Quoted manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>27.8</entry><entry>String-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>27.9</entry><entry>File-based streams</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>28</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Regular expressions</emphasis></entry></row><row><entry>28.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>28.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>28.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>28.4</entry><entry>Header <code>&lt;regex&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>28.5</entry><entry>Namespace <code>std::regex_constants</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.6</entry><entry>Class <code>regex_error</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>28.7</entry><entry>Class template <code>regex_traits</code></entry><entry>Partial</entry><entry><code>transform_primary</code> is not correctly implemented</entry></row><row><entry>28.8</entry><entry>Class template <code>basic_regex</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.9</entry><entry>Class template <code>sub_match</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.10</entry><entry>Class template <code>match_results</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.11</entry><entry>Regular expression algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>28.12</entry><entry>Regular expression Iterators</entry><entry>Y</entry><entry></entry></row><row><entry>28.13</entry><entry>Modified ECMAScript regular expression grammar</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>29</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Atomic operations</emphasis></entry></row><row><entry>29.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>29.2</entry><entry>Header <code>&lt;atomic&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>29.3</entry><entry>Order and consistency</entry><entry>Y</entry><entry></entry></row><row><entry>29.4</entry><entry>Lock-free property</entry><entry>Y</entry><entry></entry></row><row><entry>29.5</entry><entry>Atomic types</entry><entry>Y</entry><entry></entry></row><row><entry>29.6</entry><entry>Operations on atomic types</entry><entry>Y</entry><entry></entry></row><row><entry>29.7</entry><entry>Flag Type and operations</entry><entry>Y</entry><entry></entry></row><row><entry>29.8</entry><entry>Fences</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>30</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Thread support</emphasis></entry></row><row><entry>30.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>30.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>30.3</entry><entry>Threads</entry><entry></entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.3.1</entry><entry>Class <code>thread</code></entry><entry>Partial</entry><entry><code>thread::id</code> comparisons not well-defined</entry></row><row><entry>30.3.2</entry><entry>Namespace <code>this_thread</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4</entry><entry>Mutual exclusion</entry><entry></entry><entry></entry></row><row><entry>30.4.1</entry><entry>Mutex requirements</entry><entry></entry><entry></entry></row><row><entry>30.4.1.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>30.4.1.2</entry><entry>Mutex types</entry><entry></entry><entry></entry></row><row><entry>30.4.1.2.1</entry><entry>Class <code>mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.2.2</entry><entry>Class <code>recursive_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.3</entry><entry>Timed mutex types</entry><entry></entry><entry></entry></row><row><entry>30.4.1.3.1</entry><entry>Class <code>timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.3.2</entry><entry>Class <code>recursive_timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.1.4</entry><entry>Shared timed mutex types</entry><entry></entry><entry></entry></row><row><entry>30.4.1.4.1</entry><entry>Class <code>shared_timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.2</entry><entry>Locks</entry><entry></entry><entry></entry></row><row><entry>30.4.2.1</entry><entry>Class template <code>lock_guard</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.2.2</entry><entry>Class template <code>unique_lock</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.2.3</entry><entry>Class template <code>shared_lock</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.4.3</entry><entry>Generic locking algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>30.4.4</entry><entry>Call once</entry><entry></entry><entry></entry></row><row><entry>30.4.4.1</entry><entry>Struct <code>once_flag</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.4.4.2</entry><entry>Function <code>call_once</code></entry><entry>Broken</entry><entry>Exception support is broken.
	See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66146">PR
	66146</link>.
      </entry></row><row><entry>30.5</entry><entry>Condition variables</entry><entry>Y</entry><entry></entry></row><row><entry>30.5.1</entry><entry>Class <code>condition_variable</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.5.2</entry><entry>Class <code>condition_variable_any</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6</entry><entry>Futures</entry><entry></entry><entry></entry></row><row><entry>30.6.1</entry><entry>Overview</entry><entry></entry><entry></entry></row><row><entry>30.6.2</entry><entry>Error handling</entry><entry>Y</entry><entry></entry></row><row><entry>30.6.3</entry><entry>Class <code>future_error</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.4</entry><entry>Shared state</entry><entry>Y</entry><entry></entry></row><row><entry>30.6.5</entry><entry>Class template <code>promise</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.6</entry><entry>Class template <code>future</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.7</entry><entry>Class template <code>shared_future</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.8</entry><entry>Function template <code>async</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.6.9</entry><entry>Class template <code>packaged_task</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>Appendix D</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Compatibility features</emphasis></entry></row><row><entry>D.1</entry><entry>Increment operator with <code>bool</code> operand</entry><entry></entry><entry></entry></row><row><entry>D.2</entry><entry><code>register</code> keyword</entry><entry></entry><entry></entry></row><row><entry>D.3</entry><entry>Implicit declaration of copy functions</entry><entry></entry><entry></entry></row><row><entry>D.4</entry><entry>Dynamic exception specifications</entry><entry></entry><entry></entry></row><row><entry>D.5</entry><entry>C standard library headers</entry><entry>Y</entry><entry></entry></row><row><entry>D.6</entry><entry>Old iostreams members</entry><entry>Y</entry><entry></entry></row><row><entry>D.7</entry><entry><code>char*</code> streams</entry><entry>Y</entry><entry></entry></row><row><entry>D.8</entry><entry>Function objects</entry><entry>Y</entry><entry></entry></row><row><entry>D.9</entry><entry>Binders</entry><entry>Y</entry><entry></entry></row><row><entry>D.10</entry><entry><code>auto_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.11</entry><entry>Violating exception-specifications</entry><entry>Y</entry><entry></entry></row><row><entry>D.12</entry><entry>Random shuffle</entry><entry>Y</entry><entry></entry></row></tbody></tgroup></table><table frame="all" xml:id="table.ts_status"><title>C++ Technical Specifications Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Paper</entry><entry>Title</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><?dbhtml bgcolor="#C8B0B0" ?><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/sc22/WG21/docs/papers/2013/n3662.html">
	  N3662
	</link></entry><entry>C++ Dynamic Arrays</entry><entry>N</entry><entry>Array Extensions TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3793.html">
	  N3793
	</link></entry><entry>A proposal to add a utility class to represent optional objects</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3804.html">
	  N3804
	</link></entry><entry>Any library proposal</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2014/n3866.html">
	  N3866
	</link></entry><entry>Invocation type traits, but dropping function_call_operator.</entry><entry>N</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="">
	  N3905
	</link></entry><entry>Faster string searching (Boyer-Moore et al.)</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3915.pdf">
	  N3915
	</link></entry><entry>apply() call a function with arguments from a tuple</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3916.pdf">
	  N3916
	</link></entry><entry>Polymorphic memory resources</entry><entry>Partial (missing pool resource and buffer resource classes)</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3920.html">
	  N3920
	</link></entry><entry>Extending shared_ptr to support arrays</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3921.html">
	  N3921
	</link></entry><entry><code>string_view</code>: a non-owning reference to a string</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3925.pdf">
	  N3925
	</link></entry><entry>A sample proposal</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3932.htm">
	  N3932
	</link></entry><entry>Variable Templates For Type Traits</entry><entry>Y</entry><entry>Library Fundamentals TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf">
	  N4100
	</link></entry><entry>File System</entry><entry>Y</entry><entry>
	Link with
	<link linkend="manual.intro.using.linkage.experimental"><option>-lstdc++fs</option></link>
      </entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.2014.specific"><info><title>Implementation Specific Behavior</title></info><section xreflabel="Implementation Specific Behavior of the Filesystem TS" xml:id="iso.2014.filesystemts"><info><title>Filesystem TS</title></info><para><emphasis>2.1 POSIX conformance [fs.conform.9945]</emphasis>
      The behavior of the filesystem library implementation will depend on
      the target operating system. Some features will not be supported
      on some targets. Symbolic links and file permissions
      are not supported on Windows.
    </para><para><emphasis>15.30 Rename [fs.op.rename]</emphasis>
      On Windows, <code>experimental::filesystem::rename</code>
      is implemented by calling <code>MoveFileExW</code> and so
      does not meet the requirements of POSIX <code>rename</code>
      when one or both of the paths resolves to an existing directory.
      Specifically, it is possible to rename a directory so it replaces
      a non-directory (POSIX requires an error in that case),
      and it is not possible to rename a directory to replace another
      directory (POSIX requires that to work if the directory being
      replaced is empty).
    </para></section></section></section><!-- Section 01.4 : Status C++ 2017 --><section version="5.0" xreflabel="Status C++ 2017" xml:id="status.iso.2017"><?dbhtml filename="status_iso_cxx2017.html"?><info><title>C++ 2017</title><keywordset><keyword>ISO C++</keyword><keyword>2017</keyword></keywordset></info><para>
In this implementation the <literal>-std=gnu++17</literal> or
<literal>-std=c++17</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
<constant>__cplusplus</constant> is used to check for the
presence of the required flag.
GCC 9.1 was the first release with non-experimental C++17 support,
so the API and ABI of features added in C++17 is only stable
since that release.
</para><para>
This section describes the C++17 and library TS support in
mainline GCC, not in any particular release.
</para><para>
The following table lists new library features that are included in
the C++17 standard. The "Proposal" column provides a link to the
ISO C++ committee proposal that describes the feature, while the "Status"
column indicates the first version of GCC that contains an implementation of
this feature (if it has been implemented).
The "SD-6 Feature Test" column shows the corresponding macro or header from
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations">SD-6:
Feature-testing recommendations for C++</link>.
</para><table frame="all" xml:id="table.cxx17_features"><title>C++ 2017 Library Features</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Library Feature</entry><entry>Proposal</entry><entry>Status</entry><entry>SD-6 Feature Test</entry></row></thead><tbody><row><entry><code>constexpr std::hardware_{constructive,destructive}_interference_size</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0154r1.html">
	P0154R1
	</link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_hardware_interference_size &gt;= 201603</code></entry></row><row><entry> Core Issue 1776: Replacement of class objects containing reference members</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0137r1.html">
	P0137R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_launder &gt;= 201606</code></entry></row><row><entry>Wording for <code>std::uncaught_exceptions</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/sc22/WG21/docs/papers/2014/n4259.pdf">
	  N4259
	</link></entry><entry align="center">6.1</entry><entry><code>__cpp_lib_uncaught_exceptions &gt;= 201411</code></entry></row><row><entry> C++17 should refer to C11 instead of C99 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0063r3.html">
	P0063R3
	</link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry> Variant: a type-safe union for C++17 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0088r3.html">
	P0088R3
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__has_include(&lt;variant&gt;)</code>,
              <code>__cpp_lib_variant &gt;= 201603</code>
              (since 7.3, see Note 1)
      </entry></row><row><entry> Library Fundamentals V1 TS Components: <code>optional</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__has_include(&lt;optional&gt;)</code>,
              <code>__cpp_lib_optional &gt;= 201603</code>
              (since 7.3, see Note 1)
      </entry></row><row><entry> Library Fundamentals V1 TS Components: <code>any</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__has_include(&lt;any&gt;)</code>,
              <code>__cpp_lib_any &gt;= 201603</code>
              (since 7.3, see Note 1)
      </entry></row><row><entry> Library Fundamentals V1 TS Components: <code>string_view</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__has_include(&lt;string_view&gt;)</code>,
              <code>__cpp_lib_string_view &gt;= 201603</code>
              (since 7.3, see Note 1)
      </entry></row><row><entry> Library Fundamentals V1 TS Components: <code>memory_resource</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 9.1 </entry><entry><code>__has_include(&lt;memory_resource&gt;)</code>,
              <code>__cpp_lib_memory_resource &gt;= 201603</code></entry></row><row><entry> Library Fundamentals V1 TS Components: <code>apply</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_apply &gt;= 201603</code></entry></row><row><entry> Library Fundamentals V1 TS Components: <code>shared_ptr&lt;T[]&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_shared_ptr_arrays &gt;= 201603</code></entry></row><row><entry> Library Fundamentals V1 TS Components: Searchers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_boyer_moore_searcher &gt;= 201603</code></entry></row><row><entry> Library Fundamentals V1 TS Components: Sampling </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0220r1.html">
	P0220R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_sample &gt;= 201603</code></entry></row><row><entry> Constant View: A proposal for a <code>std::as_const</code> helper function template	</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="">
	P0007R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_as_const &gt;= 201510 </code></entry></row><row><entry> Improving pair and tuple </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4387">
	N4387
	</link></entry><entry align="center"> 6.1 </entry><entry> N/A </entry></row><row><entry><code>make_from_tuple</code>: apply for construction </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0209r2.pdf">
	P0209R2
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_make_from_tuple &gt;= 201606 </code></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>
        Removing <code>auto_ptr</code>, <code>random_shuffle()</code>,
        And Old <code>&lt;functional&gt;</code> Stuff
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4190.htm">
	  N4190
	</link></entry><entry align="center">No (kept for backwards compatibility)</entry><entry></entry></row><row><entry> Deprecating Vestigial Library Parts in C++17 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0174r2.html">
	P0174R2
	</link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> Making <code>std::owner_less</code> more flexible </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0074r0.html">
	P0074R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_transparent_operators &gt;= 201510 </code></entry></row><row><entry><code>std::addressof</code> should be constexpr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0304r0.html#2296">
	LWG2296
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_addressof_constexpr &gt;= 201603 </code></entry></row><row><entry> Safe conversions in <code>unique_ptr&lt;T[]&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4089.pdf">
	N4089
	</link></entry><entry align="center"> 6 </entry><entry></entry></row><row><entry> LWG 2228: Missing SFINAE rule in unique_ptr templated assignment </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4366.html">
	  N4366
	</link></entry><entry align="center"> 6 </entry><entry></entry></row><row><entry> Re-enabling <code>shared_from_this</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0033r1.html">
	P0033R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_enable_shared_from_this &gt;= 201603</code></entry></row><row><entry> A proposal to add <code>invoke</code> function template </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4169.html">
	N4169
	</link></entry><entry align="center"> 6.1 </entry><entry><code> __cpp_lib_invoke &gt;= 201411 </code></entry></row><row><entry>TriviallyCopyable <code>reference_wrapper</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4277.html">
	  N4277
	</link></entry><entry align="center"> 5.1 </entry><entry></entry></row><row><entry> Adopt <code>not_fn</code> from Library Fundamentals 2 for C++17 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0005r4.html">
	P0005R4
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_not_fn &gt;= 201603</code></entry></row><row><entry> Fixes for <code>not_fn</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0358r1.html">
	P0358R1
	</link></entry><entry align="center"> 7.1 </entry><entry></entry></row><row><entry> Fixing a design mistake in the searchers interface in Library Fundamentals </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0253r1.pdf">
	P0253R1
	</link></entry><entry align="center"> 7.1 </entry><entry></entry></row><row><entry> Extending memory management tools </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0040r3.html">
	P0040R3
	</link></entry><entry align="center"> 7.1 </entry><entry><code>__cpp_lib_raw_memory_algorithms &gt;= 201606L</code></entry></row><row><entry><code>shared_ptr::weak_type</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0163r0.html">
	P0163R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_shared_ptr_weak_type &gt;= 201606</code></entry></row><row><entry>Transformation Trait Alias <code>void_t</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/sc22/WG21/docs/papers/2014/n3911.pdf">
	  N3911
	</link></entry><entry align="center">6.1</entry><entry><code> __cpp_lib_void_t &gt;= 201411</code></entry></row><row><entry> Wording for <code>bool_constant</code>, revision 1 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4389.html">
	  N4389
	</link></entry><entry align="center">6.1</entry><entry><code> __cpp_lib_bool_constant &gt;= 201505</code></entry></row><row><entry> Adopt Type Traits Variable Templates from Library Fundamentals TS for C++17</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0006r0.html">
	P0006R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_type_trait_variable_templates &gt;= 201510 </code></entry></row><row><entry> Logical Operator Type Traits</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0013r1.html">
	P0013R1
	</link></entry><entry align="center"> 6.1 </entry><entry><code> __cpp_lib_logical_traits &gt;= 201510 </code></entry></row><row><entry> Adding [nothrow-]swappable traits </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0185r1.html">
	P0185R1
	</link></entry><entry align="center"> 7.1 (<code>__is_swappable</code> available since 6.1)</entry><entry><code> __cpp_lib_is_swappable &gt;= 201603 </code></entry></row><row><entry><code>is_callable</code>, the missing INVOKE related trait</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0077r2.html">
	P0077R2
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_is_invocable &gt;= 201703 </code></entry></row><row><entry> has_unique_object_representations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0258r2.html">
	P0258R2
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_has_unique_object_representations &gt;= 201606 </code></entry></row><row><entry> Polishing <code>&lt;chrono&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0092r1.html">
	P0092R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_chrono &gt;= 201510 </code></entry></row><row><entry> Adding more constexpr to <code>&lt;chrono&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0505r0.html">
	P0505R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_chrono &gt;= 201611 </code>
             (since 7.3, see Note 2)
      </entry></row><row><entry> Constexpr for <code>std::char_traits</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0426r1.html">
	P0426R1
	</link></entry><entry align="center"> 8.1 </entry><entry><code> __cpp_lib_constexpr_string &gt;= 201611 </code></entry></row><row><entry> Integrating <code>std::string_view</code> and <code>std::string</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0254r2.pdf">
	P0254R2
	</link></entry><entry align="center"> 7.1 </entry><entry><code> </code></entry></row><row><entry> Give 'std::string' a non-const '.data()' member function </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0272r1.html">
	P0272R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> </code></entry></row><row><entry>Cleaning-up noexcept in the Library</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4258.pdf">
	  N4258
	</link></entry><entry align="center">6.1</entry><entry><code> __cpp_lib_allocator_traits_is_always_equal &gt;= 201411 </code></entry></row><row><entry>Contiguous Iterators </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4284.html">
	  N4284
	</link></entry><entry align="center">N/A</entry><entry></entry></row><row><entry> Minimal incomplete type support for standard containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4510.html">
	N4510
	</link></entry><entry align="center"> 3.0 </entry><entry><code> __cpp_lib_incomplete_container_elements &gt;= 201505 </code>
	     (since 6.2, see Note 2)
      </entry></row><row><entry> Emplace return type </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0084r2.pdf">
	P0084R2
	</link></entry><entry align="center"> 7.1 </entry><entry></entry></row><row><entry>Improved insertion interface for unique-key maps</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4279.html">
	  N4279
	</link></entry><entry align="center"> 6.1 </entry><entry><code> __cpp_lib_map_try_emplace &gt;= 201411</code>,
	     <code> __cpp_lib_unordered_map_try_emplace &gt;= 201411</code></entry></row><row><entry> Splicing Maps and Sets </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0083r3.pdf">
	P0083R3
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_node_extract &gt;= 201606 </code></entry></row><row><entry>Non-member <code>size()</code> and more</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4280.pdf">
	  N4280
	</link></entry><entry align="center"> 6.1 </entry><entry><code> __cpp_lib_nonmember_container_access &gt;= 201411 </code></entry></row><row><entry> A Proposal to Add Constexpr Modifiers to <code>reverse_iterator</code>, <code>move_iterator</code>, <code>array</code> and Range Access </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0031r0.html">
	P0031R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_array_constexpr &gt;= 201603 </code></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry> The Parallelism TS Should be Standardized	 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0024r2.html">
	P0024R2
	</link></entry><entry align="center"> 9.1 </entry><entry><code> __has_include(&lt;execution&gt;)</code>,
	     <code> __cpp_lib_execution &gt;= 201603 </code>,
	     <code> __cpp_lib_parallel_algorithm &gt;= 201603 </code>
             (requires linking with <code>-ltbb</code>, see Note 3)
      </entry></row><row><entry> An algorithm to "clamp" a value between a pair of boundary values </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0025r0.html">
	P0025R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_clamp &gt;= 201603 </code></entry></row><row><entry> Adopt Selected Library Fundamentals V2 Components for C++17 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0295r0.pdf">
	P0295R0
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_gcd_lcm &gt;= 201606 </code></entry></row><row><entry> Proposal to Introduce a 3-Argument Overload to <code>std::hypot</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0030r1.pdf">
	P0030R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_hypot &gt;= 201603 </code></entry></row><row><entry> Mathematical Special Functions for C++17 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0226r1.pdf">
	P0226R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_math_special_functions &gt;= 201603 </code>
	     (see Note 4)
      </entry></row><row><entry>Adopt the File System TS for C++17	 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0218r1.html">
	P0218R1
	</link></entry><entry align="center"> 8.1 </entry><entry><code> __has_include(&lt;filesystem&gt;)</code>,
	     <code> __cpp_lib_filesystem &gt;= 201603 </code>
	     (GCC 8.x requires linking with <code>-lstdc++fs</code>)
      </entry></row><row><entry> Relative Paths for Filesystem</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0219r1.html">
	P0219R1
	</link></entry><entry align="center"> 8.1 </entry><entry><code> __cpp_lib_filesystem &gt;= 201606 </code></entry></row><row><entry> Adapting string_view by filesystem paths </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0392r0.pdf">
	P0392R0
	</link></entry><entry align="center"> 8.1 </entry><entry><code> __cpp_lib_filesystem &gt;= 201606 </code></entry></row><row><entry> Directory Entry Caching for Filesystem </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0317r1.html">
       P0317R1
       </link></entry><entry align="center"> 8.1 </entry><entry><code> __cpp_lib_filesystem &gt;= 201703 </code></entry></row><row><entry> constexpr <code>atomic&lt;T&gt;::is_always_lock_free</code>	 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0152r1.html">
	P0152R1
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_atomic_is_always_lock_free &gt;= 201603 </code></entry></row><row><entry>A proposal to add <code>shared_mutex</code> (untimed) (Revision 4)</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4508.html">
	  N4508
	</link></entry><entry align="center"> 6.1 </entry><entry><code> __cpp_lib_shared_mutex &gt;= 201505 </code></entry></row><row><entry> Variadic <code>lock_guard</code> (Rev. 5) </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0156r2.html">
	P0156R2
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_scoped_lock &gt;= 201703 </code></entry></row><row><entry> A byte type definition </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0298r3.pdf">
	P0298R3
	</link></entry><entry align="center"> 7.1 </entry><entry><code> __cpp_lib_byte &gt;= 201603 </code> (since 7.3, see Note 2)
      </entry></row><row><entry> Elementary string conversions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0067r5.html">
	P0067R5
	</link></entry><entry align="center"> 11.1 (integral types supported since 8.1) </entry><entry><code> __has_include(&lt;charconv&gt;)</code>,
             <code> __cpp_lib_to_chars &gt;= 201611 </code></entry></row><row><entry> Homogeneous interface for variant, any and optional </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0032r3.pdf">
	P0032R3
	</link></entry><entry align="center"> 7.1  </entry><entry><code> __cpp_lib_any &gt;= 201606 </code>,
             <code> __cpp_lib_optional &gt;= 201606 </code>,
             <code> __cpp_lib_variant &gt;= 201606 </code></entry></row><row><entry> Making Optional Greater Equal Again </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0307r2.pdf">
	P0307R2
	</link></entry><entry align="center"> 7.1  </entry><entry><code> __cpp_lib_optional &gt;= 201606 </code></entry></row></tbody></tgroup></table><para>
Note 1: This feature is supported in GCC 7.1 and 7.2 but before GCC 7.3 the
<code>__cpp_lib</code> macro is not defined, and compilation will fail if the
header is included without using <option>-std</option> to enable C++17 support.
</para><para>
Note 2: This feature is supported in older releases but the
<code>__cpp_lib</code> macro is not defined to the right value
(or not defined at all) until the version shown in parentheses.
</para><para>
Note 3: The Parallel Algorithms have an external dependency on Intel TBB 2018
or later. If the <filename class="headerfile">&lt;execution&gt;</filename>
header is included then <code>-ltbb</code> must be used to link to TBB.
</para><para>
Note 4: The mathematical special functions are enabled in C++17 mode from
GCC 7.1 onwards. For GCC 6.x or for C++11/C++14 define
<code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code> to a non-zero value
and test for <code>__STDCPP_MATH_SPEC_FUNCS__ &gt;= 201003L</code>.
</para><para>
The following status table is based on the table of contents of
ISO/IEC 14882:2017.
Some subclauses are not shown in the table where the content is unchanged
since C++14 and the implementation is complete.
</para><table frame="all" xml:id="table.cxx17_status"><title>C++ 2017 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>21</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Language support</emphasis></entry></row><row><entry>21.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>21.2</entry><entry>Common definitions</entry><entry></entry><entry></entry></row><row><entry>21.3</entry><entry>Implementation properties</entry><entry></entry><entry></entry></row><row><entry>21.3.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>21.3.2</entry><entry>Header <code>&lt;limits&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>21.3.3</entry><entry>Floating-point type properties</entry><entry></entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>21.3.3.1</entry><entry><code>float_round_style</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>21.3.3.2</entry><entry><code>float_denorm_style</code></entry><entry>N</entry><entry></entry></row><row><entry>21.3.4</entry><entry>Class template <code>numeric_limits</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.3.5</entry><entry>Header <code>&lt;climits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>21.3.6</entry><entry>Header <code>&lt;cfloat&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>21.4</entry><entry>Integer types</entry><entry></entry><entry></entry></row><row><entry>21.4.1</entry><entry>Header <code>&lt;cstdint&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>21.5</entry><entry>Start and termination</entry><entry>Partial</entry><entry>C library dependency for quick_exit, at_quick_exit</entry></row><row><entry>21.6</entry><entry>Dynamic memory management</entry><entry></entry><entry></entry></row><row><entry>21.6.1</entry><entry>Header <code>&lt;new&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>21.6.2</entry><entry>Storage allocation and deallocation</entry><entry>Y</entry><entry></entry></row><row><entry>21.6.3</entry><entry>Storage allocation errors</entry><entry>Y</entry><entry></entry></row><row><entry>21.6.4</entry><entry>Pointer optimization barrier</entry><entry>Y</entry><entry></entry></row><row><entry>21.6.5</entry><entry>Hardware interference size</entry><entry>Y</entry><entry></entry></row><row><entry>21.7</entry><entry>Type identification</entry><entry>Y</entry><entry></entry></row><row><entry>21.8</entry><entry>Exception handling</entry><entry></entry><entry></entry></row><row><entry>21.8.1</entry><entry>Header <code>&lt;exception&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>21.8.2</entry><entry>Class exception</entry><entry>Y</entry><entry></entry></row><row><entry>21.8.3</entry><entry>Class bad_exception</entry><entry>Y</entry><entry></entry></row><row><entry>21.8.4</entry><entry>Abnormal termination</entry><entry>Y</entry><entry></entry></row><row><entry>21.8.5</entry><entry><code>uncaught_exceptions</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.8.6</entry><entry>Exception Propagation</entry><entry>Y</entry><entry></entry></row><row><entry>21.8.7</entry><entry><code>nested_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>21.9</entry><entry>Initializer lists</entry><entry>Y</entry><entry></entry></row><row><entry>21.10</entry><entry>Other runtime support</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>22</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Diagnostics</emphasis></entry></row><row><entry>22.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>22.2</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>22.3</entry><entry>Assertions</entry><entry>Y</entry><entry></entry></row><row><entry>22.4</entry><entry>Error numbers</entry><entry>Y</entry><entry></entry></row><row><entry>22.5</entry><entry>System error support</entry><entry></entry><entry></entry></row><row><entry><emphasis>23</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General utilities</emphasis></entry></row><row><entry>23.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.2</entry><entry>Utility components</entry><entry></entry><entry></entry></row><row><entry>23.2.1</entry><entry>Header <code>&lt;utility&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>23.2.2</entry><entry>Operators</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.3</entry><entry><code>swap</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.4</entry><entry><code>exchange</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.5</entry><entry>Forward/move helpers</entry><entry>Y</entry><entry></entry></row><row><entry>23.2.6</entry><entry>Function template <code>as_const</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.7</entry><entry>Function template <code>declval</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.2.8</entry><entry>Primitive numeric output conversion</entry><entry>Y</entry><entry>
	Floating-point types up to 64-bit are formatted using
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/ulfjack/ryu">Ryu</link>.
	Types with greater precision are formatted using the C library
	(<function>sprintf</function> and conditionally
	<function>strfromf128</function>).
	For powerpc64le-unknown-linux-gnu <function>__sprintfieee128</function>
	must be provided by Glibc.
      </entry></row><row><entry>23.2.9</entry><entry>Primitive numeric input conversion</entry><entry>Y</entry><entry>
	Floating-point types up to 64-bit are parsed using
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/fastfloat/fast_float">fast_float</link>.
	Types with greater precision are parsed using the C library
	(<function>strtold</function>).
	For powerpc64le-unknown-linux-gnu <function>__strtoieee128</function>
	must be provided by Glibc.
      </entry></row><row><entry>23.3</entry><entry>Compile-time integer sequences</entry><entry></entry><entry></entry></row><row><entry>23.4</entry><entry>Pairs</entry><entry>Y</entry><entry></entry></row><row><entry>23.5</entry><entry>Tuples</entry><entry>Y</entry><entry></entry></row><row><entry>23.6</entry><entry>Optional objects</entry><entry>Y</entry><entry></entry></row><row><entry>23.7</entry><entry>Variants</entry><entry>Y</entry><entry></entry></row><row><entry>23.8</entry><entry>Storage for any type</entry><entry>Y</entry><entry></entry></row><row><entry>23.9</entry><entry>Bitsets</entry><entry>Y</entry><entry></entry></row><row><entry>23.10</entry><entry>Memory</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>23.10.2</entry><entry>Header <code>&lt;memory&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.3</entry><entry>Pointer traits</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.4</entry><entry>Pointer safety</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.5</entry><entry>Align</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.6</entry><entry>Allocator argument tag</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.7</entry><entry><code>uses_allocator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.10.8</entry><entry>Allocator traits</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.9</entry><entry>The default allocator</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.10</entry><entry>Specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>23.10.11</entry><entry>C library memory allocation</entry><entry>Y</entry><entry></entry></row><row><entry>23.11</entry><entry>Smart pointers</entry><entry></entry><entry></entry></row><row><entry>23.11.1</entry><entry>Class template <code>unique_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.11.2</entry><entry>Shared-ownership pointers</entry><entry>Y</entry><entry></entry></row><row><entry>23.12</entry><entry>Memory resources</entry><entry></entry><entry></entry></row><row><entry>23.12.1</entry><entry>Header <code>&lt;memory_resource&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>23.12.2</entry><entry>Class <code>memory_resource</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.12.3</entry><entry>Class template <code>polymorphic_allocator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.12.4</entry><entry>Access to program-wide <code>memory_resource</code> objects</entry><entry>Y</entry><entry></entry></row><row><entry>23.12.5</entry><entry>Pool resource classes</entry><entry>Y</entry><entry></entry></row><row><entry>23.12.6</entry><entry>Class <code>monotonic_buffer_resource</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.13</entry><entry>Class template <code>scoped_allocator_adaptor</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.14</entry><entry>Function objects</entry><entry></entry><entry></entry></row><row><entry>23.14.1</entry><entry>Header <code>&lt;functional&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>23.14.2</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>23.14.3</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>23.14.4</entry><entry>Function template <code>invoke</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.14.5</entry><entry>Class template <code>reference_wrapper</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.14.6</entry><entry>Arithmetic operation</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.7</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.8</entry><entry>Logical operations</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.9</entry><entry>Bitwise operations</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.10</entry><entry>Function template <code>not_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.14.11</entry><entry>Function object binders</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.12</entry><entry>Function template <code>mem_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.14.13</entry><entry>Polymorphic function wrappers</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.14</entry><entry>Searchers</entry><entry>Y</entry><entry></entry></row><row><entry>23.14.15</entry><entry>Class template <code>hash</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.15</entry><entry>Metaprogramming and type traits</entry><entry></entry><entry></entry></row><row><entry>23.15.1</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>23.15.2</entry><entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.3</entry><entry>Helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.4</entry><entry>Unary Type Traits</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.5</entry><entry>Type property queries</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.6</entry><entry>Relationships between types</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.7</entry><entry>Transformations between types</entry><entry>Y</entry><entry></entry></row><row><entry>23.15.8</entry><entry>Logical operator traits</entry><entry>Y</entry><entry></entry></row><row><entry>23.16</entry><entry>Compile-time rational arithmetic</entry><entry>Y</entry><entry></entry></row><row><entry>23.17.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>23.17.2</entry><entry>Header <code>&lt;chrono&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>23.17</entry><entry>Time utilities</entry><entry></entry><entry></entry></row><row><entry>23.17.3</entry><entry>Clock requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.17.4</entry><entry>Time-related traits</entry><entry>Y</entry><entry></entry></row><row><entry>23.17.5</entry><entry>Class template <code>duration</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.17.6</entry><entry>Class template <code>time_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.17.7</entry><entry>Clocks</entry><entry>Y</entry><entry></entry></row><row><entry>23.17.8</entry><entry>Header <code>&lt;ctime&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>23.18</entry><entry>Class <code>type_index</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.19</entry><entry>Execution policies</entry><entry></entry><entry></entry></row><row><entry>23.19.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>23.19.2</entry><entry>Header <code>&lt;execution&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>23.19.3</entry><entry>Execution policy type trait</entry><entry>Y</entry><entry></entry></row><row><entry>23.19.4</entry><entry>Sequenced execution policy</entry><entry>Y</entry><entry></entry></row><row><entry>23.19.5</entry><entry>Parallel execution policy</entry><entry>Y</entry><entry></entry></row><row><entry>23.19.6</entry><entry>Parallel and unsequenced execution policy</entry><entry>Y</entry><entry></entry></row><row><entry>23.19.7</entry><entry>Execution policy objects</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>24</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Strings</emphasis></entry></row><row><entry>24.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.2</entry><entry>Character traits</entry><entry>Y</entry><entry></entry></row><row><entry>24.3</entry><entry>String classes</entry><entry>Y</entry><entry></entry></row><row><entry>24.4</entry><entry>String view classes</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.1</entry><entry>Header <code>&lt;string_view&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.2</entry><entry>Class template <code>basic_string_view</code></entry><entry>Y</entry><entry></entry></row><row><entry>24.4.3</entry><entry>Non-member comparison functions</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.4</entry><entry>Inserters and extractors</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.5</entry><entry>Hash support</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.6</entry><entry>Suffix for <code>basic_string_view</code> literals</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>24.5</entry><entry>Null-terminated sequence utilities</entry><entry>Partial</entry><entry>C library dependency. </entry></row><row><entry><emphasis>25</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Localization</emphasis></entry></row><row><entry>25.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>25.2</entry><entry>Header <code>&lt;locale&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>25.3</entry><entry>Locales</entry><entry>Y</entry><entry></entry></row><row><entry>25.4</entry><entry>Standard <code>locale</code> categories</entry><entry>Y</entry><entry></entry></row><row><entry>25.5</entry><entry>C Library Locales</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>26</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers</emphasis></entry></row><row><entry>26.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>26.2</entry><entry>Container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>26.3</entry><entry>Sequence containers</entry><entry>Y</entry><entry></entry></row><row><entry>26.4</entry><entry>Associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>26.5</entry><entry>Unordered associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>26.6</entry><entry>Container adaptors</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>27</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Iterators</emphasis></entry></row><row><entry>27.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>27.2</entry><entry>Iterator requirements</entry><entry>Y</entry><entry></entry></row><row><entry>27.3</entry><entry>Header <code>&lt;iterator&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>27.4</entry><entry>Iterator primitives</entry><entry>Y</entry><entry></entry></row><row><entry>27.5</entry><entry>Iterator adaptors</entry><entry>Y</entry><entry></entry></row><row><entry>27.6</entry><entry>Stream iterators</entry><entry>Y</entry><entry></entry></row><row><entry>27.7</entry><entry>Range access</entry><entry>Y</entry><entry></entry></row><row><entry>27.8</entry><entry>Container access</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>28</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Algorithms</emphasis></entry></row><row><entry>28.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>28.2</entry><entry>Header <code>&lt;algorithm&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>28.3</entry><entry>Algorithms requirements</entry><entry></entry><entry></entry></row><row><entry>28.4</entry><entry>Parallel algorithms</entry><entry></entry><entry>Uses code from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://uxlfoundation.github.io/oneDPL/parallel_api_main.html">oneDPL</link></entry></row><row><entry>28.5</entry><entry>Non-modifying sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>28.6</entry><entry>Mutating sequence operations</entry><entry>Y</entry><entry></entry></row><row><entry>28.7</entry><entry>Sorting and related operations</entry><entry>Y</entry><entry></entry></row><row><entry>28.8</entry><entry>C library algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>29</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerics</emphasis></entry></row><row><entry>29.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>29.2</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>29.3</entry><entry>Numeric type requirements</entry><entry>Y</entry><entry></entry></row><row><entry>29.4</entry><entry>The floating-point environment</entry><entry>Y</entry><entry></entry></row><row><entry>29.5</entry><entry>Complex numbers</entry><entry>Y</entry><entry></entry></row><row><entry>29.6</entry><entry>Random number generation</entry><entry>Y</entry><entry></entry></row><row><entry>29.7</entry><entry>Numeric arrays</entry><entry>Y</entry><entry></entry></row><row><entry>29.8</entry><entry>Generalized numeric operations</entry><entry></entry><entry></entry></row><row><entry>29.8.1</entry><entry>Header <code>&lt;numeric&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>29.8.2</entry><entry>Accumulate</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.3</entry><entry>Reduce</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.4</entry><entry>Inner product</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.5</entry><entry>Transform reduce</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.6</entry><entry>Partial sum</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.7</entry><entry>Exclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.8</entry><entry>Inclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.9</entry><entry>Transform exclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.10</entry><entry>Transform inclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.11</entry><entry>Adjacent difference</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.12</entry><entry>Iota</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.13</entry><entry>Greatest common divisor</entry><entry>Y</entry><entry></entry></row><row><entry>29.8.14</entry><entry>Least common multiple</entry><entry>Y</entry><entry></entry></row><row><entry>29.9</entry><entry>Mathematical functions for floating-point types</entry><entry></entry><entry></entry></row><row><entry>29.9.1</entry><entry>Header <code>&lt;cmath&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>29.9.2</entry><entry>Absolute values</entry><entry>Y</entry><entry></entry></row><row><entry>29.9.3</entry><entry>Three-dimensional hypotenuse</entry><entry>Y</entry><entry></entry></row><row><entry>29.9.4</entry><entry>Classification / comparison functions</entry><entry>Y</entry><entry></entry></row><row><entry>29.9.5</entry><entry>Mathematical special functions</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>30</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Input/output library</emphasis></entry></row><row><entry>30.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>30.2</entry><entry>Iostreams requirements</entry><entry>Y</entry><entry></entry></row><row><entry>30.2.1</entry><entry>Imbue Limitations</entry><entry>Y</entry><entry></entry></row><row><entry>30.2.2</entry><entry>Positioning Type Limitations</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.2.3</entry><entry>Thread safety</entry><entry>Partial</entry><entry></entry></row><row><entry>30.3</entry><entry>Forward declarations</entry><entry>Y</entry><entry></entry></row><row><entry>30.4</entry><entry>Standard iostream objects</entry><entry>Y</entry><entry></entry></row><row><entry>30.5</entry><entry>Iostreams base classes</entry><entry>Y</entry><entry></entry></row><row><entry>30.6</entry><entry>Stream buffers</entry><entry>Y</entry><entry></entry></row><row><entry>30.7</entry><entry>Formatting and manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>30.8</entry><entry>String-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>30.9</entry><entry>File-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>30.10</entry><entry>File systemss</entry><entry>Y</entry><entry></entry></row><row><entry>30.11</entry><entry>C library files</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>31</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Regular expressions</emphasis></entry></row><row><entry>31.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>31.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>31.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>31.4</entry><entry>Header <code>&lt;regex&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>31.5</entry><entry>Namespace <code>std::regex_constants</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.6</entry><entry>Class <code>regex_error</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>31.7</entry><entry>Class template <code>regex_traits</code></entry><entry>Partial</entry><entry><code>transform_primary</code> is not correctly implemented</entry></row><row><entry>31.8</entry><entry>Class template <code>basic_regex</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.9</entry><entry>Class template <code>sub_match</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.10</entry><entry>Class template <code>match_results</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.11</entry><entry>Regular expression algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>31.12</entry><entry>Regular expression Iterators</entry><entry>Y</entry><entry></entry></row><row><entry>31.13</entry><entry>Modified ECMAScript regular expression grammar</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>32</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Atomic operations</emphasis></entry></row><row><entry>32.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>32.2</entry><entry>Header <code>&lt;atomic&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>32.3</entry><entry>Type aliases</entry><entry>Y</entry><entry></entry></row><row><entry>32.4</entry><entry>Order and consistency</entry><entry>Y</entry><entry></entry></row><row><entry>32.5</entry><entry>Lock-free property</entry><entry>Y</entry><entry></entry></row><row><entry>32.6</entry><entry>Class template <code>&lt;atomic&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.7</entry><entry>Non-member functions</entry><entry>Y</entry><entry></entry></row><row><entry>32.8</entry><entry>Flag Type and operations</entry><entry>Y</entry><entry></entry></row><row><entry>32.9</entry><entry>Fences</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>33</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Thread support</emphasis></entry></row><row><entry>33.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>33.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>33.3</entry><entry>Threads</entry><entry></entry><entry></entry></row><row><entry>33.3.1</entry><entry>Header <code>thread</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>33.3.2</entry><entry>Class <code>thread</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>33.3.2.1</entry><entry>Class <code>thread</code></entry><entry>Partial</entry><entry><code>thread::id</code> comparisons not well-defined</entry></row><row><entry>33.3.3</entry><entry>Namespace <code>this_thread</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4</entry><entry>Mutual exclusion</entry><entry></entry><entry></entry></row><row><entry>33.4.3</entry><entry>Mutex requirements</entry><entry></entry><entry></entry></row><row><entry>33.4.3.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>33.4.3.2</entry><entry>Mutex types</entry><entry></entry><entry></entry></row><row><entry>33.4.3.2.1</entry><entry>Class <code>mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.3.2.2</entry><entry>Class <code>recursive_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.3.3</entry><entry>Timed mutex types</entry><entry></entry><entry></entry></row><row><entry>33.4.3.3.1</entry><entry>Class <code>timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.3.3.2</entry><entry>Class <code>recursive_timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.3.4</entry><entry>Shared mutex types</entry><entry></entry><entry></entry></row><row><entry>33.4.3.4.1</entry><entry>Class <code>shared_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.3.5</entry><entry>Shared timed mutex types</entry><entry></entry><entry></entry></row><row><entry>33.4.3.5.1</entry><entry>Class <code>shared_timed_mutex</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.4</entry><entry>Locks</entry><entry></entry><entry></entry></row><row><entry>33.4.4.1</entry><entry>Class template <code>lock_guard</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.4.2</entry><entry>Class template <code>scoped_guard</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.4.3</entry><entry>Class template <code>unique_lock</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.4.4</entry><entry>Class template <code>shared_lock</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.4.5</entry><entry>Generic locking algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>33.4.6</entry><entry>Call once</entry><entry></entry><entry></entry></row><row><entry>33.4.6.1</entry><entry>Struct <code>once_flag</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>33.4.6.2</entry><entry>Function <code>call_once</code></entry><entry>Y</entry><entry>Exception support is broken.
	See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66146">PR
	66146</link>.
      </entry></row><row><entry>33.5</entry><entry>Condition variables</entry><entry>Y</entry><entry></entry></row><row><entry>33.5.1</entry><entry>Class <code>condition_variable</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.5.2</entry><entry>Class <code>condition_variable_any</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6</entry><entry>Futures</entry><entry></entry><entry></entry></row><row><entry>33.6.1</entry><entry>Overview</entry><entry></entry><entry></entry></row><row><entry>33.6.2</entry><entry>Header <code>&lt;future&gt;</code></entry><entry></entry><entry></entry></row><row><entry>33.6.3</entry><entry>Error handling</entry><entry>Y</entry><entry></entry></row><row><entry>33.6.4</entry><entry>Class <code>future_error</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6.5</entry><entry>Shared state</entry><entry>Y</entry><entry></entry></row><row><entry>33.6.6</entry><entry>Class template <code>promise</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6.7</entry><entry>Class template <code>future</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6.8</entry><entry>Class template <code>shared_future</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6.9</entry><entry>Function template <code>async</code></entry><entry>Y</entry><entry></entry></row><row><entry>33.6.10</entry><entry>Class template <code>packaged_task</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>Appendix D</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Compatibility features</emphasis></entry></row><row><entry>D.4</entry><entry>C++ standard library headers</entry><entry>Y</entry><entry></entry></row><row><entry>D.4.1</entry><entry>Header <code>&lt;ccomplex&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.4.1</entry><entry>Header <code>&lt;cstdalign&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.4.1</entry><entry>Header <code>&lt;cstdbool&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.4.1</entry><entry>Header <code>&lt;ctgmath&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.5</entry><entry>C standard library headers</entry><entry>Y</entry><entry></entry></row><row><entry>D.6</entry><entry><code>char*</code> streams</entry><entry>Y</entry><entry></entry></row><row><entry>D.7</entry><entry><code>uncaught_exception</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.8</entry><entry>Old adaptable function bindings</entry><entry>Y</entry><entry></entry></row><row><entry>D.9</entry><entry>The default allocator</entry><entry>Y</entry><entry></entry></row><row><entry>D.10</entry><entry>Raw storage iterator</entry><entry>Y</entry><entry></entry></row><row><entry>D.11</entry><entry>Temporary buffers</entry><entry>Y</entry><entry></entry></row><row><entry>D.12</entry><entry>Deprecated type traits</entry><entry>Y</entry><entry></entry></row><row><entry>D.13</entry><entry>Deprecated iterator primitives</entry><entry>Y</entry><entry></entry></row><row><entry>D.14</entry><entry>Deprecated <code>shared_ptr</code> observers</entry><entry>Y</entry><entry></entry></row><row><entry>D.15</entry><entry>Deprecated standard code conversion facets</entry><entry>Y</entry><entry></entry></row><row><entry>D.16</entry><entry>Deprecated convenience conversion interfaces</entry><entry>Y</entry><entry></entry></row></tbody></tgroup></table><table frame="all" xml:id="table.cxx17_ts_status"><title>C++ Technical Specifications Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Paper</entry><entry>Title</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2014/n4076.html">
	  N4076
	</link></entry><entry>A generalized callable negator</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2014/n4273.htm">
	  N4273
	</link></entry><entry>Uniform Container Erasure</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4061.pdf">
	  N4061
	</link></entry><entry>Greatest Common Divisor and Least Common Multiple</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4066.htm">
	  N4066
	</link></entry><entry>Delimited iterators</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4282.pdf">
	  N4282
	</link></entry><entry>The World's Dumbest Smart Pointer</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4388.html">
	  N4388
	</link></entry><entry>Const-Propagating Wrapper</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4391.html">
	  N4391
	</link></entry><entry><code>make_array</code>, revision 4 </entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4502.pdf">
	  N4502
	</link></entry><entry> Support for the C++ Detection Idiom, V2 </entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4519.pdf">
	  N4519
	</link></entry><entry> Source-Code Information Capture </entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4521.html">
	  N4521
	</link></entry><entry> Merge Fundamentals V1 into V2 </entry><entry>
        N (components from V1 are still in namespace
        <code>fundamentals_v1</code>)
      </entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2015/p0013r1.html">
	  P0013R1
	</link></entry><entry>Logical Operator Type Traits (revision 1)</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4531.html">
	  N4531
	</link></entry><entry>std::rand replacement, revision 3</entry><entry>Y</entry><entry>Library Fundamentals 2 TS</entry></row><row><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0214r9.pdf">
	  P0214R9
	</link></entry><entry>Data-Parallel Types</entry><entry>Y</entry><entry>Parallelism 2 TS</entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.2017.specific"><info><title>Implementation Specific Behavior</title></info><para>For behaviour which is also specified by previous standards,
      see <link linkend="iso.1998.specific">C++ 1998/2003 Implementation
      Specific Behavior</link> and <link linkend="iso.2011.specific">C++
      2011 Implementation Specific Behavior</link>. This section only
      documents behaviour which is new in the 2017 standard.
   </para><para><emphasis>20.5.1.2 [headers]</emphasis>
      Whether names from Annex K are declared by C++ headers depends on
      whether the underlying C library supports Annex K and declares the
      names. For the GNU C library, there is no Annex K support and so
      none of its names are declared by C++ headers.
   </para><para><emphasis>23.6.5 [optional.bad_optional_access]</emphasis><code>what()</code> returns <literal>"bad optional access"</literal>.
   </para><para><emphasis>23.7.3 [variant.variant]</emphasis><classname>variant</classname> supports over-aligned types.
   </para><para><emphasis>23.7.10 [variant.bad.access]</emphasis><code>what()</code> returns one of the strings
      <literal>"std::get: variant is valueless"</literal>,
      <literal>"std::get: wrong index for variant"</literal>,
      <literal>"std::visit: variant is valueless"</literal>,
      or <literal>"std::visit&lt;R&gt;: variant is valueless"</literal>.
   </para><para><emphasis>23.8.2 [any.bad_any_cast]</emphasis><code>what()</code> returns <literal>"bad any_cast"</literal>.
   </para><para><emphasis>23.12.5 [mem.res.pool.options]</emphasis>,
      <emphasis>23.12.5 [mem.res.pool.mem]</emphasis>
      Let S equal <code>numeric_limits&lt;size_t&gt;::digits</code>.
      The limit for maximum number of blocks in a chunk is given by
      <inlineequation><mathphrase>2<superscript>N</superscript>-1</mathphrase></inlineequation>,
      where N is <inlineequation><mathphrase>min(19, 3 + S/2)</mathphrase></inlineequation>.
      The largest allocation size that will be allocated from a pool is
      <inlineequation><mathphrase>2<superscript>22</superscript></mathphrase></inlineequation>
      when <inlineequation><mathphrase>S &gt; 20</mathphrase></inlineequation>,
      otherwise 3072 when <inlineequation><mathphrase>S &gt; 16</mathphrase></inlineequation>,
      otherwise 768.
   </para><para><emphasis>23.12.6.1 [mem.res.monotonic.buffer.ctor]</emphasis>
      The default <code>next_buffer_size</code> is <code>128 * sizeof(void*)</code>.
      The default growth factor is <code>1.5</code>.
   </para><para><emphasis>23.15.4.3 [meta.unary.prop]</emphasis>
      The predicate condition for
      <code>has_unique_object_representations</code> is true for all scalar
      types except floating point types.
   </para><para><emphasis>23.19.3 [execpol.type],
      28.4.3 [algorithms.parallel.exec]</emphasis>
      There are no implementation-defined execution policies.
   </para><para><emphasis>24.4.2 [string.view.template]</emphasis><classname>basic_string_view&lt;C, T&gt;::iterator</classname> is
      <code>C*</code> and
      <classname>basic_string_view&lt;C, T&gt;::const_iterator</classname> is
      <code>const C*</code>.
   </para><para><emphasis>28.4.3 [algorithms.parallel.exec]</emphasis>
      Threads of execution created by <classname>std::thread</classname>
      provide concurrent forward progress guarantees, so threads of execution
      implicitly created by the library will provide parallel forward
      progress guarantees.
   </para><para><emphasis>29.4.1 [cfenv.syn]</emphasis>
      The effects of the <filename>&lt;cfenv&gt;</filename> functions
      depends on whether the <code>FENV_ACCESS</code> pragma is supported,
      and on the C library that provides the header.
   </para><para><emphasis>29.6.9 [c.math.rand]</emphasis>
      Whether the <function>rand</function> function may introduce data
      races depends on the target C library that provides the function.
   </para><para><emphasis>29.9.5 [sf.cmath]</emphasis>
      Calling the mathematical special functions with large inputs is supported
      but the results may be imprecise.
   </para><para><emphasis>30.7.5.2.3 [ostream.inserters]</emphasis>
      NTCTS for <code>nullptr_t</code> is <literal>"nullptr"</literal>.
   </para><para><emphasis>30.10.2.1 [fs.conform.9945]</emphasis>,
      <emphasis>30.10.2.2 [fs.conform.os]</emphasis>
      The behavior of the filesystem library implementation will depend on
      the target operating system. Some features will not be supported
      on some targets. Symbolic links and file permissions
      are not supported on Windows.
   </para><para><emphasis>30.10.5 [fs.filesystem.syn]</emphasis>
      The clock used for file times is an unspecified type
      with a signed 64-bit representation, capable of representing
      timestamps with nanosecond resolution. The clock's epoch is
      unspecified, but is not the same as the system clock's epoch.
   </para><para><emphasis>30.10.7.1 [fs.path.generic]</emphasis>
      dot-dot in the root-directory refers to the root-directory itself.
      On Windows, a drive specifier such as <code>"C:"</code> or
      <code>"z:"</code> is treated as a root-name. On Cygwin, a path
      that begins with two successive directory separators is a
      root-name. Otherwise (for POSIX-like systems other than Cygwin),
      the implementation-defined root-name is an unspecified string
      which does not appear in any pathnames.
   </para><para><emphasis>30.10.10.1 [fs.enum.path.format]</emphasis>
      The character sequence is always interpreted in the native pathname
      format.
   </para><para><emphasis>30.10.15.4 [fs.op.file_size]</emphasis>
      If <code>!is_regular_file(p)</code>, an error is reported.
   </para><para><emphasis>30.10.15.32 [fs.op.rename]</emphasis>
      On Windows, <code>filesystem::rename</code>
      is implemented by calling <code>MoveFileExW</code> and so
      does not meet the requirements of POSIX <code>rename</code>
      when one or both of the paths resolves to an existing directory.
      Specifically, it is not possible to rename a directory to replace another
      directory (POSIX requires that to work if the directory being
      replaced is empty).
   </para><para><emphasis>30.10.29.2 [fs.enum.file_type]</emphasis>,
      <emphasis>30.10.34.3 [fs.op.copy]</emphasis>,
      <emphasis>30.10.34.35 [fs.op.status]</emphasis>
      No additional file types are supported, and there are no
      implementation-defined enumerators in
      <code>std::filesystem::file_type</code>.
   </para><para><emphasis>30.10.32 [fs.class.directory_iterator]</emphasis>,
     <emphasis>30.10.33 [fs.class.rec.dir.itr]</emphasis>
     Any directory-like file types supported by
     <code>opendir</code>/<code>readdir</code>
     (or <code>_wopendir</code>/<code>_wreaddir</code> on Windows).
   </para><section xreflabel="Implementation Specific Behavior of the Parallelism 2 TS" xml:id="iso.2017.par2ts"><info><title>Parallelism 2 TS</title></info><para><emphasis>9.3 [parallel.simd.abi]</emphasis><code>max_fixed_size&lt;T&gt;</code> is 32, except when targetting
        AVX512BW and <code>sizeof(T)</code> is 1.
     </para><para>
        When targeting 32-bit x86,
        <classname>simd_abi::compatible&lt;T&gt;</classname> is an alias for
        <classname>simd_abi::scalar</classname>.
        When targeting 64-bit x86 (including x32) or Aarch64,
        <classname>simd_abi::compatible&lt;T&gt;</classname> is an alias for
        <classname>simd_abi::_VecBuiltin&lt;16&gt;</classname>,
        unless <code>T</code> is <code>long double</code>, in which case it is
        an alias for <classname>simd_abi::scalar</classname>.
        When targeting ARM (but not Aarch64) with NEON support,
        <classname>simd_abi::compatible&lt;T&gt;</classname> is an alias for
        <classname>simd_abi::_VecBuiltin&lt;16&gt;</classname>,
        unless <code>sizeof(T) &gt; 4</code>, in which case it is
        an alias for <classname>simd_abi::scalar</classname>. Additionally,
        <classname>simd_abi::compatible&lt;float&gt;</classname> is an alias for
        <classname>simd_abi::scalar</classname> unless compiling with
        -ffast-math.
     </para><para>
        When targeting x86 (both 32-bit and 64-bit),
        <classname>simd_abi::native&lt;T&gt;</classname> is an alias for one of
        <classname>simd_abi::scalar</classname>,
        <classname>simd_abi::_VecBuiltin&lt;16&gt;</classname>,
        <classname>simd_abi::_VecBuiltin&lt;32&gt;</classname>, or
        <classname>simd_abi::_VecBltnBtmsk&lt;64&gt;</classname>, depending on
        <code>T</code> and the machine options the compiler was invoked with.
     </para><para>
        When targeting ARM/Aarch64 or POWER,
        <classname>simd_abi::native&lt;T&gt;</classname> is an alias for
        <classname>simd_abi::scalar</classname> or
        <classname>simd_abi::_VecBuiltin&lt;16&gt;</classname>, depending on
        <code>T</code> and the machine options the compiler was invoked with.
     </para><para>
        For any other targeted machine
        <classname>simd_abi::compatible&lt;T&gt;</classname> and
        <classname>simd_abi::native&lt;T&gt;</classname> are aliases for
        <classname>simd_abi::scalar</classname>. (subject to change)
     </para><para>
        The extended ABI tag types defined in the
        <code>std::experimental::parallelism_v2::simd_abi</code> namespace are:
        <classname>simd_abi::_VecBuiltin&lt;Bytes&gt;</classname>, and
        <classname>simd_abi::_VecBltnBtmsk&lt;Bytes&gt;</classname>.
     </para><para><classname>simd_abi::deduce&lt;T, N, Abis...&gt;::type</classname>,
        with <code>N &gt; 1</code> is an alias for an extended ABI tag, if a
        supported extended ABI tag exists. Otherwise it is an alias for
        <classname>simd_abi::fixed_size&lt;N&gt;</classname>. The <classname>
        simd_abi::_VecBltnBtmsk</classname> ABI tag is preferred over
        <classname>simd_abi::_VecBuiltin</classname>.
     </para><para><emphasis>9.4 [parallel.simd.traits]</emphasis><classname>memory_alignment&lt;T, U&gt;::value</classname> is
        <code>sizeof(U) * T::size()</code> rounded up to the next power-of-two
        value.
     </para><para><emphasis>9.6.1 [parallel.simd.overview]</emphasis>
        On ARM, <classname>simd&lt;T, _VecBuiltin&lt;Bytes&gt;&gt;</classname>
        is supported if <code>__ARM_NEON</code> is defined and
        <code>sizeof(T) &lt;= 4</code>. Additionally,
        <code>sizeof(T) == 8</code> with integral <code>T</code> is supported if
        <code>__ARM_ARCH &gt;= 8</code>, and <code>double</code> is supported if
        <code>__aarch64__</code> is defined.

        On POWER, <classname>simd&lt;T, _VecBuiltin&lt;Bytes&gt;&gt;</classname>
        is supported if <code>__ALTIVEC__</code> is defined and <code>sizeof(T)
        &lt; 8</code>. Additionally, <code>double</code> is supported if
        <code>__VSX__</code> is defined, and any <code>T</code> with <code>
        sizeof(T) &lt;= 8</code> is supported if <code>__POWER8_VECTOR__</code>
        is defined.

        On x86, given an extended ABI tag <code>Abi</code>,
        <classname>simd&lt;T, Abi&gt;</classname> is supported according to the
        following table:
        <table frame="all" xml:id="table.par2ts_simd_support"><title>Support for Extended ABI Tags</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>ABI tag <code>Abi</code></entry><entry>value type <code>T</code></entry><entry>values for <code>Bytes</code></entry><entry>required machine option</entry></row></thead><tbody><row><entry morerows="5"><classname>_VecBuiltin&lt;Bytes&gt;</classname></entry><entry morerows="1"><code>float</code></entry><entry>8, 12, 16</entry><entry>"-msse"</entry></row><row><entry>20, 24, 28, 32</entry><entry>"-mavx"</entry></row><row><entry morerows="1"><code>double</code></entry><entry>16</entry><entry>"-msse2"</entry></row><row><entry>24, 32</entry><entry>"-mavx"</entry></row><row><entry morerows="1">
                  integral types other than <code>bool</code>
                </entry><entry><code>Bytes</code> ≤ 16 and <code>Bytes</code> divisible by
                  <code>sizeof(T)</code>
                </entry><entry>"-msse2"</entry></row><row><entry>
                  16 &lt; <code>Bytes</code> ≤ 32 and <code>Bytes</code>
                  divisible by <code>sizeof(T)</code>
                </entry><entry>"-mavx2"</entry></row><row><entry morerows="1"><classname>_VecBuiltin&lt;Bytes&gt;</classname> and
                  <classname>_VecBltnBtmsk&lt;Bytes&gt;</classname>
                </entry><entry>
                  vectorizable types with <code>sizeof(T)</code> ≥ 4
                </entry><entry morerows="1">
                  32 &lt; <code>Bytes</code> ≤ 64 and <code>Bytes</code>
                  divisible by <code>sizeof(T)</code>
                </entry><entry>"-mavx512f"</entry></row><row><entry>
                  vectorizable types with <code>sizeof(T)</code> &lt; 4
                </entry><entry>"-mavx512bw"</entry></row><row><entry morerows="1"><classname>_VecBltnBtmsk&lt;Bytes&gt;</classname></entry><entry>
                  vectorizable types with <code>sizeof(T)</code> ≥ 4
                </entry><entry morerows="1"><code>Bytes</code> ≤ 32 and <code>Bytes</code> divisible by
                  <code>sizeof(T)</code>
                </entry><entry>"-mavx512vl"</entry></row><row><entry>
                  vectorizable types with <code>sizeof(T)</code> &lt; 4
                </entry><entry>"-mavx512bw" and "-mavx512vl"</entry></row></tbody></tgroup></table>
     </para></section></section></section><!-- Section 01.4 : Status C++ 2020 --><section version="5.0" xreflabel="Status C++ 2020" xml:id="status.iso.2020"><?dbhtml filename="status_iso_cxx2020.html"?><info><title>C++ 2020</title><keywordset><keyword>ISO C++</keyword><keyword>2020</keyword></keywordset></info><para>
In this implementation the <literal>-std=gnu++20</literal> or
<literal>-std=c++20</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
<constant>__cplusplus</constant> is used to check for the
presence of the required flag.
</para><para>
This section describes the C++20 and library TS support in
mainline GCC, not in any particular release.
</para><para>
The following table lists new library features that are included in
the C++20 standard. The "Proposal" column provides a link to the
ISO C++ committee proposal that describes the feature, while the "Status"
column indicates the first version of GCC that contains an implementation of
this feature (if it has been implemented).
A dash (—) in the status column indicates that the changes in the proposal
either do not affect the code in libstdc++, or the changes are not required for conformance.
The "SD-6 Feature Test / Notes" column shows the corresponding macro or header from
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations">SD-6:
Feature-testing recommendations for C++</link> (where applicable)
or any notes about the implementation.
</para><table frame="all" xml:id="table.cxx20_features"><title>C++ 2020 Library Features</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Library Feature</entry><entry>Proposal</entry><entry>Status</entry><entry>SD-6 Feature Test / Notes</entry></row></thead><tbody><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Compile-time programming</emphasis></entry></row><row><entry>  Add constexpr modifiers to functions in <code>&lt;algorithm&gt;</code> and <code>&lt;utility&gt;</code> Headers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0202r3.html">
        P0202R3 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_constexpr_algorithms &gt;= 201703L</code></entry></row><row><entry>  Constexpr for <code>swap</code> and swap related functions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0879r0.html">
        P0879R0 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_constexpr_algorithms &gt;= 201806L</code></entry></row><row><entry>  Constexpr for <code>std::complex</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0415r1.html">
        P0415R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_constexpr_complex &gt;= 201711L</code> (since 9.4, see Note 1) </entry></row><row><entry><code>std::is_constant_evaluated()</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0595r2.html">
        P0595R2 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_is_constant_evaluated &gt;= 201811L</code></entry></row><row><entry>  More constexpr containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0784r7.html">
        P0784R7 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_constexpr_dynamic_alloc &gt;= 201907L</code></entry></row><row><entry>  Making <code>std::string</code> constexpr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0980r1.pdf">
        P0980R1 </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_constexpr_string &gt;= 201907L</code></entry></row><row><entry>  Making <code>std::vector</code> constexpr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1004r2.pdf">
        P1004R2 </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_constexpr_vector &gt;= 201907L</code></entry></row><row><entry>  Constexpr in <code>std::pointer_traits</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1006r1.pdf">
        P1006R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_constexpr_memory &gt;= 201811L</code> (since 9.4, see Note 1) </entry></row><row><entry>  constexpr for <code>&lt;numeric&gt;</code> algorithms </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1645r1.html">
        P1645R1 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_constexpr_numeric &gt;= 201911L</code></entry></row><row><entry>  Constexpr iterator requirements </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0858r0.html">
        P0858R0 </link></entry><entry align="center"> 9.1 </entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_array_constexpr &gt;= 201803L</code></entry></row><row><entry><code>__cpp_lib_string_view &gt;= 201803L</code></entry></row><row><entry> (both since 9.4, see Note 1) </entry></row></tbody></tgroup></informaltable></entry></row><row><entry><code>constexpr</code> comparison operators for <code>std::array</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1023r0.pdf">
        P1023R0 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_array_constexpr &gt;= 201806</code></entry></row><row><entry>  Misc constexpr bits </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1032r1.html">
        P1032R1 </link></entry><entry align="center"> 10.1 </entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_array_constexpr &gt;= 201811L</code></entry></row><row><entry><code>__cpp_lib_constexpr_functional &gt;= 201811L</code></entry></row><row><entry><code>__cpp_lib_constexpr_iterator &gt;= 201811L</code></entry></row><row><entry><code>__cpp_lib_constexpr_string_view &gt;= 201811L</code></entry></row><row><entry><code>__cpp_lib_constexpr_tuple &gt;= 201811L</code></entry></row><row><entry><code>__cpp_lib_constexpr_utility &gt;= 201811L</code></entry></row></tbody></tgroup></informaltable></entry></row><row><entry><code>constexpr <emphasis>INVOKE</emphasis></code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1065r2.html">
        P1065R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_constexpr_functional &gt;= 201907L</code></entry></row><row><entry>  Transformation Trait <code>remove_cvref</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0550r2.pdf">
        P0550R2 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_remove_cvref &gt;= 201711L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Implicit conversion traits and utility functions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0758r1.html">
        P0758R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_is_nothrow_convertible &gt;= 201806L</code>  (since 9.4, see Note 1) </entry></row><row><entry>  The <code>identity</code> metafunction </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0887r1.pdf">
        P0887R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_type_identity &gt;= 201806L</code> (since 9.4, see Note 1) </entry></row><row><entry><code>unwrap_ref_decay</code> and <code>unwrap_reference</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0318r1.pdf">
        P0318R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_unwrap_ref &gt;= 201811L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Improving Completeness Requirements for Type Traits </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1285r0.pdf">
        P1285R0 </link></entry><entry align="center"> — </entry><entry> Most misuses are diagnosed, but not all. </entry></row><row><entry>  Missing feature test macros </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1353r0.html">
        P1353R0 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry> Making std::underlying_type SFINAE-friendly </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0340r3.html">
        P0340R3 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry> Traits for [Un]bounded Arrays </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1357r1.pdf">
        P1357R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_bounded_array_traits &gt;= 201902L</code></entry></row><row><entry> Layout-compatibility and pointer-interconvertibility traits </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0466r5.pdf">
        P0466R5 </link></entry><entry align="center"> 12.1 </entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_is_layout_compatible &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_is_pointer_interconvertible &gt;= 201907L</code></entry></row></tbody></tgroup></informaltable></entry></row><row><entry>  Integrating feature-test macros into the C++ WD </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0941r2.html">
        P0941R2 </link></entry><entry align="center"> 5.1 </entry><entry></entry></row><row><entry><code>&lt;version&gt;</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0754r2.pdf">
        P0754R2 </link></entry><entry align="center"> 9.1 </entry><entry><code>__has_include(&lt;version&gt;)</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Synchronization</emphasis></entry></row><row><entry>  Atomic Ref </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0019r8.html">
        P0019R8 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_atomic_ref &gt;= 201806L</code></entry></row><row><entry>  Floating Point Atomic </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0020r6.html">
        P0020R6 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_atomic_float &gt;= 201711L</code></entry></row><row><entry>  C++ Synchronized Buffered Ostream </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0053r7.pdf">
        P0053R7 </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_syncbuf &gt;= 201711L</code></entry></row><row><entry>  Manipulators for C++ Synchronized Buffered Ostream </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0753r2.pdf">
        P0753R2 </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_syncbuf &gt;= 201803L</code></entry></row><row><entry>  Make <code>std::memory_order</code> a scoped enumeration </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0439r0.html">
        P0439R0 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  The Curious Case of Padding Bits, Featuring Atomic Compare-and-Exchange </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0528r3.html">
        P0528R3 </link></entry><entry align="center"> 13.1 </entry><entry></entry></row><row><entry>  Atomic <code>shared_ptr</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0718r2.html">
        P0718R2 </link></entry><entry align="center"> 12.1 </entry><entry><code> __cpp_lib_atomic_shared_ptr &gt;= 201711L</code></entry></row><row><entry> std::stop_token and std::jthread </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0660r10.pdf">
        P0660R10 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_jthread &gt;= 201907L</code></entry></row><row><entry> Rename <code>condition_variable_any</code> interruptible wait methods </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1869r1.html">
        P1869R1 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_jthread &gt;= 201911L</code></entry></row><row><entry> Atomic waiting and notifying, std::semaphore, std::latch and std::barrier </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1135r6.html">
        P1135R6 </link></entry><entry align="center"> 11.1 </entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_atomic_lock_free_type_aliases &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_atomic_flag_test &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_atomic_wait &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_semaphore &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_latch &gt;= 201907L</code></entry></row><row><entry><code>__cpp_lib_barrier &gt;= 201907L</code></entry></row></tbody></tgroup></informaltable></entry></row><row><entry> Fixing Atomic Initialization </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0883r2.pdf">
        P0883R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_atomic_value_initialization &gt;= 201911L</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Ranges and Concepts</emphasis></entry></row><row><entry>  Standard Library Concepts </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0898r3.pdf">
        P0898R3 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_concepts &gt;= 201806L</code></entry></row><row><entry>  Rename concepts to standard_case for C++20, while we still can </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1754r1.pdf">
        P1754R1 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_concepts &gt;= 201907L</code></entry></row><row><entry>  Wording for <emphasis><code>boolean-testable</code></emphasis> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1964r2.html">
        P1964R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_concepts &gt;= 202002L</code></entry></row><row><entry>  The One Ranges Proposal </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0896r4.pdf">
        P0896R4 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_ranges &gt;= 201811L</code></entry></row><row><entry>  Input Range Adaptors </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1035r7.pdf">
        P1035R7 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_ranges &gt;= 201907L</code></entry></row><row><entry><code>ranges</code> compare algorithm are over-constrained </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1716r3.html">
        P1716R3 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_ranges &gt;= 201911L</code></entry></row><row><entry>  Remove CommonReference requirement from StrictWeakOrdering (a.k.a Fixing Relations) </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1248r1.html">
        P1248R1 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry> Ranges Design Cleanup </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1252r2.pdf">
        P1252R2 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry> Avoid template bloat for <code>safe_ranges</code> in combination with ‘subrange-y’ view adaptors.</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1739r4.html">
        P1739R4 </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Time, dates, calendars, time zones</emphasis></entry></row><row><entry>  Extending chrono to Calendars and Time Zones </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0355r7.html">
        P0355R7 </link></entry><entry> 14.1 (see Note 2) </entry><entry><code>__cpp_lib_chrono &gt;= 201803L</code></entry></row><row><entry> Miscellaneous minor fixes for chrono </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1466r3.html">
        P1466R3 </link></entry><entry> 11.1 (see Note 2) </entry><entry><code>__cpp_lib_chrono &gt;= 201907L</code></entry></row><row><entry><code>&lt;chrono&gt;</code><code>zero()</code>, <code>min()</code>, and <code>max()</code> should be <code>noexcept</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0972r0.pdf">
        P0972R0 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Three-way comparison</emphasis></entry></row><row><entry>  Library Support for the Spaceship (Comparison) Operator </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0768r1.pdf">
        P0768R1 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_three_way_comparison &gt;= 201711L</code></entry></row><row><entry>  Symmetry for spaceship </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0905r1.html">
        P0905R1 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry> Adding &lt;=&gt; to the standard library </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1614r2.html">
        P1614R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_three_way_comparison &gt;= 201907L</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Strings and text</emphasis></entry></row><row><entry><code>string::reserve</code> Should Not Shrink </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0966r1.html">
        P0966R1 </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry><code>char8_t</code>: A type for UTF-8 characters and strings </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0482r6.html">
        P0482R6 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_char8_t &gt;= 201811L</code></entry></row><row><entry><code>char8_t</code> backward compatibility remediation </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1423r3.html">
        P1423R3 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_char8_t &gt;= 201907L</code></entry></row><row><entry> Text formatting </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0645r10.html">
        P0645R10 </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_format &gt;= 201907L</code></entry></row><row><entry> Integration of chrono with text formatting </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1361r2.pdf">
        P1361R2 </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_format &gt;= 201907L</code></entry></row><row><entry> Printf corner cases in <code>std::format</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1652r1.html">
        P1652R1 </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_format &gt;= 201907L</code></entry></row><row><entry>  String Prefix and Suffix Checking </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0457r2.html">
        P0457R2 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_starts_ends_with &gt;= 201711L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Update The Reference To The Unicode Standard </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1025r1.html">
        P1025R1 </link></entry><entry align="center"> —</entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Containers</emphasis></entry></row><row><entry> span: bounds-safe views for sequences of objects </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0122r7.pdf">
        P0122R7 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_span &gt;= 201803L</code></entry></row><row><entry>
        Usability Enhancements for <classname>std::span</classname>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1024r3.pdf">
        P1024R3 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_span &gt;= 201902L</code></entry></row><row><entry>  Should Span be Regular? </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1085r2.md">
        P1085R2 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry> Fixed-size <code>&lt;span&gt;</code> construction from dynamic range </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1976r2.html">
        P1976R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_span &gt;= 202002L</code></entry></row><row><entry><code>std::to_array</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0325r4.html">
        P0325R4 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_to_array &gt;= 201907L</code></entry></row><row><entry>  Checking for Existence of an Element in Associative Containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0458r2.html">
        P0458R2 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  Comparing Unordered Containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0809r0.pdf">
        P0809R0 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>  Heterogeneous lookup for unordered containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0919r3.html">
        P0919R3 </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_generic_unordered_lookup &gt;= 201811</code></entry></row><row><entry> Refinement Proposal for P0919 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1690r1.html">
        P1690R1 </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry>  Adopt Consistent Container Erasure from Library Fundamentals 2 for C++20 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1209r0.html">
        P1209R0 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_erase_if &gt;= 201811L</code></entry></row><row><entry>  Improving the Return Value of Erase-Like Algorithms </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0646r1.pdf">
        P0646R1 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_list_remove_return_type &gt;= 201806L</code></entry></row><row><entry>  Improving the Return Value of Erase-Like Algorithms II: Free <code>erase</code>/<code>erase_if</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1115r3.pdf">
        P1115R3 </link></entry><entry align="center"> 9.1 </entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_erase_if &gt;= 202002L</code></entry></row><row><entry> (defined to <code>201900L</code> for GCC 9.1 and 9.2 so use <code>&gt; 201811L</code>) </entry></row></tbody></tgroup></informaltable></entry></row><row><entry> Signed ssize() functions, unsigned size() functions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1227r2.html">
        P1227R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_ssize &gt;= 201902L</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Memory management</emphasis></entry></row><row><entry>  Utility to convert a pointer to a raw pointer </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0653r2.html">
        P0653R2 </link></entry><entry align="center"> 8.1 </entry><entry><code>__cpp_lib_to_address &gt;= 201711L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Extending <code>make_shared</code> to Support Arrays </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0674r1.html">
        P0674R1 </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_shared_ptr_arrays &gt;= 201707L</code></entry></row><row><entry>  Efficient sized delete for variable sized classes </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0722r3.html">
        P0722R3 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_destroying_delete &gt;= 201806L</code></entry></row><row><entry>  Utility functions to implement uses-allocator construction </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0591r4.pdf">
        P0591R4 </link></entry><entry align="center"> 9.1 </entry><entry><code>std::scoped_allocator_adaptor</code> changes missing in 9.1.0
      </entry></row><row><entry><code>std::assume_aligned</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1007r3.pdf">
        P1007R3 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_assume_aligned &gt;= 201811L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Smart pointer creation with default initialization </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1020r1.html">
        P1020R1 </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_smart_ptr_for_overwrite &gt;= 201811L</code></entry></row><row><entry>  Rename "default_init" Functions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1973r1.pdf">
        P1973R1 </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_smart_ptr_for_overwrite &gt;= 201811L</code></entry></row><row><entry>  Make stateful allocator propagation more consistent for <code>operator+(basic_string)</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1165r1.html">
        P1165R1 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry><classname>polymorphic_allocator&lt;&gt;</classname> as a vocabulary type
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0339r6.pdf">
        P0339R6 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_polymorphic_allocator &gt;= 201902L</code> (since 9.4, see Note 1)
      </entry></row><row><entry>  LWG 2511: guaranteed copy elision for piecewise construction </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0475r1.html">
        P0475R1 </link></entry><entry align="center"> 7.1 </entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Miscellaneous</emphasis></entry></row><row><entry><code>nodiscard</code> in the Library </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0600r1.pdf">
        P0600R1 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  de-pessimize legacy algorithms with <code>std::move</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0616r0.pdf">
        P0616R0 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  Deprecate POD </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0767r1.html">
        P0767R1 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry>  Treating Unnecessary <code>decay</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0777r1.pdf">
        P0777R1 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>  Thou Shalt Not Specialize std Function Templates! </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0551r3.pdf">
        P0551R3 </link></entry><entry align="center"> </entry><entry>These changes will not be implemented.</entry></row><row><entry>  Bit-casting object representations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0476r2.html">
        P0476R2 </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_bit_cast &gt;= 201806L</code></entry></row><row><entry>  Integral power-of-2 operations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0556r3.html">
        P0556R3 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_int_pow2 &gt;= 201806L</code> (since 9.4, see Note 1) </entry></row><row><entry> On the names of low-level bit manipulation functions </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1956r1.pdf">
        P1956R1 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_int_pow2 &gt;= 202002L</code></entry></row><row><entry> Safe integral comparisons </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p0586r2.html">
        P0586R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_integer_comparison_functions &gt;= 202002L</code></entry></row><row><entry>  Reviewing Deprecated Facilities of C++17 for C++20 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0619r4.html">
        P0619R4 </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry><code>fpos</code> Requirements </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0759r1.html">
        P0759R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>  Add <code>shift</code> to <code>&lt;algorithm&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0769r2.pdf">
        P0769R2 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_shift &gt;= 201806L</code></entry></row><row><entry>  Standard Library Specification in a Concepts and Contracts World </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0788r3.pdf">
        P0788R3 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry><code>explicit(bool)</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0892r2.html">
        P0892R2 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>  Eradicating unnecessarily explicit default constructors from the standard library </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0935r0.html">
        P0935R0 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry><code>std::function</code> move constructor should be <code>noexcept</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0771r1.pdf">
        P0771R1 </link></entry><entry align="center"> 7.2 </entry><entry></entry></row><row><entry>  Simplified partial function application </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0356r5.html">
        P0356R5 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_bind_front &gt;= 201811L</code></entry></row><row><entry><code>bind_front</code> should not unwrap <code>reference_wrapper</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1651r0.html">
        P1651R0 </link></entry><entry align="center"> 9.3 </entry><entry><code>__cpp_lib_bind_front &gt;= 201907L</code></entry></row><row><entry><code>reference_wrapper</code> for incomplete types </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0357r3.html">
        P0357R3 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  Fixing <code>operator&gt;&gt;(basic_istream&amp;, CharT*)</code> (LWG 2499) </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0487r1.html">
        P0487R1 </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry><code>variant</code> and <code>optional</code> should propagate copy/move triviality </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0602r4.html">
        P0602R4 </link></entry><entry align="center"> 8.3 </entry><entry></entry></row><row><entry>  A sane <code>variant</code> converting constructor </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0608r3.html">
        P0608R3 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry><code>visit&lt;R&gt;</code>: Explicit Return Type for <code>visit</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0655r1.pdf">
        P0655R1 </link></entry><entry align="center"> 9.1 </entry><entry></entry></row><row><entry>  P0899R1 - LWG 3016 is not a defect </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0899r1.html">
        P0899R1 </link></entry><entry align="center"> 7.1 </entry><entry></entry></row><row><entry>  Editorial Guidance for merging P0019r8 and P0528r3 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1123r0.html">
        P1123R0 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>  Cleaning up Clause 20 </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1148r0.pdf">
        P1148R0 </link></entry><entry align="center"> — </entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>  Completing the Rebase of Library Fundamentals, Version 3, Working Draft </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1210r0.html">
        P1210R0 </link></entry><entry align="center"> </entry><entry></entry></row><row><entry>  Alternative Wording for P0907R4 Signed Integers are Two's Complement </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1236r1.html">
        P1236R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>
        I Stream, You Stream, We All Stream for
        <classname>istream_iterator</classname>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0738r2.html">
        P0738R2 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry>
        Mandating the Standard Library:
        Clause 16 - Language support library
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1458r1.pdf">
        P1458R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>
        Mandating the Standard Library:
        Clause 18 - Diagnostics library
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1458r1.pdf">
        P1459R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>
        Mandating the Standard Library:
        Clause 20 - Strings library
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1462r1.html">
        P1462R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry>
        Mandating the Standard Library:
        Clause 21 - Containers library
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1463r1.pdf">
        P1463R1 </link></entry><entry align="center"> 10.1 </entry><entry></entry></row><row><entry>
        Mandating the Standard Library:
        Clause 22 - Iterators library
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1464r1.pdf">
        P1464R1 </link></entry><entry align="center"> — </entry><entry></entry></row><row><entry> Make <code>create_directory()</code> Intuitive </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1164r1.pdf">
        P1164R1
  </link></entry><entry align="center"> 8.3 </entry><entry> Treated as a DR for C++17 </entry></row><row><entry>
        Target Vectorization Policies from Parallelism V2 TS to C++20
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1001r2.html">
        P1001R2 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_execution &gt;= 201902L</code> (since 9.4, see Note 1)</entry></row><row><entry> Merge Coroutines TS into C++20 working draft </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0912r5.html">
        P0912R5 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_coroutines &gt;= 201902L</code></entry></row><row><entry>  Endian just Endian </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0463r1.html">
        P0463R1 </link></entry><entry align="center"> 8.1 </entry><entry><code>__cpp_lib_endian &gt;= 201907L</code></entry></row><row><entry> Bit operations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0553r4.html">
        P0553R4 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_bitops &gt;= 201907L</code> (since 9.4, see Note 1) </entry></row><row><entry>  Well-behaved interpolation for numbers and pointers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0811r3.html">
        P0811R3 </link></entry><entry align="center"> 9.1 </entry><entry><code>__cpp_lib_interpolate &gt;= 201902L</code></entry></row><row><entry> Mathematical constants </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0631r8.pdf">
        P0631R8 </link></entry><entry align="center"> 10.1 </entry><entry><code>__cpp_lib_math_constants &gt;= 201907L</code></entry></row><row><entry> std::source_location </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1208r6.pdf">
        P1208R6 </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_source_location &gt;= 201907L</code></entry></row><row><entry> Efficient access to std::basic_stringbuf's Buffer </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0408r7.pdf">
        P0408R7 </link></entry><entry align="center"> 11.1 </entry><entry></entry></row></tbody></tgroup></table><para>
Note 1: This feature is supported in older releases but the
<code>__cpp_lib</code> macro is not defined to the right value
(or not defined at all) until the version shown in parentheses.
</para><para>
Note 2: The C++20 calendar types are supported since 11.1,
time zones and UTC are supported since 13.1,
and <function>chrono::parse</function> is supported since 14.1.
</para><para>
The following status table is based on the table of contents of
ISO/IEC 14882:2020.
Some subclauses are not shown in the table where the content is unchanged
since C++17 and the implementation is complete.
</para><table frame="all" xml:id="table.cxx20_status"><title>C++ 2020 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>17</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Language support library</emphasis></entry></row><row><entry>17.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>17.2</entry><entry>Common definitions</entry><entry></entry><entry></entry></row><row><entry>17.2.1</entry><entry>Header <code>&lt;cstddef&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.2.2</entry><entry>Header <code>&lt;cstdlib&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.2.3</entry><entry>Null pointers</entry><entry>Y</entry><entry></entry></row><row><entry>17.2.4</entry><entry>Sizes, alignments, and offsets</entry><entry>Y</entry><entry></entry></row><row><entry>17.2.5</entry><entry><code>byte</code> type operations</entry><entry>Y</entry><entry></entry></row><row><entry>17.3</entry><entry>Implementation properties</entry><entry></entry><entry></entry></row><row><entry>17.3.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>17.3.2</entry><entry>Header <code>&lt;version&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.3.3</entry><entry>Header <code>&lt;limits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.3.4</entry><entry>Floating-point type properties</entry><entry></entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>17.3.4.1</entry><entry>Type <code>float_round_style</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>17.3.4.2</entry><entry>Type <code>float_denorm_style</code></entry><entry>N</entry><entry></entry></row><row><entry>17.3.5</entry><entry>Class template <code>numeric_limits</code></entry><entry>Y</entry><entry></entry></row><row><entry>17.3.6</entry><entry>Header <code>&lt;climits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.3.7</entry><entry>Header <code>&lt;cfloat&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.4</entry><entry>Integer types</entry><entry></entry><entry></entry></row><row><entry>17.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>17.4.2</entry><entry>Header <code>&lt;cstdint&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>17.5</entry><entry>Startup and termination</entry><entry>Partial</entry><entry>C library dependency for quick_exit, at_quick_exit</entry></row><row><entry>17.6</entry><entry>Dynamic memory management</entry><entry>Y</entry></row><row><entry>17.7</entry><entry>Type identification</entry><entry>Y</entry><entry></entry></row><row><entry>17.8</entry><entry>Source location</entry><entry></entry><entry></entry></row><row><entry>17.8.1</entry><entry>Header <code>&lt;source_location&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.8.2</entry><entry>Class <code>source_location</code></entry><entry>Y</entry><entry></entry></row><row><entry>17.9</entry><entry>Exception handling</entry><entry>Y</entry><entry></entry></row><row><entry>17.10</entry><entry>Initializer lists</entry><entry>Y</entry><entry></entry></row><row><entry>17.11</entry><entry>Comparisons</entry><entry></entry><entry></entry></row><row><entry>17.11.1</entry><entry>Header <code>&lt;compare&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.11.2</entry><entry>Comparison category types</entry><entry>Y</entry><entry></entry></row><row><entry>17.11.3</entry><entry>Class template <code>common_comparison_category</code></entry><entry>Y</entry><entry></entry></row><row><entry>17.11.4</entry><entry>Concept <code>three_way_comparable</code></entry><entry>Y</entry><entry></entry></row><row><entry>17.11.5</entry><entry>Result of three-way comparison</entry><entry>Y</entry><entry></entry></row><row><entry>17.11.6</entry><entry>Comparison algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>17.12</entry><entry>Coroutines</entry><entry></entry><entry></entry></row><row><entry>17.12.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>17.12.2</entry><entry>Header <code>&lt;coroutine&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>17.12.3</entry><entry>Coroutine traits</entry><entry>Y</entry><entry></entry></row><row><entry>17.12.4</entry><entry>Class template <code>coroutine_handle</code></entry><entry>Y</entry><entry></entry></row><row><entry>17.12.5</entry><entry>No-op coroutines</entry><entry>Y</entry><entry></entry></row><row><entry>17.13</entry><entry>Other runtime support</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>18</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Concepts library</emphasis></entry></row><row><entry>18.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.2</entry><entry>Equality preservation</entry><entry></entry><entry></entry></row><row><entry>18.3</entry><entry>Header <code>&lt;concepts&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>18.4</entry><entry>Language-related concepts</entry><entry></entry><entry></entry></row><row><entry>18.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.4.2</entry><entry>Concept <code>same_as</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.3</entry><entry>Concept <code>derived_from</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.4</entry><entry>Concept <code>convertible_to</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.5</entry><entry>Concept <code>common_reference_with</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.6</entry><entry>Concept <code>common_with</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.7</entry><entry>Arithmetic concepts</entry><entry></entry><entry></entry></row><row><entry>18.4.8</entry><entry>Concept <code>assignable_from</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.9</entry><entry>Concept <code>swappable</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.10</entry><entry>Concept <code>destructible</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.11</entry><entry>Concept <code>constructible_from</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.12</entry><entry>Concept <code>default_initializable</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.13</entry><entry>Concept <code>move_constructible</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.4.14</entry><entry>Concept <code>copy_constructible</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.5</entry><entry>Comparison concepts</entry><entry></entry><entry></entry></row><row><entry>18.5.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.5.2</entry><entry>Boolean testability</entry><entry>Y</entry><entry></entry></row><row><entry>18.5.3</entry><entry>Concept <code>equality_comparable</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.5.4</entry><entry>Concept <code>totally_ordered</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.6</entry><entry>Object concepts</entry><entry>Y</entry><entry></entry></row><row><entry>18.7</entry><entry>Callable concepts</entry><entry></entry><entry></entry></row><row><entry>18.7.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>18.7.2</entry><entry>Concept <code>invocable</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7.3</entry><entry>Concept <code>regular_invocable</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7.4</entry><entry>Concept <code>predicate</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7.5</entry><entry>Concept <code>relation</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7.6</entry><entry>Concept <code>equivalence_relation</code></entry><entry>Y</entry><entry></entry></row><row><entry>18.7.7</entry><entry>Concept <code>strict_weak_order</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>19</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Diagnostics library</emphasis></entry></row><row><entry>19.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>19.2</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>19.3</entry><entry>Assertions</entry><entry>Y</entry><entry></entry></row><row><entry>19.4</entry><entry>Error numbers</entry><entry>Y</entry><entry></entry></row><row><entry>19.5</entry><entry>System error support</entry><entry></entry><entry></entry></row><row><entry>19.5.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>19.5.2</entry><entry>Header <code>&lt;system_error&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>19.5.3</entry><entry>Class <code>error_category</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.4</entry><entry>Class <code>error_code</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.5</entry><entry>Class <code>error_condition</code></entry><entry>Y</entry><entry></entry></row><row><entry>19.5.6</entry><entry>Comparison operator functions</entry><entry>Y</entry><entry></entry></row><row><entry>19.5.7</entry><entry>System error hash support</entry><entry>Y</entry><entry></entry></row><row><entry>19.5.8</entry><entry>Class <code>system_error</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>20</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General utilities library</emphasis></entry></row><row><entry>20.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.2</entry><entry>Utility components</entry><entry></entry><entry></entry></row><row><entry>20.2.1</entry><entry>Header <code>&lt;utility&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.2</entry><entry><code>swap</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.2.3</entry><entry><code>exchange</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.2.4</entry><entry>Forward/move helpers</entry><entry>Y</entry><entry></entry></row><row><entry>20.2.5</entry><entry>Function template <code>as_const</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.2.6</entry><entry>Function template <code>declval</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.2.7</entry><entry>Integer comparison functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.3</entry><entry>Compile-time integer sequences</entry><entry>Y</entry><entry></entry></row><row><entry>20.4</entry><entry>Pairs</entry><entry>Y</entry><entry></entry></row><row><entry>20.5</entry><entry>Tuples</entry><entry>Y</entry><entry></entry></row><row><entry>20.6</entry><entry>Optional objects</entry><entry>Y</entry><entry></entry></row><row><entry>20.7</entry><entry>Variants</entry><entry>Y</entry><entry></entry></row><row><entry>20.8</entry><entry>Storage for any type</entry><entry>Y</entry><entry></entry></row><row><entry>20.9</entry><entry>Bitsets</entry><entry>Y</entry><entry></entry></row><row><entry>20.10</entry><entry>Memory</entry><entry>Y</entry><entry></entry></row><row><entry>20.11</entry><entry>Smart pointers</entry><entry></entry><entry></entry></row><row><entry>20.11.1</entry><entry>Class template <code>unique_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.2</entry><entry>Class <code>bad_weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.3</entry><entry>Class template <code>shared_ptr</code></entry><entry>Y</entry><entry>Uses code from boost::shared_ptr.</entry></row><row><entry>20.11.4</entry><entry>Class template <code>weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.5</entry><entry>Class template <code>owner_less</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.6</entry><entry>Class template <code>enable_shared_from_this</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.11.7</entry><entry>Smart pointer hash support</entry><entry>Y</entry><entry></entry></row><row><entry>20.12</entry><entry>Memory resources</entry><entry></entry><entry></entry></row><row><entry>20.12.1</entry><entry>Header <code>&lt;memory_resource&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.2</entry><entry>Class <code>memory_resource</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.12.3</entry><entry>Class template <code>polymorphic_allocator</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.12.4</entry><entry>Access to program-wide <code>memory_resource</code> objects</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.5</entry><entry>Pool resource classes</entry><entry>Y</entry><entry></entry></row><row><entry>20.12.6</entry><entry>Class <code>monotonic_buffer_resource</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.13</entry><entry>Class template <code>scoped_allocator_adaptor</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14</entry><entry>Function objects</entry><entry></entry><entry></entry></row><row><entry>20.14.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.14.2</entry><entry>Header <code>&lt;functional&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.3</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>20.14.4</entry><entry>Requirements</entry><entry></entry><entry></entry></row><row><entry>20.14.5</entry><entry>Function template <code>invoke</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.6</entry><entry>Class template <code>reference_wrapper</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.7</entry><entry>Arithmetic operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.8</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.9</entry><entry>Concept-constrained comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.10</entry><entry>Logical operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.11</entry><entry>Bitwise operations</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.12</entry><entry>Class <code>identity</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.13</entry><entry>Function template <code>not_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.14</entry><entry>Function template <code>bind_front</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.15</entry><entry>Function object binders</entry><entry>Y</entry><entry></entry></row><row><entry>20.14.16</entry><entry>Function template <code>mem_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.17</entry><entry>Polymorphic function wrappers</entry><entry></entry><entry></entry></row><row><entry>20.14.17.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.14.17.2</entry><entry>Class <code>bad_function_call</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.17.3</entry><entry>Class template <code>function</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.14.18</entry><entry>Searchers</entry><entry>Y</entry><entry></entry></row><row><entry>20.15</entry><entry>Metaprogramming and type traits</entry><entry></entry><entry></entry></row><row><entry>20.15.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>20.15.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.3</entry><entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.4</entry><entry>Helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.5</entry><entry>Unary type traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.6</entry><entry>Type property queries</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.7</entry><entry>Relationships between types</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.8</entry><entry>Transformations between types</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.9</entry><entry>Logical operator traits</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.10</entry><entry>Member relationships</entry><entry>Y</entry><entry></entry></row><row><entry>20.15.11</entry><entry>Constant evaluation context</entry><entry>Y</entry><entry></entry></row><row><entry>20.16</entry><entry>Compile-time rational arithmetic</entry><entry>Y</entry><entry></entry></row><row><entry>20.17</entry><entry>Class <code>type_index</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.18</entry><entry>Execution policies</entry><entry>Y</entry><entry></entry></row><row><entry>20.19</entry><entry>Primitive numeric conversions</entry><entry></entry><entry></entry></row><row><entry>20.19.1</entry><entry>Header <code>&lt;charconv&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.19.2</entry><entry>Primitive numeric output conversion</entry><entry>Y</entry><entry>
 	Floating-point types up to 64-bit are formatted using
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/ulfjack/ryu">Ryu</link>.
	Types with greater precision are formatted using the C library
	(<function>sprintf</function> and conditionally
	<function>strfromf128</function>).
	For powerpc64le-unknown-linux-gnu <function>__sprintfieee128</function>
	must be provided by Glibc.
      </entry></row><row><entry>20.19.3</entry><entry>Primitive numeric input conversion</entry><entry>Y</entry><entry>
	Floating-point types up to 64-bit are parsed using
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/fastfloat/fast_float">fast_float</link>.
	Types with greater precision are parsed using the C library
	(<function>strtold</function>).
	For powerpc64le-unknown-linux-gnu <function>__strtoieee128</function>
	must be provided by Glibc.
      </entry></row><row><entry>20.20</entry><entry>Formatting</entry><entry></entry><entry></entry></row><row><entry>20.20.1</entry><entry>Header <code>&lt;format&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.2</entry><entry>Format string</entry><entry></entry><entry></entry></row><row><entry>20.20.2.1</entry><entry> In general</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.2.2</entry><entry>Standard format specifiers</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.3</entry><entry>Error reporting</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.4</entry><entry>Formatting functions</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.5</entry><entry>Formatter</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.5.1</entry><entry>Formatter requirements</entry><entry></entry><entry></entry></row><row><entry>20.20.5.2</entry><entry>Formatter specializations</entry><entry>Y</entry><entry></entry></row><row><entry>20.20.5.3</entry><entry>Class template <code>basic_format_parse_context</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.20.5.4</entry><entry>Class template <code>basic_format_context</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.20.6</entry><entry>Arguments</entry><entry></entry><entry></entry></row><row><entry>20.20.6.1</entry><entry>Class template <code>basic_format_arg</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.20.6.2</entry><entry>Class template <emphasis>format-arg-store</emphasis></entry><entry>Y</entry><entry></entry></row><row><entry>20.20.6.3</entry><entry>Class template <code>basic_format_args</code></entry><entry>Y</entry><entry></entry></row><row><entry>20.20.7</entry><entry>Class <code>format_error</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>21</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Strings library</emphasis></entry></row><row><entry>21.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>21.2</entry><entry>Character traits</entry><entry>Y</entry><entry></entry></row><row><entry>21.3</entry><entry>String classes</entry><entry>Y</entry><entry></entry></row><row><entry>21.4</entry><entry>String view classes</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>21.5</entry><entry>Null-terminated sequence utilities</entry><entry>Partial</entry><entry>C library dependency.</entry></row><row><entry><emphasis>22</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers library</emphasis></entry></row><row><entry>22.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>22.2</entry><entry>Container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>22.3</entry><entry>Sequence containers</entry><entry>Y</entry><entry></entry></row><row><entry>22.4</entry><entry>Associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>22.5</entry><entry>Unordered associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>22.6</entry><entry>Container adaptors</entry><entry>Y</entry><entry></entry></row><row><entry>22.7</entry><entry>Views</entry><entry></entry><entry></entry></row><row><entry>22.7.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>22.7.2</entry><entry>Header <code>&lt;span&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>22.7.3</entry><entry>Class template <code>span</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>23</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Iterators library</emphasis></entry></row><row><entry>23.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.2</entry><entry>Header <code>&lt;iterator&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>23.3</entry><entry>Iterator requirements</entry><entry></entry><entry></entry></row><row><entry>23.3.1</entry><entry>In general</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.2</entry><entry>Associated types</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.3</entry><entry>Customization points</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.4</entry><entry>Iterator concepts</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.5</entry><entry>C++17 iterator requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.6</entry><entry>Indirect callable requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.3.7</entry><entry>Common algorithm requirements</entry><entry>Y</entry><entry></entry></row><row><entry>23.4</entry><entry>Iterator primitives</entry><entry></entry><entry></entry></row><row><entry>23.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.4.2</entry><entry>Standard iterator tags</entry><entry>Y</entry><entry></entry></row><row><entry>23.4.3</entry><entry>Iterator operations</entry><entry>Y</entry><entry></entry></row><row><entry>23.4.4</entry><entry>Range iterator operations</entry><entry>Y</entry><entry></entry></row><row><entry>23.5</entry><entry>Iterator adaptors</entry><entry></entry><entry></entry></row><row><entry>23.5.1</entry><entry>Reverse iterators</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.2</entry><entry>Insert iterators</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.3</entry><entry>Move iterators and sentinels</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.4</entry><entry>Common iterators</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.5</entry><entry>Default sentinel</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.6</entry><entry>Counted iterators</entry><entry>Y</entry><entry></entry></row><row><entry>23.5.7</entry><entry> Unreachable sentinel</entry><entry>Y</entry><entry></entry></row><row><entry>23.6</entry><entry> Stream iterators</entry><entry>Y</entry><entry></entry></row><row><entry>23.6.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>23.6.2</entry><entry> Class template <code>istream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6.3</entry><entry>Class template <code>ostream_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6.4</entry><entry>Class template <code>istreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.6.5</entry><entry>Class template <code>ostreambuf_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>23.7</entry><entry>Range access</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>24</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Ranges library</emphasis></entry></row><row><entry>24.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.2</entry><entry>Header <code>&lt;ranges&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>24.3</entry><entry>Range access</entry><entry>Y</entry><entry></entry></row><row><entry>24.4</entry><entry>Range requirements</entry><entry></entry><entry></entry></row><row><entry>24.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.4.2</entry><entry>Ranges</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.3</entry><entry>Sized ranges</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.4</entry><entry>Views</entry><entry>Y</entry><entry></entry></row><row><entry>24.4.5</entry><entry>Other range refinements</entry><entry>Y</entry><entry></entry></row><row><entry>24.5</entry><entry>Range utilities</entry><entry></entry><entry></entry></row><row><entry>24.5.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.5.2</entry><entry>Helper concepts</entry><entry>Y</entry><entry></entry></row><row><entry>24.5.3</entry><entry>View interface</entry><entry>Y</entry><entry></entry></row><row><entry>24.5.4</entry><entry>Sub-ranges</entry><entry>Y</entry><entry></entry></row><row><entry>24.5.5</entry><entry>Dangling iterator handling</entry><entry>Y</entry><entry></entry></row><row><entry>24.6</entry><entry>Range factories</entry><entry></entry><entry></entry></row><row><entry>24.6.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.6.2</entry><entry>Empty view</entry><entry>Y</entry><entry></entry></row><row><entry>24.6.3</entry><entry>Single view</entry><entry>Y</entry><entry></entry></row><row><entry>24.6.4</entry><entry>Iota view</entry><entry>Y</entry><entry></entry></row><row><entry>24.6.5</entry><entry>Istream view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7</entry><entry>Range adaptors</entry><entry></entry><entry></entry></row><row><entry>24.7.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>24.7.2</entry><entry>Range adaptor objects</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.3</entry><entry>Semiregular wrapper</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.4</entry><entry>All view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.5</entry><entry>Filter view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.6</entry><entry>Transform view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.7</entry><entry>Take view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.8</entry><entry>Take while view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.9</entry><entry>Drop view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.10</entry><entry>Drop while view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.11</entry><entry>Join view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.12</entry><entry>Split view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.13</entry><entry>Counted view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.14</entry><entry>Common view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.15</entry><entry>Reverse view</entry><entry>Y</entry><entry></entry></row><row><entry>24.7.16</entry><entry>Elements view</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>25</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Algorithms library</emphasis></entry></row><row><entry>25.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>25.2</entry><entry>Algorithms requirements</entry><entry>Y</entry><entry></entry></row><row><entry>25.3</entry><entry>Parallel algorithms</entry><entry></entry><entry>Uses code from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://uxlfoundation.github.io/oneDPL/parallel_api_main.html">oneDPL</link></entry></row><row><entry>25.4</entry><entry>Header <code>&lt;algorithm&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>25.5</entry><entry>Algorithm result types</entry><entry>Y</entry><entry></entry></row><row><entry>25.6</entry><entry>Non-modifying sequence operations</entry><entry></entry><entry></entry></row><row><entry>25.6.1</entry><entry>All of</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.2</entry><entry>Any of</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.3</entry><entry>None of</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.4</entry><entry>For each</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.5</entry><entry>Find</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.6</entry><entry>Find end</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.7</entry><entry>Find first</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.8</entry><entry>Adjacent find</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.9</entry><entry>Count</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.10</entry><entry>Mismatch</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.11</entry><entry>Equal</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.12</entry><entry>Is permutation</entry><entry>Y</entry><entry></entry></row><row><entry>25.6.13</entry><entry>Search</entry><entry>Y</entry><entry></entry></row><row><entry>25.7</entry><entry>Mutating sequence operations</entry><entry></entry><entry></entry></row><row><entry>25.7.1</entry><entry>Copy</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.2</entry><entry>Move</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.3</entry><entry>Swap</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.4</entry><entry>Transform</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.5</entry><entry>Replace</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.6</entry><entry>Fill</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.7</entry><entry>Generate</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.8</entry><entry>Remove</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.9</entry><entry>Unique</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.10</entry><entry>Reverse</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.11</entry><entry>Rotate</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.12</entry><entry>Sample</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.13</entry><entry>Shuffle</entry><entry>Y</entry><entry></entry></row><row><entry>25.7.14</entry><entry>Shift</entry><entry>Y</entry><entry></entry></row><row><entry>25.8</entry><entry>Sorting and related operations</entry><entry></entry><entry></entry></row><row><entry>25.8.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.2</entry><entry>Sorting</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.3</entry><entry>Nth element</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.4</entry><entry>Binary search</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.5</entry><entry>Partitions</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.6</entry><entry>Merge</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.7</entry><entry>Set operations on sorted structures</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.8</entry><entry>Heap operations</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.9</entry><entry>Minimum and maximum</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.10</entry><entry>Bounded value</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.11</entry><entry>Lexicographical comparison</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.12</entry><entry>Three-way comparison algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>25.8.13</entry><entry>Permutation generators</entry><entry>Y</entry><entry></entry></row><row><entry>25.9</entry><entry>Header <code>&lt;numeric&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>25.10</entry><entry>Generalized numeric operations</entry><entry></entry><entry></entry></row><row><entry>25.10.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>25.10.2</entry><entry>Definitions</entry><entry></entry><entry></entry></row><row><entry>25.10.3</entry><entry>Accumulate</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.4</entry><entry>Reduce</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.5</entry><entry>Inner product</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.6</entry><entry>Transform reduce</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.7</entry><entry>Partial sum</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.8</entry><entry>Exclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.9</entry><entry>Inclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.10</entry><entry>Transform exclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.11</entry><entry>Transform inclusive scan</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.12</entry><entry>Adjacent difference</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.13</entry><entry>Iota</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.14</entry><entry>Greatest common divisor</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.15</entry><entry>Least common multiple</entry><entry>Y</entry><entry></entry></row><row><entry>25.10.16</entry><entry>Midpoint</entry><entry>Y</entry><entry></entry></row><row><entry>25.11</entry><entry>Specialized <code>&lt;memory&gt;</code> algorithms</entry><entry></entry><entry></entry></row><row><entry>25.11.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>25.11.2</entry><entry>Special memory concepts</entry><entry>Y</entry><entry></entry></row><row><entry>25.11.3</entry><entry><code>uninitialized_default_construct</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.4</entry><entry><code>uninitialized_value_construct</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.5</entry><entry><code>uninitialized_copy</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.6</entry><entry><code>uninitialized_move</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.7</entry><entry><code>uninitialized_fill</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.8</entry><entry><code>construct_at</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.11.9</entry><entry><code>destroy</code></entry><entry>Y</entry><entry></entry></row><row><entry>25.12</entry><entry>C library algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>26</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerics library</emphasis></entry></row><row><entry>26.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>26.2</entry><entry>Numeric type requirements</entry><entry>Y</entry><entry></entry></row><row><entry>26.3</entry><entry>The floating-point environment</entry><entry>Y</entry><entry></entry></row><row><entry>26.4</entry><entry>Complex numbers</entry><entry>Y</entry><entry></entry></row><row><entry>26.5</entry><entry>Bit manipulation</entry><entry></entry><entry></entry></row><row><entry>26.5.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>26.5.2</entry><entry>Header <code>&lt;bit&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>26.5.3</entry><entry>Function template <code>bit_cast</code></entry><entry>Y</entry><entry></entry></row><row><entry>26.5.4</entry><entry>Integral powers of 2</entry><entry>Y</entry><entry></entry></row><row><entry>26.5.5</entry><entry>Rotating</entry><entry>Y</entry><entry></entry></row><row><entry>26.5.6</entry><entry>Counting</entry><entry>Y</entry><entry></entry></row><row><entry>26.5.7</entry><entry>Endian</entry><entry>Y</entry><entry></entry></row><row><entry>26.6</entry><entry>Random number generation</entry><entry>Y</entry><entry></entry></row><row><entry>26.7</entry><entry>Numeric arrays</entry><entry>Y</entry><entry></entry></row><row><entry>26.8</entry><entry>Mathematical functions for floating-point types</entry><entry>Y</entry><entry></entry></row><row><entry>26.9</entry><entry>Numbers</entry><entry></entry><entry></entry></row><row><entry>26.9.1</entry><entry>Header <code>&lt;numbers&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>26.9.2</entry><entry>Mathematical constants</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>27</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Time library</emphasis></entry></row><row><entry>27.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>27.2</entry><entry>Header <code>&lt;chrono&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>27.3</entry><entry><emphasis>Cpp17Clock</emphasis> requirements</entry><entry>Y</entry><entry></entry></row><row><entry>27.4</entry><entry>Time-related traits</entry><entry></entry><entry></entry></row><row><entry>27.4.1</entry><entry><code>treat_as_floating_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.4.2</entry><entry><code>duration_values</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.4.3</entry><entry>Specializations of <code>common_type</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.4.4</entry><entry>Class template <code>is_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.5</entry><entry>Class template <code>duration</code></entry><entry></entry><entry></entry></row><row><entry>27.5.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.2</entry><entry>Constructors</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.3</entry><entry>Observer</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.4</entry><entry>Arithmetic</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.5</entry><entry>Special values</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.6</entry><entry>Non-member arithmetic</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.7</entry><entry>Comparisons</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.8</entry><entry>Conversions</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.9</entry><entry>Suffixes for duration literals</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.10</entry><entry>Algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>27.5.11</entry><entry>I/O</entry><entry>Y</entry><entry></entry></row><row><entry>27.6</entry><entry>Class template <code>time_point</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7</entry><entry>Clocks</entry><entry></entry><entry></entry></row><row><entry>27.7.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>27.7.2</entry><entry>Class <code>system_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.3</entry><entry>Class <code>utc_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.4</entry><entry>Class <code>tai_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.5</entry><entry>Class <code>gps_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.6</entry><entry>Type <code>file_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.7</entry><entry>Class <code>steady_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.8</entry><entry>Class <code>high_resolution_clock</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.7.9</entry><entry>Local time</entry><entry>Y</entry><entry></entry></row><row><entry>27.7.10</entry><entry><code>time_point</code> conversions</entry><entry>Y</entry><entry></entry></row><row><entry>27.8</entry><entry>The civil calendar</entry><entry></entry><entry></entry></row><row><entry>27.8.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>27.8.2</entry><entry>Class <code>last_spec</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.3</entry><entry>Class <code>day</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.4</entry><entry>Class <code>month</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.5</entry><entry>Class <code>year</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.6</entry><entry>Class <code>weekday</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.7</entry><entry>Class <code>weekday_indexed</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.8</entry><entry>Class <code>weekday_last</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.9</entry><entry>Class <code>month_day</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.10</entry><entry>Class <code>month_day_last</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.11</entry><entry>Class <code>month_weekday</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.12</entry><entry>Class <code>month_weekday_last</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.13</entry><entry>Class <code>year_month</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.14</entry><entry>Class <code>year_month_day</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.15</entry><entry>Class <code>year_month_day_last</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.16</entry><entry>Class <code>year_month_weekday</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.8.17</entry><entry>Class <code>year_month_weekday_last</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.9</entry><entry>Class template <code>hh_mm_ss</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.10</entry><entry>12/24 hours functions</entry><entry>Y</entry><entry></entry></row><row><entry>27.11</entry><entry>Time zones</entry><entry></entry><entry></entry></row><row><entry>27.11.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>27.11.2</entry><entry>Time zone database</entry><entry>Y</entry><entry></entry></row><row><entry>27.11.3</entry><entry>Exception classes</entry><entry>Y</entry><entry></entry></row><row><entry>27.11.4</entry><entry>Information classes</entry><entry>Y</entry><entry></entry></row><row><entry>27.11.5</entry><entry>Class <code>time_zone</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.11.6</entry><entry>Class template <code>zoned_traits</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.11.7</entry><entry>Class template <code>zoned_time</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.11.8</entry><entry>Class <code>leap_second</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.11.9</entry><entry>Class <code>time_zone_link</code></entry><entry>Y</entry><entry></entry></row><row><entry>27.12</entry><entry>Formatting</entry><entry>Y</entry><entry></entry></row><row><entry>27.13</entry><entry>Parsing</entry><entry>Y</entry><entry></entry></row><row><entry>27.14</entry><entry>Header <code>&lt;ctime&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>28</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Localization library</emphasis></entry></row><row><entry>28.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>28.2</entry><entry>Header <code>&lt;locale&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>28.3</entry><entry>Locales</entry><entry></entry><entry></entry></row><row><entry>28.3.1</entry><entry>Class <code>locale</code></entry><entry>Y</entry><entry></entry></row><row><entry>28.3.2</entry><entry><code>locale</code> globals</entry><entry>Y</entry><entry></entry></row><row><entry>28.3.3</entry><entry>Convenience interfaces</entry><entry></entry><entry></entry></row><row><entry>28.3.3.1</entry><entry>Character classification</entry><entry>Y</entry><entry></entry></row><row><entry>28.3.3.2</entry><entry>Character conversions</entry><entry>Y</entry><entry></entry></row><row><entry>28.4</entry><entry>Standard <code>locale</code> categories</entry><entry></entry><entry></entry></row><row><entry>28.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>28.4.2</entry><entry>The <code>ctype</code> category</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.3</entry><entry>The numeric category</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.4</entry><entry>The numeric punctuation facet</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.5</entry><entry>The collate category</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.6</entry><entry>The time category</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.7</entry><entry>The monetary category</entry><entry>Y</entry><entry></entry></row><row><entry>28.4.8</entry><entry>The message retrieval category</entry><entry>Y</entry><entry></entry></row><row><entry>28.5</entry><entry>C library locales</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>29</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Input/output library</emphasis></entry></row><row><entry>29.1</entry><entry> General</entry><entry>Y</entry><entry></entry></row><row><entry>29.2</entry><entry>Iostreams requirements</entry><entry></entry><entry></entry></row><row><entry>29.2.1</entry><entry>Imbue limitations</entry><entry>Y</entry><entry></entry></row><row><entry>29.2.2</entry><entry>Positioning type limitations</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>29.2.3</entry><entry>Thread safety</entry><entry>Partial</entry><entry></entry></row><row><entry>29.3</entry><entry>Forward declarations</entry><entry>Y</entry><entry></entry></row><row><entry>29.4</entry><entry>Standard iostream objects</entry><entry>Y</entry><entry></entry></row><row><entry>29.5</entry><entry>Iostreams base classes</entry><entry>Y</entry><entry></entry></row><row><entry>29.6</entry><entry>Stream buffers</entry><entry>Y</entry><entry></entry></row><row><entry>29.7</entry><entry>Formatting and manipulators</entry><entry>Y</entry><entry></entry></row><row><entry>29.8</entry><entry>String-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>29.9</entry><entry>File-based streams</entry><entry>Y</entry><entry></entry></row><row><entry>29.10</entry><entry>Synchronized output streams</entry><entry></entry><entry></entry></row><row><entry>29.10.1</entry><entry>Header <code>&lt;syncstream&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>29.10.2</entry><entry>Class template <code>basic_syncbuf</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.10.3</entry><entry>Class template <code>basic_osyncstream</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11</entry><entry>File systems</entry><entry></entry><entry></entry></row><row><entry>29.11.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>29.11.2</entry><entry>Conformance</entry><entry>Y</entry><entry></entry></row><row><entry>29.11.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>29.11.4</entry><entry>Header <code>&lt;filesystem&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>29.11.5</entry><entry>Error reporting</entry><entry>Y</entry><entry></entry></row><row><entry>29.11.6</entry><entry>Class <code>path</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.7</entry><entry>Class <code>filesystem_error</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8</entry><entry>Enumerations</entry><entry></entry><entry></entry></row><row><entry>29.11.8.1</entry><entry>Enum <code>path::format</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8.2</entry><entry>Enum class <code>file_type</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8.3</entry><entry>Enum class <code>copy_options</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8.4</entry><entry>Enum class <code>perms</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8.5</entry><entry>Enum class <code>perm_options</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.8.6</entry><entry>Enum class <code>directory_options</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.9</entry><entry>Class <code>file_status</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.10</entry><entry>Class <code>directory_entry</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.11</entry><entry>Class <code>directory_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.12</entry><entry>Class <code>recursive_directory_iterator</code></entry><entry>Y</entry><entry></entry></row><row><entry>29.11.13</entry><entry>Filesystem operation functions</entry><entry>Y</entry><entry></entry></row><row><entry>29.12</entry><entry>C library files</entry><entry></entry><entry></entry></row><row><entry>29.12.1</entry><entry>Header <code>&lt;cstdio&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>29.12.2</entry><entry>Header <code>&lt;cinttypes&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>30</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Regular expressions library</emphasis></entry></row><row><entry>30.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>30.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>30.3</entry><entry>Header <code>&lt;regex&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>30.4</entry><entry>Namespace <code>std::regex_constants</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.5</entry><entry>Class <code>regex_error</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>30.6</entry><entry>Class template <code>regex_traits</code></entry><entry>Partial</entry><entry><code>transform_primary</code> is not correctly implemented</entry></row><row><entry>30.7</entry><entry>Class template <code>basic_regex</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.8</entry><entry>Class template <code>sub_match</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.9</entry><entry>Class template <code>match_results</code></entry><entry>Y</entry><entry></entry></row><row><entry>30.10</entry><entry>Regular expression algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>30.11</entry><entry>Regular expression iterators</entry><entry>Y</entry><entry></entry></row><row><entry>30.12</entry><entry>Modified ECMAScript regular expression grammar</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>31</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Atomics library</emphasis></entry></row><row><entry>31.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>31.2</entry><entry>Header <code>&lt;atomic&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>31.3</entry><entry>Type aliases</entry><entry>Y</entry><entry></entry></row><row><entry>31.4</entry><entry>Order and consistency</entry><entry>Y</entry><entry></entry></row><row><entry>31.5</entry><entry>Lock-free property</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>31.6</entry><entry>Waiting and notifying</entry><entry>Partial</entry><entry>Waiting and notifying is not supported for volatile objects.</entry></row><row><entry>31.7</entry><entry>Class template <code>atomic_ref</code></entry><entry></entry><entry></entry></row><row><entry>31.7.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>31.7.2</entry><entry>Operations</entry><entry>Partial</entry><entry>
	volatile-qualified overloads for <code>wait</code>,
        <code>notify_one</code>, and <code>notify_all</code> are not provided.
      </entry></row><row><entry>31.7.3</entry><entry>Specializations for integral types</entry><entry>Y</entry><entry></entry></row><row><entry>31.7.4</entry><entry>Specializations for floating-point types</entry><entry>Y</entry><entry></entry></row><row><entry>31.7.5</entry><entry>Partial specialization for pointers</entry><entry>Y</entry><entry></entry></row><row><entry>31.8</entry><entry>Class template <code>atomic</code></entry><entry></entry><entry></entry></row><row><entry>31.8.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>31.8.2</entry><entry>Operations on atomic types</entry><entry>Partial</entry><entry>Waiting and notifying is not supported for volatile objects.</entry></row><row><entry>31.8.3</entry><entry>Specializations for integers</entry><entry>Y</entry><entry></entry></row><row><entry>31.8.4</entry><entry>Specializations for floating-point types</entry><entry>Y</entry><entry></entry></row><row><entry>31.8.5</entry><entry>Partial specialization for pointers</entry><entry>Y</entry><entry></entry></row><row><entry>31.8.6</entry><entry>Member operators common to integers and pointers to objects</entry><entry>Y</entry><entry></entry></row><row><entry>31.8.7</entry><entry>Partial specializations for smart pointers</entry><entry></entry><entry></entry></row><row><entry>31.8.7.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>31.8.7.2</entry><entry>Partial specialization for <code>shared_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.8.7.3</entry><entry>Partial specialization for <code>weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>31.9</entry><entry>Non-member functions</entry><entry>Y</entry><entry></entry></row><row><entry>31.10</entry><entry>Flag type and operations</entry><entry>Y</entry><entry></entry></row><row><entry>31.11</entry><entry>Fences</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>32</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Threads library</emphasis></entry></row><row><entry>32.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>32.2</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>32.3</entry><entry>Stop tokens</entry><entry></entry><entry></entry></row><row><entry>32.3.1</entry><entry>Introduction</entry><entry>Y</entry><entry></entry></row><row><entry>32.3.2</entry><entry>Header <code>&lt;stop_token&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>32.3.3</entry><entry>Class <code>stop_token</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.3.4</entry><entry>Class <code>stop_source</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.3.5</entry><entry>Class template <code>stop_callback</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.4</entry><entry>Threads</entry><entry></entry><entry></entry></row><row><entry>32.4.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.4.2</entry><entry>Header <code>&lt;thread&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>32.4.3</entry><entry>Class <code>thread</code></entry><entry>Partial</entry><entry><code>thread::id</code> comparisons not well-defined</entry></row><row><entry>32.4.4</entry><entry>Class <code>jthread</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.4.5</entry><entry>Namespace <code>this_thread</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.5</entry><entry>Mutual exclusion</entry><entry></entry><entry></entry></row><row><entry>32.5.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.5.2</entry><entry>Header <code>&lt;mutex&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>32.5.3</entry><entry>Header <code>&lt;shared_mutex&gt;</code> synopsis</entry><entry></entry><entry></entry></row><row><entry>32.5.4</entry><entry>Mutex requirements</entry><entry></entry><entry></entry></row><row><entry>32.5.4.1</entry><entry>In general</entry><entry></entry><entry></entry></row><row><entry>32.5.4.2</entry><entry>Mutex types</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.4.3</entry><entry>Timed mutex types</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.4.4</entry><entry>Shared mutex types</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.4.5</entry><entry>Shared timed mutex types</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.5</entry><entry>Locks</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.6</entry><entry>Generic locking algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>32.5.7</entry><entry>Call once</entry><entry></entry><entry></entry></row><row><entry>32.5.7.1</entry><entry>Struct <code>once_flag</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>32.5.7.2</entry><entry>Function <code>call_once</code></entry><entry>Partial</entry><entry>Exception support is broken.
	See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66146">PR
	66146</link>.
      </entry></row><row><entry>32.6</entry><entry>Condition variables</entry><entry>Y</entry><entry></entry></row><row><entry>32.7</entry><entry>Semaphore</entry><entry>Y</entry><entry></entry></row><row><entry>32.7.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.7.2</entry><entry>Header <code>&lt;semaphore&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>32.7.3</entry><entry>Class template <code>counting_semaphore</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.8</entry><entry>Coordination types</entry><entry></entry><entry></entry></row><row><entry>32.8.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.8.2</entry><entry>Latches</entry><entry></entry><entry></entry></row><row><entry>32.8.2.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.8.2.2</entry><entry>Header <code>&lt;latch&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>32.8.2.3</entry><entry>Class <code>latch</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.8.3</entry><entry>Barriers</entry><entry></entry><entry></entry></row><row><entry>32.8.3.1</entry><entry>General</entry><entry></entry><entry></entry></row><row><entry>32.8.3.2</entry><entry>Header <code>&lt;barrier&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>32.8.3.3</entry><entry>Class template <code>barrier</code></entry><entry>Y</entry><entry></entry></row><row><entry>32.9</entry><entry>Futures</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>Appendix D</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Compatibility features</emphasis></entry></row><row><entry>D.10</entry><entry>C headers</entry><entry></entry><entry></entry></row><row><entry>D.10.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.2</entry><entry>Header <code>&lt;complex.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.3</entry><entry>Header <code>&lt;iso646.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.4</entry><entry>Header <code>&lt;stdalign.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.5</entry><entry>Header <code>&lt;stdbool.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.6</entry><entry>Header <code>&lt;tgmath.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.10.7</entry><entry>Other C headers</entry><entry>Y</entry><entry></entry></row><row><entry>D.12</entry><entry>Relational operators</entry><entry>Y</entry><entry></entry></row><row><entry>D.13</entry><entry><code>char*</code> streams</entry><entry>Y</entry><entry></entry></row><row><entry>D.13.1</entry><entry>Header <code>&lt;strstream&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.13.2</entry><entry>Class <code>strstreambuf</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.13.3</entry><entry>Class <code>istrstream</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.13.4</entry><entry>Class <code>ostrstream</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.13.5</entry><entry>Class <code>strstream</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.14</entry><entry>Deprecated type traits</entry><entry>Y</entry><entry></entry></row><row><entry>D.15</entry><entry>Tuple</entry><entry>Y</entry><entry></entry></row><row><entry>D.16</entry><entry>Variant</entry><entry>Y</entry><entry></entry></row><row><entry>D.17</entry><entry>Deprecated <code>iterator</code> class template</entry><entry>Y</entry><entry></entry></row><row><entry>D.18</entry><entry>Deprecated <code>move_iterator</code> access</entry><entry>Y</entry><entry></entry></row><row><entry>D.19</entry><entry>Deprecated <code>shared_ptr</code> atomic access</entry><entry>Y</entry><entry></entry></row><row><entry>D.20</entry><entry>Deprecated <code>basic_string</code> capacity</entry><entry>Y</entry><entry></entry></row><row><entry>D.21</entry><entry>Deprecated standard code conversion facets</entry><entry></entry><entry></entry></row><row><entry>D.21.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>D.21.2</entry><entry>Header <code>&lt;codecvt&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>D.21.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>D.22</entry><entry>Deprecated convenience conversion interfaces</entry><entry></entry><entry></entry></row><row><entry>D.22.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>D.22.2</entry><entry>Class template <code>wstring_convert</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.22.3</entry><entry>Class template <code>wbuffer_convert</code></entry><entry>Y</entry><entry></entry></row><row><entry>D.23</entry><entry>Deprecated locale category facets</entry><entry>Y</entry><entry></entry></row><row><entry>D.24</entry><entry>Deprecated filesystem path factory functions</entry><entry>Y</entry><entry></entry></row><row><entry>D.25</entry><entry>Deprecated atomic operations</entry><entry></entry><entry></entry></row><row><entry>D.25.1</entry><entry>General</entry><entry>Y</entry><entry></entry></row><row><entry>D.25.2</entry><entry>Volatile access</entry><entry>Y</entry><entry></entry></row><row><entry>D.25.3</entry><entry>Non-member functions</entry><entry>Y</entry><entry></entry></row><row><entry>D.25.4</entry><entry>Operations on atomic types</entry><entry>Y</entry><entry></entry></row><row><entry>D.25.5</entry><entry>Flag type and operations</entry><entry>Y</entry><entry></entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.2020.specific"><info><title>Implementation Specific Behavior</title></info><para>For behaviour which is also specified by previous standards,
      see <link linkend="iso.1998.specific">C++ 1998/2003 Implementation
      Specific Behavior</link>, <link linkend="iso.2011.specific">C++
      2011 Implementation Specific Behavior</link>, and
      <link linkend="iso.2017.specific">C++ 2017 Implementation Specific
      Behavior</link>. This section only documents behaviour which is new in
      the 2020 standard.
   </para><para><emphasis>16.4.2.4 [compliance]</emphasis> The implementation is
      freestanding if the <code>-ffreestanding</code> compiler flag is used, 
      and hosted otherwise.
   </para><para><emphasis>16.4.2.4 [compliance]</emphasis>
      The support for always lock-free integral atomic types and presence of
      <code>atomic_signed_lock_free</code> and
      <code>atomic_unsigned_lock_free</code> type aliases depends on the
      target.
   </para><para><emphasis>27.5.11 [time.duration.io]</emphasis>
      The <literal>"μs"</literal> (<literal>"\u00b5\u0073"</literal>) is used
      for <code>std::micro</code> <code>Period::type</code> if the macro
      <code>_GLIBCXX_USE_ALT_MICROSECONDS_SUFFIX</code> is defined to a value
      other than zero before inclusion of the <code>chrono</code> header,
      <literal>"us"</literal> is used otherwise.
   </para><para><emphasis>29.8.2.2 [stringbuf.cons]</emphasis> Sequence pointers are
      initialized to null pointers by the
      <code>basic_stringbuf(ios_base::openmode)</code> constructor.
   </para><para><emphasis>31.7.1 [atomics.ref.generic.general]</emphasis>,
      <emphasis>31.7.3 [atomics.ref.int]</emphasis>,
      <emphasis>31.7.4 [atomics.ref.float]</emphasis>,
      <emphasis>31.7.5 [atomics.ref.pointer]</emphasis>
      The values of <code>is_always_lock_free</code> members depend on the
      target and cannot be listed here.
   </para><para><emphasis>31.7.1 [atomics.ref.generic.general]</emphasis>
      If <code>sizeof(T)</code> is equal to either <code>1</code>,
      <code>2</code>, <code>4</code>, <code>8</code>, or <code>16</code>,
      then the value of <code>required_alignment</code> member is equal to
      the maximum of <code>alignof(T)</code> and <code>sizeof(T)</code>.
      Otherwise <code>required_alignment</code> value is <code>alignof(T)</code>.
   </para><para><emphasis>31.7.3 [atomics.ref.int]</emphasis>
      The value of <code>required_alignment</code> member is equal to the
      maximum of <code>alignof(value_type)</code> and
      <code>sizeof(value_type)</code>.
   </para><para><emphasis>31.7.4 [atomics.ref.float]</emphasis>,
      <emphasis>31.7.5 [atomics.ref.pointer]</emphasis>
      The value of <code>required_alignment</code> member is equal to
      <code>alignof(value_type)</code>.
   </para><para><emphasis>32.7.3 [thread.sema.cnt]</emphasis> The value of default
      argument for the <code>least_max_value</code> parameter depends on the
      target operating system and platform, however the value of
      <code>counting_semaphore&lt;&gt;::max()</code> is greater than or equal
      to <code>numeric_limits&lt;int&gt;::max()</code>.
   </para></section></section><!-- Section 01.5 : Status C++ 2023 --><section version="5.0" xreflabel="Status C++ 2023" xml:id="status.iso.2023"><?dbhtml filename="status_iso_cxx2023.html"?><info><title>C++ 2023</title><keywordset><keyword>ISO C++</keyword><keyword>2023</keyword></keywordset></info><para>
In this implementation the <literal>-std=gnu++23</literal> or
<literal>-std=c++23</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
<constant>__cplusplus</constant> is used to check for the
presence of the required flag.
</para><para>
This section describes the C++23 and library TS support in
mainline GCC, not in any particular release.
</para><para>
The following table lists new library features that have been accepted into
the C++23 working draft. The "Proposal" column provides a link to the
ISO C++ committee proposal that describes the feature, while the "Status"
column indicates the first version of GCC that contains an implementation of
this feature (if it has been implemented).
A dash (—) in the status column indicates that the changes in the proposal
either do not affect the code in libstdc++, or the changes are not required for conformance.
The "SD-6 Feature Test / Notes" column shows the corresponding macro or header from
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations">SD-6:
Feature-testing recommendations for C++</link> (where applicable)
or any notes about the implementation.
</para><table frame="all" xml:id="table.cxx23_features"><title>C++ 2023 Library Features</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Library Feature</entry><entry>Proposal</entry><entry>Status</entry><entry>SD-6 Feature Test / Notes</entry></row></thead><tbody><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Ranges and Views</emphasis></entry></row><row><entry> Range constructor for std::string_view </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1989r2.pdf">
        P1989R2
        </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry><code>join_view</code> should join all views of ranges </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2328r1.html">
        P2328R1
        </link></entry><entry align="center"> 11.2 </entry><entry></entry></row><row><entry> Clarifying range adaptor objects </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2281r1.html">
        P2281R1
        </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry> Views should not be required to be default constructible </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2325r3.html">
        P2325R3
        </link></entry><entry align="center"> 11.3 </entry><entry><code>__cpp_lib_ranges &gt;= 202106L</code></entry></row><row><entry> Conditionally borrowed ranges </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p2017r1.html">
        P2017R1
        </link></entry><entry align="center"> 11.1 </entry><entry></entry></row><row><entry> Require <code>span</code> &amp; <code>basic_string_view</code> to be Trivially Copyable </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2251r1.pdf">
        P2251R1
        </link></entry><entry align="center"> Yes </entry><entry></entry></row><row><entry> Repairing input range adaptors and counted_iterator </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2259r1.html">
        P2259R1
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> Superior String Splitting </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2210r2.html">
        P2210R2
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> What is a <code>view</code>? </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2415r2.html">
        P2415R2
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_ranges &gt;= 202110L</code></entry></row><row><entry> Fix istream_view </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2432r1.pdf">
        P2432R1
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry><code>starts_with</code> and <code>ends_with</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1659r3.html">
        P1659R3
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_ranges_starts_ends_with &gt;= 202106L</code></entry></row><row><entry><code>zip</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2321r2.html">
        P2321R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_zip &gt;= 202110L</code></entry></row><row><entry><code>views::repeat</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2474r2.html">
        P2474R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_repeat &gt;= 202207L</code></entry></row><row><entry><code>views::enumerate</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2164r9.pdf">
        P2164R9
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_enumerate &gt;= 202302L</code></entry></row><row><entry><code>views::join_with</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2441r2.html">
        P2441R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_join_with &gt;= 202202L</code></entry></row><row><entry>
	Windowing range adaptors: <code>views::chunk</code>
	and <code>views::slide</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2442r1.html">
        P2442R1
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_slide &gt;= 202202L</code></entry></row><row><entry><code>views::chunk_by</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2443r1.html">
        P2443R1
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_chunk_by &gt;= 202202L</code></entry></row><row><entry><code>views::stride</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1899r3.html">
        P1899R3
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_stride &gt;= 202207L</code></entry></row><row><entry><code>views::cartesian_product</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2374r4.html">
        P2374R4
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_cartesian_product &gt;= 202207L</code></entry></row><row><entry> Empty Product for certain Views </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2540r1.html">
        P2540R1
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_cartesian_product &gt;= 202207L</code></entry></row><row><entry><code>views::as_rvalue</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2446r2.html">
        P2446R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_as_rvalue &gt;= 202207L</code></entry></row><row><entry><code>cbegin</code> should always return a constant iterator
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2278r4.html">
        P2278R4
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_as_const &gt;= 202207L</code></entry></row><row><entry><code>ranges::to</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1206r7.pdf">
        P1206R7
        </link></entry><entry align="center"><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry> 14.1 (<code>ranges::to</code> function) </entry></row><row><entry> 15.1 (new members in containers) </entry></row></tbody></tgroup></informaltable></entry><entry><code>__cpp_lib_ranges_to_container &gt;= 202202L</code>,
	<code>__cpp_lib_containers_ranges &gt;= 202202L</code></entry></row><row><entry> Ranges iterators as inputs to non-Ranges algorithms </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2408r5.html">
        P2408R5
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_algorithm_iterator_requirements &gt;= 202207L</code></entry></row><row><entry> Pipe support for user-defined range adaptors </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2387r3.html">
        P2387R3
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_bind_pack &gt;= 202202L</code>,
	<code>__cpp_lib_ranges &gt;= 202202L</code></entry></row><row><entry><code>ranges::iota</code>, <code>ranges::shift_left</code>,
        and <code>ranges::shift_right</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2440r1.html">
        P2440R1
        </link></entry><entry align="center"><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry> 13.1 (<code>ranges::iota</code>) </entry></row><row><entry> 16.1 (shift algos) </entry></row></tbody></tgroup></informaltable></entry><entry><code>__cpp_lib_ranges_iota &gt;= 202202L</code>,
	<code>__cpp_lib_shift &gt;= 202202L</code></entry></row><row><entry><code>ranges::find_last</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1223r5.pdf">
        P1223R5
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_find_last &gt;= 202207L</code></entry></row><row><entry><code>ranges::contains</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2302r4.html">
        P2302R4
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_contains &gt;= 202207L</code></entry></row><row><entry> Making multi-param constructors of views explicit </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2711r1.html">
        P2711R1
        </link></entry><entry align="center"> 16.1 </entry><entry></entry></row><row><entry><code>ranges::fold</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2322r6.html">
        P2322R6
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_ranges_fold &gt;= 202207L</code></entry></row><row><entry> Relaxing Ranges Just A Smidge</entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2609r3.html">
        P2609R3
        </link></entry><entry align="center"> 14.3 </entry><entry><code>__cpp_lib_ranges &gt;= 202302L</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Compile-time programming</emphasis></entry></row><row><entry> A proposal for a type trait to detect scoped enumerations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1048r1.pdf">
        P1048R1
        </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_is_scoped_enum &gt;= 202011L</code></entry></row><row><entry> std::to_underlying for enumerations </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1682r3.html">
        P1682R3
        </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_to_underlying &gt;= 202102L</code></entry></row><row><entry> Missing constexpr in std::optional and std::variant </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2231r1.html">
        P2231R1
        </link></entry><entry align="center"><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry> 11.3 (<code>optional</code>) </entry></row><row><entry> 12.1 (<code>variant</code>) </entry></row></tbody></tgroup></informaltable></entry><entry><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry><code>__cpp_lib_constexpr_optional &gt;= 202106L</code></entry></row><row><entry><code>__cpp_lib_variant &gt;= 202106L</code></entry></row></tbody></tgroup></informaltable></entry></row><row><entry> Making <code>std::unique_ptr</code> constexpr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2273r3.pdf">
        P2273R3
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_constexpr_memory &gt;= 202202L</code></entry></row><row><entry> Making <code>std::type_info::operator==</code> constexpr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1328r1.html">
        P1328R1
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_constexpr_typeinfo &gt;= 202106L</code></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry> constexpr for <code>&lt;cmath&gt;</code> and <code>&lt;cstdlib&gt;</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0533r9.pdf">
        P0533R9
        </link></entry><entry align="center"> </entry><entry><code>__cpp_lib_constexpr_cmath &gt;= 202202L</code></entry></row><row><entry> Deprecate std::aligned_storage and std::aligned_union </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1413r3.pdf">
        P1413R3
        </link></entry><entry align="center"> 13.1 </entry><entry></entry></row><row><entry> A type trait to detect reference binding to temporary </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2255r2.html">
        P2255R2
        </link></entry><entry align="center"><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry> 13.1 (missing changes to <code>std::tuple</code>) </entry></row><row><entry> 14.1 (complete) </entry></row></tbody></tgroup></informaltable></entry><entry><code>__cpp_lib_reference_from_temporary &gt;= 202202L</code></entry></row><row><entry>
        Move-only types for equality_comparable_with, totally_ordered_with,
	and three_way_comparable_with
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2404r3.pdf">
        P2404R3
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_concepts &gt;= 202207L</code></entry></row><row><entry> A trait for implicit lifetime types </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2674r1.pdf">
        P2674R1
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_is_implicit_lifetime &gt;= 202302L</code></entry></row><row><entry><code>common_reference_t</code> of <code>reference_wrapper</code>
	Should Be a Reference Type
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2655r3.html">
        P2655R3
        </link></entry><entry align="center"> 15.3 </entry><entry><code>__cpp_lib_common_reference &gt;= 202302L</code></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry> Deprecate <code>numeric_limits::has_denorm</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2614r2.pdf">
        P2614R2
        </link></entry><entry align="center"> </entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Containers</emphasis></entry></row><row><entry> Iterator pair constructors for stack and queue </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1425r4.pdf">
        P1425R4
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_adaptor_iterator_pair_constructor &gt;= 202106L</code></entry></row><row><entry> Stop overconstraining allocators in container deduction guides </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1518r2.html">
        P1518R2
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> Heterogeneous erasure overloads for associative containers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2077r3.html">
        P2077R3
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_associative_heterogeneous_erasure &gt;= 202110L</code></entry></row><row><entry><code>&lt;flat_map&gt;</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0429r9.pdf">
        P0429R9
        </link></entry><entry align="center"> 15.1 </entry><entry><code>__cpp_lib_flat_map &gt;= 202207L</code></entry></row><row><entry><code>&lt;flat_set&gt;</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1222r4.pdf">
        P1222R4
        </link></entry><entry align="center"> 15.1 </entry><entry><code>__cpp_lib_flat_set &gt;= 202207L</code></entry></row><row><entry><code>mdspan</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0009r18.html">
        P0009R18
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_mdspan &gt;= 202207L</code></entry></row><row><entry><code>index_type</code> &amp; <code>size_type</code>
	in <code>mdspan</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2599r2.pdf">
        P2599R2
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_mdspan &gt;= 202207L</code></entry></row><row><entry><code>mdspan</code>: rename <code>pointer</code> and
	<code>contiguous</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2604r0.html">
        P2604R0
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_mdspan &gt;= 202207L</code></entry></row><row><entry> Add the missing <code>empty</code> to <code>mdspan</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2613r1.html">
        P2613R1
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_mdspan &gt;= 202207L</code></entry></row><row><entry><code>layout_stride</code> static extents default constructor fix
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2763r1.html">
        P2763R1
        </link></entry><entry align="center"> 16.1 </entry><entry></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Strings and text</emphasis></entry></row><row><entry> string contains function </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1679r3.html">
        P1679R3
        </link></entry><entry align="center"> 11.1 </entry><entry><code>__cpp_lib_string_contains &gt;= 202011L</code></entry></row><row><entry> Prohibit std::basic_string and std::basic_string_view construction from nullptr </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p2166r1.html">
        P2166R1
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> basic_string::resize_and_overwrite </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1072r10.html">
        P1072R10
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_resize_and_overwrite &gt;= 202110L</code></entry></row><row><entry> A strstream replacement using span&lt;charT&gt; as buffer </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0448r4.pdf">
        P0448R4
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_spanstream &gt;= 202106L</code></entry></row><row><entry><code> std::string::substr() &amp;&amp; </code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2438r2.html">
        P2438R2
        </link></entry><entry align="center"> </entry><entry></entry></row><row><entry> std::format improvements </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2216r3.html">
        P2216R3
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_format &gt;= 202106L</code></entry></row><row><entry>
	Add support for <code>std::generator</code>-like types to
	<code>std::format</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2418r2.html">
        P2418R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_format &gt;= 202110L</code></entry></row><row><entry>
	Expose <code>std::<emphasis>basic-format-string</emphasis>&lt;charT, Args...&gt;</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2508r1.html">
        P2508R1
        </link></entry><entry align="center"> 13.1 (feature test macro not updated until 15.1) </entry><entry><code>__cpp_lib_format &gt;= 202207L</code></entry></row><row><entry>
	Clarify handling of encodings in localized formatting of chrono types
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2419r2.html">
        P2419R2
        </link></entry><entry align="center"> 15.1 </entry><entry><code>__cpp_lib_format &gt;= 202207L</code></entry></row><row><entry>
	Formatting pointers
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2510r3.pdf">
        P2510R3
        </link></entry><entry align="center"> 13.2 (feature test macro not updated until 15.1) </entry><entry><code>__cpp_lib_format &gt;= 202207L</code></entry></row><row><entry> Formatting Ranges </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2286r8.html">
        P2286R8
        </link></entry><entry align="center"><informaltable colsep="0" frame="none" rowheader="norowheader" rowsep="0"><tgroup cols="1"><tbody><row><entry> 15.1 (changes to adaptors missing) </entry></row><row><entry> 15.2 (complete) </entry></row></tbody></tgroup></informaltable></entry><entry><code>__cpp_lib_format_ranges &gt;= 202207L</code></entry></row><row><entry> Improve default container formatting </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2585r1.html">
        P2585R1
        </link></entry><entry align="center"> 15.1 (feature test macro not defined until 15.2) </entry><entry><code>__cpp_lib_format_ranges &gt;= 202207L</code></entry></row><row><entry> Formatted output </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2093r14.html">
        P2093R14
        </link></entry><entry align="center"> 14.1 </entry><entry><code>__cpp_lib_print &gt;= 202207L</code></entry></row><row><entry>
	Should the output of std::print to a terminal be synchronized with
	the underlying stream?
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2539r3.html">
        P2539R3
        </link></entry><entry align="center"> 14.1 </entry><entry></entry></row><row><entry>
	Formatting <code>thread::id</code> and <code>stacktrace</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2693r1.pdf">
        P2693R1
        </link></entry><entry align="center"> 14.1 </entry><entry><code>__cpp_lib_formatters &gt;= 202302L</code></entry></row><row><entry>
	Add Constexpr Modifiers to Functions <code>to_chars</code> and
	<code>from_chars</code> for Integral Types in
	<code>&lt;charconv&gt;</code> Header
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2291r3.pdf">
        P2291R3
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_constexpr_charconv &gt;= 202207L</code></entry></row><row><entry align="left" nameend="c4" namest="c1"><emphasis role="bold">Miscellaneous</emphasis></entry></row><row><entry> Inheriting from <code>std::variant</code> </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2162r2.html">
        P2162R2
        </link></entry><entry align="center"> 11.3 </entry><entry><code>__cpp_lib_variant &gt;= 202102L</code></entry></row><row><entry> Printing <code>volatile</code> Pointers </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1147r1.html">
        P1147R1
        </link></entry><entry align="center"> 11.3 </entry><entry></entry></row><row><entry> A Proposal to add stacktrace library </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p0881r7.html">
        P0881R7
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_stacktrace &gt;= 202011L</code></entry></row><row><entry> Add a pmr alias for std::stacktrace </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2301r1.html">
        P2301R1
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry><code>std::expected</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0323r12.html">
        P0323R12
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_expected &gt;= 202202L</code></entry></row><row><entry> Monadic operations for std::expected </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2505r5.html">
        P2505R5
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_expected &gt;= 202211L</code></entry></row><row><entry> Monadic operations for std::optional </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0798r8.html">
        P0798R8
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_optional &gt;= 202110L</code></entry></row><row><entry>
	Compatibility between <code>tuple</code>, <code>pair</code>
	and <emphasis>tuple-like</emphasis> objects </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2165r4.pdf">
        P2165R4
        </link></entry><entry align="center"> 14.1 </entry><entry><code>__cpp_lib_tuple_like &gt;= 202207L</code></entry></row><row><entry>
	Default Arguments for <code>pair</code>'s Forwarding Constructor
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1951r1.html">
        P1951R1
        </link></entry><entry align="center"> 14.1 </entry><entry></entry></row><row><entry><code>move_only_function</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0288r9.html">
        P0288R9
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_move_only_function &gt;= 202110L</code></entry></row><row><entry><code>invoke_r</code></entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2136r3.html">
        P2136R3
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_invoke_r &gt;= 202106L</code></entry></row><row><entry> Byteswapping for fun&amp;&amp;nuf </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1272r4.html">
        P1272R4
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_byteswap &gt;= 202110L</code></entry></row><row><entry> Function to mark unreachable code </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0627r6.pdf">
        P0627R6
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_unreachable &gt;= 202202L</code></entry></row><row><entry> Add a conditional noexcept specification to std::exchange </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2401r0.html">
        P2401R0
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> A more constexpr bitset </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2417r2.pdf">
        P2417R2
        </link></entry><entry align="center"> 13.1 </entry><entry><code>__cpp_lib_constexpr_bitset &gt;= 202207L</code></entry></row><row><entry> Extended floating-point types and standard names </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1467r9.html">
        P1467R9
        </link></entry><entry align="center"> 13.1 </entry><entry></entry></row><row><entry> Support C atomics in C++ </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p0943r6.html">
        P0943R6
        </link></entry><entry align="center"> 12.1 </entry><entry><code>__cpp_lib_stdatomic_h &gt;= 202011L</code></entry></row><row><entry> Clarifying the status of the "C headers" </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2340r1.html">
        P2340R1
        </link></entry><entry align="center"> Yes </entry><entry></entry></row><row><entry> Relax Requirements for time_point::clock </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p2212r2.html">
        P2212R2
        </link></entry><entry align="center"> Yes </entry><entry></entry></row><row><entry> Removing Garbage Collection Support </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2186r2.html">
        P2186R2
        </link></entry><entry align="center"> 12.1 </entry><entry></entry></row><row><entry> Easy [utilities], [ranges], and [iterators] </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1642r11.html">
        P1642R11
        </link></entry><entry align="center"> 13.1 </entry><entry></entry></row><row><entry> Providing size feedback in the Allocator interface </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0401r6.html">
        P0401R6
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_allocate_at_least &gt;= 202306L</code></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>
	Disallow User Specialization of <code>allocator_traits</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2652r2.html">
        P2652R2
        </link></entry><entry align="center"> </entry><entry></entry></row><row><entry> Explicit lifetime management </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2590r2.pdf">
        P2590R2
        </link></entry><entry align="center"> 16.1 </entry><entry><code>__cpp_lib_start_lifetime_as &gt;= 202207L</code></entry></row><row><entry>
	Fixing <code>std::start_lifetime_as</code> and
	<code>std::start_lifetime_as_array</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2679r2.pdf">
        P2679R2
        </link></entry><entry align="center"> 16.1 </entry><entry></entry></row><row><entry> out_ptr - a scalable output pointer abstraction </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1132r8.html">
        P1132R8
        </link></entry><entry align="center"> 14.1 </entry><entry><code>__cpp_lib_out_ptr &gt;= 202106L</code></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry><code>barrier</code>'s phase completion guarantees </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2588r3.html">
        P2588R3
        </link></entry><entry align="center"> </entry><entry><code>__cpp_lib_barrier &gt;= 202302L</code></entry></row><row><entry>
        Standard Library Modules <code>std</code> and <code>std.compat</code>
      </entry><entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2465r3.pdf">
        P2465R3
        </link></entry><entry align="center"> 15.1 </entry><entry><code>__cpp_lib_modules &gt;= 202207L</code></entry></row></tbody></tgroup></table></section><!-- Section 01.6 : Status C++ TR1 --><section version="5.0" xreflabel="Status C++ TR1" xml:id="status.iso.tr1"><?dbhtml filename="status_iso_cxxtr1.html"?><info><title>C++ TR1</title><keywordset><keyword>ISO C++</keyword><keyword>tr1</keyword></keywordset></info><para>
This table is based on the table of contents of ISO/IEC DTR 19768,
Doc No: N1836=05-0096, Date: 2005-06-24,
"Draft Technical Report on C++ Library Extensions".
</para><para>
In this implementation the header names are prefixed by
<code>tr1/</code>, for instance <code>&lt;tr1/functional&gt;</code>,
<code>&lt;tr1/memory&gt;</code>, and so on.
</para><para>
This page describes the TR1 support in
mainline GCC, not in any particular release.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.tr1_status"><title>C++ TR1 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>2</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>General Utilities</emphasis></entry></row><row><entry>2.1</entry><entry>Reference wrappers</entry><entry></entry><entry></entry></row><row><entry>2.1.1</entry><entry>Additions to header <code>&lt;functional&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>2.1.2</entry><entry>Class template <code>reference_wrapper</code></entry><entry></entry><entry></entry></row><row><entry>2.1.2.1</entry><entry><code>reference_wrapper</code> construct/copy/destroy</entry><entry>Y</entry><entry></entry></row><row><entry>2.1.2.2</entry><entry><code>reference_wrapper</code> assignment</entry><entry>Y</entry><entry></entry></row><row><entry>2.1.2.3</entry><entry><code>reference_wrapper</code> access</entry><entry>Y</entry><entry></entry></row><row><entry>2.1.2.4</entry><entry><code>reference_wrapper</code> invocation</entry><entry>Y</entry><entry></entry></row><row><entry>2.1.2.5</entry><entry><code>reference_wrapper</code> helper functions</entry><entry>Y</entry><entry></entry></row><row><entry>2.2</entry><entry>Smart pointers</entry><entry></entry><entry></entry></row><row><entry>2.2.1</entry><entry>Additions to header <code>&lt;memory&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.2</entry><entry>Class <code>bad_weak_ptr</code></entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3</entry><entry>Class template <code>shared_ptr</code></entry><entry></entry><entry><para>
	  Uses code from
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
	</para></entry></row><row><entry>2.2.3.1</entry><entry><code>shared_ptr</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.2</entry><entry><code>shared_ptr</code> destructor</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.3</entry><entry><code>shared_ptr</code> assignment</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.4</entry><entry><code>shared_ptr</code> modifiers</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.5</entry><entry><code>shared_ptr</code> observers</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.6</entry><entry><code>shared_ptr</code> comparison</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.7</entry><entry><code>shared_ptr</code> I/O</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.8</entry><entry><code>shared_ptr</code> specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.9</entry><entry><code>shared_ptr</code> casts</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.3.10</entry><entry><code>get_deleter</code></entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4</entry><entry>Class template <code>weak_ptr</code></entry><entry></entry><entry></entry></row><row><entry>2.2.4.1</entry><entry><code>weak_ptr</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.2</entry><entry><code>weak_ptr</code> destructor</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.3</entry><entry><code>weak_ptr</code> assignment</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.4</entry><entry><code>weak_ptr</code> modifiers</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.5</entry><entry><code>weak_ptr</code> observers</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.6</entry><entry><code>weak_ptr</code> comparison</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.4.7</entry><entry><code>weak_ptr</code> specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>2.2.5</entry><entry>Class template <code>enable_shared_from_this</code></entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>3</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Function Objects</emphasis></entry></row><row><entry>3.1</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>3.2</entry><entry>Additions to <code>&lt;functional&gt; synopsis</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.3</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>3.4</entry><entry>Function return types</entry><entry>Y</entry><entry></entry></row><row><entry>3.5</entry><entry>Function template <code>mem_fn</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.6</entry><entry>Function object binders</entry><entry></entry><entry></entry></row><row><entry>3.6.1</entry><entry>Class template <code>is_bind_expression</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.6.2</entry><entry>Class template <code>is_placeholder</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.6.3</entry><entry>Function template <code>bind</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.6.4</entry><entry>Placeholders</entry><entry>Y</entry><entry></entry></row><row><entry>3.7</entry><entry>Polymorphic function wrappers</entry><entry></entry><entry></entry></row><row><entry>3.7.1</entry><entry>Class <code>bad_function_call</code></entry><entry>Y</entry><entry></entry></row><row><entry>3.7.1.1</entry><entry><code>bad_function_call</code> constructor</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2</entry><entry>Class template <code>function</code></entry><entry></entry><entry></entry></row><row><entry>3.7.2.1</entry><entry><code>function</code> construct/copy/destroy</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.2</entry><entry><code>function</code> modifiers</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.3</entry><entry><code>function</code> capacity</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.4</entry><entry><code>function</code> invocation</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.5</entry><entry><code>function</code> target access</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.6</entry><entry>undefined operators</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.7</entry><entry>null pointer comparison operators</entry><entry>Y</entry><entry></entry></row><row><entry>3.7.2.8</entry><entry>specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>4</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Metaprogramming and type traits</emphasis></entry></row><row><entry>4.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>4.2</entry><entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>4.3</entry><entry>Helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>4.4</entry><entry>General Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>4.5</entry><entry>Unary Type Traits</entry><entry></entry><entry></entry></row><row><entry>4.5.1</entry><entry>Primary Type Categories</entry><entry>Y</entry><entry></entry></row><row><entry>4.5.2</entry><entry>Composite type traits</entry><entry>Y</entry><entry></entry></row><row><entry>4.5.3</entry><entry>Type properties</entry><entry>Y</entry><entry></entry></row><row><entry>4.6</entry><entry>Relationships between types</entry><entry>Y</entry><entry></entry></row><row><entry>4.7</entry><entry>Transformations between types</entry><entry></entry><entry></entry></row><row><entry>4.7.1</entry><entry>Const-volatile modifications</entry><entry>Y</entry><entry></entry></row><row><entry>4.7.2</entry><entry>Reference modifications</entry><entry>Y</entry><entry></entry></row><row><entry>4.7.3</entry><entry>Array modifications</entry><entry>Y</entry><entry></entry></row><row><entry>4.7.4</entry><entry>Pointer modifications</entry><entry>Y</entry><entry></entry></row><row><entry>4.8</entry><entry>Other transformations</entry><entry>Y</entry><entry></entry></row><row><entry>4.9</entry><entry>Implementation requirements</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>5</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Numerical Facilities</emphasis></entry></row><row><entry>5.1</entry><entry>Random number generation</entry><entry></entry><entry></entry></row><row><entry>5.1.1</entry><entry>Requirements</entry><entry>Y</entry><entry></entry></row><row><entry>5.1.2</entry><entry>Header <code>&lt;random&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>5.1.3</entry><entry>Class template <code>variate_generator</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4</entry><entry>Random number engine class templates</entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.1</entry><entry>Class template <code>linear_congruential</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.2</entry><entry>Class template <code>mersenne_twister</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.3</entry><entry>Class template <code>subtract_with_carry</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.4</entry><entry>Class template <code>subtract_with_carry_01</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.5</entry><entry>Class template <code>discard_block</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.4.6</entry><entry>Class template <code>xor_combine</code></entry><entry>Y</entry><entry>operator()() per N2079</entry></row><row><entry>5.1.5</entry><entry>Engines with predefined parameters</entry><entry>Y</entry><entry></entry></row><row><entry>5.1.6</entry><entry>Class <code>random_device</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7</entry><entry>Random distribution class templates</entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.1</entry><entry>Class template <code>uniform_int</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.2</entry><entry>Class <code>bernoulli_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.3</entry><entry>Class template <code>geometric_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.4</entry><entry>Class template <code>poisson_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.5</entry><entry>Class template <code>binomial_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.6</entry><entry>Class template <code>uniform_real</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.7</entry><entry>Class template <code>exponential_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.8</entry><entry>Class template <code>normal_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.1.7.9</entry><entry>Class template <code>gamma_distribution</code></entry><entry>Y</entry><entry></entry></row><row><entry>5.2</entry><entry>Mathematical special functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1</entry><entry>Additions to header <code>&lt;cmath&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.1</entry><entry>associated Laguerre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.2</entry><entry>associated Legendre functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.3</entry><entry>beta function</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.4</entry><entry>(complete) elliptic integral of the first kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.5</entry><entry>(complete) elliptic integral of the second kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.6</entry><entry>(complete) elliptic integral of the third kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.7</entry><entry>confluent hypergeometric functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.8</entry><entry>regular modified cylindrical Bessel functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.9</entry><entry>cylindrical Bessel functions (of the first kind)</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.10</entry><entry>irregular modified cylindrical Bessel functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.11</entry><entry>cylindrical Neumann functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.12</entry><entry>(incomplete) elliptic integral of the first kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.13</entry><entry>(incomplete) elliptic integral of the second kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.14</entry><entry>(incomplete) elliptic integral of the third kind</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.15</entry><entry>exponential integral</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.16</entry><entry>Hermite polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.17</entry><entry>hypergeometric functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.18</entry><entry>Laguerre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.19</entry><entry>Legendre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.20</entry><entry>Riemann zeta function</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.21</entry><entry>spherical Bessel functions (of the first kind)</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.22</entry><entry>spherical associated Legendre functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.1.23</entry><entry>spherical Neumann functions</entry><entry>Y</entry><entry></entry></row><row><entry>5.2.2</entry><entry>Additions to header <code>&lt;math.h&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>6</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Containers</emphasis></entry></row><row><entry>6.1</entry><entry>Tuple types</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.1</entry><entry>Header <code>&lt;tuple&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.2</entry><entry>Additions to header <code>&lt;utility&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3</entry><entry>Class template <code>tuple</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3.1</entry><entry>Construction</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3.2</entry><entry>Tuple creation functions</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3.3</entry><entry>Tuple helper classes</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3.4</entry><entry>Element access</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.3.5</entry><entry>Relational operators</entry><entry>Y</entry><entry></entry></row><row><entry>6.1.4</entry><entry>Pairs</entry><entry>Y</entry><entry></entry></row><row><entry>6.2</entry><entry>Fixed size array</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.1</entry><entry>Header <code>&lt;array&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2</entry><entry>Class template <code>array</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2.1</entry><entry><code>array</code> constructors, copy, and assignment</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2.2</entry><entry><code>array</code> specialized algorithms</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2.3</entry><entry><code>array</code> size</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2.4</entry><entry>Zero sized <code>array</code>s</entry><entry>Y</entry><entry></entry></row><row><entry>6.2.2.5</entry><entry>Tuple interface to class template <code>array</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3</entry><entry>Unordered associative containers</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.1</entry><entry>Unordered associative container requirements</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.1.1</entry><entry>Exception safety guarantees</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.2</entry><entry>Additions to header <code>&lt;functional&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.3</entry><entry>Class template <code>hash</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4</entry><entry>Unordered associative container classes</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.1</entry><entry>Header <code>&lt;unordered_set&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.2</entry><entry>Header <code>&lt;unordered_map&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.3</entry><entry>Class template <code>unordered_set</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.3.1</entry><entry><code>unordered_set</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.3.2</entry><entry><code>unordered_set</code> swap</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.4</entry><entry>Class template <code>unordered_map</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.4.1</entry><entry><code>unordered_map</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.4.2</entry><entry><code>unordered_map</code> element access</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.4.3</entry><entry><code>unordered_map</code> swap</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.5</entry><entry>Class template <code>unordered_multiset</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.5.1</entry><entry><code>unordered_multiset</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.5.2</entry><entry><code>unordered_multiset</code> swap</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.6</entry><entry>Class template <code>unordered_multimap</code></entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.6.1</entry><entry><code>unordered_multimap</code> constructors</entry><entry>Y</entry><entry></entry></row><row><entry>6.3.4.6.2</entry><entry><code>unordered_multimap</code> swap</entry><entry>Y</entry><entry></entry></row><row><entry><emphasis>7</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Regular Expressions</emphasis></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.1</entry><entry>Definitions</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.2</entry><entry>Requirements</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.3</entry><entry>Regular expressions summary</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.4</entry><entry>Header <code>&lt;regex&gt;</code> synopsis</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.5</entry><entry>Namespace <code>tr1::regex_constants</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.5.1</entry><entry>Bitmask Type <code>syntax_option_type</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.5.2</entry><entry>Bitmask Type <code>regex_constants::match_flag_type</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.5.3</entry><entry>Implementation defined <code>error_type</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.6</entry><entry>Class <code>regex_error</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.7</entry><entry>Class template <code>regex_traits</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8</entry><entry>Class template <code>basic_regex</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.1</entry><entry><code>basic_regex</code> constants</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.2</entry><entry><code>basic_regex</code> constructors</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.3</entry><entry><code>basic_regex</code> assign</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.4</entry><entry><code>basic_regex</code> constant operations</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.5</entry><entry><code>basic_regex</code> locale</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.6</entry><entry><code>basic_regex</code> swap</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.7</entry><entry><code>basic_regex</code> non-member functions</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.8.7.1</entry><entry><code>basic_regex</code> non-member swap</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.9</entry><entry>Class template <code>sub_match</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.9.1</entry><entry><code>sub_match</code> members</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.9.2</entry><entry><code>sub_match</code> non-member operators</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10</entry><entry>Class template <code>match_results</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.1</entry><entry><code>match_results</code> constructors</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.2</entry><entry><code>match_results</code> size</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.3</entry><entry><code>match_results</code> element access</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.4</entry><entry><code>match_results</code> formatting</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.5</entry><entry><code>match_results</code> allocator</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.10.6</entry><entry><code>match_results</code> swap</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.11</entry><entry>Regular expression algorithms</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.11.1</entry><entry>exceptions</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.11.2</entry><entry><code>regex_match</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.11.3</entry><entry><code>regex_search</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.11.4</entry><entry><code>regex_replace</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12</entry><entry>Regular expression Iterators</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.1</entry><entry>Class template <code>regex_iterator</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.1.1</entry><entry><code>regex_iterator</code> constructors</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.1.2</entry><entry><code>regex_iterator</code> comparisons</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.1.3</entry><entry><code>regex_iterator</code> dereference</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.1.4</entry><entry><code>regex_iterator</code> increment</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.2</entry><entry>Class template <code>regex_token_iterator</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.2.1</entry><entry><code>regex_token_iterator</code> constructors</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.2.2</entry><entry><code>regex_token_iterator</code> comparisons</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.2.3</entry><entry><code>regex_token_iterator</code> dereference</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.12.2.4</entry><entry><code>regex_token_iterator</code> increment</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>7.13</entry><entry>Modified ECMAScript regular expression grammar</entry><entry>N</entry><entry></entry></row><row><entry><emphasis>8</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>C Compatibility</emphasis></entry></row><row><entry>8.1</entry><entry>Additions to header <code>&lt;complex&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.2</entry><entry>Function <code>acos</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.3</entry><entry>Function <code>asin</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.4</entry><entry>Function <code>atan</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.5</entry><entry>Function <code>acosh</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.6</entry><entry>Function <code>asinh</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.7</entry><entry>Function <code>atanh</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.8</entry><entry>Function <code>fabs</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.1.9</entry><entry>Additional Overloads</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.2</entry><entry>Header <code>&lt;ccomplex&gt;</code></entry><entry>N</entry><entry>DR 551</entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.3</entry><entry>Header <code>&lt;complex.h&gt;</code></entry><entry>N</entry><entry>DR 551</entry></row><row><entry>8.4</entry><entry>Additions to header <code>&lt;cctype&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.4.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.4.2</entry><entry>Function <code>isblank</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.5</entry><entry>Additions to header <code>&lt;ctype.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.6</entry><entry>Header <code>&lt;cfenv&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.6.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.6.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.7</entry><entry>Header <code>&lt;fenv.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.8</entry><entry>Additions to header <code>&lt;cfloat&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.9</entry><entry>Additions to header <code>&lt;float.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.10</entry><entry>Additions to header <code>&lt;ios&gt;</code></entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.10.1</entry><entry>Synopsis</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.10.2</entry><entry>Function <code>hexfloat</code></entry><entry>N</entry><entry></entry></row><row><entry>8.11</entry><entry>Header <code>&lt;cinttypes&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.11.1</entry><entry>Synopsis</entry><entry>Y</entry><entry>DR 557</entry></row><row><entry>8.11.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.12</entry><entry>Header <code>&lt;inttypes.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.13</entry><entry>Additions to header <code>&lt;climits&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.14</entry><entry>Additions to header <code>&lt;limits.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.15</entry><entry>Additions to header <code>&lt;locale&gt;</code></entry><entry>N</entry><entry></entry></row><row><entry>8.16</entry><entry>Additions to header <code>&lt;cmath&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.16.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.16.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.16.3</entry><entry>Function template definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.16.4</entry><entry>Additional overloads</entry><entry>Y</entry><entry>DR 568; DR 550</entry></row><row><entry>8.17</entry><entry>Additions to header <code>&lt;math.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.18</entry><entry>Additions to header <code>&lt;cstdarg&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.19</entry><entry>Additions to header <code>&lt;stdarg.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.20</entry><entry>The header <code>&lt;cstdbool&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.21</entry><entry>The header <code>&lt;stdbool.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.22</entry><entry>The header <code>&lt;cstdint&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.22.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.22.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.23</entry><entry>The header <code>&lt;stdint.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.24</entry><entry>Additions to header <code>&lt;cstdio&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.24.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.24.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.24.3</entry><entry>Additional format specifiers</entry><entry>Y</entry><entry>C library dependency</entry></row><row><entry>8.24.4</entry><entry>Additions to header <code>&lt;stdio.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.25</entry><entry>Additions to header <code>&lt;cstdlib&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.25.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.25.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.25.3</entry><entry>Function <code>abs</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.25.4</entry><entry>Function <code>div</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.26</entry><entry>Additions to header <code>&lt;stdlib.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.27</entry><entry>Header <code>&lt;ctgmath&gt;</code></entry><entry>Y</entry><entry>DR 551</entry></row><row><entry>8.28</entry><entry>Header <code>&lt;tgmath.h&gt;</code></entry><entry>Y</entry><entry>DR 551</entry></row><row><entry>8.29</entry><entry>Additions to header <code>&lt;ctime&gt;</code></entry><entry>Y</entry><entry>C library dependency</entry></row><row><entry>8.30</entry><entry>Additions to header <code>&lt;cwchar&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.30.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.30.2</entry><entry>Definitions</entry><entry>Y</entry><entry></entry></row><row><entry>8.30.3</entry><entry>Additional wide format specifiers</entry><entry>Y</entry><entry>C library dependency</entry></row><row><entry>8.31</entry><entry>Additions to header <code>&lt;wchar.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.32</entry><entry>Additions to header <code>&lt;cwctype&gt;</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.32.1</entry><entry>Synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.32.2</entry><entry>Function <code>iswblank</code></entry><entry>Y</entry><entry></entry></row><row><entry>8.33</entry><entry>Additions to header <code>&lt;wctype.h&gt;</code></entry><entry>Y</entry><entry></entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.tr1.specific"><info><title>Implementation Specific Behavior</title></info><para>For behaviour which is specified by the 1998 and 2003 standards,
      see <link linkend="iso.1998.specific">C++ 1998/2003 Implementation
      Specific Behavior</link>. This section documents behaviour which
      is required by TR1.
   </para><para><emphasis>3.6.4 [tr.func.bind.place]/1</emphasis> There are 29
     placeholders defined and the placeholder types are
     <literal>Assignable</literal>.
   </para></section></section><!-- Section 01.7 : Status C++ TR24733 --><section version="5.0" xreflabel="Status C++ TR24733" xml:id="status.iso.tr24733"><?dbhtml filename="status_iso_cxxtr24733.html"?><info><title>C++ TR 24733</title><keywordset><keyword>TR 24733</keyword><keyword>decimal floating-point</keyword></keywordset></info><para>
This table is based on the table of contents of
ISO/IEC TR 24733:2011,
"Extensions for the programming language C++ to support
decimal floating-point arithmetic".
</para><para>
This page describes the TR 24733 support in
mainline GCC, not in any particular release.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.decfp_status"><title>C++ TR 24733 Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><entry><emphasis>0</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Introduction</emphasis></entry></row><row><entry><emphasis>1</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Normative references</emphasis></entry></row><row><entry><emphasis>2</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Conventions</emphasis></entry></row><row><entry><emphasis>3</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Decimal floating-point types</emphasis></entry></row><row><entry>3.1</entry><entry>Characteristics of decimal floating-point types</entry><entry></entry><entry></entry></row><row><entry>3.2</entry><entry>Decimal Types</entry><entry></entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>3.2.1</entry><entry>Class <code>decimal</code> synopsis</entry><entry>Partial</entry><entry>Missing declarations for formatted input/output; non-conforming extension for functions converting to integral type</entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>3.2.2</entry><entry>Class <code>decimal32</code></entry><entry>Partial</entry><entry>Missing 3.2.2.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>3.2.3</entry><entry>Class <code>decimal64</code></entry><entry>Partial</entry><entry>Missing 3.2.3.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>3.2.4</entry><entry>Class <code>decimal128</code></entry><entry>Partial</entry><entry>Missing 3.2.4.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry></row><row><entry>3.2.5</entry><entry>Initialization from coefficient and exponent</entry><entry>Y</entry><entry></entry></row><row><entry>3.2.6</entry><entry>Conversion to generic floating-point type</entry><entry>Y</entry><entry></entry></row><row><entry>3.2.7</entry><entry>Unary arithmetic operators</entry><entry>Y</entry><entry></entry></row><row><entry>3.2.8</entry><entry>Binary arithmetic operators</entry><entry>Y</entry><entry></entry></row><row><entry>3.2.9</entry><entry>Comparison operators</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.2.10</entry><entry>Formatted input</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.2.11</entry><entry>Formatted output</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.3</entry><entry>Additions to header <code>limits</code></entry><entry>N</entry><entry></entry></row><row><entry>3.4</entry><entry>Headers <code>cfloat</code> and <code>float.h</code></entry><entry></entry><entry></entry></row><row><entry>3.4.2</entry><entry>Additions to header <code>cfloat</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>3.4.3</entry><entry>Additions to header <code>float.h</code> synopsis</entry><entry>N</entry><entry></entry></row><row><entry>3.4.4</entry><entry>Maximum finite value</entry><entry>Y</entry><entry></entry></row><row><entry>3.4.5</entry><entry>Epsilon</entry><entry>Y</entry><entry></entry></row><row><entry>3.4.6</entry><entry>Minimum positive normal value</entry><entry>Y</entry><entry></entry></row><row><entry>3.4.7</entry><entry>Minimum positive subnormal value</entry><entry>Y</entry><entry></entry></row><row><entry>3.4.8</entry><entry>Evaluation format</entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.5</entry><entry>Additions to <code>cfenv</code> and <code>fenv.h</code></entry><entry>Outside the scope of GCC</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.6</entry><entry>Additions to <code>cmath</code> and <code>math.h</code></entry><entry>Outside the scope of GCC</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.7</entry><entry>Additions to <code>cstdio</code> and <code>stdio.h</code></entry><entry>Outside the scope of GCC</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.8</entry><entry>Additions to <code>cstdlib</code> and <code>stdlib.h</code></entry><entry>Outside the scope of GCC</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.9</entry><entry>Additions to <code>cwchar</code> and <code>wchar.h</code></entry><entry>Outside the scope of GCC</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.10</entry><entry>Facets</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.11</entry><entry>Type traits</entry><entry>N</entry><entry></entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>3.12</entry><entry>Hash functions</entry><entry>N</entry><entry></entry></row><row><entry><emphasis>4</emphasis></entry><entry align="left" nameend="c4" namest="c2"><emphasis>Notes on C compatibility</emphasis></entry></row></tbody></tgroup></table></section><!-- Section 01.8 : Status C++ IS 29124 --><section version="5.0" xreflabel="Status C++ 29124" xml:id="status.iso.specfun"><?dbhtml filename="status_iso_cxxis29124.html"?><info><title>C++ IS 29124</title><keywordset><keyword>ISO C++</keyword><keyword>Special Functions</keyword></keywordset></info><para>
This table is based on the table of contents of ISO/IEC FDIS 29124,
Doc No: N3060, Date: 2010-03-06,
"Extensions to the C++ Library to support mathematical special functions".
</para><para>
Complete support for IS 29124 is in GCC 6.1 and later releases, when using
at least C++11 (for older releases or C++98/C++03 use TR1 instead).
For C++11 and C++14 the additions to the library are not declared by their
respective headers unless <code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code>
is defined as a macro that expands to a non-zero integer constant.
For C++17 the special functions are always declared (since GCC 7.1).
</para><para>
When the special functions are declared the macro
<code>__STDCPP_MATH_SPEC_FUNCS__</code> is defined to <code>201003L</code>.
</para><para>
In addition to the special functions defined in IS 29124, for
non-strict modes (i.e. <code>-std=gnu++NN</code> modes) the
hypergeometric functions and confluent hypergeometric functions
from TR1 are also provided, defined in namespace
<code>__gnu_cxx</code>.
</para><!-- Status is Yes or No, Broken/Partial--><!--
   Yes

   No
      <?dbhtml bgcolor="#C8B0B0" ?>
   Broken/Partial
      <?dbhtml bgcolor="#B0B0B0" ?>
--><table frame="all" xml:id="table.specfun_status"><title>C++ Special Functions Implementation Status</title><tgroup align="left" cols="4" colsep="0" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Section</entry><entry>Description</entry><entry>Status</entry><entry>Comments</entry></row></thead><tbody><row><?dbhtml bgcolor="#B0B0B0" ?><entry>7</entry><entry>Macro names</entry><entry>Partial</entry><entry>No diagnostic for inconsistent definitions of
             <code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></entry></row><row><entry>8</entry><entry>Mathematical special functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1</entry><entry>Additions to header <code>&lt;cmath&gt;</code> synopsis</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.1</entry><entry>associated Laguerre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.2</entry><entry>associated Legendre functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.3</entry><entry>beta function</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.4</entry><entry>(complete) elliptic integral of the first kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.5</entry><entry>(complete) elliptic integral of the second kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.6</entry><entry>(complete) elliptic integral of the third kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.7</entry><entry>regular modified cylindrical Bessel functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.8</entry><entry>cylindrical Bessel functions (of the first kind)</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.9</entry><entry>irregular modified cylindrical Bessel functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.10</entry><entry>cylindrical Neumann functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.11</entry><entry>(incomplete) elliptic integral of the first kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.12</entry><entry>(incomplete) elliptic integral of the second kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.13</entry><entry>(incomplete) elliptic integral of the third kind</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.14</entry><entry>exponential integral</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.15</entry><entry>Hermite polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.16</entry><entry>Laguerre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.17</entry><entry>Legendre polynomials</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.18</entry><entry>Riemann zeta function</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.19</entry><entry>spherical Bessel functions (of the first kind)</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.20</entry><entry>spherical associated Legendre functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.1.21</entry><entry>spherical Neumann functions</entry><entry>Y</entry><entry></entry></row><row><entry>8.2</entry><entry>Additions to header <code>&lt;math.h&gt;</code></entry><entry>Y</entry><entry></entry></row><row><?dbhtml bgcolor="#B0B0B0" ?><entry>8.3</entry><entry>The header <code>&lt;ctgmath&gt;</code></entry><entry>Partial</entry><entry>Conflicts with C++ 2011 requirements.</entry></row><row><?dbhtml bgcolor="#C8B0B0" ?><entry>8.4</entry><entry>The header <code>&lt;tgmath.h&gt;</code></entry><entry>N</entry><entry>Conflicts with C++ 2011 requirements.</entry></row></tbody></tgroup></table><section xreflabel="Implementation Specific" xml:id="iso.specfun.specific"><info><title>Implementation Specific Behavior</title></info><para>For behaviour which is specified by the 2011 standard,
      see <link linkend="iso.2011.specific">C++ 2011 Implementation
      Specific Behavior</link>. This section documents behaviour which
      is required by IS 29124.
   </para><para><emphasis>7.2 [macro.user]/3 /4</emphasis> The functions declared in
     Clause 8 are only declared when
     <code>__STDCPP_WANT_MATH_SPEC_FUNCS__ == 1</code>
     (or in C++17 mode, for GCC 7.1 and later).
   </para><para><emphasis>8.1.1 [sf.cmath.Lnm]/1</emphasis> The effect of calling
     these functions with <code>n &gt;= 128</code> or <code>m &gt;= 128</code>
     should be described here.
   </para><para><emphasis>8.1.2 [sf.cmath.Plm]/3</emphasis> The effect of calling
     these functions with <code>l &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.3 [sf.cmath.I]/3</emphasis> The effect of calling
     these functions with <code>nu &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.8 [sf.cmath.J]/3</emphasis> The effect of calling
     these functions with <code>nu &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.9 [sf.cmath.K]/3</emphasis> The effect of calling
     these functions with <code>nu &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.10 [sf.cmath.N]/3</emphasis> The effect of calling
     these functions with <code>nu &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.15 [sf.cmath.Hn]/3</emphasis> The effect of calling
     these functions with <code>n &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.16 [sf.cmath.Ln]/3</emphasis> The effect of calling
     these functions with <code>n &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.17 [sf.cmath.Pl]/3</emphasis> The effect of calling
     these functions with <code>l &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.19 [sf.cmath.j]/3</emphasis> The effect of calling
     these functions with <code>n &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.20 [sf.cmath.Ylm]/3</emphasis> The effect of calling
     these functions with <code>l &gt;= 128</code> should be described here.
   </para><para><emphasis>8.1.21 [sf.cmath.n]/3</emphasis> The effect of calling
     these functions with <code>n &gt;= 128</code> should be described here.
   </para></section></section></section><!-- Section 02 : License --><section xreflabel="License" xml:id="manual.intro.status.license"><info><title>License</title></info><?dbhtml filename="license.html"?><para>
    There are two licenses affecting GNU libstdc++: one for the code,
    and one for the documentation.
    </para><para>
      There is a license section in the FAQ regarding common <link linkend="faq.license">questions</link>. If you have more
      questions, ask the FSF or the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/lists.html">gcc mailing list</link>.
    </para><section xreflabel="License GPL" xml:id="manual.intro.status.license.gpl"><info><title>The Code: GPL</title></info><para>
      The source code is distributed under the <link linkend="appendix.gpl-3.0">GNU General Public License version 3</link>,
      with the addition under section 7 of an exception described in
      the <quote>GCC Runtime Library Exception, version 3.1</quote>
      as follows (or see the file COPYING.RUNTIME):
    </para><literallayout class="normal">
GCC RUNTIME LIBRARY EXCEPTION

Version 3.1, 31 March 2009

Copyright (C) 2009 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.fsf.org">Free Software Foundation, Inc.</link>

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

This GCC Runtime Library Exception ("Exception") is an additional
permission under section 7 of the GNU General Public License, version
3 ("GPLv3"). It applies to a given file (the "Runtime Library") that
bears a notice placed by the copyright holder of the file stating that
the file is governed by GPLv3 along with this Exception.

When you use GCC to compile a program, GCC may combine portions of
certain GCC header files and runtime libraries with the compiled
program. The purpose of this Exception is to allow compilation of
non-GPL (including proprietary) programs to use, in this way, the
header files and runtime libraries covered by this Exception.

0. Definitions.

A file is an "Independent Module" if it either requires the Runtime
Library for execution after a Compilation Process, or makes use of an
interface provided by the Runtime Library, but is not otherwise based
on the Runtime Library.

"GCC" means a version of the GNU Compiler Collection, with or without
modifications, governed by version 3 (or a specified later version) of
the GNU General Public License (GPL) with the option of using any
subsequent versions published by the FSF.

"GPL-compatible Software" is software whose conditions of propagation,
modification and use would permit combination with GCC in accord with
the license of GCC.

"Target Code" refers to output from any compiler for a real or virtual
target processor architecture, in executable form or suitable for
input to an assembler, loader, linker and/or execution
phase. Notwithstanding that, Target Code does not include data in any
format that is used as a compiler intermediate representation, or used
for producing a compiler intermediate representation.

The "Compilation Process" transforms code entirely represented in
non-intermediate languages designed for human-written code, and/or in
Java Virtual Machine byte code, into Target Code. Thus, for example,
use of source code generators and preprocessors need not be considered
part of the Compilation Process, since the Compilation Process can be
understood as starting with the output of the generators or
preprocessors.

A Compilation Process is "Eligible" if it is done using GCC, alone or
with other GPL-compatible software, or if it is done without using any
work based on GCC. For example, using non-GPL-compatible Software to
optimize any GCC intermediate representations would not qualify as an
Eligible Compilation Process.

1. Grant of Additional Permission.

You have permission to propagate a work of Target Code formed by
combining the Runtime Library with Independent Modules, even if such
propagation would otherwise violate the terms of GPLv3, provided that
all Target Code was generated by Eligible Compilation Processes. You
may then convey such a combination under terms of your choice,
consistent with the licensing of the Independent Modules.

2. No Weakening of GCC Copyleft.

The availability of this Exception does not imply any general
presumption that third-party software is unaffected by the copyleft
requirements of the license of GCC.
    </literallayout><para>
      Hopefully that text is self-explanatory.  If it isn't, you need to speak
      to your lawyer, or the Free Software Foundation.
    </para></section><section xreflabel="License FDL" xml:id="manual.intro.status.license.fdl"><info><title>The Documentation: GPL, FDL</title></info><para>
      The documentation shipped with the library and made available over
      the web, excluding the pages generated from source comments, are
      copyrighted by the Free Software Foundation, and placed under the
      <link linkend="appendix.gfdl-1.3"> GNU Free Documentation
      License version 1.3</link>.  There are no Front-Cover Texts, no
      Back-Cover Texts, and no Invariant Sections.
    </para><para>
      For documentation generated by doxygen or other automated tools
      via processing source code comments and markup, the original source
      code license applies to the generated files. Thus, the doxygen
      documents are licensed <link linkend="appendix.gpl-3.0">GPL</link>.
    </para><para>
      If you plan on making copies of the documentation, please let us know.
      We can probably offer suggestions.
    </para></section></section><!-- Section 03 : Known Bugs --><section xreflabel="Bugs" xml:id="manual.intro.status.bugs"><info><title>Bugs</title></info><?dbhtml filename="bugs.html"?><section xreflabel="Bugs impl" xml:id="manual.intro.status.bugs.impl"><info><title>Implementation Bugs</title></info><para>
      Information on known bugs, details on efforts to fix them, and
      fixed bugs are all available as part of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugs/">GCC bug tracking system</link>,
      under the component <quote>libstdc++</quote>.
    </para></section><section xreflabel="Bugs iso" xml:id="manual.intro.status.bugs.iso"><info><title>Standard Bugs</title></info><para>
	Everybody's got issues.  Even the C++ Standard Library.
      </para><para>
	The Library Working Group, or LWG, is the ISO subcommittee responsible
	for making changes to the library.  They periodically publish an
	Issues List containing problems and possible solutions.  As they reach
	a consensus on proposed solutions, we often incorporate the solution.
      </para><para>
	Here are the issues which have resulted in code changes to the library.
	The links are to the full version of the Issues List.
        You can read the full version online
	at the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/">ISO C++
	Committee homepage</link>.
      </para><para>
	If a DR is not listed here, we may simply not have gotten to
	it yet; feel free to submit a patch.  Search the
        <filename class="directory">include</filename> and
        <filename class="directory">src</filename>
	directories for appearances of
	<constant>_GLIBCXX_RESOLVE_LIB_DEFECTS</constant> for examples
	of style.  Note that we usually do not make changes to the
	code until an issue has reached <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#DR">DR</link> status.
      </para><variablelist><varlistentry xml:id="manual.bugs.dr5"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#5">5</link>:
	<emphasis role="bold">string::compare specification questionable</emphasis></term><listitem><para>This should be two overloaded functions rather than a single function.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr17"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#17">17</link>:
	<emphasis role="bold">Bad bool parsing</emphasis></term><listitem><para>Apparently extracting Boolean values was messed up...
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr19"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#19">19</link>:
	<emphasis role="bold">"Noconv" definition too vague</emphasis></term><listitem><para>If <code>codecvt::do_in</code> returns <code>noconv</code> there are
	no changes to the values in <code>[to, to_limit)</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr22"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#22">22</link>:
	<emphasis role="bold">Member open vs flags</emphasis></term><listitem><para>Re-opening a file stream does <emphasis>not</emphasis> clear the state flags.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr23"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#23">23</link>:
	<emphasis role="bold">Num_get overflow result</emphasis></term><listitem><para>Implement the proposed resolution.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr25"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#25">25</link>:
	<emphasis role="bold">String operator&lt;&lt; uses width() value wrong</emphasis></term><listitem><para>Padding issues.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr48"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#48">48</link>:
	<emphasis role="bold">Use of non-existent exception constructor</emphasis></term><listitem><para>An instance of <code>ios_base::failure</code> is constructed instead.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr49"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#49">49</link>:
	<emphasis role="bold">Underspecification of ios_base::sync_with_stdio</emphasis></term><listitem><para>The return type is the <emphasis>previous</emphasis> state of synchronization.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr50"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#50">50</link>:
	<emphasis role="bold">Copy constructor and assignment operator of ios_base</emphasis></term><listitem><para>These members functions are declared <code>private</code> and are
	thus inaccessible.  Specifying the correct semantics of
	"copying stream state" was deemed too complicated.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr60"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#60">60</link>:
	<emphasis role="bold">What is a formatted input function?</emphasis></term><listitem><para>This DR made many widespread changes to <code>basic_istream</code>
	and <code>basic_ostream</code> all of which have been implemented.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr63"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#63">63</link>:
	<emphasis role="bold">Exception-handling policy for unformatted output</emphasis></term><listitem><para>Make the policy consistent with that of formatted input, unformatted
	input, and formatted output.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr68"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#68">68</link>:
	<emphasis role="bold">Extractors for char* should store null at end</emphasis></term><listitem><para>And they do now.  An editing glitch in the last item in the list of
	[27.6.1.2.3]/7.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr74"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#74">74</link>:
	<emphasis role="bold">Garbled text for codecvt::do_max_length</emphasis></term><listitem><para>The text of the standard was gibberish.  Typos gone rampant.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr75"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#75">75</link>:
	<emphasis role="bold">Contradiction in codecvt::length's argument types</emphasis></term><listitem><para>Change the first parameter to <code>stateT&amp;</code> and implement
	the new effects paragraph.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr83"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#83">83</link>:
	<emphasis role="bold">string::npos vs. string::max_size()</emphasis></term><listitem><para>Safety checks on the size of the string should test against
	<code>max_size()</code> rather than <code>npos</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr90"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#90">90</link>:
	<emphasis role="bold">Incorrect description of operator&gt;&gt; for strings</emphasis></term><listitem><para>The effect contain <code>isspace(c,getloc())</code> which must be
	replaced by <code>isspace(c,is.getloc())</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr91"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#91">91</link>:
	<emphasis role="bold">Description of operator&gt;&gt; and getline() for string&lt;&gt;
	    might cause endless loop</emphasis></term><listitem><para>They behave as a formatted input function and as an unformatted
	input function, respectively (except that <code>getline</code> is
	not required to set <code>gcount</code>).
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr103"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#103">103</link>:
	<emphasis role="bold">set::iterator is required to be modifiable, but this allows
	    modification of keys.</emphasis></term><listitem><para>For associative containers where the value type is the same as
	the key type, both <code>iterator</code> and <code>const_iterator
	</code> are constant iterators.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr109"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#109">109</link>:
	<emphasis role="bold">Missing binders for non-const sequence elements</emphasis></term><listitem><para>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
	<code>operator()</code> taking a non-const parameter.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr110"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#110">110</link>:
	<emphasis role="bold">istreambuf_iterator::equal not const</emphasis></term><listitem><para>This was not a const member function.  Note that the DR says to
	replace the function with a const one; we have instead provided an
	overloaded version with identical contents.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr117"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#117">117</link>:
	<emphasis role="bold">basic_ostream uses nonexistent num_put member functions</emphasis></term><listitem><para><code>num_put::put()</code> was overloaded on the wrong types.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr118"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#118">118</link>:
	<emphasis role="bold">basic_istream uses nonexistent num_get member functions</emphasis></term><listitem><para>Same as 117, but for <code>num_get::get()</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr129"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#129">129</link>:
	<emphasis role="bold">Need error indication from seekp() and seekg()</emphasis></term><listitem><para>These functions set <code>failbit</code> on error now.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr130"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#130">130</link>:
	<emphasis role="bold">Return type of container::erase(iterator) differs for associative containers</emphasis></term><listitem><para>Make member <code>erase</code> return iterator for <code>set</code>, <code>multiset</code>, <code>map</code>, <code>multimap</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr136"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#136">136</link>:
	<emphasis role="bold">seekp, seekg setting wrong streams?</emphasis></term><listitem><para><code>seekp</code> should only set the output stream, and
	<code>seekg</code> should only set the input stream.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr167"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#167">167</link>:
	<emphasis role="bold">Improper use of traits_type::length()</emphasis></term><listitem><para><code>op&lt;&lt;</code> with a <code>const char*</code> was
	calculating an incorrect number of characters to write.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr169"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#169">169</link>:
	<emphasis role="bold">Bad efficiency of overflow() mandated</emphasis></term><listitem><para>Grow efficiently the internal array object.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr171"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#171">171</link>:
	<emphasis role="bold">Strange seekpos() semantics due to joint position</emphasis></term><listitem><para>Quite complex to summarize...
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr181"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#181">181</link>:
	<emphasis role="bold">make_pair() unintended behavior</emphasis></term><listitem><para>This function used to take its arguments as reference-to-const, now
	it copies them (pass by value).
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr195"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#195">195</link>:
	<emphasis role="bold">Should basic_istream::sentry's constructor ever set eofbit?</emphasis></term><listitem><para>Yes, it can, specifically if EOF is reached while skipping whitespace.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr206"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#206">206</link>:
	<emphasis role="bold"><code>operator new(size_t, nothrow)</code> may become
	  unlinked to ordinary <code>operator new</code> if ordinary
	  version replaced
	</emphasis></term><listitem><para>The <code>nothrow</code> forms of new and delete were
      changed to call the throwing forms, handling any exception by
      catching it and returning a null pointer.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr211"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#211">211</link>:
	<emphasis role="bold">operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</emphasis></term><listitem><para>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
	sets <code>failbit</code> (which can cause an exception, etc., etc.).
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr214"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#214">214</link>:
	<emphasis role="bold">set::find() missing const overload</emphasis></term><listitem><para>Both <code>set</code> and <code>multiset</code> were missing
	overloaded find, lower_bound, upper_bound, and equal_range functions
	for const instances.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr231"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#231">231</link>:
	<emphasis role="bold">Precision in iostream?</emphasis></term><listitem><para>For conversion from a floating-point type, <code>str.precision()</code>
	is specified in the conversion specification.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr233"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#233">233</link>:
	<emphasis role="bold">Insertion hints in associative containers</emphasis></term><listitem><para>Implement N1780, first check before then check after, insert as close
	to hint as possible.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr235"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#235">235</link>:
	<emphasis role="bold">No specification of default ctor for reverse_iterator</emphasis></term><listitem><para>The declaration of <code>reverse_iterator</code> lists a default constructor.
	However, no specification is given what this constructor should do.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr241"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#241">241</link>:
	<emphasis role="bold">Does unique_copy() require CopyConstructible and Assignable?</emphasis></term><listitem><para>Add a helper for forward_iterator/output_iterator, fix the existing
	one for input_iterator/output_iterator to not rely on Assignability.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr243"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#243">243</link>:
	<emphasis role="bold">get and getline when sentry reports failure</emphasis></term><listitem><para>Store a null character only if the character array has a non-zero size.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr251"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#251">251</link>:
	<emphasis role="bold">basic_stringbuf missing allocator_type</emphasis></term><listitem><para>This nested typedef was originally not specified.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr253"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#253">253</link>:
	<emphasis role="bold">valarray helper functions are almost entirely useless</emphasis></term><listitem><para>Make the copy constructor and copy-assignment operator declarations
	public in gslice_array, indirect_array, mask_array, slice_array; provide
	definitions.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr265"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#265">265</link>:
	<emphasis role="bold">std::pair::pair() effects overly restrictive</emphasis></term><listitem><para>The default ctor would build its members from copies of temporaries;
	now it simply uses their respective default ctors.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr266"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#266">266</link>:
	<emphasis role="bold">bad_exception::~bad_exception() missing Effects clause</emphasis></term><listitem><para>The <code>bad_</code>* classes no longer have destructors (they
	are trivial), since no description of them was ever given.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr271"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#271">271</link>:
	<emphasis role="bold">basic_iostream missing typedefs</emphasis></term><listitem><para>The typedefs it inherits from its base classes can't be used, since
	(for example) <code>basic_iostream&lt;T&gt;::traits_type</code> is ambiguous.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr275"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#275">275</link>:
	<emphasis role="bold">Wrong type in num_get::get() overloads</emphasis></term><listitem><para>Similar to 118.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr280"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#280">280</link>:
	<emphasis role="bold">Comparison of reverse_iterator to const reverse_iterator</emphasis></term><listitem><para>Add global functions with two template parameters.
	(NB: not added for now a templated assignment operator)
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr292"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#292">292</link>:
	<emphasis role="bold">Effects of a.copyfmt (a)</emphasis></term><listitem><para>If <code>(this == &amp;rhs)</code> do nothing.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr300"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#300">300</link>:
	<emphasis role="bold">List::merge() specification incomplete</emphasis></term><listitem><para>If <code>(this == &amp;x)</code> do nothing.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr303"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#303">303</link>:
	<emphasis role="bold">Bitset input operator underspecified</emphasis></term><listitem><para>Basically, compare the input character to
		    <code>is.widen(0)</code> and <code>is.widen(1)</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr305"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#305">305</link>:
	<emphasis role="bold">Default behavior of codecvt&lt;wchar_t, char,
		  mbstate_t&gt;::length()</emphasis></term><listitem><para>Do not specify what <code>codecvt&lt;wchar_t, char,
		    mbstate_t&gt;::do_length</code> must return.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr328"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#328">328</link>:
	<emphasis role="bold">Bad sprintf format modifier in
		  money_put&lt;&gt;::do_put()</emphasis></term><listitem><para>Change the format string to "%.0Lf".
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr365"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#365">365</link>:
	<emphasis role="bold">Lack of const-qualification in clause 27</emphasis></term><listitem><para>Add const overloads of <code>is_open</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr387"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#387">387</link>:
	<emphasis role="bold">std::complex over-encapsulated</emphasis></term><listitem><para>Add the <code>real(T)</code> and <code>imag(T)</code>
		    members;  in C++11 mode, also adjust the existing
		    <code>real()</code> and <code>imag()</code> members and
		    free functions.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr389"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#389">389</link>:
	<emphasis role="bold">Const overload of valarray::operator[] returns
		  by value</emphasis></term><listitem><para>Change it to return a <code>const T&amp;</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr396"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#396">396</link>:
	<emphasis role="bold">what are characters zero and one</emphasis></term><listitem><para>Implement the proposed resolution.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr402"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#402">402</link>:
	<emphasis role="bold">Wrong new expression in [some_]allocator::construct</emphasis></term><listitem><para>Replace "new" with "::new".
    </para></listitem></varlistentry><varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#408">408</link>:
	<emphasis role="bold">
	Is vector&lt;reverse_iterator&lt;char*&gt; &gt; forbidden?
	</emphasis></term><listitem><para>Tweak the debug-mode checks in _Safe_iterator.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr409"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#409">409</link>:
	<emphasis role="bold">Closing an fstream should clear the error state</emphasis></term><listitem><para>Have <code>open</code> clear the error flags.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr415"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#415">415</link>:
	<emphasis role="bold">Behavior of std::ws</emphasis></term><listitem><para>Change it to be an unformatted input function
      (i.e. construct a sentry and catch exceptions).
    </para></listitem></varlistentry><varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#431">431</link>:
	<emphasis role="bold">Swapping containers with unequal allocators</emphasis></term><listitem><para>Implement Option 3, as per N1599.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr432"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#432">432</link>:
	<emphasis role="bold">stringbuf::overflow() makes only one write position
	    available</emphasis></term><listitem><para>Implement the resolution, beyond DR 169.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr434"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#434">434</link>:
	<emphasis role="bold">bitset::to_string() hard to use</emphasis></term><listitem><para>Add three overloads, taking fewer template arguments.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr438"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#438">438</link>:
	<emphasis role="bold">Ambiguity in the "do the right thing" clause</emphasis></term><listitem><para>Implement the resolution, basically cast less.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr445"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#445">445</link>:
	<emphasis role="bold">iterator_traits::reference unspecified for some iterator categories</emphasis></term><listitem><para>Change <code>istreambuf_iterator::reference</code> in C++11 mode.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr453"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#453">453</link>:
	<emphasis role="bold">basic_stringbuf::seekoff need not always fail for an empty stream</emphasis></term><listitem><para>Don't fail if the next pointer is null and newoff is zero.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr455"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#455">455</link>:
	<emphasis role="bold">cerr::tie() and wcerr::tie() are overspecified</emphasis></term><listitem><para>Initialize cerr tied to cout and wcerr tied to wcout.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr464"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#464">464</link>:
	<emphasis role="bold">Suggestion for new member functions in standard containers</emphasis></term><listitem><para>Add <code>data()</code> to <code>std::vector</code> and
	<code>at(const key_type&amp;)</code> to <code>std::map</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr467"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#467">467</link>:
	<emphasis role="bold">char_traits::lt(), compare(), and memcmp()</emphasis></term><listitem><para>Change <code>lt</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr508"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#508">508</link>:
	<emphasis role="bold">Bad parameters for ranlux64_base_01</emphasis></term><listitem><para>Fix the parameters.
    </para></listitem></varlistentry><varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#512">512</link>:
	<emphasis role="bold">Seeding subtract_with_carry_01 from a single unsigned long</emphasis></term><listitem><para>Construct a <code>linear_congruential</code> engine and seed with it.
    </para></listitem></varlistentry><varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#526">526</link>:
	<emphasis role="bold">Is it undefined if a function in the standard changes in
	    parameters?</emphasis></term><listitem><para>Use &amp;value.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr538"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#538">538</link>:
	<emphasis role="bold">241 again: Does unique_copy() require CopyConstructible
	    and Assignable?</emphasis></term><listitem><para>In case of input_iterator/output_iterator rely on Assignability of
	input_iterator' value_type.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr539"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#539">539</link>:
	<emphasis role="bold">partial_sum and adjacent_difference should mention
	    requirements</emphasis></term><listitem><para>We were almost doing the right thing, just use std::move
	in adjacent_difference.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr541"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#541">541</link>:
	<emphasis role="bold">shared_ptr template assignment and void</emphasis></term><listitem><para>Add an auto_ptr&lt;void&gt; specialization.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr543"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#543">543</link>:
	<emphasis role="bold">valarray slice default constructor</emphasis></term><listitem><para>Follow the straightforward proposed resolution.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr550"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#550">550</link>:
	<emphasis role="bold">What should the return type of pow(float,int) be?</emphasis></term><listitem><para>In C++11 mode, remove the pow(float,int), etc., signatures.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr581"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#581">581</link>:
	<emphasis role="bold"><code>flush()</code> not unformatted function</emphasis></term><listitem><para>Change it to be a unformatted output function (i.e. construct a sentry and catch exceptions).
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr586"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#586">586</link>:
	<emphasis role="bold">string inserter not a formatted function</emphasis></term><listitem><para>Change it to be a formatted output function (i.e. catch exceptions).
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr596"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#596">596</link>:
	<emphasis role="bold">27.8.1.3 Table 112 omits "a+" and "a+b" modes</emphasis></term><listitem><para>Add the missing modes to fopen_mode.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr630"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#630">630</link>:
	<emphasis role="bold">arrays of valarray</emphasis></term><listitem><para>Implement the simple resolution.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr660"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#660">660</link>:
	<emphasis role="bold">Missing bitwise operations</emphasis></term><listitem><para>Add the missing operations.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr691"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#691">691</link>:
	<emphasis role="bold">const_local_iterator cbegin, cend missing from TR1</emphasis></term><listitem><para>In C++11 mode add cbegin(size_type) and cend(size_type)
		    to the unordered containers.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr693"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#693">693</link>:
	<emphasis role="bold">std::bitset::all() missing</emphasis></term><listitem><para>Add it, consistently with the discussion.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr695"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#695">695</link>:
	<emphasis role="bold">ctype&lt;char&gt;::classic_table() not accessible</emphasis></term><listitem><para>Make the member functions table and classic_table public.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr696"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#696">696</link>:
	<emphasis role="bold">istream::operator&gt;&gt;(int&amp;) broken</emphasis></term><listitem><para>Implement the straightforward resolution.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr761"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#761">761</link>:
	<emphasis role="bold">unordered_map needs an at() member function</emphasis></term><listitem><para>In C++11 mode, add at() and at() const.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr775"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#775">775</link>:
	<emphasis role="bold">Tuple indexing should be unsigned?</emphasis></term><listitem><para>Implement the int -&gt; size_t replacements.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr776"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#776">776</link>:
	<emphasis role="bold">Undescribed assign function of std::array</emphasis></term><listitem><para>In C++11 mode, remove assign, add fill.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr781"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#781">781</link>:
	<emphasis role="bold">std::complex should add missing C99 functions</emphasis></term><listitem><para>In C++11 mode, add std::proj.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr809"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#809">809</link>:
	<emphasis role="bold">std::swap should be overloaded for array types</emphasis></term><listitem><para>Add the overload.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr853"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#853">853</link>:
	<emphasis role="bold">to_string needs updating with zero and one</emphasis></term><listitem><para>Update / add the signatures.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr865"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#865">865</link>:
	<emphasis role="bold">More algorithms that throw away information</emphasis></term><listitem><para>The traditional HP / SGI return type and value is blessed
		    by the resolution of the DR.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr1203"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#1203">1203</link>:
	<emphasis role="bold">More useful rvalue stream insertion</emphasis></term><listitem><para>Return the stream as its original type, not the base class.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr1339"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#1339">1339</link>:
	<emphasis role="bold">uninitialized_fill_n should return the end of its range</emphasis></term><listitem><para>Return the end of the filled range.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2021"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2021">2021</link>:
	<emphasis role="bold">Further incorrect uses of <code>result_of</code></emphasis></term><listitem><para>Correctly decay types in signature of <code>std::async</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2049"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2049">2049</link>:
	<emphasis role="bold"><code>is_destructible</code> underspecified</emphasis></term><listitem><para>Handle non-object types.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2056"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2056">2056</link>:
	<emphasis role="bold">future_errc enums start with value 0 (invalid value for broken_promise)</emphasis></term><listitem><para>Reorder enumerators.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2059"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2059">2059</link>:
	<emphasis role="bold">C++0x ambiguity problem with map::erase</emphasis></term><listitem><para>Add additional overloads.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2062"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2062">2062</link>:
	<emphasis role="bold">2062. Effect contradictions w/o no-throw guarantee of <code>std::function</code> swaps</emphasis></term><listitem><para>Add <code>noexcept</code> to swap functions.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2063"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2063">2063</link>:
	<emphasis role="bold">Contradictory requirements for string move assignment</emphasis></term><listitem><para>Respect propagation trait for move assignment.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2064"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2064">2064</link>:
	<emphasis role="bold">More noexcept issues in basic_string</emphasis></term><listitem><para>Add noexcept to the comparison operators.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2067"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2067">2067</link>:
	<emphasis role="bold">packaged_task should have deleted copy c'tor with const parameter</emphasis></term><listitem><para>Fix signatures.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2101"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2101">2101</link>:
	<emphasis role="bold">Some transformation types can produce impossible types</emphasis></term><listitem><para>Use the referenceable type concept.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2106"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2106">2106</link>:
	<emphasis role="bold">move_iterator wrapping iterators returning prvalues</emphasis></term><listitem><para>Change the <code>reference</code> type.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2108"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2108">2108</link>:
	<emphasis role="bold">No way to identify allocator types that always compare equal</emphasis></term><listitem><para>Define and use <code>is_always_equal</code> even for C++11.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2118"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2118">2118</link>:
	<emphasis role="bold"><code>unique_ptr</code> for array does not support cv qualification conversion of actual argument</emphasis></term><listitem><para>Adjust constraints to allow safe conversions.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2127"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2127">2127</link>:
	<emphasis role="bold">Move-construction with <code>raw_storage_iterator</code></emphasis></term><listitem><para>Add assignment operator taking an rvalue.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2132"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2132">2132</link>:
	<emphasis role="bold"><code>std::function</code> ambiguity</emphasis></term><listitem><para>Constrain the constructor to only accept callable types.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2141"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2141">2141</link>:
	<emphasis role="bold"><code>common_type</code> trait produces reference types</emphasis></term><listitem><para>Use <code>decay</code> for the result type.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2144"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2144">2144</link>:
	<emphasis role="bold">Missing <code>noexcept</code> specification in <code>type_index</code></emphasis></term><listitem><para>Add <code>noexcept</code>
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2145"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2145">2145</link>:
	<emphasis role="bold"><code>error_category</code> default constructor</emphasis></term><listitem><para>Declare a public constexpr constructor.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2162"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2162">2162</link>:
	<emphasis role="bold"><code>allocator_traits::max_size</code> missing <code>noexcept</code></emphasis></term><listitem><para>Add <code>noexcept</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2187"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2187">2187</link>:
	<emphasis role="bold"><code>vector&lt;bool&gt;</code> is missing <code>emplace</code> and <code>emplace_back</code> member functions</emphasis></term><listitem><para>Add <code>emplace</code> and <code>emplace_back</code> member functions.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2192"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2192">2192</link>:
	<emphasis role="bold">Validity and return type of <code>std::abs(0u)</code> is unclear</emphasis></term><listitem><para>Move all declarations to a common header and remove the
    generic <code>abs</code> which accepted unsigned arguments.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2196"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2196">2196</link>:
	<emphasis role="bold">Specification of <code>is_*[copy/move]_[constructible/assignable]</code> unclear for non-referencable types</emphasis></term><listitem><para>Use the referenceable type concept.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2212"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2212">2212</link>:
	<emphasis role="bold"><code>tuple_size</code> for <code>const pair</code> request <code>&lt;tuple&gt;</code> header</emphasis></term><listitem><para>The <code>tuple_size</code> and <code>tuple_element</code>
    partial specializations are defined in <code>&lt;utility&gt;</code> which
    is included by <code>&lt;array&gt;</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2296"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2296">2296</link>:
	<emphasis role="bold"><code>std::addressof</code> should be constexpr</emphasis></term><listitem><para>Use <code>__builtin_addressof</code> and add
    <code>constexpr</code> to <code>addressof</code> for C++17 and later.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2306"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2306">2306</link>:
	<emphasis role="bold"><code>match_results::reference</code> should be <code>value_type&amp;</code>, not <code>const value_type&amp;</code></emphasis></term><listitem><para>Change typedef.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2313"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2313">2313</link>:
	<emphasis role="bold"><code>tuple_size</code> should always derive from <code>integral_constant&lt;size_t, N&gt;</code></emphasis></term><listitem><para>Update definitions of the partial specializations for const and volatile types.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2328"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2328">2328</link>:
	<emphasis role="bold">Rvalue stream extraction should use perfect forwarding</emphasis></term><listitem><para>Use perfect forwarding for right operand.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2329"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2329">2329</link>:
	<emphasis role="bold"><code>regex_match()/regex_search()</code> with <code>match_results</code> should forbid temporary strings</emphasis></term><listitem><para>Add deleted overloads for rvalue strings.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2332"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2332">2332</link>:
	<emphasis role="bold"><code>regex_iterator/regex_token_iterator</code> should forbid temporary regexes</emphasis></term><listitem><para>Add deleted constructors.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2354"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2354">2332</link>:
	<emphasis role="bold">Unnecessary copying when inserting into maps with braced-init syntax</emphasis></term><listitem><para>Add overloads of <code>insert</code> taking <code>value_type&amp;&amp;</code> rvalues.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2399"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2399">2399</link>:
	<emphasis role="bold"><code>shared_ptr</code>'s constructor from <code>unique_ptr</code> should be constrained</emphasis></term><listitem><para>Constrain the constructor to require convertibility.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2400"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2400">2400</link>:
	<emphasis role="bold"><code>shared_ptr</code>'s <code>get_deleter()</code> should use <code>addressof()</code></emphasis></term><listitem><para>Use <code>addressof</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2401"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2401">2401</link>:
	<emphasis role="bold"><code>std::function</code> needs more <code>noexcept</code></emphasis></term><listitem><para>Add <code>noexcept</code> to the assignment and comparisons.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2407"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2407">2407</link>:
	<emphasis role="bold"><code>packaged_task(allocator_arg_t, const Allocator&amp;, F&amp;&amp;)</code>
                 should neither be constrained nor <code>explicit</code>
	</emphasis></term><listitem><para>Remove <code>explicit</code> from the constructor.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2408"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2408">2408</link>:
	<emphasis role="bold">SFINAE-friendly
         <code>common_type</code>/<code>iterator_traits</code>
         is missing in C++14
	</emphasis></term><listitem><para>Make <code>iterator_traits</code> empty if any of the
      types is not present in the iterator.
      Make <code>common_type&lt;&gt;</code> empty.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2415"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2415">2415</link>:
	<emphasis role="bold">Inconsistency between <code>unique_ptr</code> and <code>shared_ptr</code></emphasis></term><listitem><para>Create empty an <code>shared_ptr</code> from an empty
                    <code>unique_ptr</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2418"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2418">2418</link>:
	<emphasis role="bold"><code>apply</code> does not work with member pointers</emphasis></term><listitem><para>Use <code>mem_fn</code> for member pointers.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2440"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2440">2440</link>:
	<emphasis role="bold"><code>seed_seq::size()</code> should be <code>noexcept</code></emphasis></term><listitem><para>Add <code>noexcept</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2441"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2441">2441</link>:
	<emphasis role="bold">Exact-width atomic typedefs should be provided</emphasis></term><listitem><para>Define the typedefs.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2442"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2442">2442</link>:
	<emphasis role="bold"><code>call_once()</code> shouldn't <code>DECAY_COPY()</code></emphasis></term><listitem><para>Remove indirection through call wrapper that made copies
    of arguments and forward arguments straight to <code>std::invoke</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2454"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2454">2454</link>:
	<emphasis role="bold">Add <code>raw_storage_iterator::base()</code> member
	</emphasis></term><listitem><para>Add the <code>base()</code> member function.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2455"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2455">2455</link>:
	<emphasis role="bold">Allocator default construction should be allowed to throw
	</emphasis></term><listitem><para>Make <code>noexcept</code> specifications conditional.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2458"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2458">2458</link>:
	<emphasis role="bold">N3778 and new library deallocation signatures
	</emphasis></term><listitem><para>Remove unused overloads.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2459"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2459">2459</link>:
	<emphasis role="bold"><code>std::polar</code> should require a non-negative rho
	</emphasis></term><listitem><para>Add debug mode assertion.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2465"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2465">2465</link>:
	<emphasis role="bold">SFINAE-friendly <code>common_type</code> is nearly impossible
       to specialize correctly and regresses key functionality
	</emphasis></term><listitem><para>Detect whether <code>decay_t</code> changes either type
      and use the decayed types if so.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2466"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2466">2466</link>:
	<emphasis role="bold"><code>allocator_traits::max_size()</code> default behavior is incorrect
	</emphasis></term><listitem><para>Divide by the object type.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2484"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2484">2484</link>:
	<emphasis role="bold"><code>rethrow_if_nested()</code>  is doubly unimplementable
	</emphasis></term><listitem><para>Avoid using <code>dynamic_cast</code> when it would be
    ill-formed.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2487"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2487">2487</link>:
	<emphasis role="bold"><code>bind()</code> should be <code>const</code>-overloaded
	not <emphasis>cv</emphasis>-overloaded
	</emphasis></term><listitem><para>Deprecate volatile-qualified <code>operator()</code>
    for C++17, make it ill-formed for C++20.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2499"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2499">2499</link>:
	<emphasis role="bold"><code>operator&gt;&gt;(basic_istream&amp;, CharT*)</code> makes it hard to avoid buffer overflows
	</emphasis></term><listitem><para>Replace <code>operator&gt;&gt;(basic_istream&amp;, CharT*)</code>
     and other overloads writing through pointers.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2537"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2537">2537</link>:
	<emphasis role="bold">Constructors for <code>priority_queue</code> taking allocators
	 should call <code>make_heap</code>
	</emphasis></term><listitem><para>Call <code>make_heap</code>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2566"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2566">2566</link>:
	<emphasis role="bold">Requirements on the first template parameter of container adaptors
	</emphasis></term><listitem><para>Add static assertions to enforce the requirement.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2583"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2583">2583</link>:
	<emphasis role="bold">There is no way to supply an allocator for <code>basic_string(str, pos)</code>
	</emphasis></term><listitem><para>Add new constructor.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2586"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2586">2586</link>:
	<emphasis role="bold">Wrong value category used in <code>scoped_allocator_adaptor::construct()</code>
	</emphasis></term><listitem><para>Change internal helper for uses-allocator construction
      to always check using const lvalue allocators.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2684"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2684">2684</link>:
	<emphasis role="bold"><code>priority_queue</code> lacking comparator typedef
	</emphasis></term><listitem><para>Define the <code>value_compare</code> typedef.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2735"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2735">2735</link>:
	<emphasis role="bold"><code>std::abs(short)</code>,
	 <code>std::abs(signed char)</code> and others should return
	 <code>int</code> instead of <code>double</code> in order to be
	 compatible with C++98 and C
	</emphasis></term><listitem><para>Resolved by the changes for
      <link linkend="manual.bugs.dr2192">2192</link>.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2770"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2770">2770</link>:
	<emphasis role="bold"><code>tuple_size&lt;const T&gt;</code> specialization is not
	 SFINAE compatible and breaks decomposition declarations
	</emphasis></term><listitem><para>Safely detect <code>tuple_size&lt;T&gt;::value</code> and
      only use it if valid.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2781"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2781">2781</link>:
	<emphasis role="bold">Contradictory requirements for <code>std::function</code>
         and <code>std::reference_wrapper</code>
	</emphasis></term><listitem><para>Remove special handling for <code>reference_wrapper</code>
      arguments and store them directly as the target object.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2802"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2802">2802</link>:
	<emphasis role="bold">Add noexcept to several <code>shared_ptr</code> related
         functions
	</emphasis></term><listitem><para>Add noexcept.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2873"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2873">2873</link>:
	<emphasis role="bold"><code>shared_ptr</code> constructor requirements for a deleter
	</emphasis></term><listitem><para>Use rvalues for deleters.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2921"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2921">2921</link>:
	<emphasis role="bold"><code>packaged_task</code> and type-erased allocators
	</emphasis></term><listitem><para>For C++17 mode, remove the constructors taking
      an allocator argument.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2942"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2942">2942</link>:
	<emphasis role="bold">LWG 2873's resolution missed
         <code>weak_ptr::owner_before</code>
	</emphasis></term><listitem><para>Add noexcept.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2996"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2996">2996</link>:
	<emphasis role="bold">Missing rvalue overloads for
         <code>shared_ptr</code> operations
	</emphasis></term><listitem><para>Add additional constructor and cast overloads.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr2993"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2993">2993</link>:
	<emphasis role="bold"><code>reference_wrapper&lt;T&gt;</code> conversion from <code>T&amp;&amp;</code>
	</emphasis></term><listitem><para>Replaced the constructors with a constrained template,
      to prevent participation in overload resolution when not valid.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr3074"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3074">3074</link>:
	<emphasis role="bold">Non-member functions for <code>valarray</code> should only deduce from the <code>valarray</code>
	</emphasis></term><listitem><para>Change scalar operands to be non-deduced context, so that
      they will allow conversions from other types to the value_type.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr3076"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3076">3076</link>:
	<emphasis role="bold"><code>basic_string</code> CTAD ambiguity
	</emphasis></term><listitem><para>Change constructors to constrained templates.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr3096"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3096">3096</link>:
	<emphasis role="bold"><code>path::lexically_relative</code> is confused by trailing slashes
	</emphasis></term><listitem><para>Implement the fix for trailing slashes.
    </para></listitem></varlistentry><varlistentry xml:id="manual.bugs.dr3656"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3656">3656</link>:
	<emphasis role="bold">Inconsistent bit operations returning a count
	</emphasis></term><listitem><para>Changed <code>bit_width</code> to return <code>int</code>.
    </para></listitem></varlistentry></variablelist></section></section></chapter><!-- Chapter 02 : Setup --><chapter xreflabel="Setup" xml:id="manual.intro.setup"><info><title>Setup</title></info><?dbhtml filename="setup.html"?><para>Transforming libstdc++ sources into installed include files
   and properly built binaries useful for linking to other software is
   done as part of building GCC. Building libstdc++ separately from the
   rest of GCC is not supported.
   </para><para>The general outline of commands to build GCC is something like:
   </para><programlisting><replaceable>get gcc sources</replaceable><replaceable>extract into gccsrcdir</replaceable>
   mkdir <replaceable>gccbuilddir</replaceable>
   cd <replaceable>gccbuilddir</replaceable>
   <replaceable>gccsrcdir</replaceable>/configure --prefix=<replaceable>destdir</replaceable> --other-opts...
   make
   make check
   make install
</programlisting><para>
     Each step is described in more detail in the following sections.
   </para><!-- Section 01 : Prerequisites --><section version="5.0" xreflabel="Prerequisites" xml:id="manual.intro.setup.prereq"><?dbhtml filename="prerequisites.html"?><info><title>Prerequisites</title><keywordset><keyword>ISO C++</keyword><keyword>Prerequisites</keyword></keywordset></info><para>
  Because libstdc++ is part of GCC, the primary source for
   installation instructions is
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/">the GCC install page</link>.
   In particular, list of prerequisite software needed to build the library
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/prerequisites.html">
   starts with those requirements.</link> The same pages also list
   the tools you will need if you wish to modify the source.
</para><para>
   Additional data is given here only where it applies to libstdc++.
  </para><para>To take full advantage of useful space-saving features and
      bug-fixes you should use a recent binutils whenever possible.
      The configure process will automatically detect and use these
      features if the underlying support is present.
   </para><para>
     To generate the API documentation from the sources you will need
     Doxygen, see <link linkend="appendix.porting.doc">Documentation
     Hacking</link> in the appendix for full details.
   </para><para>
   Finally, a few system-specific requirements:
   </para><variablelist><varlistentry><term>linux</term><listitem><para>
	  The 'gnu' locale model makes use of <function>iconv</function>
	  for character set conversions. The relevant functions are provided
	  by Glibc and so are always available, however they can also be
	  provided by the separate GNU libiconv library. If GNU libiconv is
	  found when GCC is built (e.g., because its headers are installed
	  in <filename class="directory">/usr/local/include</filename>)
	  then the <filename>libstdc++.so.6</filename> library will have a
	  run-time dependency on <filename>libiconv.so.2</filename>.
	  If you do not want that run-time dependency then you should do
	  one of the following:
	</para><itemizedlist><listitem><para>
	      Uninstall the libiconv headers before building GCC.
	      Glibc already provides <function>iconv</function> so you should
	      not need libiconv anyway.
	    </para></listitem><listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/software/libiconv/#downloading">
	    Download</link> the libiconv sources and extract them into the
	    top level of the GCC source tree, e.g.,
	    </para><programlisting>
wget https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.16.tar.gz
tar xf libiconv-1.16.tar.gz
ln -s libiconv-1.16 libiconv
</programlisting><para>
	      This will build libiconv as part of building GCC and link to
	      it statically, so there is no <filename>libiconv.so.2</filename>
	      dependency.
	    </para></listitem><listitem><para>
	      Configure GCC with <option>--with-libiconv-type=static</option>.
	      This requires the static <filename>libiconv.a</filename> library,
	      which is not installed by default. You might need to reinstall
	      libiconv using the <option>--enable-static</option> configure
	      option to get the static library.
	    </para></listitem></itemizedlist></listitem><listitem><para>
	  If GCC 3.1.0 or later on is being used on GNU/Linux, an attempt
	  will be made to use "C" library functionality necessary for
	  C++ named locale support, e.g. the <function>newlocale</function>
	  and <function>uselocale</function> functions.
	  For GCC 4.6.0 and later,
	  this means that glibc 2.3 or later is required.
	</para><para>
	  If the 'gnu' locale model is being used, the following
	  locales are used and tested in the libstdc++ testsuites.
	  The first column is the name of the locale, the second is
	  the character set it is expected to use.
	</para><programlisting>
de_DE               ISO-8859-1
de_DE@euro          ISO-8859-15
en_GB               ISO-8859-1
en_HK               ISO-8859-1
en_PH               ISO-8859-1
en_US               ISO-8859-1
en_US.ISO-8859-1    ISO-8859-1
en_US.ISO-8859-15   ISO-8859-15
en_US.UTF-8         UTF-8
es_ES               ISO-8859-1
es_MX               ISO-8859-1
fr_FR               ISO-8859-1
fr_FR@euro          ISO-8859-15
is_IS               UTF-8
it_IT               ISO-8859-1
ja_JP.eucjp         EUC-JP
ru_RU.ISO-8859-5    ISO-8859-5
ru_RU.UTF-8         UTF-8
se_NO.UTF-8         UTF-8
ta_IN               UTF-8
zh_TW               BIG5
</programlisting><para>Failure to have installed the underlying "C" library
      locale information for any of the above regions means that
      the corresponding C++ named locale will not work:  because of
      this, the libstdc++ testsuite will skip named locale tests
      which need missing information.  If this isn't an issue, don't
      worry about it.  If a named locale is needed, the underlying
      locale information must be installed.  Note that rebuilding
      libstdc++ after "C" locales are installed is not necessary.
      </para><para>
	To install support for locales, do only one of the following:
      </para><itemizedlist><listitem><para>install all locales, e.g., run
	    <code> dnf install glibc-all-langpacks </code>
	    for Fedora and related distributions.
	  </para></listitem><listitem><para>install just the necessary locales</para><itemizedlist><listitem><para>with Debian GNU/Linux:</para><para> Add the above list, as shown, to the file
	      <code>/etc/locale.gen</code> </para><para> run <code>/usr/sbin/locale-gen</code> </para></listitem><listitem><para>on most Unix-like operating systems:</para><para><code> localedef -i de_DE -f ISO-8859-1 de_DE </code></para><para>(repeat for each entry in the above list) </para></listitem><listitem><para>
	       Instructions for other operating systems solicited.
	    </para></listitem></itemizedlist></listitem></itemizedlist></listitem><listitem>
	Some tests for the <code>std::messages</code> facet require a
	message catalog created by the <command>msgfmt</command> utility.
	That is usually installed as part of the GNU gettext library.
	If <command>msgfmt</command> is not available, some tests under
	the <filename class="directory">22_locale/messages</filename>
	directory will fail.
      </listitem></varlistentry></variablelist></section><!-- Section 02 : Configure --><section version="5.0" xreflabel="Configuring" xml:id="manual.intro.setup.configure"><?dbhtml filename="configure.html"?><info><title>Configure</title><keywordset><keyword>ISO C++</keyword><keyword>configure</keyword><keyword>options</keyword></keywordset></info><para>
  When configuring libstdc++, you'll have to configure the entire
  <emphasis>gccsrcdir</emphasis> directory. Consider using the
  toplevel gcc configuration option
  <literal>--enable-languages=c++</literal>, which saves time by only
  building the C++ toolchain.
</para><para>
  Here are all of the configure options specific to libstdc++.  Keep
  in mind that
   <!-- This SECnn should be the "Choosing Package Options" section. -->
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/autobook/autobook/autobook_14.html">they
   all have opposite forms as well</link> (enable/disable and
   with/without).  The defaults are for the <emphasis>current
   development sources</emphasis>, which may be different than those
   for released versions.
</para><para>The canonical way to find out the configure options that are
   available for a given set of libstdc++ sources is to go to the
   source directory and then type: <command>./configure --help</command>.
</para><variablelist><varlistentry><term><code>--enable-multilib</code>[default]</term><listitem><para>This is part of the generic multilib support for building cross
	compilers.  As such, targets like "powerpc-elf" will have
	libstdc++ built many different ways:  "-msoft-float"
	and not, etc.  A different libstdc++ will be built for each of
	the different multilib versions.  This option is on by default.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-version-specific-runtime-libs</code></term><listitem><para>Specify that run-time libraries should be installed in the
	compiler-specific subdirectory (i.e.,
	<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
	instead of <code>${libdir}</code>.  This option is useful if you
	intend to use several versions of gcc in parallel.  In addition,
	libstdc++'s include files will be installed in
	<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
	unless you also specify
       <literal>--with-gxx-include-dir=</literal><filename class="directory">dirname</filename> during configuration.
     </para></listitem></varlistentry><varlistentry><term><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code></term><listitem><para>Adds support for named libstdc++ include directory.  For instance,
	the following puts all the libstdc++ headers into a directory
	called "4.4-20090404" instead of the usual
	"c++/(version)".
     </para><programlisting>
   --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</programlisting></listitem></varlistentry><varlistentry><term><code>--enable-cstdio</code></term><listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
	(described next).
     </para></listitem></varlistentry><varlistentry><term><code>--enable-cstdio=OPTION</code></term><listitem><para>Select a target-specific I/O package. The choices are 'stdio'
       which is a generic abstraction using POSIX file I/O APIs
       (<function>read</function>, <function>write</function>,
       <function>lseek</function>, etc.), and 'stdio_pure' which is similar
       but only uses standard C file I/O APIs (<function>fread</function>,
       <function>fwrite</function>, <function>fseek</function>, etc.).
       The 'stdio_posix' choice is a synonym for 'stdio'.
       The default is 'stdio'. This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-clocale</code></term><listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
	(described next).
     </para></listitem></varlistentry><varlistentry><term><code>--enable-clocale=OPTION</code></term><listitem><para>Select a target-specific underlying locale package.  The
	choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
	(IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
	'gnu' to specify a model based on functionality from the GNU C
	library (langinfo/iconv/gettext) (from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/software/libc/">glibc</link>, the GNU C
	library), 'generic' to use a generic "C" abstraction which consists
	of "C" locale info, 'newlib' to specify the Newlib C library model
	which only differs from the 'generic' model in the handling of
	ctype, or 'darwin' which omits the <type>wchar_t</type> specializations
	needed by the 'generic' model.
     </para><para>If not explicitly specified, the configure process tries
      to guess the most suitable package from the choices above. The
      default is 'generic'. On glibc-based systems of sufficient
      vintage (2.3 and newer), 'gnu' is automatically selected. On newlib-based
      systems (<code>'--with_newlib=yes'</code>) and OpenBSD, 'newlib' is
      automatically selected. On Mac OS X 'darwin' is automatically selected.
      This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-allocator</code></term><listitem><para>This is an abbreviated form of
	<code>'--enable-libstdcxx-allocator=auto'</code> (described
	next).
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-allocator=OPTION  </code></term><listitem><para>Select a target-specific underlying std::allocator.  The
	choices are 'new' to specify a wrapper for new, and 'malloc' to
	specify a wrapper for malloc.
	See <xref linkend="allocator.ext"></xref> for more information.
	This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-cheaders=OPTION</code></term><listitem><para>This allows the user to define the approach taken for C header
	compatibility with C++. Options are c, c_std, and c_global.
	These correspond to the source directory's include/c,
	include/c_std, and include/c_global, and may also include
	include/c_compatibility.  The default is 'c_global'.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-threads</code></term><listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code>
	(described next).
     </para></listitem></varlistentry><varlistentry><term><code>--enable-threads=OPTION</code></term><listitem><para>Select a threading library.  A full description is
	given in the
	general <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/configure.html">compiler
	configuration instructions</link>. This option can change the
	library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-threads</code></term><listitem><para>Enable C++11 threads support.  If not explicitly specified,
        the  configure process enables it if possible.  This
	option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-time</code></term><listitem><para>This is an abbreviated form of
	<code>'--enable-libstdcxx-time=yes'</code>(described next).
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term><listitem><para>Enables link-type checks for the availability of the
	<function>clock_gettime</function> clocks, used in the implementation
	of [time.clock], and of the <function>nanosleep</function> and
	<function>sched_yield</function> functions, used in the
	implementation of [thread.thread.this] of the 2011 ISO C++ standard.
	The choice OPTION=yes checks for the availability of the facilities
	in libc.  OPTION=rt also checks in
	librt (and, if it's needed, links to it).  Note that linking to librt
	is not always desirable because for glibc it requires linking to
	libpthread too, which causes all reference counting to use atomic
	operations, resulting in a potentially large overhead for
	single-threaded programs.  OPTION=no skips the tests completely.
	The default is OPTION=auto, which skips the checks and enables the
	features only for targets known to support them.
	For Linux targets, if <function>clock_gettime</function> is not used
	then the [time.clock] implementation will use a system call to access
	the realtime and monotonic clocks, which is significantly slower than
	the C library's <function>clock_gettime</function> function.
    </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-debug</code></term><listitem><para>Build separate debug libraries in addition to what is normally built.
	By default, the debug libraries are compiled with
	<code> CXXFLAGS='-g3 -O0 -fno-inline'</code>
	, are installed in <code>${libdir}/debug</code>, and have the
	same names and versioning information as the non-debug
	libraries. This option is off by default.
     </para><para>Note this make command, executed in
	the build directory, will do much the same thing, without the
	configuration difference and without building everything twice:
	<code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term><listitem><para>This option is only valid when
	<code>--enable-libstdcxx-debug</code>
	is also specified, and applies to the debug builds only. With
	this option, you can pass a specific string of flags to the
	compiler to use when building the debug versions of libstdc++.
	FLAGS is a quoted string of options, like
     </para><programlisting>
  --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting></listitem></varlistentry><varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term><listitem><para>With this option, you can pass a string of -f (functionality)
	flags to the compiler to use when building libstdc++. This
	option can change the library ABI. FLAGS is a quoted string of
	options, like
     </para><programlisting>
  --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting><para>
	Note that the flags don't necessarily have to all be -f flags,
	as shown, but usually those are the ones that will make sense
	for experimentation and configure-time overriding.
     </para><para>The advantage of --enable-cxx-flags over setting CXXFLAGS in
	the 'make' environment is that, if files are automatically
	rebuilt, the same flags will be used when compiling those files
	as well, so that everything matches.
     </para><para>Fun flags to try might include combinations of
     </para><programlisting>
  -fstrict-aliasing
  -fno-exceptions
  -ffunction-sections
  -fvtable-gc</programlisting><para>and opposite forms (-fno-) of the same.  Tell us (the libstdc++
	mailing list) if you discover more!
     </para></listitem></varlistentry><varlistentry><term><code>--enable-c99</code></term><listitem><para>The <type>long long</type> type was introduced in C99, along
	with many other functions for wide characters, and math
	classification macros, etc.  If enabled, all C99 functions not
	specified by the C++ standard will be put into <code>namespace
	__gnu_cxx</code>, and then all these names will
	be injected into namespace std, so that C99 functions can be
	used "as if" they were in the C++ standard (as they
	will eventually be in some future revision of the standard,
	without a doubt).  By default, C99 support is on, assuming the
	configure probes find all the necessary functions and bits
	necessary. This option can change the library ABI.
    </para></listitem></varlistentry><varlistentry><term><code>--enable-wchar_t</code>[default]</term><listitem><para>Template specializations for the <type>wchar_t</type> type are
	required for wide character conversion support.  Disabling
	wide character specializations may be expedient for initial
	porting efforts, but builds only a subset of what is required by
	ISO, and is not recommended.  By default, this option is on.
	This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-long-long  </code></term><listitem><para>The <type>long long</type> type was introduced in C99.  It is
	provided as a GNU extension to C++98 in g++.  This flag builds
	support for "long long" into the library (specialized
	templates and the like for iostreams).  This option is on by default:
	if enabled, users will have to either use the new-style "C"
	headers by default (i.e., &lt;cmath&gt; not &lt;math.h&gt;)
	or add appropriate compile-time flags to all compile lines to
	allow "C" visibility of this feature (on GNU/Linux,
	the flag is -D_ISOC99_SOURCE, which is added automatically via
	CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
	This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-fully-dynamic-string</code></term><listitem><para>This option enables a special version of basic_string avoiding
	the optimization that allocates empty objects in static memory.
	Mostly useful together with shared memory allocators, see PR
	libstdc++/16612 for details.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-concept-checks</code></term><listitem><para>This turns on additional compile-time checks for instantiated
	library templates, in the form of specialized templates described in
        the <link linkend="std.diagnostics.concept_checking">Concept
        Checking</link> section.  They
	can help users discover when they break the rules of the STL, before
	their programs run. These checks are based on C++03 rules and some of
	them are not compatible with correct C++11 code.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-symvers[=style]</code></term><listitem><para>In 3.1 and later, tries to turn on symbol versioning in the
	shared library (if a shared library has been
	requested). Values for 'style' that are currently supported
	are 'gnu', 'gnu-versioned-namespace', 'darwin',
	'darwin-export', and 'sun'. Both gnu- options require that a recent
	version of the GNU linker be in use. Both darwin options are
	equivalent. With no style given, the configure script will try
	to guess correct defaults for the host system, probe to see if
	additional requirements are necessary and present for
	activation, and if so, will turn symbol versioning on. This
	option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-visibility</code></term><listitem><para> In 4.2 and later, enables or disables visibility
        attributes. If enabled (as by default), and the compiler seems
        capable of passing the simple sanity checks thrown at it, adjusts
        items in namespace std, namespace std::tr1, namespace std::tr2,
        and namespace __gnu_cxx to have <code>visibility ("default")</code>
        so that -fvisibility options can be used without affecting the
        normal external-visibility of namespace std entities.
        Prior to 4.7 this option was spelled <code>--enable-visibility</code>.
    </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-pch</code></term><listitem><para>In 3.4 and later, tries to turn on the generation of
	stdc++.h.gch, a pre-compiled file including all the standard
	C++ includes. If enabled (as by default), and the compiler
	seems capable of passing the simple sanity checks thrown at
	it, try to build stdc++.h.gch as part of the make process.
	In addition, this generated file is used later on (by appending
	<code>-include bits/stdc++.h</code> to CXXFLAGS) when running the
	testsuite.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-extern-template</code>[default]</term><listitem><para>Use extern template to pre-instantiate all required
 	specializations for certain types defined in the standard libraries.
	These types include <classname>string</classname> and dependents like
	<classname>char_traits</classname>, the templatized IO classes,
	<classname>allocator</classname>, and others.
	Disabling means that implicit
	template generation will be used when compiling these types.  By
	default, this option is on. This option can change the library ABI.
     </para></listitem></varlistentry><varlistentry><term><code>--disable-hosted-libstdcxx</code></term><listitem><para>
     By default, a complete <emphasis>hosted</emphasis> C++ library is
     built.  The C++ Standard also describes a
     <emphasis>freestanding</emphasis> environment, in which only a
     minimal set of headers are provided.  This option builds such an
     environment.  Note that a hosted library installs headers that still can
     be used in non hosted environments, as the library checks for
     <code>__STDC_HOSTED__</code>, however, a library configured with
     <code>--disable-hosted-libstdcxx</code> will not install unusable headers.
     </para></listitem></varlistentry><varlistentry><term><code>--disable-libstdcxx-hosted</code></term><listitem><para>This is an alias for <code>--disable-hosted-libstdcxx</code>.</para></listitem></varlistentry><varlistentry><term><code>--disable-libstdcxx-verbose</code></term><listitem><para>
     By default, the library is configured to write descriptive messages
     to standard error for certain events such as calling a pure virtual
     function or the invocation of the standard terminate handler.  Those
     messages cause the library to depend on the demangler and standard I/O
     facilities, which might be undesirable in a low-memory environment or
     when standard error is not available.  This option disables those
     messages.  This option does not change the library ABI.
   </para></listitem></varlistentry><varlistentry><term><code>--disable-libstdcxx-dual-abi</code></term><listitem><para>
     Disable support for the new, C++11-conforming implementations of
     <code>std::string</code>, <code>std::list</code> etc. so that the
     library only provides definitions of types using the old ABI
     (see <xref linkend="manual.intro.using.abi"></xref>).
     This option changes the library ABI.
   </para></listitem></varlistentry><varlistentry><term><code>--with-default-libstdcxx-abi=</code><replaceable>OPTION</replaceable></term><listitem><para>
     Set the default value for the <symbol>_GLIBCXX_USE_CXX11_ABI</symbol>
     macro (see <xref linkend="manual.intro.using.macros"></xref>).
     The default is <option>OPTION=new</option> which sets the macro to
     <literal>1</literal>,
     use <option>OPTION=gcc4-compatible</option> to set it to
     <literal>0</literal>.
     This option does not change the library ABI.
   </para></listitem></varlistentry><varlistentry><term><code>--with-libstdcxx-lock-policy=OPTION</code></term><listitem><para>Sets the lock policy that controls how
        <classname>shared_ptr</classname> reference counting is
        synchronized.
        The choice OPTION=atomic enables use of atomics for updates to
        <classname>shared_ptr</classname> reference counts.
        The choice OPTION=mutex enables use of a mutex to synchronize updates
        to <classname>shared_ptr</classname> reference counts.
        If the compiler's thread model is "single" then this option has no
        effect, as no synchronization is used for the reference counts.
	The default is OPTION=auto, which checks for the availability of
        compiler built-ins for 2-byte and 4-byte atomic compare-and-swap,
        and uses OPTION=atomic if they're available, OPTION=mutex otherwise.
        This option can change the library ABI.
        If the library is configured to use atomics and user programs are
        compiled using a target that doesn't natively support the atomic
        operations (e.g. the library is configured for armv7 and then code
        is compiled with <option>-march=armv5t</option>) then the program
        might rely on support in libgcc to provide the atomics.
    </para></listitem></varlistentry><varlistentry><term><code>--enable-vtable-verify</code></term><listitem><para>Use <code>-fvtable-verify=std</code> to compile the C++
    runtime with instrumentation for vtable verification. All virtual
    functions in the standard library will be verified at runtime.
    Types impacted include <classname>locale</classname> and
    <classname>iostream</classname>, and others.  Disabling means that
    the C++ runtime is compiled without support for vtable
    verification. By default, this option is off.
     </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-filesystem-ts</code>[default]</term><listitem><para>Build <filename class="libraryfile">libstdc++fs.a</filename> as well
      as the usual libstdc++ and libsupc++ libraries. This is enabled by
      default on select POSIX targets where it is known to work and disabled
      otherwise.
    </para></listitem></varlistentry><varlistentry><term><code>--enable-libstdcxx-static-eh-pool</code></term><listitem><para>Use a fixed-size static buffer for the emergency exception handling
      pool (see <xref linkend="intro.using.exception.alloc"></xref>). The default
      is to allocate the pool on program startup using <code>malloc</code>.
      With this option, a static buffer will be provided by libstdc++ instead.
      This does not change the library ABI.
    </para></listitem></varlistentry><varlistentry><term><code>--with-libstdcxx-eh-pool-obj-count=NUM</code></term><listitem><para>Set the size of the emergency exception handling pool. NUM is the
      number of simultaneous allocated exceptions to support.
      This does not change the library ABI.
    </para></listitem></varlistentry><varlistentry><term><code>--with-libstdcxx-zoneinfo=OPTION</code></term><listitem><para>Choose how <classname>std::chrono::tzdb</classname> will obtain
      the time zone info. The library requires a copy of the
      <filename>tzdata.zi</filename> and <filename>leapseconds</filename>
      files from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iana.org/time-zones">IANA Time Zone
      Database</link>. The choice OPTION=static will embed a copy of the files
      into the library, and use that static data when time zone information
      is required. The choice OPTION=dir will use the files
      <filename>dir/tzdata.zi</filename> and
      <filename>dir/leapseconds</filename> (which must exist when a program
      tries to access time zone information). The choice OPTION=dir,static
      will try to use files in <filename>dir</filename> but if they are
      not available the embedded static data will be used instead.
      The default choice is OPTION=yes. This is equivalent to OPTION=dir,static
      with a system-specific default directory (if a suitable default for
      the target is known).
      The choice OPTION=no will disable all code for loading time zone info
      from file or from the embedded static data, which means that only the
      "UTC" and "GMT" time zones are defined. Using OPTION=no results in a
      smaller library, so is suitable for systems that will never need to
      query the time zone database.
      This does not change the library ABI.
    </para></listitem></varlistentry></variablelist></section><!-- Section 03 : Make --><section xreflabel="Make" xml:id="manual.intro.setup.make"><info><title>Make</title></info><?dbhtml filename="make.html"?><para>If you have never done this before, you should read the basic
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/">GCC Installation
      Instructions</link> first.  Read <emphasis>all of them</emphasis>.
      <emphasis>Twice.</emphasis>
   </para><para>Then type: <command>make</command>, and congratulations, you've
started to build.
</para></section></chapter><!-- Chapter 03 : Using --><chapter version="5.0" xreflabel="Using" xml:id="manual.intro.using"><info><title>Using</title></info><?dbhtml filename="using.html"?><section xreflabel="Flags" xml:id="manual.intro.using.flags"><info><title>Command Options</title></info><para>
      The set of features available in the GNU C++ library is shaped by
      several <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html">GCC
      Command Options</link>. Options that impact libstdc++ are
      enumerated and detailed in the table below.
    </para><para>
      The standard library conforms to the dialect of C++ specified by the
      <option>-std</option> option passed to the compiler.
      By default, <command>g++</command> is equivalent to
      <command>g++ -std=gnu++20</command> since GCC 16, and
      <command>g++ -std=gnu++17</command> in GCC 11-15, and
      <command>g++ -std=gnu++14</command> in GCC 6-10, and
      <command>g++ -std=gnu++98</command> for older releases.
    </para><table frame="all" xml:id="table.cmd_options"><title>C++ Command Options</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><thead><row><entry>Option Flags</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>-std</literal></entry><entry>
	Select the C++ standard, and whether to use the base standard
	or GNU dialect.
      </entry></row><row><entry><literal>-fno-exceptions</literal></entry><entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry></row><row><entry><literal>-fno-rtti</literal></entry><entry>As above, but RTTI-free dialect.</entry></row><row><entry><literal>-pthread</literal></entry><entry>For ISO C++11
        <filename class="headerfile">&lt;thread&gt;</filename>,
        <filename class="headerfile">&lt;future&gt;</filename>,
        <filename class="headerfile">&lt;mutex&gt;</filename>,
        or <filename class="headerfile">&lt;condition_variable&gt;</filename>.
      </entry></row><row><entry><literal>-latomic</literal></entry><entry>Linking to <filename class="libraryfile">libatomic</filename>
        is required for some uses of ISO C++11
        <filename class="headerfile">&lt;atomic&gt;</filename>.
      </entry></row><row><entry><literal>-lstdc++exp</literal></entry><entry>Linking to <filename class="libraryfile">libstdc++exp.a</filename>
        is required for use of experimental C++ library features.
        This currently provides support for the C++23 types defined in the
        <filename class="headerfile">&lt;stacktrace&gt;</filename> header,
	the C++23 functions defined in the
	<filename class="headerfile">&lt;print&gt;</filename> header,
        the Filesystem library extensions defined in the
        <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
        header,
        and the Contracts extensions enabled by <literal>-fcontracts</literal>.
      </entry></row><row><entry><literal>-lstdc++fs</literal></entry><entry>Linking to <filename class="libraryfile">libstdc++fs.a</filename>
        is another way to use the Filesystem library extensions defined in the
        <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
        header.
        The <filename class="libraryfile">libstdc++exp.a</filename> library
        also provides all the symbols contained in this library.
      </entry></row><row><entry><literal>-fopenmp</literal></entry><entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry></row><row><entry><literal>-ltbb</literal></entry><entry>Linking to tbb (Thread Building Blocks) is required for use of the
        Parallel Standard Algorithms and execution policies in
        <filename class="headerfile">&lt;execution&gt;</filename>.
      </entry></row><row><entry><literal>-ffreestanding</literal></entry><entry>
	Limits the library to its freestanding subset.  Headers that are
	not supported in freestanding will emit a "This header is not available
	in freestanding mode" error.
	Headers that are in the freestanding subset partially will not expose
	functionality that is not part of the freestanding subset.
      </entry></row></tbody></tgroup></table></section><section xreflabel="Headers" xml:id="manual.intro.using.headers"><info><title>Headers</title></info><?dbhtml filename="using_headers.html"?><section xreflabel="Header Files" xml:id="manual.intro.using.headers.all"><info><title>Header Files</title></info><para>
     The C++ standard specifies the entire set of header files that
     must be available to all hosted implementations.  Actually, the
     word "files" is a misnomer, since the contents of the
     headers don't necessarily have to be in any kind of external
     file.  The only rule is that when one <code>#include</code>s a
     header, the contents of that header become available, no matter
     how.
   </para><para>
   That said, in practice files are used.
   </para><para>
     There are two main types of include files: header files related
     to a specific version of the ISO C++ standard (called Standard
     Headers), and all others (TS, TR1, C++ ABI, and Extensions).
   </para><para>
     Multiple dialects of standard headers are supported, corresponding to
     the 1998 standard as updated for 2003, the 2011 standard, the 2014
     standard, and so on.
   </para><para><xref linkend="table.cxx98_headers"></xref> and
     <xref linkend="table.cxx98_cheaders"></xref> and
     <xref linkend="table.cxx98_deprheaders"></xref>
     show the C++98/03 include files.
     These are available in the C++98 compilation mode,
     i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
     Unless specified otherwise below, they are also available in later modes
     (C++11, C++14 etc).
   </para><table frame="all" xml:id="table.cxx98_headers"><title>C++ 1998 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">algorithm</filename></entry><entry><filename class="headerfile">bitset</filename></entry><entry><filename class="headerfile">complex</filename></entry><entry><filename class="headerfile">deque</filename></entry><entry><filename class="headerfile">exception</filename></entry></row><row><entry><filename class="headerfile">fstream</filename></entry><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">iomanip</filename></entry><entry><filename class="headerfile">ios</filename></entry><entry><filename class="headerfile">iosfwd</filename></entry></row><row><entry><filename class="headerfile">iostream</filename></entry><entry><filename class="headerfile">istream</filename></entry><entry><filename class="headerfile">iterator</filename></entry><entry><filename class="headerfile">limits</filename></entry><entry><filename class="headerfile">list</filename></entry></row><row><entry><filename class="headerfile">locale</filename></entry><entry><filename class="headerfile">map</filename></entry><entry><filename class="headerfile">memory</filename></entry><entry><filename class="headerfile">new</filename></entry><entry><filename class="headerfile">numeric</filename></entry></row><row><entry><filename class="headerfile">ostream</filename></entry><entry><filename class="headerfile">queue</filename></entry><entry><filename class="headerfile">set</filename></entry><entry><filename class="headerfile">sstream</filename></entry><entry><filename class="headerfile">stack</filename></entry></row><row><entry><filename class="headerfile">stdexcept</filename></entry><entry><filename class="headerfile">streambuf</filename></entry><entry><filename class="headerfile">string</filename></entry><entry><filename class="headerfile">utility</filename></entry><entry><filename class="headerfile">typeinfo</filename></entry></row><row><entry><filename class="headerfile">valarray</filename></entry><entry><filename class="headerfile">vector</filename></entry><entry nameend="c5" namest="c3"></entry></row></tbody></tgroup></table><para></para><table frame="all" xml:id="table.cxx98_cheaders"><title>C++ 1998 Library Headers for C Library Facilities</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">cassert</filename></entry><entry><filename class="headerfile">cerrno</filename></entry><entry><filename class="headerfile">cctype</filename></entry><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">ciso646</filename></entry></row><row><entry><filename class="headerfile">climits</filename></entry><entry><filename class="headerfile">clocale</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">csetjmp</filename></entry><entry><filename class="headerfile">csignal</filename></entry></row><row><entry><filename class="headerfile">cstdarg</filename></entry><entry><filename class="headerfile">cstddef</filename></entry><entry><filename class="headerfile">cstdio</filename></entry><entry><filename class="headerfile">cstdlib</filename></entry><entry><filename class="headerfile">cstring</filename></entry></row><row><entry><filename class="headerfile">ctime</filename></entry><entry><filename class="headerfile">cwchar</filename></entry><entry><filename class="headerfile">cwctype</filename></entry><entry nameend="c5" namest="c4"></entry></row></tbody></tgroup></table><para>
  The following header is deprecated
  and might be removed from a future C++ standard.
</para><table frame="all" xml:id="table.cxx98_deprheaders"><title>C++ 1998 Deprecated Library Header</title><tgroup align="left" cols="1" colsep="1" rowsep="1"><colspec colname="c1"></colspec><tbody><row><entry><filename class="headerfile">strstream</filename></entry></row></tbody></tgroup></table><para><xref linkend="table.cxx11_headers"></xref> and
<xref linkend="table.cxx11_cheaders"></xref> show the C++11 include files.
These are available in C++11 compilation
mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
Including these headers in C++98/03 mode may result in compilation errors.
Unless specified otherwise below, they are also available in later modes
(C++14 etc).
</para><para></para><table frame="all" xml:id="table.cxx11_headers"><title>C++ 2011 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">array</filename></entry><entry><filename class="headerfile">atomic</filename></entry><entry><filename class="headerfile">chrono</filename></entry><entry><filename class="headerfile">codecvt</filename></entry><entry><filename class="headerfile">condition_variable</filename></entry></row><row><entry><filename class="headerfile">forward_list</filename></entry><entry><filename class="headerfile">future</filename></entry><entry><filename class="headerfile">initalizer_list</filename></entry><entry><filename class="headerfile">mutex</filename></entry><entry><filename class="headerfile">random</filename></entry></row><row><entry><filename class="headerfile">ratio</filename></entry><entry><filename class="headerfile">regex</filename></entry><entry><filename class="headerfile">scoped_allocator</filename></entry><entry><filename class="headerfile">system_error</filename></entry><entry><filename class="headerfile">thread</filename></entry></row><row><entry><filename class="headerfile">tuple</filename></entry><entry><filename class="headerfile">typeindex</filename></entry><entry><filename class="headerfile">type_traits</filename></entry><entry><filename class="headerfile">unordered_map</filename></entry><entry><filename class="headerfile">unordered_set</filename></entry></row></tbody></tgroup></table><para></para><table frame="all" xml:id="table.cxx11_cheaders"><title>C++ 2011 Library Headers for C Library Facilities</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">ccomplex</filename></entry><entry><filename class="headerfile">cfenv</filename></entry><entry><filename class="headerfile">cinttypes</filename></entry><entry><filename class="headerfile">cstdalign</filename></entry><entry><filename class="headerfile">cstdbool</filename></entry></row><row><entry><filename class="headerfile">cstdint</filename></entry><entry><filename class="headerfile">ctgmath</filename></entry><entry><filename class="headerfile">cuchar</filename></entry><entry nameend="c5" namest="c4"></entry></row></tbody></tgroup></table><para><xref linkend="table.cxx14_headers"></xref> shows the C++14 include file.
This is available in C++14 compilation
mode, i.e. <literal>-std=c++14</literal> or <literal>-std=gnu++14</literal>.
Including this header in C++98/03 mode or C++11 will not result in
compilation errors, but will not define anything.
Unless specified otherwise below, it is also available in later modes
(C++17 etc).
</para><para></para><table frame="all" xml:id="table.cxx14_headers"><title>C++ 2014 Library Header</title><tgroup align="left" cols="1" colsep="1" rowsep="1"><colspec colname="c1"></colspec><tbody><row><entry><filename class="headerfile">shared_mutex</filename></entry></row></tbody></tgroup></table><para><xref linkend="table.cxx17_headers"></xref> shows the C++17 include files.
These are available in C++17 compilation
mode, i.e. <literal>-std=c++17</literal> or <literal>-std=gnu++17</literal>.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
Unless specified otherwise below, they are also available in later modes
(C++20 etc).
</para><para></para><table frame="all" xml:id="table.cxx17_headers"><title>C++ 2017 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">any</filename></entry><entry><filename class="headerfile">charconv</filename></entry><entry><filename class="headerfile">execution</filename></entry><entry><filename class="headerfile">filesystem</filename></entry><entry><filename class="headerfile">memory_resource</filename></entry></row><row><entry><filename class="headerfile">optional</filename></entry><entry><filename class="headerfile">string_view</filename></entry><entry><filename class="headerfile">variant</filename></entry><entry nameend="c5" namest="c4"></entry></row></tbody></tgroup></table><para><xref linkend="table.cxx20_headers"></xref>
shows the C++20 include files.
These are available in C++20 compilation
mode, i.e. <literal>-std=c++20</literal> or <literal>-std=gnu++20</literal>.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
<!--
Unless specified otherwise below, they are also available in later modes
(C++23 etc).
-->
</para><para></para><table frame="all" xml:id="table.cxx20_headers"><title>C++ 2020 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">barrier</filename></entry><entry><filename class="headerfile">bit</filename></entry><entry><filename class="headerfile">charconv</filename></entry><entry><filename class="headerfile">compare</filename></entry><entry><filename class="headerfile">concepts</filename></entry></row><row><entry><filename class="headerfile">coroutine</filename></entry><entry><filename class="headerfile">format</filename></entry><entry><filename class="headerfile">latch</filename></entry><entry><filename class="headerfile">numbers</filename></entry><entry><filename class="headerfile">ranges</filename></entry></row><row><entry><filename class="headerfile">semaphore</filename></entry><entry><filename class="headerfile">source_location</filename></entry><entry><filename class="headerfile">span</filename></entry><entry><filename class="headerfile">stop_token</filename></entry><entry><filename class="headerfile">syncstream</filename></entry></row><row><entry><filename class="headerfile">version</filename></entry><entry nameend="c5" namest="c2"></entry></row></tbody></tgroup></table><para>
  The following headers have been removed in the C++20 standard.
  They are still available when using this implementation, but in future
  they might start to produce warnings or errors when included in C++20 mode.
  Programs that intend to be portable should not include them.
</para><table frame="all" xml:id="table.cxx20_deprheaders"><title>C++ 2020 Obsolete Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">ccomplex</filename></entry><entry><filename class="headerfile">ciso646</filename></entry><entry><filename class="headerfile">cstdalign</filename></entry><entry><filename class="headerfile">cstdbool</filename></entry><entry><filename class="headerfile">ctgmath</filename></entry></row></tbody></tgroup></table><para><xref linkend="table.cxx23_headers"></xref>
shows the C++23 include files.
These are available in C++23 compilation
mode, i.e. <literal>-std=c++23</literal> or <literal>-std=gnu++23</literal>.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
<!--
Unless specified otherwise below, they are also available in later modes
(C++26 etc).
-->
</para><para></para><table frame="all" xml:id="table.cxx23_headers"><title>C++ 2023 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">expected</filename></entry><entry><filename class="headerfile">generator</filename></entry><entry><filename class="headerfile">print</filename></entry><entry><filename class="headerfile">spanstream</filename></entry><entry><filename class="headerfile">stacktrace</filename></entry></row><row><entry><filename class="headerfile">stdatomic.h</filename></entry><entry><filename class="headerfile">stdfloat</filename></entry><entry nameend="c5" namest="c3"></entry><!-- TODO flat_map, flat_set, mdspan --></row></tbody></tgroup></table><para><xref linkend="table.cxx26_headers"></xref>
shows the C++26 include files.
These are available in C++26 compilation
mode, i.e. <literal>-std=c++26</literal> or <literal>-std=gnu++26</literal>.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
<!--
Unless specified otherwise below, they are also available in later modes
(C++2d etc).
-->
</para><para></para><table frame="all" xml:id="table.cxx26_headers"><title>C++ 2026 Library Headers</title><tgroup align="left" cols="1" colsep="1" rowsep="1"><colspec colname="c1"></colspec><!--
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
--><tbody><row><entry><filename class="headerfile">text_encoding</filename></entry><!-- TODO debugging, hazard_pointer, linalg, rcu --></row></tbody></tgroup></table><para><xref linkend="table.filesystemts_headers"></xref>,
shows the additional include file define by the
File System Technical Specification, ISO/IEC TS 18822:2015.
This is available in C++11 and later compilation modes.
Including this header in earlier modes will not result in
compilation errors, but will not define anything.
</para><para></para><table frame="all" xml:id="table.filesystemts_headers"><title>File System TS Header</title><tgroup align="left" cols="1" colsep="1" rowsep="1"><colspec colname="c1"></colspec><tbody><row><entry><filename class="headerfile">experimental/filesystem</filename></entry></row></tbody></tgroup></table><para><xref linkend="table.libfundts_headers"></xref>,
shows the additional include files define by the C++ Extensions for
Library Fundamentals Technical Specification, ISO/IEC TS 19568:2015,
ISO/IEC TS 19568:2017, and ISO/IEC TS 19568:2024.
These are available in C++14 and later compilation modes, except for
<filename class="headerfile">&lt;experimental/scope&gt;</filename>
which is available in C++20 and later compilation modes.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
</para><para></para><table frame="all" xml:id="table.libfundts_headers"><title>Library Fundamentals TS Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">experimental/algorithm</filename></entry><entry><filename class="headerfile">experimental/any</filename></entry><entry><filename class="headerfile">experimental/array</filename></entry><entry><filename class="headerfile">experimental/chrono</filename></entry><entry><filename class="headerfile">experimental/deque</filename></entry></row><row><entry><filename class="headerfile">experimental/forward_list</filename></entry><entry><filename class="headerfile">experimental/functional</filename></entry><entry><filename class="headerfile">experimental/iterator</filename></entry><entry><filename class="headerfile">experimental/list</filename></entry><entry><filename class="headerfile">experimental/map</filename></entry></row><row><entry><filename class="headerfile">experimental/memory</filename></entry><entry><filename class="headerfile">experimental/memory_resource</filename></entry><entry><filename class="headerfile">experimental/numeric</filename></entry><entry><filename class="headerfile">experimental/optional</filename></entry><entry><filename class="headerfile">experimental/propagate_const</filename></entry></row><row><entry><filename class="headerfile">experimental/random</filename></entry><entry><filename class="headerfile">experimental/ratio</filename></entry><entry><filename class="headerfile">experimental/regex</filename></entry><entry><filename class="headerfile">experimental/scope</filename></entry><entry><filename class="headerfile">experimental/set</filename></entry></row><row><entry><filename class="headerfile">experimental/source_location</filename></entry><entry><filename class="headerfile">experimental/string</filename></entry><entry><filename class="headerfile">experimental/string_view</filename></entry><entry><filename class="headerfile">experimental/system_error</filename></entry><entry><filename class="headerfile">experimental/tuple</filename></entry></row><row><entry><filename class="headerfile">experimental/type_traits</filename></entry><entry><filename class="headerfile">experimental/unordered_map</filename></entry><entry><filename class="headerfile">experimental/unordered_set</filename></entry><entry><filename class="headerfile">experimental/utility</filename></entry><entry><filename class="headerfile">experimental/vector</filename></entry></row></tbody></tgroup></table><para><xref linkend="table.networkingts_headers"></xref>,
shows the additional include files define by the
Networking Technical Specification, ISO/IEC TS 19216:2018.
These are available in C++14 and later compilation modes.
Including these headers in earlier modes will not result in
compilation errors, but will not define anything.
</para><para></para><table frame="all" xml:id="table.networkingts_headers"><title>Networking TS Headers</title><tgroup align="left" cols="4" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><tbody><row><entry><filename class="headerfile">experimental/buffer</filename></entry><entry><filename class="headerfile">experimental/executor</filename></entry><entry><filename class="headerfile">experimental/internet</filename></entry><entry><filename class="headerfile">experimental/io_context</filename></entry></row><row><entry><filename class="headerfile">experimental/net</filename></entry><entry><filename class="headerfile">experimental/netfwd</filename></entry><entry><filename class="headerfile">experimental/socket</filename></entry><entry><filename class="headerfile">experimental/timer</filename></entry></row></tbody></tgroup></table><para>
  In addition, TR1 includes as:
</para><table frame="all" xml:id="table.tr1_headers"><title>C++ TR 1 Library Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">tr1/array</filename></entry><entry><filename class="headerfile">tr1/complex</filename></entry><entry><filename class="headerfile">tr1/memory</filename></entry><entry><filename class="headerfile">tr1/functional</filename></entry><entry><filename class="headerfile">tr1/random</filename></entry></row><row><entry><filename class="headerfile">tr1/regex</filename></entry><entry><filename class="headerfile">tr1/tuple</filename></entry><entry><filename class="headerfile">tr1/type_traits</filename></entry><entry><filename class="headerfile">tr1/unordered_map</filename></entry><entry><filename class="headerfile">tr1/unordered_set</filename></entry></row><row><entry><filename class="headerfile">tr1/utility</filename></entry><entry nameend="c5" namest="c2"></entry></row></tbody></tgroup></table><para></para><table frame="all" xml:id="table.tr1_cheaders"><title>C++ TR 1 Library Headers for C Library Facilities</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">tr1/ccomplex</filename></entry><entry><filename class="headerfile">tr1/cfenv</filename></entry><entry><filename class="headerfile">tr1/cfloat</filename></entry><entry><filename class="headerfile">tr1/cmath</filename></entry><entry><filename class="headerfile">tr1/cinttypes</filename></entry></row><row><entry><filename class="headerfile">tr1/climits</filename></entry><entry><filename class="headerfile">tr1/cstdarg</filename></entry><entry><filename class="headerfile">tr1/cstdbool</filename></entry><entry><filename class="headerfile">tr1/cstdint</filename></entry><entry><filename class="headerfile">tr1/cstdio</filename></entry></row><row><entry><filename class="headerfile">tr1/cstdlib</filename></entry><entry><filename class="headerfile">tr1/ctgmath</filename></entry><entry><filename class="headerfile">tr1/ctime</filename></entry><entry><filename class="headerfile">tr1/cwchar</filename></entry><entry><filename class="headerfile">tr1/cwctype</filename></entry></row></tbody></tgroup></table><para>Decimal floating-point arithmetic is available if the C++
compiler supports scalar decimal floating-point types defined via
<code>__attribute__((mode(SD|DD|LD)))</code>.
</para><table frame="all" xml:id="table.decfp_headers"><title>C++ TR 24733 Decimal Floating-Point Header</title><tgroup align="left" cols="1" colsep="1" rowsep="1"><colspec colname="c1"></colspec><tbody><row><entry><filename class="headerfile">decimal/decimal</filename></entry></row></tbody></tgroup></table><para>
  Also included are files for the C++ ABI interface:
</para><table frame="all" xml:id="table.abi_headers"><title>C++ ABI Headers</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><tbody><row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row></tbody></tgroup></table><para>
  And a large variety of extensions.
</para><table frame="all" xml:id="table.ext_headers"><title>Extension Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">ext/algorithm</filename></entry><entry><filename class="headerfile">ext/atomicity.h</filename></entry><entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry><entry><filename class="headerfile">ext/cast.h</filename></entry></row><row><entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry><entry><filename class="headerfile">ext/concurrence.h</filename></entry><entry><filename class="headerfile">ext/debug_allocator.h</filename></entry><entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry><entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry></row><row><entry><filename class="headerfile">ext/functional</filename></entry><entry><filename class="headerfile">ext/iterator</filename></entry><entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry><entry><filename class="headerfile">ext/memory</filename></entry><entry><filename class="headerfile">ext/mt_allocator.h</filename></entry></row><row><entry><filename class="headerfile">ext/new_allocator.h</filename></entry><entry><filename class="headerfile">ext/numeric</filename></entry><entry><filename class="headerfile">ext/numeric_traits.h</filename></entry><entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry><entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry></row><row><entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry><entry><filename class="headerfile">ext/pool_allocator.h</filename></entry><entry><filename class="headerfile">ext/rb_tree</filename></entry><entry><filename class="headerfile">ext/rope</filename></entry><entry><filename class="headerfile">ext/slist</filename></entry></row><row><entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry><entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry><entry><filename class="headerfile">ext/throw_allocator.h</filename></entry><entry><filename class="headerfile">ext/typelist.h</filename></entry><entry><filename class="headerfile">ext/type_traits.h</filename></entry></row><row><entry><filename class="headerfile">ext/vstring.h</filename></entry><entry nameend="c5" namest="c2"></entry></row></tbody></tgroup></table><para></para><table frame="all" xml:id="table.debug_headers"><title>Extension Debug Headers</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry><filename class="headerfile">debug/array</filename></entry><entry><filename class="headerfile">debug/bitset</filename></entry><entry><filename class="headerfile">debug/deque</filename></entry><entry><filename class="headerfile">debug/forward_list</filename></entry><entry><filename class="headerfile">debug/list</filename></entry></row><row><entry><filename class="headerfile">debug/map</filename></entry><entry><filename class="headerfile">debug/set</filename></entry><entry><filename class="headerfile">debug/string</filename></entry><entry><filename class="headerfile">debug/unordered_map</filename></entry><entry><filename class="headerfile">debug/unordered_set</filename></entry></row><row><entry><filename class="headerfile">debug/vector</filename></entry><entry nameend="c5" namest="c2"></entry></row></tbody></tgroup></table><para></para><table frame="all" xml:id="table.parallel_headers"><title>Extension Parallel Headers</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><tbody><row><entry><filename class="headerfile">parallel/algorithm</filename></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row></tbody></tgroup></table></section><section xreflabel="Mixing Headers" xml:id="manual.intro.using.headers.mixing"><info><title>Mixing Headers</title></info><para> A few simple rules.
</para><para>First, mixing different dialects of the standard headers is not
possible. It's an all-or-nothing affair. Thus, code like
</para><programlisting>
#include &lt;array&gt;
#include &lt;functional&gt;
</programlisting><para>Implies C++11 mode. To use the entities in &lt;array&gt;, the C++11
compilation mode must be used, which implies the C++11 functionality
(and deprecations) in &lt;functional&gt; will be present.
</para><para>Second, the other headers can be included with either dialect of
the standard headers, although features and types specific to C++11
are still only enabled when in C++11 compilation mode. So, to use
rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
debug-mode versions of <code>std::unordered_map</code>, one must use
the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.)
</para><para>A special case of the second rule is the mixing of TR1 and C++11
facilities. It is possible (although not especially prudent) to
include both the TR1 version and the C++11 version of header in the
same translation unit:
</para><programlisting>
#include &lt;tr1/type_traits&gt;
#include &lt;type_traits&gt;
</programlisting><para> Several parts of C++11 diverge quite substantially from TR1 predecessors.
</para></section><section xreflabel="C Headers and" xml:id="manual.intro.using.headers.cheaders"><info><title>The C Headers and <code>namespace std</code></title></info><para>
	The standard specifies that if one includes the C-style header
	(&lt;math.h&gt; in this case), the symbols will be available
	in the global namespace and perhaps in
	namespace <code>std::</code> (but this is no longer a firm
	requirement.) On the other hand, including the C++-style
	header (&lt;cmath&gt;) guarantees that the entities will be
	found in namespace std and perhaps in the global namespace.
      </para><para>
Usage of C++-style headers is recommended, as then
C-linkage names can be disambiguated by explicit qualification, such
as by <code>std::abort</code>. In addition, the C++-style headers can
use function overloading to provide a simpler interface to certain
families of C-functions. For instance in &lt;cmath&gt;, the
function <code>std::sin</code> has overloads for all the builtin
floating-point types. This means that <code>std::sin</code> can be
used uniformly, instead of a combination
of <code>std::sinf</code>, <code>std::sin</code>,
and <code>std::sinl</code>.
</para></section><section xreflabel="Precompiled Headers" xml:id="manual.intro.using.headers.pre"><info><title>Precompiled Headers</title></info><para>There are three base header files that are provided. They can be
used to precompile the standard headers and extensions into binary
files that may then be used to speed up compilations that use these headers.
</para><itemizedlist><listitem><para>stdc++.h</para><para>Includes all standard headers. Actual content varies depending on
<link linkend="manual.intro.using.flags">language dialect</link>.
</para></listitem><listitem><para>stdtr1c++.h</para><para>Includes all of &lt;stdc++.h&gt;, and adds all the TR1 headers.
</para></listitem><listitem><para>extc++.h</para><para>Includes all of &lt;stdc++.h&gt;, and adds all the Extension headers
(and in C++98 mode also adds all the TR1 headers by including all of
&lt;stdtr1c++.h&gt;).
</para></listitem></itemizedlist><para>To construct a .gch file from one of these base header files,
first find the include directory for the compiler. One way to do
this is:</para><programlisting>
g++ -v hello.cc

#include &lt;...&gt; search starts here:
 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
...
End of search list.
</programlisting><para>Then, create a precompiled header file with the same flags that
will be used to compile other projects.</para><programlisting>
g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h
</programlisting><para>The resulting file will be quite large: the current size is around
thirty megabytes. </para><para>How to use the resulting file.</para><programlisting>
g++ -I. -include stdc++.h  -H -g -O2 hello.cc
</programlisting><para>Verification that the PCH file is being used is easy:</para><programlisting>
g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
! ./stdc++.h.gch
. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
</programlisting><para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para><para></para><para>Detailed information about creating precompiled header files can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</link>.
</para></section></section><section xreflabel="Macros" xml:id="manual.intro.using.macros"><info><title>Macros</title></info><?dbhtml filename="using_macros.html"?><para>
     All library macros begin with <code>_GLIBCXX_</code>.
   </para><para>
     Furthermore, all pre-processor macros, switches, and
      configuration options are gathered in the
      file <filename class="headerfile">c++config.h</filename>, which
      is generated during the libstdc++ configuration and build
      process. This file is then included when needed by files part of
      the public libstdc++ API, like
      <filename class="headerfile">&lt;ios&gt;</filename>. Most of these
      macros should not be used by consumers of libstdc++, and are reserved
      for internal implementation use. <emphasis>These macros cannot
      be redefined</emphasis>.
   </para><para>
     A select handful of macros control libstdc++ extensions and extra
      features, or provide versioning information for the API.  Only
      those macros listed below are offered for consideration by the
      general public.
   </para><para>Below are the macros which users may check for library version
      information. </para><variablelist><varlistentry><term><code>_GLIBCXX_RELEASE</code></term><listitem><para>The major release number for libstdc++.  This macro is defined
        to the GCC major version that the libstdc++ headers belong to,
        as an integer constant.
        When compiling with GCC it has the same value as GCC's pre-defined
        macro <symbol>__GNUC__</symbol>.
        This macro can be used when libstdc++ is used with a non-GNU
        compiler where <symbol>__GNUC__</symbol> is not defined, or has a
        different value that doesn't correspond to the libstdc++ version.
        This macro first appeared in the GCC 7.1 release and is not defined
        for GCC 6.x or older releases.
      </para></listitem></varlistentry><varlistentry><term><code>__GLIBCXX__</code></term><listitem><para>The revision date of the libstdc++ source code,
        in compressed ISO date format, as an unsigned
        long. For notes about using this macro and details on the value of
        this macro for a particular release, please consult the
        <link linkend="abi.versioning.__GLIBCXX__">ABI History</link>
        appendix.
        </para></listitem></varlistentry></variablelist><para>Below are the macros which users may change with #define/#undef or
      with -D/-U compiler flags.  The default state of the symbol is
      listed.</para><para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
      that the symbol is initially chosen (or not) based on
      --enable/--disable options at library build and configure time
      (documented in
      <link linkend="manual.intro.setup.configure">Configure</link>),
      with the various --enable/--disable choices being translated to
      #define/#undef).
   </para><para><acronym>ABI</acronym>-changing means that changing from the default value may
  mean changing the <acronym>ABI</acronym> of compiled code. In other words,
  these choices control code which has already been compiled (i.e., in a
  binary such as libstdc++.a/.so).  If you explicitly #define or
  #undef these macros, the <emphasis>headers</emphasis> may see different code
  paths, but the <emphasis>libraries</emphasis> which you link against will not.
  Experimenting with different values with the expectation of
  consistent linkage requires changing the config headers before
  building/installing the library.
   </para><variablelist><varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term><listitem><para>
	Defined to the value <literal>1</literal> by default.
	Not configurable. ABI-changing. Turning this off
	removes older ARM-style iostreams code, and other anachronisms
	from the API.  This macro is dependent on the version of the
	standard being tracked, and as a result may give different results for
	different <code>-std</code> options.  This may
	be useful in updating old C++ code which no longer meet the
	requirements of the language, or for checking current code
	against new language standards.
    </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term><listitem><para>
        Defined to the value <literal>1</literal> by default.
        Configurable via  <code>--disable-libstdcxx-dual-abi</code>
        and/or <code>--with-default-libstdcxx-abi</code>.
        ABI-changing.
        When defined to a non-zero value the library headers will use the
        new C++11-conforming ABI introduced in GCC 5, rather than the older
        ABI introduced in GCC 3.4. This changes the definition of several
        class templates, including <classname>std:string</classname>,
        <classname>std::list</classname> and some locale facets.
        For more details see <xref linkend="manual.intro.using.abi"></xref>.
    </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term><listitem><para>
	Undefined by default.  Configurable via
	<code>--enable-concept-checks</code>.  When defined, performs
	compile-time checking on certain template instantiations to
	detect violations of the requirements of the standard.  This
	macro has no effect for freestanding implementations.
	This is described in more detail in
	<link linkend="manual.ext.compile_checks">Compile Time Checks</link>.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_ASSERTIONS</code></term><listitem><para>
	Defined by default when compiling with no optimization, undefined
	by default when compiling with optimization.
	When defined, enables extra error checking in the form of
	precondition assertions, such as bounds checking in strings
	and null pointer checks when dereferencing smart pointers.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_NO_ASSERTIONS</code></term><listitem><para>
	Undefined by default.  When defined, prevents the implicit
	definition of <code>_GLIBCXX_ASSERTIONS</code> when compiling
	with no optimization.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_DEBUG</code></term><listitem><para>
	Undefined by default. When defined, compiles user code using
	the <link linkend="manual.ext.debug_mode">debug mode</link>.
        When defined, <code>_GLIBCXX_ASSERTIONS</code> is defined
        automatically, so all the assertions enabled by that macro are also
        enabled in debug mode.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term><listitem><para>
	Undefined by default. When defined while compiling with
	the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
	the debug mode extremely picky by making the use of libstdc++
	extensions and libstdc++-specific behavior into errors.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_DEBUG_BACKTRACE</code></term><listitem><para>
	Undefined by default. Considered only if libstdc++ has been configured with
	<option>--enable-libstdcxx-backtrace=yes</option> and if <code>_GLIBCXX_DEBUG</code>
	is defined. When defined display backtraces on
	<link linkend="manual.ext.debug_mode">debug mode</link> assertions.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_PARALLEL</code></term><listitem><para>Undefined by default. When defined, compiles user code
	using the <link linkend="manual.ext.parallel_mode">parallel
	mode</link>.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_PARALLEL_ASSERTIONS</code></term><listitem><para>Undefined by default, but when any parallel mode header is included
      this macro will be defined to a non-zero value if
      <code>_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero.
      When defined to a non-zero value, it enables extra error checking and
      assertions in the parallel mode.
      </para></listitem></varlistentry><varlistentry><term><code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></term><listitem><para>Undefined by default. When defined to a non-zero integer constant,
	enables support for ISO/IEC 29124 Special Math Functions.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_SANITIZE_VECTOR</code></term><listitem><para>
	Undefined by default. When defined, <classname>std::vector</classname>
        operations will be annotated so that AddressSanitizer can detect
        invalid accesses to the unused capacity of a
        <classname>std::vector</classname>. These annotations are only
        enabled for
        <classname>std::vector&lt;T, std::allocator&lt;T&gt;&gt;</classname>
        and only when <classname>std::allocator</classname> is derived from
        <link linkend="allocator.ext"><classname>new_allocator</classname>
        or <classname>malloc_allocator</classname></link>. The annotations
        must be present on all vector operations or none, so this macro must
        be defined to the same value for all translation units that create,
        destroy, or modify vectors.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_NO_FREESTANDING_CHRONO</code></term><listitem><para>
	Undefined by default. When defined, the
	<filename class="headerfile">&lt;chrono&gt;</filename> header cannot
	be used with <option>-ffreestanding</option>.
	When not defined, durations, time points, and calendar types are
	available for freestanding, but the standard clocks and the time zone
	database are not (because they require OS support).
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_USE_OLD_GENERATE_CANONICAL</code></term><listitem><para>
	Undefined by default. When defined <code>generate_canonical</code>
	reverts to the algorithm used prior to the implementation of
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html">
	P0952: A new specification for std::generate_canonical</link> in GCC-16.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_USE_VARIANT_CXX17_OLD_ABI</code></term><listitem><para>
	Undefined by default. When defined <code>variant</code> in C++17
	mode will revert to the non-conforming implementation used prior to the
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=112591">PR112591</link>
	in GCC-16. Has no impact for C++20 or later modes.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_NO_INLINE_PRINT</code></term><listitem><para>
	Undefined by default. When defined <code>std::print</code> and
	<code>std::println</code> are not implemented using inline functions.
	This means that code using those functions will compile faster,
	but <option>-lstdc++exp</option> must be used when linking.
	The non-inline definitions are compiled using
	<option>-fexec-charset=UTF-8</option> so might give incorrect results
	if called from a source file that uses a non-Unicode encoding,
	especially for format strings using non-ASCII fill characters.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_USE_OLD_PIECEWISE_DISTRIBUTIONS</code></term><listitem><para>
	Undefined by default.
	When defined, the behavior of specializations of
	<code>piecewise_constant_distribution</code> and
	<code>piecewise_linear_distribution</code>
	is restored to their state prior the implementation
	of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=82749">
	PR82749</link> (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://cplusplus.github.io/LWG/lwg-defects.html#1439">
	LWG1439</link>), <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://cplusplus.github.io/LWG/lwg-defects.html#4052">
	LWG4052</link>,	and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=125548">
	PR125548</link>) in GCC 17.
      </para></listitem></varlistentry><varlistentry><term><code>_GLIBCXX_USE_RESULT_TYPE_FOR_PIECEWISE_DENSITIES</code></term><listitem><para>
	Undefined by default. ABI-changing.
	When defined, specializations of
	<code>piecewise_constant_distribution</code> and
	<code>piecewise_linear_distribution</code> with a
	<code>result_type</code> of either <code>float</code> or
	<code>long double</code> will manage their internal state using
	<code>result_type</code> values (instead of <code>double</code>).
	This is required for standard conformance, but is incompatible with
	the default implementation of those class templates.
      </para></listitem></varlistentry></variablelist></section><section xreflabel="Dual ABI" xml:id="manual.intro.using.abi"><info><title>Dual ABI</title></info><?dbhtml filename="using_dual_abi.html"?><para> In the GCC 5.1 release libstdc++ introduced a new library ABI that
  includes new implementations of <classname>std::string</classname> and
  <classname>std::list</classname>. These changes were necessary to conform
  to the 2011 C++ standard which forbids Copy-On-Write strings and requires
  lists to keep track of their size.
</para><para> In order to maintain backwards compatibility for existing code linked
  to libstdc++ the library's soname has not changed and the old
  implementations are still supported in parallel with the new ones.
  This is achieved by defining the new implementations in an inline namespace
  so they have different names for linkage purposes, e.g. the new version of
  <classname>std::list&lt;int&gt;</classname> is actually defined as
  <classname>std::__cxx11::list&lt;int&gt;</classname>. Because the symbols
  for the new implementations have different names the definitions for both
  versions can be present in the same library.
</para><para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
  <xref linkend="manual.intro.using.macros"></xref>) controls whether
  the declarations in the library headers use the old or new ABI.
  So the decision of which ABI to use can be made separately for each
  source file being compiled.
  Using the default configuration options for GCC the default value
  of the macro is <literal>1</literal> which causes the new ABI to be active,
  so to use the old ABI you must explicitly define the macro to
  <literal>0</literal> before including any library headers.
  (Be aware that some GNU/Linux distributions configured GCC 5 differently so
  that the default value of the macro is <literal>0</literal> and users must
  define it to <literal>1</literal> to enable the new ABI.)
</para><para> Although the changes were made for C++11 conformance, the choice of ABI
  to use is independent of the <option>-std</option> option used to compile
  your code, i.e. for a given GCC build the default value of the
  <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects.
  This ensures that the <option>-std</option> does not change the ABI, so
  that it is straightforward to link C++03 and C++11 code together.
</para><para> Because <classname>std::string</classname> is used extensively
  throughout the library a number of other types are also defined twice,
  including the stringstream classes and several facets used by
  <classname>std::locale</classname>. The standard facets which are always
  installed in a locale may be present twice, with both ABIs, to ensure that
  code like
  <code>std::use_facet&lt;std::time_get&lt;char&gt;&gt;(locale);</code>
  will work correctly for both <classname>std::time_get</classname> and
  <classname>std::__cxx11::time_get</classname> (even if a user-defined
  facet that derives from one or other version of
  <classname>time_get</classname> is installed in the locale).
</para><para> Although the standard exception types defined in
  <filename class="headerfile">&lt;stdexcept&gt;</filename> use strings, most
  are not defined twice, so that a <classname>std::out_of_range</classname>
  exception thrown in one file can always be caught by a suitable handler in
  another file, even if the two files are compiled with different ABIs.
</para><para> One exception type does change when using the new ABI, namely
  <classname>std::ios_base::failure</classname>.
  This is necessary because the 2011 standard changed its base class from
  <classname>std::exception</classname> to
  <classname>std::system_error</classname>, which causes its layout to change.
  Exceptions due to iostream errors are thrown by a function inside
  <filename class="libraryfile">libstdc++.so</filename>, so whether the thrown
  exception uses the old <classname>std::ios_base::failure</classname> type
  or the new one depends on the ABI that was active when
  <filename class="libraryfile">libstdc++.so</filename> was built,
  <emphasis>not</emphasis> the ABI active in the user code that is using
  iostreams.
  This means that for a given build of GCC the type thrown is fixed.
  In current releases the library throws a special type that can be caught
  by handlers for either the old or new type,
  but for GCC 7.1, 7.2 and 7.3 the library throws the new
  <classname>std::ios_base::failure</classname> type,
  and for GCC 5.x and 6.x the library throws the old type.
  Catch handlers of type <classname>std::ios_base::failure</classname>
  will only catch the exceptions if using a newer release,
  or if the handler is compiled with the same ABI as the type thrown by
  the library.
  Handlers for <classname>std::exception</classname> will always catch
  iostreams exceptions, because the old and new type both inherit from
  <classname>std::exception</classname>.
</para><para>
  Some features are not supported when using the old ABI, including:
  <itemizedlist><listitem>
    Using <classname>std::string::const_iterator</classname> for
    positional arguments to member functions such as
    <function>std::string::erase</function>.
  </listitem><listitem>
    Allocator propagation in <classname>std::string</classname>.
  </listitem><listitem>
    Using <classname>std::string</classname> at compile-time in
    <code>constexpr</code> functions.
  </listitem><listitem>
    Class <classname>std::chrono::time_zone</classname> and all related APIs.
  </listitem><listitem>
    The <filename class="headerfile">&lt;syncstream&gt;</filename> header.
  </listitem></itemizedlist>
</para><section xreflabel="Dual ABI Troubleshooting" xml:id="manual.intro.using.abi.trouble"><info><title>Troubleshooting</title></info><para> If you get linker errors about undefined references to symbols
  that involve types in the <code>std::__cxx11</code> namespace or the tag
  <code>[abi:cxx11]</code> then it probably indicates that you are trying to
  link together object files that were compiled with different values for the
  <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when
  linking to a third-party library that was compiled with an older version
  of GCC. If the third-party library cannot be rebuilt with the new ABI then
  you will need to recompile your code with the old ABI.
</para><para> Not all uses of the new ABI will cause changes in symbol names, for
  example a class with a <classname>std::string</classname> member variable
  will have the same mangled name whether compiled with the old or new ABI.
  In order to detect such problems the new types and functions are
  annotated with the <property>abi_tag</property> attribute, allowing the
  compiler to warn about potential ABI incompatibilities in code using them.
  Those warnings can be enabled with the <option>-Wabi-tag</option> option.
</para></section></section><section xreflabel="Namespaces" xml:id="manual.intro.using.namespaces"><info><title>Namespaces</title></info><?dbhtml filename="using_namespaces.html"?><section xreflabel="Available Namespaces" xml:id="manual.intro.using.namespaces.all"><info><title>Available Namespaces</title></info><para> There are three main namespaces.
</para><itemizedlist><listitem><para>std</para><para>The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namespaces nested
within namespace <code>std</code>, such as namespace
<code>std::chrono</code>.
</para></listitem><listitem><para>abi</para><para>Specified by the C++ ABI. This ABI specifies a number of type and
function APIs supplemental to those required by the ISO C++ Standard,
but necessary for interoperability.
</para></listitem><listitem><para>__gnu_</para><para>Indicating one of several GNU extensions. Choices
include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
and <code>__gnu_pbds</code>.
</para></listitem></itemizedlist><para> The library uses a number of inline namespaces as implementation
details that are not intended for users to refer to directly, these include
<code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>.
</para><para>A complete list of implementation namespaces (including namespace contents) is available in the generated source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</link>.
</para></section><section xreflabel="namespace std" xml:id="manual.intro.using.namespaces.std"><info><title>namespace std</title></info><para>
      One standard requirement is that the library components are defined
      in <code>namespace std::</code>. Thus, in order to use these types or
      functions, one must do one of two things:
</para><itemizedlist><listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
(either <code>using namespace std;</code> or i.e. <code>using
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
	  </para></listitem><listitem><para>use a <emphasis>fully
qualified name</emphasis> for each library symbol
(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
	  </para></listitem></itemizedlist></section><section xreflabel="Using Namespace Composition" xml:id="manual.intro.using.namespaces.comp"><info><title>Using Namespace Composition</title></info><para>
Best practice in programming suggests sequestering new data or
functionality in a sanely-named, unique namespace whenever
possible. This is considered an advantage over dumping everything in
the global namespace, as then name look-up can be explicitly enabled or
disabled as above, symbols are consistently mangled without repetitive
naming prefixes or macros, etc.
</para><para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
	adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
	<emphasis>namespace composition</emphasis>. This is what happens if
	a <emphasis>using</emphasis>-declaration is put into a
	namespace-definition: the imported symbol(s) gets imported into the
	currently active namespace(s). For example:
</para><programlisting>
namespace gtk
{
  using std::string;
  using std::tr1::array;

  class Window { ... };
}
</programlisting><para>
	In this example, <code>std::string</code> gets imported into
	<code>namespace gtk</code>.  The result is that use of
	<code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
	As an added bonus,
	<code>std::string</code> does not get imported into
	the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
	<code>using</code>-declarations can wrapped in macros that
	are set based on autoconf-tests to either "" or i.e. <code>using
	  std::string;</code> (depending on whether the system has
	libstdc++ in <code>std::</code> or not).  (ideas from
	Llewelly and Karl Nelson)
</para></section></section><section xreflabel="Linkage" xml:id="manual.intro.using.linkage"><info><title>Linking</title></info><?dbhtml filename="using_dynamic_or_shared.html"?><section xreflabel="Freestanding" xml:id="manual.intro.using.linkage.freestanding"><info><title>Almost Nothing</title></info><para>
	Or as close as it gets: freestanding. This is a minimal
	configuration, with only partial support for the standard
	library. Assume only the following header files can be used:
      </para><itemizedlist><listitem><para><filename class="headerfile">cstdarg</filename></para></listitem><listitem><para><filename class="headerfile">cstddef</filename></para></listitem><listitem><para><filename class="headerfile">cstdlib</filename></para></listitem><listitem><para><filename class="headerfile">exception</filename></para></listitem><listitem><para><filename class="headerfile">limits</filename></para></listitem><listitem><para><filename class="headerfile">new</filename></para></listitem><listitem><para><filename class="headerfile">exception</filename></para></listitem><listitem><para><filename class="headerfile">typeinfo</filename></para></listitem></itemizedlist><para>
	In addition, throw in
      </para><itemizedlist><listitem><para><filename class="headerfile">cxxabi.h</filename>.
	  </para></listitem></itemizedlist><para>
	In the
	C++11 <link linkend="manual.intro.using.flags">dialect</link> add
      </para><itemizedlist><listitem><para><filename class="headerfile">initializer_list</filename></para></listitem><listitem><para><filename class="headerfile">type_traits</filename></para></listitem></itemizedlist><para>
	As of GCC 13, libstdc++ implements P1642, which brings in many more
	headers, as well a quite a few ones not covered by the paper.

	In general, if a feature does not require traditionally libc-provided
	facilities, or dynamic memory allocation, it's enabled in the
	freestanding subset.  In addition, if only a subset of a header
	requires such features, it is partially included.  Some examples
	include:
      </para><itemizedlist><listitem><para><filename class="headerfile">string_view</filename></para></listitem><listitem><para><filename class="headerfile">tuple</filename></para></listitem><listitem><para><filename class="headerfile">bitset</filename></para></listitem></itemizedlist><para>
	Currently, this subset includes all of the iterator APIs (including the
	ranges APIs) that do not involve streams, the entire C++ algorithms
	library, excluding parallel algorithms, and a large part of the
	utilities library.  This is on top of the headers included in the lists
	above.
      </para><para>
	If you're using a libstdc++ configured for hosted environments, and
	would like to not involve the libraries libstdc++ would depend on in
	your programs, you will need to use <command>gcc</command> to link your
	application with only <filename class="libraryfile">libsupc++.a</filename>,
	like so:
      </para><para><command>gcc -ffreestanding foo.cc -lsupc++</command></para><para>
	If you configured libstdc++ with
	<code>--disable-hosted-libstdcxx</code>, however, you can use the
	normal <command>g++</command> command to link, as this configuration
	provides a (nearly) empty <filename class="libraryfile">libstdc++.a</filename>.
      </para></section><section xreflabel="Dynamic and Shared" xml:id="manual.intro.using.linkage.dynamic"><info><title>Finding Dynamic or Shared Libraries</title></info><para>
      If the only library built is the static library
      (<filename class="libraryfile">libstdc++.a</filename>), or if
      specifying static linking, this section is can be skipped.  But
      if building or using a shared library
      (<filename class="libraryfile">libstdc++.so</filename>), then
      additional location information will need to be provided.
    </para><para>
      But how?
    </para><para>
A quick read of the relevant part of the GCC
      manual, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling
      C++ Programs</link>, specifies linking against a C++
      library. More details from the
      GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/faq.html#rpath">FAQ</link>,
      which states <emphasis>GCC does not, by default, specify a
      location so that the dynamic linker can find dynamic libraries at
      runtime.</emphasis>
    </para><para>
      Users will have to provide this information.
    </para><para>
      Methods vary for different platforms and different styles, and
      are printed to the screen during installation. To summarize:
    </para><itemizedlist><listitem><para>
	  At runtime set <literal>LD_LIBRARY_PATH</literal> in your
	  environment correctly, so that the shared library for
	  libstdc++ can be found and loaded.  Be certain that you
	  understand all of the other implications and behavior
	  of <literal>LD_LIBRARY_PATH</literal> first.
	</para></listitem><listitem><para>
	  Compile the path to find the library at runtime into the
	  program.  This can be done by passing certain options to
	  <command>g++</command>, which will in turn pass them on to
	  the linker.  The exact format of the options is dependent on
	  which linker you use:
	</para><itemizedlist><listitem><para>
	      GNU ld (default on GNU/Linux):
              <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
	    </para></listitem><listitem><para>
	    Solaris ld:
            <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
	  </para></listitem></itemizedlist></listitem><listitem><para>
	  Some linkers allow you to specify the path to the library by
	  setting <literal>LD_RUN_PATH</literal> in your environment
	  when linking.
	</para></listitem><listitem><para>
	  On some platforms the system administrator can configure the
	  dynamic linker to always look for libraries in
	  <filename class="directory">destdir/lib</filename>, for example
	  by using the <command>ldconfig</command> utility on GNU/Linux
	  or the <command>crle</command> utility on Solaris. This is a
	  system-wide change which can make the system unusable so if you
	  are unsure then use one of the other methods described above.
	</para></listitem></itemizedlist><para>
      Use the <command>ldd</command> utility on the linked executable
      to show
      which <filename class="libraryfile">libstdc++.so</filename>
      library the system will get at runtime.
    </para><para>
      A <filename class="libraryfile">libstdc++.la</filename> file is
      also installed, for use with Libtool.  If you use Libtool to
      create your executables, these details are taken care of for
      you.
    </para></section><section xreflabel="Library Extensions" xml:id="manual.intro.using.linkage.experimental"><info><title>Experimental Library Extensions</title></info><para>
      GCC 5.3 includes an implementation of the Filesystem library defined
      by the technical specification ISO/IEC TS 18822:2015. Because this is
      an experimental library extension, not part of the C++ standard, it
      is implemented in a separate library,
      <filename class="libraryfile">libstdc++fs.a</filename>, and there is
      no shared library for it. To use the library you should include
      <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
      and link with <option>-lstdc++fs</option>. The library implementation
      is incomplete on non-POSIX platforms, specifically Windows is only
      partially supported.
      Since GCC 14, <filename class="libraryfile">libstdc++exp.a</filename>
      also contains the definitions for this library,
      so <option>-lstdc++exp</option> can be used instead of
      <option>-lstdc++fs</option>.
    </para><para>
      GCC 13 includes an implementation of the C++ Contracts library defined by
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1429r3.pdf">P1429R3</link>.
      Because this is an experimental extension, not part of the C++ standard,
      it is implemented in a separate library,
      <filename class="libraryfile">libstdc++exp.a</filename>, and there is
      no shared library for it. To use the library you should include
      <filename class="headerfile">&lt;experimental/contract&gt;</filename>
      and link with <option>-lstdc++exp</option>.
    </para><para>
      Due to the experimental nature of these libraries the usual
      guarantees about ABI stability and backwards compatibility do not apply
      to them. There is no guarantee that the components in any
      <filename class="headerfile">&lt;experimental/xxx&gt;</filename>
      header will remain compatible between different GCC releases.
    </para></section></section><section xreflabel="Concurrency" xml:id="manual.intro.using.concurrency"><info><title>Concurrency</title></info><?dbhtml filename="using_concurrency.html"?><para>This section discusses issues surrounding the proper compilation
      of multithreaded applications which use the Standard C++
      library.  This information is GCC-specific since the C++
      standard does not address matters of multithreaded applications.
   </para><section xreflabel="Thread Prereq" xml:id="manual.intro.using.concurrency.prereq"><info><title>Prerequisites</title></info><para>All normal disclaimers aside, multithreaded C++ application are
      only supported when libstdc++ and all user code was built with
      compilers which report (via <code> gcc/g++ -v </code>) the same thread
      model and that model is not <emphasis>single</emphasis>.  As long as your
      final application is actually single-threaded, then it should be
      safe to mix user code built with a thread model of
      <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
      with another thread model useful on the platform.  Other mixes
      may or may not work but are not considered supported.  (Thus, if
      you distribute a shared C++ library in binary form only, it may
      be best to compile it with a GCC configured with
      --enable-threads for maximal interchangeability and usefulness
      with a user population that may have built GCC with either
      --enable-threads or --disable-threads.)
   </para><para>When you link a multithreaded application, you will probably
      need to add a library or flag to g++.  This is a very
      non-standardized area of GCC across ports.  Some ports support a
      special flag (the spelling isn't even standardized yet) to add
      all required macros to a compilation (if any such flags are
      required then you must provide the flag for all compilations not
      just linking) and link-library additions and/or replacements at
      link time.  The documentation is weak.  On several targets (including
      GNU/Linux, Solaris and various BSDs) -pthread is honored.
      Some other ports use other switches.
      This is not well documented anywhere other than
      in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
   </para><para>
     Some uses of <classname>std::atomic</classname> also require linking
     to <filename class="libraryfile">libatomic</filename>.
   </para></section><section xreflabel="Thread Safety" xml:id="manual.intro.using.concurrency.thread_safety"><info><title>Thread Safety</title></info><para>
In the terms of the 2011 C++ standard a thread-safe program is one which
does not perform any conflicting non-atomic operations on memory locations
and so does not contain any data races.
The standard places requirements on the library to ensure that no data
races are caused by the library itself or by programs which use the
library correctly (as described below).
The C++11 memory model and library requirements are a more formal version
of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171221154911/http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</link> definition of thread safety, which the library used
prior to the 2011 standard.
</para><para>The library strives to be thread-safe when all of the following
	 conditions are met:
      </para><itemizedlist><listitem><para>The system's libc is itself thread-safe,
       </para></listitem><listitem><para>
	   The compiler in use reports a thread model other than
	   'single'. This can be tested via output from <code>gcc
	   -v</code>. Multi-thread capable versions of gcc output
	   something like this:
	 </para><programlisting>
%gcc -v
Using built-in specs.
...
Thread model: posix
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
</programlisting><para>Look for "Thread model" lines that aren't equal to "single."</para></listitem><listitem><para>
	 Requisite command-line flags are used for atomic operations
	 and threading. Examples of this include <code>-pthread</code>
	 and <code>-march=native</code>, although specifics vary
	 depending on the host environment. See
	 <link linkend="manual.intro.using.flags">Command Options</link> and
	 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
	 Dependent Options</link>.
       </para></listitem><listitem><para>
	   An implementation of the
	   <filename class="headerfile">atomicity.h</filename> functions
	   exists for the architecture in question. See the
	   <link linkend="internals.thread_safety">internals
	   documentation</link> for more details.
       </para></listitem></itemizedlist><para>The user code must guard against concurrent function calls which
         access any particular library object's state when one or more of
         those accesses modifies the state. An object will be modified by
         invoking a non-const member function on it or passing it as a
         non-const argument to a library function. An object will not be
         modified by invoking a const member function on it or passing it to
         a function as a pointer- or reference-to-const.
         Typically, the application
         programmer may infer what object locks must be held based on the
         objects referenced in a function call and whether the objects are
         accessed as const or non-const.  Without getting
	 into great detail, here is an example which requires user-level
	 locks:
      </para><programlisting>
     library_class_a shared_object_a;

     void thread_main () {
       library_class_b *object_b = new library_class_b;
       shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
       shared_object_a.mutate ();          // must hold lock for shared_object_a
     }

     // Multiple copies of thread_main() are started in independent threads.</programlisting><para>Under the assumption that object_a and object_b are never exposed to
	 another thread, here is an example that does not require any
	 user-level locks:
      </para><programlisting>
     void thread_main () {
       library_class_a object_a;
       library_class_b *object_b = new library_class_b;
       object_a.add_b (object_b);
       object_a.mutate ();
     } </programlisting><para>All library types are safe to use in a multithreaded program
         if objects are not shared between threads or as
	 long each thread carefully locks out access by any other
	 thread while it modifies any object visible to another thread.
	 Unless otherwise documented, the only exceptions to these rules
         are atomic operations on the types in
         <filename class="headerfile">&lt;atomic&gt;</filename>
         and lock/unlock operations on the standard mutex types in
         <filename class="headerfile">&lt;mutex&gt;</filename>. These
         atomic operations allow concurrent accesses to the same object
         without introducing data races.
      </para><para>The following member functions of standard containers can be
         considered to be const for the purposes of avoiding data races:
         <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
         <code>front</code>, <code>back</code>, <code>data</code>,
         <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
         <code>equal_range</code>, <code>at</code>
         and, except in associative or unordered associative containers,
         <code>operator[]</code>. In other words, although they are non-const
         so that they can return mutable iterators, those member functions
         will not modify the container.
         Accessing an iterator might cause a non-modifying access to
         the container the iterator refers to (for example incrementing a
         list iterator must access the pointers between nodes, which are part
         of the container and so conflict with other accesses to the container).
      </para><para>
	 The Copy-On-Write <classname>std::string</classname> implementation
	 used before GCC 5 (and with
	 <link linkend="manual.intro.using.abi">_GLIBCXX_USE_CXX11_ABI=0</link>)
	 is not a standard container and does not conform to the data race
	 avoidance rules described above. For the Copy-On-Write
	 <classname>std::string</classname>, non-const member functions such as
	 <function>begin()</function> are considered to be modifying accesses
	 and so must not be used concurrently with any other accesses to the
	 same object.
      </para><para>Programs which follow the rules above will not encounter data
         races in library code, even when using library types which share
         state between distinct objects.  In the example below the
         <code>shared_ptr</code> objects share a reference count, but
         because the code does not perform any non-const operations on the
         globally-visible object, the library ensures that the reference
         count updates are atomic and do not introduce data races:
      </para><programlisting>
    std::shared_ptr&lt;int&gt; global_sp;

    void thread_main() {
      auto local_sp = global_sp;  // OK, copy constructor's parameter is reference-to-const

      int i = *global_sp;         // OK, operator* is const
      int j = *local_sp;          // OK, does not operate on global_sp

      // *global_sp = 2;          // NOT OK, modifies int visible to other threads
      // *local_sp = 2;           // NOT OK, modifies int visible to other threads

      // global_sp.reset();       // NOT OK, reset is non-const
      local_sp.reset();           // OK, does not operate on global_sp
    }

    int main() {
      global_sp.reset(new int(1));
      std::thread t1(thread_main);
      std::thread t2(thread_main);
      t1.join();
      t2.join();
    }
</programlisting><para>For further details of the C++11 memory model see Hans-J. Boehm's
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/">Threads
      and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/threadsintro.html">introduction</link>
      and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/user-faq.html">FAQ</link>.
      </para></section><section xreflabel="Atomics" xml:id="manual.intro.using.concurrency.atomics"><info><title>Atomics</title></info><para>
    </para></section><section xreflabel="IO" xml:id="manual.intro.using.concurrency.io"><info><title>IO</title></info><para>This gets a bit tricky.  Please read carefully, and bear with me.
   </para><section xreflabel="Structure" xml:id="concurrency.io.structure"><info><title>Structure</title></info><para>A wrapper
      type called <code>__basic_file</code> provides our abstraction layer
      for the <code>std::filebuf</code> classes.  Nearly all decisions dealing
      with actual input and output must be made in <code>__basic_file</code>.
   </para><para>A generic locking mechanism is somewhat in place at the filebuf layer,
      but is not used in the current code.  Providing locking at any higher
      level is akin to providing locking within containers, and is not done
      for the same reasons (see the links above).
   </para></section><section xreflabel="Defaults" xml:id="concurrency.io.defaults"><info><title>Defaults</title></info><para>The __basic_file type is simply a collection of small wrappers around
      the C stdio layer (again, see the link under Structure).  We do no
      locking ourselves, but simply pass through to calls to <code>fopen</code>,
      <code>fwrite</code>, and so forth.
   </para><para>So, for 3.0, the question of "is multithreading safe for I/O"
      must be answered with, "is your platform's C library threadsafe
      for I/O?"  Some are by default, some are not; many offer multiple
      implementations of the C library with varying tradeoffs of threadsafety
      and efficiency.  You, the programmer, are always required to take care
      with multiple threads.
   </para><para>(As an example, the POSIX standard requires that C stdio
       <code>FILE*</code> operations are atomic.  POSIX-conforming C libraries
       (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
       operations on <code>FILE*</code>s.
       However, you still need to not do stupid things like calling
       <code>fclose(fs)</code> in one thread followed by an access of
       <code>fs</code> in another.)
   </para><para>So, if your platform's C library is threadsafe, then your
      <code>fstream</code> I/O operations will be threadsafe at the lowest
      level.  For higher-level operations, such as manipulating the data
      contained in the stream formatting classes (e.g., setting up callbacks
      inside an <code>std::ofstream</code>), you need to guard such accesses
      like any other critical shared resource.
   </para></section><section xreflabel="Future" xml:id="concurrency.io.future"><info><title>Future</title></info><para> A
      second choice may be available for I/O implementations:  libio.  This is
      disabled by default, and in fact will not currently work due to other
      issues.  It will be revisited, however.
   </para><para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
      implementation.  When libio is in use, the <code>__basic_file</code>
      type is basically derived from FILE.  (The real situation is more
      complex than that... it's derived from an internal type used to
      implement FILE.  See libio/libioP.h to see scary things done with
      vtbls.)  The result is that there is no "layer" of C stdio
      to go through; the filebuf makes calls directly into the same
      functions used to implement <code>fread</code>, <code>fwrite</code>,
      and so forth, using internal data structures.  (And when I say
      "makes calls directly," I mean the function is literally
      replaced by a jump into an internal function.  Fast but frightening.
      *grin*)
   </para><para>Also, the libio internal locks are used.  This requires pulling in
      large chunks of glibc, such as a pthreads implementation, and is one
      of the issues preventing widespread use of libio as the libstdc++
      cstdio implementation.
   </para><para>But we plan to make this work, at least as an option if not a future
      default.  Platforms running a copy of glibc with a recent-enough
      version will see calls from libstdc++ directly into the glibc already
      installed.  For other platforms, a copy of the libio subsection will
      be built and included in libstdc++.
   </para></section><section xreflabel="Alt" xml:id="concurrency.io.alt"><info><title>Alternatives</title></info><para>Don't forget that other cstdio implementations are possible.  You could
      easily write one to perform your own forms of locking, to solve your
      "interesting" problems.
   </para></section></section><section xreflabel="Containers" xml:id="manual.intro.using.concurrency.containers"><info><title>Containers</title></info><para>This section discusses issues surrounding the design of
      multithreaded applications which use Standard C++ containers.
      All information in this section is current as of the gcc 3.0
      release and all later point releases.  Although earlier gcc
      releases had a different approach to threading configuration and
      proper compilation, the basic code design rules presented here
      were similar.  For information on all other aspects of
      multithreading as it relates to libstdc++, including details on
      the proper compilation of threaded code (and compatibility between
      threaded and non-threaded code), see Chapter 17.
   </para><para>Two excellent pages to read when working with the Standard C++
      containers and threads are
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171221154911/http://www.sgi.com/tech/stl/thread_safety.html">SGI's
      https://web.archive.org/web/20171221154911/http://www.sgi.com/tech/stl/thread_safety.html</link> and
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171108142526/http://www.sgi.com/tech/stl/Allocators.html">SGI's
      https://web.archive.org/web/20171108142526/http://www.sgi.com/tech/stl/Allocators.html</link>.
   </para><para><emphasis>However, please ignore all discussions about the user-level
      configuration of the lock implementation inside the STL
      container-memory allocator on those pages.  For the sake of this
      discussion, libstdc++ configures the SGI STL implementation,
      not you.  This is quite different from how gcc pre-3.0 worked.
      In particular, past advice was for people using g++ to
      explicitly define _PTHREADS or other macros or port-specific
      compilation options on the command line to get a thread-safe
      STL.  This is no longer required for any port and should no
      longer be done unless you really know what you are doing and
      assume all responsibility.</emphasis></para><para>Since the container implementation of libstdc++ uses the SGI
      code, we use the same definition of thread safety as SGI when
      discussing design.  A key point that beginners may miss is the
      fourth major paragraph of the first page mentioned above
      (<emphasis>For most clients...</emphasis>), which points out that
      locking must nearly always be done outside the container, by
      client code (that'd be you, not us).  There is a notable
      exceptions to this rule.  Allocators called while a container or
      element is constructed uses an internal lock obtained and
      released solely within libstdc++ code (in fact, this is the
      reason STL requires any knowledge of the thread configuration).
   </para><para>For implementing a container which does its own locking, it is
      trivial to provide a wrapper class which obtains the lock (as
      SGI suggests), performs the container operation, and then
      releases the lock.  This could be templatized <emphasis>to a certain
      extent</emphasis>, on the underlying container and/or a locking
      mechanism.  Trying to provide a catch-all general template
      solution would probably be more trouble than it's worth.
   </para><para>The library implementation may be configured to use the
      high-speed caching memory allocator, which complicates thread
      safety issues. For all details about how to globally override
      this at application run-time
      see <link linkend="manual.intro.using.macros">here</link>. Also
      useful are details
      on <link linkend="std.util.memory.allocator">allocator</link>
      options and capabilities.
   </para></section></section><!-- Section 0x : Exception policies, expectations, topics --><section version="5.0" xreflabel="Using Exceptions" xml:id="manual.intro.using.exceptions"><?dbhtml filename="using_exceptions.html"?><info><title>Exceptions</title><keywordset><keyword>C++</keyword><keyword>exception</keyword><keyword>error</keyword><keyword>exception neutrality</keyword><keyword>exception safety</keyword><keyword>exception propagation</keyword><keyword>-fno-exceptions</keyword></keywordset></info><para>
The C++ language provides language support for stack unwinding
with <literal>try</literal> and <literal>catch</literal> blocks and
the <literal>throw</literal> keyword.
</para><para>
These are very powerful constructs, and require some thought when
applied to the standard library in order to yield components that work
efficiently while cleaning up resources when unexpectedly killed via
exceptional circumstances.
</para><para>
Two general topics of discussion follow:
exception neutrality and exception safety.
</para><section xreflabel="Exception Safety" xml:id="intro.using.exception.safety"><info><title>Exception Safety</title></info><para>
    What is exception-safe code?
  </para><para>
    Will define this as reasonable and well-defined behavior by classes
    and functions from the standard library when used by user-defined
    classes and functions that are themselves exception safe.
  </para><para>
    Please note that using exceptions in combination with templates
    imposes an additional requirement for exception
    safety. Instantiating types are required to have destructors that
    do no throw.
  </para><para>
    Using the layered approach from Abrahams, can classify library
    components as providing set levels of safety. These will be called
    exception guarantees, and can be divided into three categories.
  </para><itemizedlist><listitem><para>
    One. Don't throw.
  </para><para>
    As specified in 23.2.1 general container requirements. Applicable
    to container and string classes.
  </para><para>
    Member
    functions <function>erase</function>, <function>pop_back</function>, <function>pop_front</function>, <function>swap</function>, <function>clear</function>. And <type>iterator</type>
    copy constructor and assignment operator.
  </para></listitem><listitem><para>
    Two. Don't leak resources when exceptions are thrown. This is
    also referred to as the <quote>basic</quote> exception safety guarantee.
  </para><para>
    This applicable throughout the standard library.
  </para></listitem><listitem><para>
    Three. Commit-or-rollback semantics.  This is
    referred to as <quote>strong</quote> exception safety guarantee.
  </para><para>
    As specified in 23.2.1 general container requirements. Applicable
    to container and string classes.
  </para><para>
    Member functions <function>insert</function> of a single
    element, <function>push_back</function>, <function>push_front</function>,
    and <function>rehash</function>.
  </para></listitem></itemizedlist></section><section xreflabel="Exceptions Neutrality" xml:id="intro.using.exception.propagating"><info><title>Exception Neutrality</title></info><para>
    Simply put, once thrown an exception object should continue in
    flight unless handled explicitly. In practice, this means
    propagating exceptions should not be swallowed in
    gratuitous <literal>catch(...)</literal> blocks. Instead,
    matching <literal>try</literal> and <literal>catch</literal>
    blocks should have specific catch handlers and allow un-handed
    exception objects to propagate. If a
    terminating <literal>catch(...)</literal> blocks exist then it
    should end with a <literal>throw</literal> to re-throw the current
    exception.
  </para><para>
    Why do this?
  </para><para>
    By allowing exception objects to propagate, a more flexible
    approach to error handling is made possible (although not
    required.) Instead of dealing with an error immediately, one can
    allow the exception to propagate up until sufficient context is
    available and the choice of exiting or retrying can be made in an
    informed manner.
  </para><para>
    Unfortunately, this tends to be more of a guideline than a strict
    rule as applied to the standard library. As such, the following is
    a list of known problem areas where exceptions are not propagated.
  </para><itemizedlist><listitem><para>
      Input/Output
    </para><para>
    The destructor <function>ios_base::Init::~Init()</function>
    swallows all exceptions from <function>flush</function> called on
    all open streams at termination.
  </para><para>
    All formatted input in <classname>basic_istream</classname> or
    formatted output in <classname>basic_ostream</classname> can be
    configured to swallow exceptions
    when <function>exceptions</function> is set to
    ignore <type>ios_base::badbit</type>.
  </para><para>
    Functions that have been registered
    with <function>ios_base::register_callback</function> swallow all
    exceptions when called as part of a callback event.
  </para><para>
    When closing the underlying
    file, <function>basic_filebuf::close</function> will swallow
    (non-cancellation) exceptions thrown and return <literal>NULL</literal>.
  </para></listitem><listitem><para>
      Thread
    </para><para>
      The constructors of <classname>thread</classname> that take a
      callable function argument swallow all exceptions resulting from
      executing the function argument.
    </para></listitem></itemizedlist></section><section xreflabel="Memory allocation for exceptions" xml:id="intro.using.exception.alloc"><info><title>Memory allocation</title></info><para>
    When the program throws an exception the runtime will obtain storage for
    a <code>__cxa_exception</code> header and the thrown object itself.
    Libstdc++ will try to use <code>malloc</code> to obtain storage,
    but provides an emergency buffer to be used if malloc fails,
    as described by the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#imp-emergency">Itanium
    exception handling ABI</link>.
  </para><para>
    Contrary to the ABI, the libstdc++ emergency buffer is not always 64kB,
    and does not always allocate 1kB chunks. The buffer is used as a pool for
    variable-sized allocations, so that it doesn't waste space for smaller
    exception objects such as <code>std::bad_alloc</code>.
    The total size of the buffer is scaled appropriately for the target.
    Specifically it depends on <code>sizeof(void*)</code>, so that a 64-bit
    system uses a larger pool than a 32-bit system. This is done because for
    32-bit systems the exception objects (and the exception header) require
    less space, and core counts and thread counts are typically lower as well.
  </para><para>
    By default, libstdc++ will use <code>malloc</code> to allocate the buffer
    on program startup.
    <xref linkend="manual.intro.setup.configure"></xref> libstdc++ with the
    <code>--enable-libstdcxx-static-eh-pool</code> option will make it
    use a static buffer instead of using <code>malloc</code>.
  </para><para>
    The buffer size is chosen automatically, but can be overridden
    by configuring with <code>--with-libstdcxx-eh-pool-obj-count=NUM</code>,
    where <code>NUM</code> is the number of simultaneous allocations that
    should be supported. The size of the pool will be sufficient for
    <code>NUM</code> exceptions of <code>6 * sizeof(void*)</code> bytes,
    plus another <code>NUM</code> exceptions captured in
    <classname>std::exception_ptr</classname> and rethrown using
    <code>std::rethrow_exception</code>. The buffer size determined by the
    obj-count value applies whether the buffer is reserved as static storage
    or is allocated dynamically.
    Setting obj-count to zero will disable the pool, so that no emergency
    buffer is present.
  </para><para>
    For a dynamic buffer, the default size can also be changed at runtime,
    per-process, via the <literal>GLIBCXX_TUNABLES</literal> environment
    variable.
    The <literal>GLIBCXX_TUNABLES</literal> environment variable should be
    a string of colon-separated <emphasis>name=value</emphasis> pairs. The
    following names will be recognized, with the specified semantics:
  </para><variablelist><varlistentry><term><code>glibcxx.eh_pool.obj_count</code></term><listitem>
    The number of exception objects to provide space for in the pool.
    The value must be a non-negative integer and has the same meaning as the
    <code>--with-libstdcxx-eh-pool-obj-count</code> option for
    <filename>configure</filename>.
  </listitem></varlistentry><varlistentry><term><code>glibcxx.eh_pool.obj_size</code></term><listitem>
    The expected size of exception objects that the pool might get used for.
    The value must be a positive integer, and is measured in units of
    <code>sizeof(void*)</code>. The default value is <literal>6</literal>
    which is large enough to store any exception type thrown by libstdc++.
    Exceptions larger than this can still be allocated from the pool,
    but larger exceptions will exhaust the pool more rapidly.
  </listitem></varlistentry></variablelist></section><section xreflabel="-fno-exceptions" xml:id="intro.using.exception.no"><info><title>Doing without</title></info><para>
    C++ is a language that strives to be as efficient as is possible
    in delivering features. As such, considerable care is used by both
    language implementer and designers to make sure unused features do
    not impose hidden or unexpected costs. The GNU system tries to be
    as flexible and as configurable as possible. So, it should come as
    no surprise that GNU C++ provides an optional language extension,
    spelled <literal>-fno-exceptions</literal>, as a way to excise the
    implicitly generated magic necessary to
    support <literal>try</literal> and <literal>catch</literal> blocks
    and thrown objects. (Language support
    for <literal>-fno-exceptions</literal> is documented in the GCC
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options">manual</link>.)
  </para><para>Before detailing the library support
    for <literal>-fno-exceptions</literal>, first a passing note on
    the things lost when this flag is used: it will break exceptions
    trying to pass through code compiled
    with <literal>-fno-exceptions</literal> whether or not that code
    has any <literal>try</literal> or <literal>catch</literal>
    constructs. If you might have some code that throws, you shouldn't
    use <literal>-fno-exceptions</literal>. If you have some code that
    uses <literal>try</literal> or <literal>catch</literal>, you
    shouldn't use <literal>-fno-exceptions</literal>.
  </para><para>
    And what is to be gained, tinkering in the back alleys with a
    language like this? Exception handling overhead can be measured
    in the size of the executable binary, and varies with the
    capabilities of the underlying operating system and specific
    configuration of the C++ compiler. On recent hardware with GNU
    system software of the same age, the combined code and data size
    overhead for enabling exception handling is around 7%. Of course,
    if code size is of singular concern than using the appropriate
    optimizer setting with exception handling enabled
    (ie, <literal>-Os -fexceptions</literal>) may save up to twice
    that, and preserve error checking.
  </para><para>
    So. Hell bent, we race down the slippery track, knowing the brakes
    are a little soft and that the right front wheel has a tendency to
    wobble at speed. Go on: detail the standard library support
    for <literal>-fno-exceptions</literal>.
  </para><para>
    In sum, valid C++ code with exception handling is transformed into
    a dialect without exception handling. In detailed steps: all use
    of the C++
    keywords <literal>try</literal>, <literal>catch</literal>,
    and <literal>throw</literal> in the standard library have been
    permanently replaced with the pre-processor controlled equivalents
    spelled <literal>__try</literal>, <literal>__catch</literal>,
    and <literal>__throw_exception_again</literal>. They are defined
    as follows.
  </para><programlisting>
#if __cpp_exceptions
# define __try      try
# define __catch(X) catch(X)
# define __throw_exception_again throw
#else
# define __try      if (true)
# define __catch(X) if (false)
# define __throw_exception_again
#endif
</programlisting><para>
  In addition, for most of the classes derived from
  class <classname>exception</classname>, there exists a corresponding
  function with C language linkage. An example:
</para><programlisting>
#if __cpp_exceptions
  void __throw_bad_exception()
  { throw bad_exception(); }
#else
  void __throw_bad_exception()
  { abort(); }
#endif
</programlisting><para>
  The last language feature needing to be transformed
  by <literal>-fno-exceptions</literal> is treatment of exception
  specifications on member functions. Fortunately, the compiler deals
  with this by ignoring exception specifications and so no alternate
  source markup is needed.
</para><para>
  By using this combination of language re-specification by the
  compiler, and the pre-processor tricks and the functional
  indirection layer for thrown exception objects by the library,
  libstdc++ files can be compiled
  with <literal>-fno-exceptions</literal>.
</para><para>
 User code that uses C++ keywords
 like <literal>throw</literal>, <literal>try</literal>,
 and <literal>catch</literal> will produce errors even if the user
 code has included libstdc++ headers and is using constructs
 like <classname>basic_iostream</classname>. Even though the standard
 library has been transformed, user code may need modification. User
  code that attempts or expects to do error checking on standard
  library components compiled with exception handling disabled should
  be evaluated and potentially made conditional.
</para><para>
  Some issues remain with this approach (see bugzilla entry
  25191). Code paths are not equivalent, in
  particular <literal>catch</literal> blocks are not evaluated. Also
  problematic are <literal>throw</literal> expressions expecting a
  user-defined throw handler. Known problem areas in the standard
  library include using an instance
  of <classname>basic_istream</classname>
  with <function>exceptions</function> set to specific
  <type>ios_base::iostate</type> conditions, or
  cascading <literal>catch</literal> blocks that dispatch error
  handling or recovery efforts based on the type of exception object
  thrown.
</para><para>
  Oh, and by the way: none of this hackery is at all
  special. (Although perhaps well-deserving of a raised eyebrow.)
  Support continues to evolve and may change in the future. Similar
  and even additional techniques are used in other C++ libraries and
  compilers.
</para><para>
 C++ hackers with a bent for language and control-flow purity have
  been successfully consoled by grizzled C veterans lamenting the
  substitution of the C language keyword
  <literal>const</literal> with the uglified
  doppelganger <literal>__const</literal>.
</para></section><section xml:id="intro.using.exception.compat"><info><title>Compatibility</title></info><section xml:id="using.exception.compat.c"><info><title>With <literal>C</literal></title></info><para>
  C language code that is expecting to interoperate with C++ should be
  compiled with <literal>-fexceptions</literal>. This will make
  debugging a C language function called as part of C++-induced stack
  unwinding possible.
</para><para>
  In particular, unwinding into a frame with no exception handling
data will cause a runtime abort. If the unwinder runs out of unwind
info before it finds a handler, <function>std::terminate()</function>
is called.
</para><para>
  Please note that most development environments should take care of
  getting these details right. For GNU systems, all appropriate parts
  of the GNU C library are already compiled
  with <literal>-fexceptions</literal>.
</para></section><section xml:id="using.exception.compat.posix"><info><title>With <literal>POSIX</literal> thread cancellation</title></info><para>
  GNU systems re-use some of the exception handling mechanisms to
  track control flow for <literal>POSIX</literal> thread cancellation.
</para><para>
  Cancellation points are functions defined by POSIX as worthy of
  special treatment. The standard library may use some of these
  functions to implement parts of the ISO C++ standard or depend on
  them for extensions.
</para><para>
  Of note:
</para><para><function>nanosleep</function>,
  <function>read</function>, <function>write</function>, <function>open</function>, <function>close</function>,
  and <function>wait</function>.
</para><para>
  The parts of libstdc++ that use C library functions marked as
  cancellation points should take pains to be exception neutral.
  Failing this, <literal>catch</literal> blocks have been augmented to
  show that the POSIX cancellation object is in flight.
</para><para>
  This augmentation adds a <literal>catch</literal> block
  for <classname>__cxxabiv1::__forced_unwind</classname>, which is the
  object representing the POSIX cancellation object. Like so:
</para><programlisting>
  catch(const __cxxabiv1::__forced_unwind&amp;)
  {
    this-&gt;_M_setstate(ios_base::badbit);
    throw;
  }
  catch(...)
  { this-&gt;_M_setstate(ios_base::badbit); }
</programlisting></section></section><bibliography xml:id="using.exceptions.biblio"><info><title>Bibliography</title></info><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.opengroup.org/austin/">
	System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
	</link></title><pagenums>
      2.9.5 Thread Cancellation
    </pagenums><copyright><year>2008</year><holder>
	The Open Group/The Institute of Electrical and Electronics
	Engineers, Inc.
      </holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.boost.org/doc/libs/1_34_1/more/error_handling.html">
	Error and Exception Handling
	</link></title><author><personname><firstname>David</firstname><surname>Abrahams </surname></personname></author><publisher><publishername>
	Boost
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.boost.org/doc/user-guide/exception-safety.html">
	Exception-Safety in Generic Components
	</link></title><author><personname><firstname>David</firstname><surname>Abrahams</surname></personname></author><publisher><publishername>
	Boost
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf">
	Standard Library Exception Policy
	</link></title><author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author><publisher><publishername>
	WG21 N1077
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html">
	ia64 c++ abi exception handling
	</link></title><author><personname><firstname>Richard</firstname><surname>Henderson</surname></personname></author><publisher><publishername>
	GNU
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.stroustrup.com/3rd_safe.pdf">
	Appendix E: Standard-Library Exception Safety
	</link></title><author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author></biblioentry><biblioentry><citetitle>
      Exceptional C++
    </citetitle><pagenums>
      Exception-Safety Issues and Techniques
    </pagenums><author><personname><firstname>Herb</firstname><surname>Sutter</surname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR25191">
      GCC Bug 25191: exception_defines.h #defines try/catch
	</link></title></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/glibc/manual/latest/html_node/Tunables.html">
      Tunables, The GNU C Library
	</link></title></biblioentry></bibliography></section><!-- Section 0x : Debug --><section version="5.0" xreflabel="Debugging Support" xml:id="manual.intro.using.debug"><?dbhtml filename="debug.html"?><info><title>Debugging Support</title><keywordset><keyword>C++</keyword><keyword>debug</keyword></keywordset></info><para>
  There are numerous things that can be done to improve the ease with
  which C++ binaries are debugged when using the GNU tool chain. Here
  are some of them.
</para><section xml:id="debug.compiler"><info><title>Using <command>g++</command></title></info><para>
    Compiler flags determine how debug information is transmitted
    between compilation and debug or analysis tools.
  </para><para>
    The default optimizations and debug flags for a libstdc++ build
    are <code>-g -O2</code>. However, both debug and optimization
    flags can be varied to change debugging characteristics. For
    instance, turning off all optimization via the <code>-g -O0
    -fno-inline</code> flags will disable inlining and optimizations,
    and include debugging information, so that stepping through all functions,
    (including inlined constructors and destructors) is possible. In
    addition, <code>-fno-eliminate-unused-debug-types</code> can be
    used when additional debug information, such as nested class info,
    is desired.
</para><para>
  Or, the debug format that the compiler and debugger use to
  communicate information about source constructs can be changed via
  <code>-gdwarf-2</code> or <code>-gstabs</code> flags: some debugging
  formats permit more expressive type and scope information to be
  shown in GDB. Expressiveness can be enhanced by flags like
  <code>-g3</code>. The default debug information for a particular
  platform can be identified via the value set by the
  PREFERRED_DEBUGGING_TYPE macro in the GCC sources.
</para><para>
  Many other options are available: please see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
  for Debugging Your Program"</link> in Using the GNU Compiler
  Collection (GCC) for a complete list.
</para></section><section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info><para>
  The <link linkend="manual.ext.debug_mode">Debug Mode</link>
  has compile and run-time checks for many containers.
</para><para>
  There are also lightweight assertions for checking function preconditions,
  such as checking for out-of-bounds indices when accessing a
  <classname>std::vector</classname>. These can be enabled without using
  the full Debug Mode, by using <option>-D_GLIBCXX_ASSERTIONS</option>
  (see <xref linkend="manual.intro.using.macros"></xref>).
</para></section><section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info><para>
  The <link linkend="support.termination.verbose">verbose
  termination handler</link> gives information about uncaught
  exceptions which kill the program.
</para></section><section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info><para>
  On many targets GCC supports AddressSanitizer, a fast memory error detector,
  which is enabled by the <option>-fsanitize=address</option> option.
</para><para>
  The <classname>std::vector</classname> implementation has additional
  instrumentation to work with AddressSanitizer, but this has to be enabled
  explicitly by using <option>-D_GLIBCXX_SANITIZE_VECTOR</option>
  (see <xref linkend="manual.intro.using.macros"></xref>).
</para><para>
  There are also various third party memory tracing and debug utilities
  that can be used to provide detailed memory allocation information
  about C++ code. An exhaustive list of tools is not going to be
  attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
  <code>mudflap</code> (no longer supported since GCC 4.9.0), ElectricFence,
  and the non-free commercial product <code>purify</code>.
  In addition, <code>libcwd</code>, jemalloc and TCMalloc have replacements
  for the global <code>new</code> and <code>delete</code> operators
  that can track memory allocation and deallocation and provide useful
  memory statistics.
</para><para>
  For valgrind, there are some specific items to keep in mind. First
  of all, use a version of valgrind that will work with current GNU
  C++ tools: the first that can do this is valgrind 1.0.4, but later
  versions should work better. Second, using an unoptimized build
  might avoid confusing valgrind.
</para><para>
  Third, it may be necessary to force deallocation in other libraries
  as well, namely the "C" library. On GNU/Linux, this can be accomplished
  with the appropriate use of the <code>__cxa_atexit</code> or
  <code>atexit</code> functions.
</para><programlisting>
   #include &lt;cstdlib&gt;

   extern "C" void __libc_freeres(void);

   void do_something() { }

   int main()
   {
     atexit(__libc_freeres);
     do_something();
     return 0;
   }
</programlisting><para>or, using <code>__cxa_atexit</code>:</para><programlisting>
   extern "C" void __libc_freeres(void);
   extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);

   void do_something() { }

   int main()
   {
      extern void* __dso_handle __attribute__ ((__weak__));
      __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
		   &amp;__dso_handle ? __dso_handle : NULL);
      do_test();
      return 0;
   }
</programlisting><para>
  Suggested valgrind flags, given the suggestions above about setting
  up the runtime environment, library, and test file, might be:
</para><programlisting>
   valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
</programlisting><section xml:id="debug.memory.mtalloc"><info><title>Non-memory leaks in Pool and MT allocators</title></info><para>
  There are different kinds of allocation schemes that can be used by
  <code>std::allocator</code>. Prior to GCC 3.4.0 the default was to use
  a pooling allocator, <classname>pool_allocator</classname>,
  which is still available as the optional
  <classname>__pool_alloc</classname> extension.
  Another optional extension, <classname>__mt_alloc</classname>,
  is a high-performance pool allocator.
</para><para>
  In a suspect executable these pooling allocators can give
  the mistaken impression that memory is being leaked,
  when in reality the memory "leak" is a pool being used
  by the library's allocator and is reclaimed after program
  termination.
</para><para>
  If you're using memory debugging tools on a program that uses
  one of these pooling allocators, you can set the environment variable
  <literal>GLIBCXX_FORCE_NEW</literal> to keep extraneous pool allocation
  noise from cluttering debug information.
  For more details, see the
  <link linkend="manual.ext.allocator.mt">mt allocator</link>
  documentation and look specifically for <code>GLIBCXX_FORCE_NEW</code>.
</para></section></section><section xml:id="debug.races"><info><title>Data Race Hunting</title></info><para>
  All synchronization primitives used in the library internals need to be
  understood by race detectors so that they do not produce false reports.
</para><para>
  Two annotation macros are used to explain low-level synchronization
  to race detectors:
  <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
  <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
  By default, these macros are defined empty -- anyone who wants
  to use a race detector needs to redefine them to call an
  appropriate API.
  Since these macros are empty by default when the library is built,
  redefining them will only affect inline functions and template
  instantiations which are compiled in user code. This allows annotation
  of templates such as <code>shared_ptr</code>, but not code which is
  only instantiated in the library.  Code which is only instantiated in
  the library needs to be recompiled with the annotation macros defined.
  That can be done by rebuilding the entire
  <filename class="libraryfile">libstdc++.so</filename> file but a simpler
  alternative exists for ELF platforms such as GNU/Linux, because ELF
  symbol interposition allows symbols defined in the shared library to be
  overridden by symbols with the same name that appear earlier in the
  runtime search path. This means you only need to recompile the functions
  that are affected by the annotation macros, which can be done by
  recompiling individual files.
  Annotating <code>std::string</code> and <code>std::wstring</code>
  reference counting can be done by disabling extern templates (by defining
  <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
  <filename>src/string-inst.cc</filename> file.
  Annotating the remaining atomic operations (at the time of writing these
  are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code>,
  <code>locale::facet</code> and <code>thread::_M_start_thread</code>)
  requires rebuilding the relevant source files.
</para><para>
  The approach described above is known to work with the following race
  detection tools:
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://valgrind.org/docs/manual/drd-manual.html">
  DRD</link>,
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://valgrind.org/docs/manual/hg-manual.html">
  Helgrind</link>, and
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/google/sanitizers">
  ThreadSanitizer</link> (this refers to ThreadSanitizer v1, not the
  new "tsan" feature built-in to GCC itself).
</para><para>
  With DRD, Helgrind and ThreadSanitizer you will need to define
  the macros like this:
<programlisting>
  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A)  ANNOTATE_HAPPENS_AFTER(A)
</programlisting>
  Refer to the documentation of each particular tool for details.
</para></section><section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info><para>
  </para><para>
  Many options are available for GDB itself: please see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/gdb/current/onlinedocs/gdb">
  "GDB features for C++" </link> in the GDB documentation. Also
  recommended: the other parts of this manual.
</para><para>
  These settings can either be switched on in at the GDB command line,
  or put into a <filename>.gdbinit</filename> file to establish default
  debugging characteristics, like so:
</para><programlisting>
   set print pretty on
   set print object on
   set print static-members on
   set print vtbl on
   set print demangle on
   set demangle-style gnu-v3
</programlisting><para>
  Starting with version 7.0, GDB includes support for writing
  pretty-printers in Python.  Pretty printers for containers and other
  classes are distributed with GCC from version 4.5.0 and should be installed
  alongside the libstdc++ shared library files and found automatically by
  GDB.
</para><para>
  Depending where libstdc++ is installed, GDB might refuse to auto-load
  the python printers and print a warning instead.
  If this happens the python printers can be enabled by following the
  instructions GDB gives for setting your <code>auto-load safe-path</code>
  in your <filename>.gdbinit</filename> configuration file.
</para><para>
  Once loaded, standard library classes that the printers support
  should print in a more human-readable format.  To print the classes
  in the old style, use the <userinput>/r</userinput> (raw) switch in the
  print command (i.e., <userinput>print /r foo</userinput>).  This will
  print the classes as if the Python pretty-printers were not loaded.
</para><para>
  For additional information on STL support and GDB please visit:
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
  for STL" </link> in the GDB wiki.  Additionally, in-depth
  documentation and discussion of the pretty printing feature can be
  found in "Pretty Printing" node in the GDB manual.  You can find
  on-line versions of the GDB user manual in GDB's homepage, at
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/gdb/"> "GDB: The GNU Project
  Debugger" </link>.
</para></section><section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info><para>
  As described above, libstdc++ is built with debug symbols enabled by default,
  but because it's also built with optimizations the code can be hard to
  follow when stepping into the library in a debugger.
</para><para>
  If you would like to debug <filename>libstdc++.so</filename> itself,
  there are two ways to build an unoptimized libstdc++ with debug flags.
  The first is to create a separate debug build by running make from the
  top-level of a tree freshly-configured with
</para><programlisting>
     --enable-libstdcxx-debug
</programlisting><para>and perhaps</para><programlisting>
     --enable-libstdcxx-debug-flags='...'
</programlisting><para>
  Both the normal build and the debug build will persist, without
  having to specify <code>CXXFLAGS</code>, and the debug library will
  be installed in a separate directory tree, in <code>(prefix)/lib/debug</code>.
  For more information, look at the
  <link linkend="manual.intro.setup.configure">configuration</link> section.
</para><para>
  A second approach is to use the configuration flags
</para><programlisting>
     make CXXFLAGS='-g3 -fno-inline -O0' all
</programlisting></section><section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info><para> The <link linkend="manual.ext.compile_checks">Compile-Time
  Checks</link> extension has compile-time checks for many algorithms.
  These checks were designed for C++98 and have not been updated to work
  with C++11 and later standards. They might be removed at a future date.
  </para></section></section></chapter></part><!-- Part 02 : Standard Contents --><part xreflabel="Standard Contents" xml:id="manual.std"><info><title>
    Standard Contents
  </title></info><?dbhtml filename="std_contents.html"?><!-- Chapter 01 : Support --><chapter version="5.0" xreflabel="Support" xml:id="std.support"><?dbhtml filename="support.html"?><info><title>
  Support
  <indexterm><primary>Support</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><para>
    This part deals with the functions called and objects created
    automatically during the course of a program's existence.
  </para><para>
    While we can't reproduce the contents of the Standard here (you
    need to get your own copy from your nation's member body; see our
    homepage for help), we can mention a couple of changes in what
    kind of support a C++ program gets from the Standard Library.
  </para><section xreflabel="Types" xml:id="std.support.types"><info><title>Types</title></info><?dbhtml filename="fundamental_types.html"?><section xreflabel="Fundamental Types" xml:id="std.support.types.fundamental"><info><title>Fundamental Types</title></info><para>
      C++ has the following builtin types:
    </para><itemizedlist><listitem><para>
	char
      </para></listitem><listitem><para>
	signed char
      </para></listitem><listitem><para>
	unsigned char
      </para></listitem><listitem><para>
	signed short
      </para></listitem><listitem><para>
	signed int
      </para></listitem><listitem><para>
	signed long
      </para></listitem><listitem><para>
	unsigned short
      </para></listitem><listitem><para>
	unsigned int
      </para></listitem><listitem><para>
	unsigned long
      </para></listitem><listitem><para>
	bool
      </para></listitem><listitem><para>
	wchar_t
      </para></listitem><listitem><para>
	float
      </para></listitem><listitem><para>
	double
      </para></listitem><listitem><para>
	long double
      </para></listitem></itemizedlist><para>
      These fundamental types are always available, without having to
      include a header file. These types are exactly the same in
      either C++ or in C.
    </para><para>
      Specializing parts of the library on these types is prohibited:
      instead, use a POD.
    </para></section><section xreflabel="Numeric Properties" xml:id="std.support.types.numeric_limits"><info><title>Numeric Properties</title></info><para>
    The header <filename class="headerfile">&lt;limits&gt;</filename> defines
    traits classes to give access to various implementation
    defined-aspects of the fundamental types. The traits classes --
    fourteen in total -- are all specializations of the class template
    <classname>numeric_limits</classname>
    and defined as follows:
    </para><programlisting>
   template&lt;typename T&gt;
     struct class
     {
       static const bool is_specialized;
       static T max() throw();
       static T min() throw();

       static const int digits;
       static const int digits10;
       static const bool is_signed;
       static const bool is_integer;
       static const bool is_exact;
       static const int radix;
       static T epsilon() throw();
       static T round_error() throw();

       static const int min_exponent;
       static const int min_exponent10;
       static const int max_exponent;
       static const int max_exponent10;

       static const bool has_infinity;
       static const bool has_quiet_NaN;
       static const bool has_signaling_NaN;
       static const float_denorm_style has_denorm;
       static const bool has_denorm_loss;
       static T infinity() throw();
       static T quiet_NaN() throw();
       static T denorm_min() throw();

       static const bool is_iec559;
       static const bool is_bounded;
       static const bool is_modulo;

       static const bool traps;
       static const bool tinyness_before;
       static const float_round_style round_style;
     };
</programlisting></section><section xreflabel="NULL" xml:id="std.support.types.null"><info><title>NULL</title></info><para>
     The only change that might affect people is the type of
     <constant>NULL</constant>: while it is required to be a macro,
     the definition of that macro is <emphasis>not</emphasis> allowed
     to be an expression with pointer type such as
     <constant>(void*)0</constant>, which is often used in C.
    </para><para>
     For <command>g++</command>, <constant>NULL</constant> is
     <code>#define</code>'d to be
     <constant>__null</constant>, a magic keyword extension of
     <command>g++</command> that is slightly safer than a plain integer.
    </para><para>
     The biggest problem of #defining <constant>NULL</constant> to be
     something like <quote>0L</quote> is that the compiler will view
     that as a long integer before it views it as a pointer, so
     overloading won't do what you expect. It might not even have the
     same size as a pointer, so passing <constant>NULL</constant> to a
     varargs function where a pointer is expected might not even work
     correctly if <code>sizeof(NULL) &lt; sizeof(void*)</code>.
     The G++ <constant>__null</constant> extension is defined so that
     <code>sizeof(__null) == sizeof(void*)</code> to avoid this problem.
    </para><para>
     Scott Meyers explains this in more detail in his book
     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.aristeia.com/books.html"><emphasis>Effective
     Modern C++</emphasis></link> and as a guideline to solve this problem
     recommends to not overload on pointer-vs-integer types to begin with.
    </para><para>
     The C++ 2011 standard added the <constant>nullptr</constant> keyword,
     which is a null pointer constant of a special type,
     <classname>std::nullptr_t</classname>. Values of this type can be
     implicitly converted to <emphasis>any</emphasis> pointer type,
     and cannot convert to integer types or be deduced as an integer type.
     Unless you need to be compatible with C++98/C++03 or C you should prefer
     to use <constant>nullptr</constant>  instead of <constant>NULL</constant>.
    </para></section></section><section xreflabel="Dynamic Memory" xml:id="std.support.memory"><info><title>Dynamic Memory</title></info><?dbhtml filename="dynamic_memory.html"?><para>
    In C++98 there are six flavors each of <function>operator new</function>
    and <function>operator delete</function>, so make certain that you're
    using the right ones.
    Here are quickie descriptions of <function>operator new</function>:
  </para><variablelist><varlistentry><term><code>void* operator new(std::size_t);</code></term><listitem>
	Single object form.
        Throws <classname>std::bad_alloc</classname> on error.
        This is what most people are used to using.
      </listitem></varlistentry><varlistentry><term><code>void* operator new(std::size_t, std::nothrow_t) noexcept;</code></term><listitem>
	Single object <quote>nothrow</quote> form.
        Calls <code>operator new(std::size_t)</code> but if that throws,
        returns a null pointer instead.
      </listitem></varlistentry><varlistentry><term><code>void* operator new[](std::size_t);</code></term><listitem>
	Array <function>new</function>.
        Calls <code>operator new(std::size_t)</code> and so
	throws <classname>std::bad_alloc</classname> on error.
      </listitem></varlistentry><varlistentry><term><code>void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></term><listitem>
	Array <quote>nothrow</quote> <function>new</function>.
        Calls <code>operator new[](std::size_t)</code> but if that throws,
        returns a null pointer instead.
      </listitem></varlistentry><varlistentry><term><code>void* operator new(std::size_t, void*) noexcept;</code></term><listitem>
	Non-allocating, <quote>placement</quote> single-object <function>new</function>,
        which does nothing except return its argument.
        This function cannot be replaced.
      </listitem></varlistentry><varlistentry><term><code>void* operator new[](std::size_t, void*) noexcept;</code></term><listitem>
	Non-allocating, <quote>placement</quote> array <function>new</function>,
        which also does nothing except return its argument.
        This function cannot be replaced.
      </listitem></varlistentry></variablelist><para>
     They are distinguished by the arguments that you pass to them, like
     any other overloaded function.  The six flavors of
     <function>operator delete</function>
     are distinguished the same way, but none of them are allowed to throw
     an exception under any circumstances anyhow.  (The overloads match up
     with the ones above, for completeness' sake.)
   </para><para>
     The C++ 2014 revision of the standard added two additional overloads of
     <function>operator delete</function> for <quote>sized deallocation</quote>,
     allowing the compiler to provide the size of the storage being freed.
   </para><para>
     The C++ 2017 standard added even more overloads of both
     <function>operator new</function> and <function>operator delete</function>
     for allocating and deallocating storage for overaligned types.
     These overloads correspond to each of the allocating forms of
     <function>operator new</function> and <function>operator delete</function>
     but with an additional parameter of type <type>std::align_val_t</type>.
     These new overloads are not interchangeable with the versions without
     an aligment parameter, so if memory was allocated by an overload of
     <function>operator new</function> taking an alignment parameter,
     then it must be decallocated by the corresponding overload of
     <function>operator delete</function> that takes an alignment parameter.
   </para><para>
     Apart from the non-allocating forms, the default versions of the array
     and nothrow <function>operator new</function> functions will all result
     in a call to either <function>operator new(std::size_t)</function> or
     <function>operator new(std::size_t, std::align_val_t)</function>,
     and similarly the default versions of the array and nothrow
     <function>operator delete</function> functions will result in a call to
     either <function>operator delete(void*)</function> or
     <function>operator delete(void*, std::align_val_t)</function>
     (or the sized versions of those).
   </para><para>
     Apart from the non-allocating forms, any of these functions can be
     replaced by defining a function with the same signature in your program.
     Replacement versions must preserve certain guarantees, such as memory
     obtained from a nothrow <function>operator new</function> being free-able
     by the normal (non-nothrow) <function>operator delete</function>,
     and the sized and unsized forms of <function>operator delete</function>
     being interchangeable (because it's unspecified whether
     the compiler calls the sized delete instead of the normal one).
     The simplest way to meet the guarantees is to only replace the ordinary
     <function>operator new(size_t)</function> and
     <function>operator delete(void*)</function> and
     <function>operator delete(void*, std::size_t)</function>
     functions, and the replaced versions will be used by all of
     <function>operator new(size_t, nothrow_t)</function>,
     <function>operator new[](size_t)</function> and
     <function>operator new[](size_t, nothrow_t)</function>
     and the corresponding <function>operator delete</function> functions.
     To support types with extended alignment you may also need to replace
     <function>operator new(size_t, align_val_t)</function> and
     <function>operator delete(void*, align_val_t)</function>
     <function>operator delete(void*, size_t, align_val_t)</function>
     (which will then be used by the nothrow and array forms for
     extended alignments).
     If you do need to replace other forms (e.g. to define the nothrow
     <function>operator new</function> to allocate memory directly, so it
     works with exceptions disabled) then make sure the memory it allocates
     can still be freed by the non-nothrow forms of
     <function>operator delete</function>.
   </para><para>
     If the default versions of <function>operator new(std::size_t)</function>
     and <function>operator new(size_t, std::align_val_t)</function>
     can't allocate the memory requested, they usually throw an exception
     object of type <classname>std::bad_alloc</classname> (or some class
     derived from that). However, the program can influence that behavior
     by registering a <quote>new-handler</quote>, because what
     <function>operator new</function> actually does is something like:
   </para><programlisting>
    while (true)
    {
      if (void* p = /* try to allocate memory */)
        return p;
      else if (std::new_handler h = std::get_new_handler ())
        h ();
      else
        throw bad_alloc{};
    }
</programlisting><para>
     This means you can influence what happens on allocation failure by
     writing your own new-handler and then registering it with
     <function>std::set_new_handler</function>:
   </para><programlisting>
   typedef void (*PFV)();

   static char*  safety;
   static PFV    old_handler;

   void my_new_handler ()
   {
       delete[] safety;
       safety = nullptr;
       popup_window ("Dude, you are running low on heap memory.  You"
		     " should, like, close some windows, or something."
		     " The next time you run out, we're gonna burn!");
       set_new_handler (old_handler);
       return;
   }

   int main ()
   {
       safety = new char[500000];
       old_handler = set_new_handler (&amp;my_new_handler);
       ...
   }
</programlisting><section xreflabel="Dynamic Memory Notes" xml:id="std.support.memory.notes"><info><title>Additional Notes</title></info><para>
     Remember that it is perfectly okay to <function>delete</function> a
     null pointer!  Nothing happens, by definition.  That is not the
     same thing as deleting a pointer twice.
   </para><para><classname>std::bad_alloc</classname> is derived from the base
     <classname>std::exception</classname> class,
     see <xref linkend="std.diagnostics.exceptions"></xref>.
   </para></section></section><section xreflabel="Termination" xml:id="std.support.termination"><info><title>Termination</title></info><?dbhtml filename="termination.html"?><section xreflabel="Termination Handlers" xml:id="support.termination.handlers"><info><title>Termination Handlers</title></info><para>
      Not many changes here to
      <filename class="headerfile">&lt;cstdlib&gt;</filename>.
      You should note that the
      <function>abort()</function> function does not call the
      destructors of automatic nor static objects, so if you're
      depending on those to do cleanup, it isn't going to happen.
      (The functions registered with <function>atexit()</function>
      don't get called either, so you can forget about that
      possibility, too.)
    </para><para>
      The good old <function>exit()</function> function can be a bit
      funky, too, until you look closer.  Basically, three points to
      remember are:
    </para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>
	Static objects are destroyed in reverse order of their creation.
	</para></listitem><listitem><para>
	Functions registered with <function>atexit()</function> are called in
	reverse order of registration, once per registration call.
	(This isn't actually new.)
	</para></listitem><listitem><para>
	The previous two actions are <quote>interleaved,</quote> that is,
	given this pseudocode:
	</para><programlisting>
  extern "C or C++" void f1 ();
  extern "C or C++" void f2 ();

  static Thing obj1;
  atexit(f1);
  static Thing obj2;
  atexit(f2);
</programlisting><para>
	then at a call of <function>exit()</function>,
	<varname>f2</varname> will be called, then
	<varname>obj2</varname> will be destroyed, then
	<varname>f1</varname> will be called, and finally
	<varname>obj1</varname> will be destroyed. If
	<varname>f1</varname> or <varname>f2</varname> allow an
	exception to propagate out of them, Bad Things happen.
	</para></listitem></orderedlist><para>
      Note also that <function>atexit()</function> is only required to store 32
      functions, and the compiler/library might already be using some of
      those slots.  If you think you may run out, we recommend using
      the <function>xatexit</function>/<function>xexit</function> combination
      from <literal>libiberty</literal>, which has no such limit.
    </para></section><section xreflabel="Verbose Terminate Handler" xml:id="support.termination.verbose"><info><title>Verbose Terminate Handler</title></info><?dbhtml filename="verbose_termination.html"?><para>
      If you are having difficulty with uncaught exceptions and want a
      little bit of help debugging the causes of the core dumps, you can
      make use of a GNU extension, the verbose terminate handler.
    </para><para>
      The verbose terminate handler is only available for hosted environments
      (see <xref linkend="manual.intro.setup.configure"></xref>) and will be used
      by default unless the library is built with
      <option>--disable-libstdcxx-verbose</option>
      or with exceptions disabled.
      If you need to enable it explicitly you can do so by calling the
      <function>std::set_terminate</function> function.
    </para><programlisting>
#include &lt;exception&gt;

int main()
{
  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
  ...

  throw <replaceable>anything</replaceable>;
}
</programlisting><para>
     The <function>__verbose_terminate_handler</function> function
     obtains the name of the current exception, attempts to demangle
     it, and prints it to <literal>stderr</literal>.
     If the exception is derived from
     <classname>std::exception</classname> then the output from
     <function>what()</function> will be included.
   </para><para>
     Any replacement termination function is required to kill the
     program without returning; this one calls <function>std::abort</function>.
   </para><para>
     For example:
   </para><programlisting>
#include &lt;exception&gt;
#include &lt;stdexcept&gt;

struct argument_error : public std::runtime_error
{
  argument_error(const std::string&amp; s): std::runtime_error(s) { }
};

int main(int argc)
{
  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
  if (argc &gt; 5)
    throw argument_error("argc is greater than 5!");
  else
    throw argc;
}
</programlisting><para>
     With the verbose terminate handler active, this gives:
   </para><screen><computeroutput>
   % ./a.out
   terminate called after throwing a `int'
   Aborted
   % ./a.out f f f f f f f f f f f
   terminate called after throwing an instance of `argument_error'
   what(): argc is greater than 5!
   Aborted
   </computeroutput></screen><para>
     The 'Aborted' line is printed by the shell after the process exits
     by calling <function>abort()</function>.
   </para><para>
     As this is the default termination handler, nothing need be done to
     use it.  To go back to the previous <quote>silent death</quote>
     method, simply include
     <filename class="headerfile">&lt;exception&gt;</filename> and
     <filename class="headerfile">&lt;cstdlib&gt;</filename>, and call
   </para><programlisting>
     std::set_terminate(std::abort);
</programlisting><para>
     After this, all calls to <function>terminate</function> will use
     <function>abort</function> as the terminate handler.
   </para><para>
     Note: the verbose terminate handler will attempt to write to
     <literal>stderr</literal>.  If your application closes
     <literal>stderr</literal> or redirects it to an inappropriate location,
     <function>__verbose_terminate_handler</function> will behave in
     an unspecified manner.
   </para></section></section></chapter><!-- Chapter 02 : Diagnostics --><chapter version="5.0" xreflabel="Diagnostics" xml:id="std.diagnostics"><?dbhtml filename="diagnostics.html"?><info><title>
  Diagnostics
  <indexterm><primary>Diagnostics</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><section xreflabel="Exceptions" xml:id="std.diagnostics.exceptions"><info><title>Exceptions</title></info><?dbhtml filename="exceptions.html"?><section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info><para>
      Most exception classes are defined in one of the standard headers
      <filename class="headerfile">&lt;exception&gt;</filename>,
      <filename class="headerfile">&lt;stdexcept&gt;</filename>,
      <filename class="headerfile">&lt;new&gt;</filename>, and
      <filename class="headerfile">&lt;typeinfo&gt;</filename>.
      The C++ 2011 revision of the standard added more exception types
      in the headers
      <filename class="headerfile">&lt;functional&gt;</filename>,
      <filename class="headerfile">&lt;future&gt;</filename>,
      <filename class="headerfile">&lt;regex&gt;</filename>, and
      <filename class="headerfile">&lt;system_error&gt;</filename>.
      The C++ 2017 revision of the standard added more exception types
      in the headers
      <filename class="headerfile">&lt;any&gt;</filename>,
      <filename class="headerfile">&lt;filesystem&gt;</filename>,
      <filename class="headerfile">&lt;optional&gt;</filename>, and
      <filename class="headerfile">&lt;variant&gt;</filename>.
    </para><para>
      All exceptions thrown by the library have a base class of type
      <classname>std::exception</classname>,
      defined in <filename class="headerfile">&lt;exception&gt;</filename>.
      This type has no <classname>std::string</classname> member.
    </para><para>
      Derived from this are several classes that may have a
      <classname>std::string</classname> member. A full hierarchy can be
      found in the source documentation.
    </para><!-- Doxygen XML: api/group__exceptions.xml --></section><section xreflabel="Adding Data to Exceptions" xml:id="std.diagnostics.exceptions.data"><info><title>Adding Data to <classname>exception</classname></title></info><para>
      The standard exception classes carry with them a single string as
      data (usually describing what went wrong or where the 'throw' took
    place).  It's good to remember that you can add your own data to
    these exceptions when extending the hierarchy:
   </para><programlisting>
   struct My_Exception : public std::runtime_error
   {
     public:
       My_Exception (const string&amp; whatarg)
	   : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
       int  errno_at_time_of_throw() const { return e; }
       DBID id_of_thing_that_threw() const { return id; }
     protected:
       int    e;
       DBID   id;     // some user-defined type
   };
</programlisting></section></section><section xreflabel="errno" xml:id="std.diagnostics.errno"><info><title>Use of errno by the library</title></info><?dbhtml filename="errno.html"?><para>
    The C and POSIX standards guarantee that <varname>errno</varname>
    is never set to zero by any library function.
    The C++ standard has less to say about when <varname>errno</varname>
    is or isn't set, but libstdc++ follows the same rule and never sets
    it to zero.
  </para><para>
    On the other hand, there are few guarantees about when the C++ library
    sets <varname>errno</varname> on error, beyond what is specified for
    functions that come from the C library.
    For example, when <function>std::stoi</function> throws an exception of
    type <classname>std::out_of_range</classname>, <varname>errno</varname>
    may or may not have been set to <constant>ERANGE</constant>.
  </para><para>
    Parts of the C++ library may be implemented in terms of C library
    functions, which may result in <varname>errno</varname> being set
    with no explicit call to a C function. For example, on a target where
    <function>operator new</function> uses <function>malloc</function>
    a failed memory allocation with <function>operator new</function> might
    set <varname>errno</varname> to <constant>ENOMEM</constant>.
    Which C++ library functions can set <varname>errno</varname> in this way
    is unspecified because it may vary between platforms and between releases.
  </para></section><section xreflabel="Concept Checking" xml:id="std.diagnostics.concept_checking"><info><title>Concept Checking</title></info><?dbhtml filename="concept_checking.html"?><para>
    In 1999, SGI added <quote>concept checkers</quote> to their
    implementation of the STL: code which checked the template
    parameters of instantiated pieces of the STL, in order to insure
    that the parameters being used met the requirements of the
    standard.  For example, the Standard requires that types passed as
    template parameters to <classname>vector</classname> be
    "Assignable" (which means what you think it means).  The
    checking was done during compilation, and none of the code was
    executed at runtime.
   </para><para>
     Unfortunately, the size of the compiler files grew significantly
     as a result.  The checking code itself was cumbersome.  And bugs
     were found in it on more than one occasion.
   </para><para>
     The primary author of the checking code, Jeremy Siek, had already
     started work on a replacement implementation.  The new code was
     formally reviewed and accepted into
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
   Boost libraries</link>, and we are pleased to incorporate it into the
   GNU C++ library.
 </para><para>
   The new version imposes a much smaller space overhead on the generated
   object file.  The checks are also cleaner and easier to read and
   understand.
 </para><para>
   They are off by default for all versions of GCC.
   They can be enabled at configure time with
   <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
   You can enable them on a per-translation-unit basis with
     <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>.
 </para><para>
   Please note that the checks are based on the requirements in the original
   C++ standard, many of which were relaxed in the C++11 standard and so valid
   C++11 code may be incorrectly rejected by the concept checks.  Additionally,
   some correct C++03 code might be rejected by the concept checks,
   for example template argument types may need to be complete when used in
   a template definition, rather than at the point of instantiation.
   There are no plans to address these shortcomings.
 </para></section></chapter><!-- Chapter 03 : Utilities --><chapter version="5.0" xreflabel="Utilities" xml:id="std.util"><?dbhtml filename="utilities.html"?><info><title>
  Utilities
  <indexterm><primary>Utilities</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Section 01 : Functors --><section xreflabel="Functors" xml:id="std.util.functors"><info><title>Functors</title></info><?dbhtml filename="functors.html"?><para>If you don't know what functors are, you're not alone.  Many people
      get slightly the wrong idea.  In the interest of not reinventing
      the wheel, we will refer you to the introduction to the functor
      concept written by SGI as part of their STL, in
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171209002754/http://www.sgi.com/tech/stl/functors.html">their
      https://web.archive.org/web/20171209002754/http://www.sgi.com/tech/stl/functors.html</link>.
   </para></section><!-- Section 02 : Pairs --><section xreflabel="Pairs" xml:id="std.util.pairs"><info><title>Pairs</title></info><?dbhtml filename="pairs.html"?><para>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to
      carry around a pair of objects.  One is of type T1, and another of
      type T2; they may be the same type, but you don't get anything
      extra if they are.  The two members can be accessed directly, as
      <code>.first</code> and <code>.second</code>.
   </para><para>Construction is simple.  The default ctor initializes each member
      with its respective default ctor.  The other simple ctor,
   </para><programlisting>
    pair (const T1&amp; x, const T2&amp; y);
</programlisting><para>does what you think it does, <code>first</code> getting <code>x</code>
      and <code>second</code> getting <code>y</code>.
   </para><para>There is a constructor template for copying pairs of other types:
   </para><programlisting>
    template &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; p);
</programlisting><para>The compiler will convert as necessary from U to T1 and from
      V to T2 in order to perform the respective initializations.
   </para><para>The comparison operators are done for you.  Equality
      of two <code>pair&lt;T1,T2&gt;</code>s is defined as both <code>first</code>
      members comparing equal and both <code>second</code> members comparing
      equal; this simply delegates responsibility to the respective
      <code>operator==</code> functions (for types like MyClass) or builtin
      comparisons (for types like int, char, etc).
   </para><para>
      The less-than operator is a bit odd the first time you see it.  It
      is defined as evaluating to:
   </para><programlisting>
    x.first  &lt;  y.first  ||
	( !(y.first  &lt;  x.first)  &amp;&amp;  x.second  &lt;  y.second )
</programlisting><para>The other operators are not defined using the <code>rel_ops</code>
      functions above, but their semantics are the same.
   </para><para>Finally, there is a template function called <function>make_pair</function>
      that takes two references-to-const objects and returns an
      instance of a pair instantiated on their respective types:
   </para><programlisting>
    pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</programlisting></section><!-- Section 03 : Memory --><section xreflabel="Memory" xml:id="std.util.memory"><info><title>Memory</title></info><?dbhtml filename="memory.html"?><para>
    Memory contains three general areas. First, function and operator
    calls via <function>new</function> and <function>delete</function>
    operator or member function calls.  Second, allocation via
    <classname>allocator</classname>. And finally, smart pointer and
    intelligent pointer abstractions.
  </para><!--  Section 01 : allocator --><section version="5.0" xreflabel="Allocator" xml:id="std.util.memory.allocator"><?dbhtml filename="allocator.html"?><info><title>Allocators</title><keywordset><keyword>ISO C++</keyword><keyword>allocator</keyword></keywordset></info><para>
 Memory management for Standard Library entities is encapsulated in a
 class template called <classname>allocator</classname>. The
 <classname>allocator</classname> abstraction is used throughout the
 library in <classname>string</classname>, container classes,
 algorithms, and parts of iostreams. This class, and base classes of
 it, are the superset of available free store (<quote>heap</quote>)
 management classes.
</para><section xml:id="allocator.req"><info><title>Requirements</title></info><para>
    The C++ standard only gives a few directives in this area:
  </para><itemizedlist><listitem><para>
       When you add elements to a container, and the container must
       allocate more memory to hold them, the container makes the
       request via its <type>Allocator</type> template
       parameter, which is usually aliased to
       <type>allocator_type</type>.  This includes adding chars
       to the string class, which acts as a regular STL container in
       this respect.
      </para></listitem><listitem><para>
       The default <type>Allocator</type> argument of every
       container-of-T is <classname>allocator&lt;T&gt;</classname>.
       </para></listitem><listitem><para>
       The interface of the <classname>allocator&lt;T&gt;</classname> class is
	 extremely simple.  It has about 20 public declarations (nested
	 typedefs, member functions, etc), but the two which concern us most
	 are:
       </para><programlisting>
	 T*    allocate   (size_type n, const void* hint = 0);
	 void  deallocate (T* p, size_type n);
</programlisting><para>
	 The <varname>n</varname> arguments in both those
	 functions is a <emphasis>count</emphasis> of the number of
	 <type>T</type>'s to allocate space for, <emphasis>not their
	 total size</emphasis>.
	 (This is a simplification; the real signatures use nested typedefs.)
       </para></listitem><listitem><para>
	 The storage is obtained by calling <function>::operator
	 new</function>, but it is unspecified when or how
	 often this function is called.  The use of the
	 <varname>hint</varname> is unspecified, but intended as an
	 aid to locality if an implementation so
	 desires. <constant>[20.4.1.1]/6</constant>
       </para></listitem></itemizedlist><para>
     Complete details can be found in the C++ standard, look in
     <constant>[20.4 Memory]</constant>.
   </para></section><section xml:id="allocator.design_issues"><info><title>Design Issues</title></info><para>
    The easiest way of fulfilling the requirements is to call
    <function>operator new</function> each time a container needs
    memory, and to call <function>operator delete</function> each time
    the container releases memory. This method may be <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</link>
    than caching the allocations and re-using previously-allocated
    memory, but has the advantage of working correctly across a wide
    variety of hardware and operating systems, including large
    clusters. The <classname>__gnu_cxx::new_allocator</classname>
    implements the simple operator new and operator delete semantics,
    while <classname>__gnu_cxx::malloc_allocator</classname>
    implements much the same thing, only with the C language functions
    <function>std::malloc</function> and <function>std::free</function>.
  </para><para>
    Another approach is to use intelligence within the allocator
    class to cache allocations. This extra machinery can take a variety
    of forms: a bitmap index, an index into an exponentially increasing
    power-of-two-sized buckets, or simpler fixed-size pooling cache.
    The cache is shared among all the containers in the program: when
    your program's <classname>std::vector&lt;int&gt;</classname> gets
  cut in half and frees a bunch of its storage, that memory can be
  reused by the private
  <classname>std::list&lt;WonkyWidget&gt;</classname> brought in from
  a KDE library that you linked against.  And operators
  <function>new</function> and <function>delete</function> are not
  always called to pass the memory on, either, which is a speed
  bonus. Examples of allocators that use these techniques are
  <classname>__gnu_cxx::bitmap_allocator</classname>,
  <classname>__gnu_cxx::pool_allocator</classname>, and
  <classname>__gnu_cxx::__mt_alloc</classname>.
  </para><para>
    Depending on the implementation techniques used, the underlying
    operating system, and compilation environment, scaling caching
    allocators can be tricky. In particular, order-of-destruction and
    order-of-creation for memory pools may be difficult to pin down
    with certainty, which may create problems when used with plugins
    or loading and unloading shared objects in memory. As such, using
    caching allocators on systems that do not support
    <function>abi::__cxa_atexit</function> is not recommended.
  </para></section><section xml:id="allocator.impl"><info><title>Implementation</title></info><section xml:id="allocator.interface"><info><title>Interface Design</title></info><para>
     The only allocator interface that
     is supported is the standard C++ interface. As such, all STL
     containers have been adjusted, and all external allocators have
     been modified to support this change.
   </para><para>
     The class <classname>allocator</classname> just has typedef,
   constructor, and rebind members. It inherits from one of the
   high-speed extension allocators, covered below. Thus, all
   allocation and deallocation depends on the base class.
   </para><para>
     The choice of base class that <classname>allocator</classname>
     is derived from is fixed at the time when GCC is built,
     and the different choices are not ABI compatible.
</para></section><section xml:id="allocator.default"><info><title>Selecting Default Allocation Policy</title></info><para>
     It's difficult to pick an allocation strategy that will provide
   maximum utility, without excessively penalizing some behavior. In
   fact, it's difficult just deciding which typical actions to measure
   for speed.
   </para><para>
     Three synthetic benchmarks have been created that provide data
     that is used to compare different C++ allocators. These tests are:
   </para><orderedlist><listitem><para>
       Insertion.
       </para><para>
       Over multiple iterations, various STL container
     objects have elements inserted to some maximum amount. A variety
     of allocators are tested.
     Test source for <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert/sequence.cc">sequence</link>
     and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert/associative.cc">associative</link>
     containers.
       </para></listitem><listitem><para>
       Insertion and erasure in a multi-threaded environment.
       </para><para>
       This test shows the ability of the allocator to reclaim memory
     on a per-thread basis, as well as measuring thread contention
     for memory resources.
     Test source
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert_erase/associative.cc">here</link>.
       </para></listitem><listitem><para>
	 A threaded producer/consumer model.
       </para><para>
       Test source for
     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc">sequence</link>
     and
     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc">associative</link>
     containers.
     </para></listitem></orderedlist><para>
     Since GCC 12 the default choice for
     <classname>allocator</classname> is
     <classname>std::__new_allocator</classname>.
     Before GCC 12 it was the <classname>__gnu_cxx::new_allocator</classname>
     extension (which has identical behaviour).
   </para></section><section xml:id="allocator.caching"><info><title>Disabling Memory Caching</title></info><para>
      In use, <classname>allocator</classname> may allocate and
      deallocate using implementation-specific strategies and
      heuristics. Because of this, a given call to an allocator object's
      <function>allocate</function> member function may not actually
      call the global <code>operator new</code> and a given call to
      to the <function>deallocate</function> member function may not
      call <code>operator delete</code>.
    </para><para>
     This can be confusing.
   </para><para>
     In particular, this can make debugging memory errors more
     difficult, especially when using third-party tools like valgrind or
     debug versions of <function>new</function>.
   </para><para>
     There are various ways to solve this problem. One would be to use
     a custom allocator that just called operators
     <function>new</function> and <function>delete</function>
     directly, for every allocation. (See the default allocator,
     <filename>include/ext/new_allocator.h</filename>, for instance.)
     However, that option may involve changing source code to use
     a non-default allocator. Another option is to force the
     default allocator to remove caching and pools, and to directly
     allocate with every call of <function>allocate</function> and
     directly deallocate with every call of
     <function>deallocate</function>, regardless of efficiency. As it
     turns out, this last option is also available.
   </para><para>
     To globally disable memory caching within the library for some of
     the optional non-default allocators, merely set
     <constant>GLIBCXX_FORCE_NEW</constant> (with any value) in the
     system's environment before running the program. If your program
     crashes with <constant>GLIBCXX_FORCE_NEW</constant> in the
     environment, it likely means that you linked against objects
     built against the older library (objects which might still using the
     cached allocations...).
  </para></section></section><section xml:id="allocator.using"><info><title>Using a Specific Allocator</title></info><para>
     You can specify different memory management schemes on a
     per-container basis, by overriding the default
     <type>Allocator</type> template parameter.  For example, an easy
      (but non-portable) method of specifying that only <function>malloc</function> or <function>free</function>
      should be used instead of the default node allocator is:
   </para><programlisting>
    std::list &lt;int, __gnu_cxx::malloc_allocator&lt;int&gt; &gt;  malloc_list;</programlisting><para>
      Likewise, a debugging form of whichever allocator is currently in use:
    </para><programlisting>
    std::deque &lt;int, __gnu_cxx::debug_allocator&lt;std::allocator&lt;int&gt; &gt; &gt;  debug_deque;
</programlisting></section><section xml:id="allocator.custom"><info><title>Custom Allocators</title></info><para>
    Writing a portable C++ allocator would dictate that the interface
    would look much like the one specified for
    <classname>allocator</classname>. Additional member functions, but
    not subtractions, would be permissible.
  </para><para>
     Probably the best place to start would be to copy one of the
   extension allocators: say a simple one like
   <classname>new_allocator</classname>.
   </para><para>
     Since C++11 the minimal interface require for an allocator is
     much smaller, as <classname>std::allocator_traits</classname>
     can provide default for much of the interface.
   </para></section><section xml:id="allocator.ext"><info><title>Extension Allocators</title></info><para>
    Several other allocators are provided as part of this
    implementation.  The location of the extension allocators and their
    names have changed, but in all cases, functionality is
    equivalent. Starting with gcc-3.4, all extension allocators are
    standard style. Before this point, SGI style was the norm. Because of
    this, the number of template arguments also changed.
    <xref linkend="table.extension_allocators"></xref> tracks the changes.
  </para><para>
    More details on each of these extension allocators follows.
  </para><orderedlist><listitem><para><classname>new_allocator</classname></para><para>
	 Simply wraps <function>::operator new</function>
	 and <function>::operator delete</function>.
       </para></listitem><listitem><para><classname>malloc_allocator</classname></para><para>
	 Simply wraps <function>malloc</function> and
	 <function>free</function>. There is also a hook for an
	 out-of-memory handler (for
	 <function>new</function>/<function>delete</function> this is
	 taken care of elsewhere).
       </para></listitem><listitem><para><classname>debug_allocator</classname></para><para>
	 A wrapper around an arbitrary allocator <classname>A</classname>.
	 It passes on slightly increased size requests to <classname>A</classname>,
	 and uses the extra memory to store size information.
	 When a pointer is passed
	 to <function>deallocate()</function>, the stored size is
	 checked, and <function>assert()</function> is used to
	 guarantee they match.
       </para></listitem><listitem><para><classname>throw_allocator</classname></para><para>
	  Includes memory tracking and marking abilities as well as hooks for
	  throwing exceptions at configurable intervals (including random,
	  all, none).
	</para></listitem><listitem><para><classname>__pool_alloc</classname></para><para>
	 A high-performance, single pool allocator.  The reusable
	 memory is shared among identical instantiations of this type.
	 It calls through <function>::operator new</function> to
	 obtain new memory when its lists run out.  If a client
	 container requests a block larger than a certain threshold
	 size, then the pool is bypassed, and the allocate/deallocate
	 request is passed to <function>::operator new</function>
	 directly.
       </para><para>
	 For thread-enabled configurations, the pool is locked with a
	 single big lock. In some situations, this implementation detail
	 may result in severe performance degradation.
       </para><para>
	 (Note that the GCC thread abstraction layer allows us to provide
	 safe zero-overhead stubs for the threading routines, if threads
	 were disabled at configuration time.)
       </para></listitem><listitem><para><classname>__mt_alloc</classname></para><para>
	 A high-performance fixed-size allocator with
	 exponentially-increasing allocations. It has its own
	 <link linkend="manual.ext.allocator.mt">chapter</link>
         in the documentation.
       </para></listitem><listitem><para><classname>bitmap_allocator</classname></para><para>
	 A high-performance allocator that uses a bit-map to keep track
	 of the used and unused memory locations. It has its own
	 <link linkend="manual.ext.allocator.bitmap">chapter</link>
         in the documentation.
       </para></listitem></orderedlist></section><bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
    ISO/IEC 14882:1998 Programming languages - C++
    </citetitle><abbrev>
      isoc++_1998
    </abbrev><pagenums>20.4 Memory</pagenums></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20190622154249/http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759">
      The Standard Librarian: What Are Allocators Good For?
      </link></title><author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author><publisher><publishername>
	C/C++ Users Journal
      </publishername></publisher><pubdate>2000-12</pubdate></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://hoard.org">
      The Hoard Memory Allocator
	</link></title><author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf">
      Reconsidering Custom Memory Allocation
	</link></title><author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author><author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author><author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author><copyright><year>2002</year><holder>OOPSLA</holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://angelikalanger.com/Articles/C++Report/Allocators/Allocators.html">
      Allocator Types
	</link></title><author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author><author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author><publisher><publishername>
	C/C++ Users Journal
      </publishername></publisher></biblioentry><biblioentry><citetitle>The C++ Programming Language</citetitle><author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author><copyright><year>2000</year><holder></holder></copyright><pagenums>19.4 Allocators</pagenums><publisher><publishername>
	Addison Wesley
      </publishername></publisher></biblioentry><biblioentry><citetitle>Yalloc: A Recycling C++ Allocator</citetitle><author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author></biblioentry></bibliography></section><!--  Section 02 : auto_ptr --><section version="5.0" xreflabel="auto_ptr" xml:id="std.util.memory.auto_ptr"><?dbhtml filename="auto_ptr.html"?><info><title>auto_ptr</title><keywordset><keyword>ISO C++</keyword><keyword>auto_ptr</keyword></keywordset></info><section xml:id="auto_ptr.limitations"><info><title>Limitations</title></info><para>Explaining all of the fun and delicious things that can
   happen with misuse of the <classname>auto_ptr</classname> class
   template (called <acronym>AP</acronym> here) would take some
   time. Suffice it to say that the use of <acronym>AP</acronym>
   safely in the presence of copying has some subtleties.
   </para><para>
     The AP class is a really
      nifty idea for a smart pointer, but it is one of the dumbest of
      all the smart pointers -- and that's fine.
   </para><para>
     AP is not meant to be a supersmart solution to all resource
      leaks everywhere.  Neither is it meant to be an effective form
      of garbage collection (although it can help, a little bit).
      And it can <emphasis>not</emphasis>be used for arrays!
   </para><para><acronym>AP</acronym> is meant to prevent nasty leaks in the
     presence of exceptions.  That's <emphasis>all</emphasis>.  This
     code is AP-friendly:
   </para><programlisting>
    // Not a recommend naming scheme, but good for web-based FAQs.
    typedef std::auto_ptr&lt;MyClass&gt;  APMC;

    extern function_taking_MyClass_pointer (MyClass*);
    extern some_throwable_function ();

    void func (int data)
    {
	APMC  ap (new MyClass(data));

	some_throwable_function();   // this will throw an exception

	function_taking_MyClass_pointer (ap.get());
    }
</programlisting><para>When an exception gets thrown, the instance of MyClass that's
      been created on the heap will be <function>delete</function>'d as the stack is
      unwound past <function>func()</function>.
   </para><para>Changing that code as follows is not <acronym>AP</acronym>-friendly:
   </para><programlisting>
	APMC  ap (new MyClass[22]);
</programlisting><para>You will get the same problems as you would without the use
      of <acronym>AP</acronym>:
   </para><programlisting>
	char*  array = new char[10];       // array new...
	...
	delete array;                      // ...but single-object delete
</programlisting><para>
     AP cannot tell whether the pointer you've passed at creation points
      to one or many things.  If it points to many things, you are about
      to die.  AP is trivial to write, however, so you could write your
      own <code>auto_array_ptr</code> for that situation (in fact, this has
      been done many times; check the mailing lists, Usenet, Boost, etc).
   </para></section><section xml:id="auto_ptr.using"><info><title>Use in Containers</title></info><para>
  </para><para>All of the <link linkend="std.containers">containers</link>
      described in the standard library require their contained types
      to have, among other things, a copy constructor like this:
  </para><programlisting>
    struct My_Type
    {
	My_Type (My_Type const&amp;);
    };
</programlisting><para>
     Note the const keyword; the object being copied shouldn't change.
     The template class <code>auto_ptr</code> (called AP here) does not
     meet this requirement.  Creating a new AP by copying an existing
     one transfers ownership of the pointed-to object, which means that
     the AP being copied must change, which in turn means that the
     copy ctors of AP do not take const objects.
   </para><para>
     The resulting rule is simple: <emphasis>Never ever use a
     container of auto_ptr objects</emphasis>. The standard says that
     <quote>undefined</quote> behavior is the result, but it is
     guaranteed to be messy.
   </para><para>
     To prevent you from doing this to yourself, the
      <link linkend="manual.ext.compile_checks">concept checks</link> built
      in to this implementation will issue an error if you try to
      compile code like this:
   </para><programlisting>
    #include &lt;vector&gt;
    #include &lt;memory&gt;

    void f()
    {
	std::vector&lt; std::auto_ptr&lt;int&gt; &gt;   vec_ap_int;
    }
</programlisting><para>
Should you try this with the checks enabled, you will see an error.
   </para></section></section><!--  Section 03 : shared_ptr --><section version="5.0" xreflabel="shared_ptr" xml:id="std.util.memory.shared_ptr"><?dbhtml filename="shared_ptr.html"?><info><title>shared_ptr</title><keywordset><keyword>ISO C++</keyword><keyword>shared_ptr</keyword></keywordset></info><para>
The shared_ptr class template stores a pointer, usually obtained via new,
and implements shared ownership semantics.
</para><section xml:id="shared_ptr.req"><info><title>Requirements</title></info><para>
  </para><para>
    The standard deliberately doesn't require a reference-counted
    implementation, allowing other techniques such as a
    circular-linked-list.
  </para><para>
  </para></section><section xml:id="shared_ptr.design_issues"><info><title>Design Issues</title></info><para>
The <classname>shared_ptr</classname> code is kindly donated to GCC by the Boost
project and the original authors of the code. The basic design and
algorithms are from Boost, the notes below describe details specific to
the GCC implementation. Names have been uglified in this implementation,
but the design should be recognisable to anyone familiar with the Boost
1.32 shared_ptr.
  </para><para>
The basic design is an abstract base class, <code>_Sp_counted_base</code> that
does the reference-counting and calls virtual functions when the count
drops to zero.
Derived classes override those functions to destroy resources in a context
where the correct dynamic type is known. This is an application of the
technique known as type erasure.
  </para></section><section xml:id="shared_ptr.impl"><info><title>Implementation</title></info><section xml:id="shared_ptr.hier"><info><title>Class Hierarchy</title></info><para>
A <classname>shared_ptr&lt;T&gt;</classname> contains a pointer of
type <type>T*</type> and an object of type
<classname>__shared_count</classname>. The shared_count contains a
pointer of type <type>_Sp_counted_base*</type> which points to the
object that maintains the reference-counts and destroys the managed
resource.
    </para><variablelist><varlistentry><term><classname>_Sp_counted_base&lt;Lp&gt;</classname></term><listitem><para>
The base of the hierarchy is parameterized on the lock policy (see below.)
_Sp_counted_base doesn't depend on the type of pointer being managed,
it only maintains the reference counts and calls virtual functions when
the counts drop to zero. The managed object is destroyed when the last
strong reference is dropped, but the _Sp_counted_base itself must exist
until the last weak reference is dropped.
    </para></listitem></varlistentry><varlistentry><term><classname>_Sp_counted_base_impl&lt;Ptr, Deleter, Lp&gt;</classname></term><listitem><para>
Inherits from _Sp_counted_base and stores a pointer of type <code>Ptr</code>
and a deleter of type <code>Deleter</code>.  <classname>_Sp_deleter</classname> is
used when the user doesn't supply a custom deleter. Unlike Boost's, this
default deleter is not "checked" because GCC already issues a warning if
<function>delete</function> is used with an incomplete type.
This is the only derived type used by <classname>tr1::shared_ptr&lt;Ptr&gt;</classname>
and it is never used by <classname>std::shared_ptr</classname>, which uses one of
the following types, depending on how the shared_ptr is constructed.
    </para></listitem></varlistentry><varlistentry><term><classname>_Sp_counted_ptr&lt;Ptr, Lp&gt;</classname></term><listitem><para>
Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type>,
which is passed to <function>delete</function> when the last reference is dropped.
This is the simplest form and is used when there is no custom deleter or
allocator.
    </para></listitem></varlistentry><varlistentry><term><classname>_Sp_counted_deleter&lt;Ptr, Deleter, Alloc&gt;</classname></term><listitem><para>
Inherits from _Sp_counted_ptr and adds support for custom deleter and
allocator. Empty Base Optimization is used for the allocator. This class
is used even when the user only provides a custom deleter, in which case
<classname>allocator</classname> is used as the allocator.
    </para></listitem></varlistentry><varlistentry><term><classname>_Sp_counted_ptr_inplace&lt;Tp, Alloc, Lp&gt;</classname></term><listitem><para>
Used by <code>allocate_shared</code> and <code>make_shared</code>.
Contains aligned storage to hold an object of type <type>Tp</type>,
which is constructed in-place with placement <function>new</function>.
Has a variadic template constructor allowing any number of arguments to
be forwarded to <type>Tp</type>'s constructor.
Unlike the other <classname>_Sp_counted_*</classname> classes, this one is parameterized on the
type of object, not the type of pointer; this is purely a convenience
that simplifies the implementation slightly.
    </para></listitem></varlistentry></variablelist><para>
C++11-only features are: rvalue-ref/move support, allocator support,
aliasing constructor, make_shared &amp; allocate_shared. Additionally,
the constructors taking <classname>auto_ptr</classname> parameters are
deprecated in C++11 mode.
    </para></section><section xml:id="shared_ptr.thread"><info><title>Thread Safety</title></info><para>
The
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread
Safety</link> section of the Boost shared_ptr documentation says "shared_ptr
objects offer the same level of thread safety as built-in types."
The implementation must ensure that concurrent updates to separate shared_ptr
instances are correct even when those instances share a reference count e.g.
</para><programlisting>
shared_ptr&lt;A&gt; a(new A);
shared_ptr&lt;A&gt; b(a);

// Thread 1     // Thread 2
   a.reset();      b.reset();
</programlisting><para>
The dynamically-allocated object must be destroyed by exactly one of the
threads. Weak references make things even more interesting.
The shared state used to implement shared_ptr must be transparent to the
user and invariants must be preserved at all times.
The key pieces of shared state are the strong and weak reference counts.
Updates to these need to be atomic and visible to all threads to ensure
correct cleanup of the managed resource (which is, after all, shared_ptr's
job!)
On multi-processor systems memory synchronisation may be needed so that
reference-count updates and the destruction of the managed resource are
race-free.
</para><para>
The function <function>_Sp_counted_base::_M_add_ref_lock()</function>, called when
obtaining a shared_ptr from a weak_ptr, has to test if the managed
resource still exists and either increment the reference count or throw
<classname>bad_weak_ptr</classname>.
In a multi-threaded program there is a potential race condition if the last
reference is dropped (and the managed resource destroyed) between testing
the reference count and incrementing it, which could result in a shared_ptr
pointing to invalid memory.
</para><para>
The Boost shared_ptr (as used in GCC) features a clever lock-free
algorithm to avoid the race condition, but this relies on the
processor supporting an atomic <emphasis>Compare-And-Swap</emphasis>
instruction. For other platforms there are fall-backs using mutex
locks.  Boost (as of version 1.35) includes several different
implementations and the preprocessor selects one based on the
compiler, standard library, platform etc. For the version of
shared_ptr in libstdc++ the compiler and library are fixed, which
makes things much simpler: we have an atomic CAS or we don't, see Lock
Policy below for details.
</para></section><section xml:id="shared_ptr.policy"><info><title>Selecting Lock Policy</title></info><para>
    </para><para>
There is a single <classname>_Sp_counted_base</classname> class,
which is a template parameterized on the enum
<type>__gnu_cxx::_Lock_policy</type>.  The entire family of classes is
parameterized on the lock policy, right up to
<classname>__shared_ptr</classname>, <classname>__weak_ptr</classname> and
<classname>__enable_shared_from_this</classname>. The actual
<classname>std::shared_ptr</classname> class inherits from
<classname>__shared_ptr</classname> with the lock policy parameter
selected automatically based on the thread model and platform that
libstdc++ is configured for, so that the best available template
specialization will be used. This design is necessary because it would
not be conforming for <classname>shared_ptr</classname> to have an
extra template parameter, even if it had a default value.  The
available policies are:
    </para><orderedlist><listitem><para><constant>_S_atomic</constant></para><para>
Selected when GCC supports a builtin atomic compare-and-swap operation
on the target processor (see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html">Atomic
Builtins</link>.)  The reference counts are maintained using a lock-free
algorithm and GCC's atomic builtins, which provide the required memory
synchronisation.
       </para></listitem><listitem><para><constant>_S_mutex</constant></para><para>
The _Sp_counted_base specialization for this policy contains a mutex,
which is locked in add_ref_lock(). This policy is used when GCC's atomic
builtins aren't available so explicit memory barriers are needed in places.
       </para></listitem><listitem><para><constant>_S_single</constant></para><para>
This policy uses a non-reentrant add_ref_lock() with no locking. It is
used when libstdc++ is built without <literal>--enable-threads</literal>.
       </para></listitem></orderedlist><para>
       For all three policies, reference count increments and
       decrements are done via the functions in
       <filename>ext/atomicity.h</filename>, which detect if the program
       is multi-threaded.  If only one thread of execution exists in
       the program then less expensive non-atomic operations are used.
     </para></section><section xml:id="shared_ptr.rel"><info><title>Related functions and classes</title></info><variablelist><varlistentry><term><code>dynamic_pointer_cast</code>, <code>static_pointer_cast</code>,
<code>const_pointer_cast</code></term><listitem><para>
As noted in N2351, these functions can be implemented non-intrusively using
the alias constructor.  However the aliasing constructor is only available
in C++11 mode, so in TR1 mode these casts rely on three non-standard
constructors in shared_ptr and __shared_ptr.
In C++11 mode these constructors and the related tag types are not needed.
    </para></listitem></varlistentry><varlistentry><term><code>enable_shared_from_this</code></term><listitem><para>
The clever overload to detect a base class of type
<code>enable_shared_from_this</code> comes straight from Boost.
There is an extra overload for <code>__enable_shared_from_this</code> to
work smoothly with <code>__shared_ptr&lt;Tp, Lp&gt;</code> using any lock
policy.
    </para></listitem></varlistentry><varlistentry><term><code>make_shared</code>, <code>allocate_shared</code></term><listitem><para><code>make_shared</code> simply forwards to <code>allocate_shared</code>
with <code>std::allocator</code> as the allocator.
Although these functions can be implemented non-intrusively using the
alias constructor, if they have access to the implementation then it is
possible to save storage and reduce the number of heap allocations. The
newly constructed object and the _Sp_counted_* can be allocated in a single
block and the standard says implementations are "encouraged, but not required,"
to do so. This implementation provides additional non-standard constructors
(selected with the type <code>_Sp_make_shared_tag</code>) which create an
object of type <code>_Sp_counted_ptr_inplace</code> to hold the new object.
The returned <code>shared_ptr&lt;A&gt;</code> needs to know the address of the
new <code>A</code> object embedded in the <code>_Sp_counted_ptr_inplace</code>,
but it has no way to access it.
This implementation uses a "covert channel" to return the address of the
embedded object when <code>get_deleter&lt;_Sp_make_shared_tag&gt;()</code>
is called.  Users should not try to use this.
As well as the extra constructors, this implementation also needs some
members of _Sp_counted_deleter to be protected where they could otherwise
be private.
    </para></listitem></varlistentry></variablelist></section></section><section xml:id="shared_ptr.using"><info><title>Use</title></info><section xml:id="shared_ptr.examples"><info><title>Examples</title></info><para>
      Examples of use can be found in the testsuite, under
      <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>,
      <filename class="directory">testsuite/20_util/shared_ptr</filename>
      and
      <filename class="directory">testsuite/20_util/weak_ptr</filename>.
    </para></section><section xml:id="shared_ptr.issues"><info><title>Unresolved Issues</title></info><para>
      The <emphasis><classname>shared_ptr</classname> atomic access</emphasis>
      clause in the C++11 standard is not implemented in GCC.
    </para><para>
      Unlike Boost, this implementation does not use separate classes
      for the pointer+deleter and pointer+deleter+allocator cases in
      C++11 mode, combining both into _Sp_counted_deleter and using
      <classname>allocator</classname> when the user doesn't specify
      an allocator.  If it was found to be beneficial an additional
      class could easily be added.  With the current implementation,
      the _Sp_counted_deleter and __shared_count constructors taking a
      custom deleter but no allocator are technically redundant and
      could be removed, changing callers to always specify an
      allocator. If a separate pointer+deleter class was added the
      __shared_count constructor would be needed, so it has been kept
      for now.
    </para><para>
      The hack used to get the address of the managed object from
      <function>_Sp_counted_ptr_inplace::_M_get_deleter()</function>
      is accessible to users. This could be prevented if
      <function>get_deleter&lt;_Sp_make_shared_tag&gt;()</function>
      always returned NULL, since the hack only needs to work at a
      lower level, not in the public API. This wouldn't be difficult,
      but hasn't been done since there is no danger of accidental
      misuse: users already know they are relying on unsupported
      features if they refer to implementation details such as
      _Sp_make_shared_tag.
    </para><para>
      tr1::_Sp_deleter could be a private member of tr1::__shared_count but it
      would alter the ABI.
    </para></section></section><section xml:id="shared_ptr.ack"><info><title>Acknowledgments</title></info><para>
    The original authors of the Boost shared_ptr, which is really nice
    code to work with, Peter Dimov in particular for his help and
    invaluable advice on thread safety.  Phillip Jordan and Paolo
    Carlini for the lock policy implementation.
  </para></section><bibliography xml:id="shared_ptr.biblio"><info><title>Bibliography</title></info><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm">
      Improving shared_ptr for C++0x, Revision 2
	</link></title><subtitle>
      N2351
    </subtitle></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html">
      C++ Standard Library Active Issues List
	</link></title><subtitle>
      N2456
    </subtitle></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf">
      Working Draft, Standard for Programming Language C++
	</link></title><subtitle>
      N2461
    </subtitle></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">
      Boost C++ Libraries documentation, shared_ptr
	</link></title><subtitle>
      N2461
    </subtitle></biblioentry></bibliography></section></section><!-- Section 04 : Traits --><section xreflabel="Traits" xml:id="std.util.traits"><info><title>Traits</title></info><?dbhtml filename="traits.html"?><para>
  </para></section></chapter><!-- Chapter 04 : Strings --><chapter version="5.0" xreflabel="Strings" xml:id="std.strings"><?dbhtml filename="strings.html"?><info><title>
  Strings
  <indexterm><primary>Strings</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Sect1 01 : Character Traits --><!-- Sect1 02 : String Classes --><section xreflabel="string" xml:id="std.strings.string"><info><title>String Classes</title></info><section xreflabel="Simple Transformations" xml:id="strings.string.simple"><info><title>Simple Transformations</title></info><para>
      Here are Standard, simple, and portable ways to perform common
      transformations on a <code>string</code> instance, such as
      "convert to all upper case." The word transformations
      is especially apt, because the standard template function
      <code>transform&lt;&gt;</code> is used.
   </para><para>
     This code will go through some iterations.  Here's a simple
     version:
   </para><programlisting>
   #include &lt;string&gt;
   #include &lt;algorithm&gt;
   #include &lt;cctype&gt;      // old &lt;ctype.h&gt;

   struct ToLower
   {
     char operator() (char c) const  { return std::tolower(c); }
   };

   struct ToUpper
   {
     char operator() (char c) const  { return std::toupper(c); }
   };

   int main()
   {
     std::string  s ("Some Kind Of Initial Input Goes Here");

     // Change everything into upper case
     std::transform (s.begin(), s.end(), s.begin(), ToUpper());

     // Change everything into lower case
     std::transform (s.begin(), s.end(), s.begin(), ToLower());

     // Change everything back into upper case, but store the
     // result in a different string
     std::string  capital_s;
     capital_s.resize(s.size());
     std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
   }
</programlisting><para><emphasis>Note</emphasis> that these calls all
      involve the global C locale through the use of the C functions
      <code>toupper</code>/<code>tolower</code>.
      This is absolutely guaranteed to work
      -- but <emphasis>only</emphasis> if the string contains
      <emphasis>only</emphasis> characters from the basic source character set,
      and there are <emphasis>only</emphasis> 96 of those.
      Which means that not even all English text can be
      represented (certain British spellings, proper names, and so forth).
      So, if all your input forevermore consists of only those 96
      characters (hahahahahaha), then you're done.
   </para><para><emphasis>Note</emphasis> that the
      <code>ToUpper</code> and <code>ToLower</code> function objects
      are needed because <code>toupper</code> and <code>tolower</code>
      are overloaded names (declared in <code>&lt;cctype&gt;</code> and
      <code>&lt;locale&gt;</code>) so the template-arguments for
      <code>transform&lt;&gt;</code> cannot be deduced, as explained in
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this
      message</link>.
      <!-- section 14.8.2.4 clause 16 in ISO 14882:1998  -->
      At minimum, you can write short wrappers like
   </para><programlisting>
   char toLower (char c)
   {
      // std::tolower(c) is undefined if c &lt; 0 so cast to unsigned char.
      return std::tolower((unsigned char)c);
   } </programlisting><para>(Thanks to James Kanze for assistance and suggestions on all of this.)
   </para><para>
     Since C++11 the wrapper can be replaced with a lambda expression,
     which can perform the conversion to <code>unsigned char</code> and
     also ensure the single-argument form of <code>std::lower</code> is used:
   </para><programlisting>
     std::transform (s.begin(), s.end(), capital_s.begin(),
                     [](unsigned char c) { return std::tolower(c); });
</programlisting><para>Another common operation is trimming off excess whitespace.  Much
      like transformations, this task is trivial with the use of string's
      <code>find</code> family.  These examples are broken into multiple
      statements for readability:
   </para><programlisting>
   std::string  str (" \t blah blah blah    \n ");

   // trim leading whitespace
   string::size_type  notwhite = str.find_first_not_of(" \t\n");
   str.erase(0,notwhite);

   // trim trailing whitespace
   notwhite = str.find_last_not_of(" \t\n");
   str.erase(notwhite+1); </programlisting><para>Obviously, the calls to <code>find</code> could be inserted directly
      into the calls to <code>erase</code>, in case your compiler does not
      optimize named temporaries out of existence.
   </para></section><section xreflabel="Case Sensitivity" xml:id="strings.string.case"><info><title>Case Sensitivity</title></info><para>
    </para><para>The well-known-and-if-it-isn't-well-known-it-ought-to-be
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gotw.ca/gotw/">Guru of the Week</link>
      discussions held on Usenet covered this topic in January of 1998.
      Briefly, the challenge was, <quote>write a 'ci_string' class which
      is identical to the standard 'string' class, but is
      case-insensitive in the same way as the (common but nonstandard)
      C function stricmp()</quote>.
   </para><programlisting>
   ci_string s( "AbCdE" );

   // case insensitive
   assert( s == "abcde" );
   assert( s == "ABCDE" );

   // still case-preserving, of course
   assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
   assert( strcmp( s.c_str(), "abcde" ) != 0 ); </programlisting><para>The solution is surprisingly easy.  The original answer was
   posted on Usenet, and a revised version appears in Herb Sutter's
   book <emphasis>Exceptional C++</emphasis> and on his website as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gotw.ca/gotw/029.htm">GotW 29</link>.
   </para><para>See?  Told you it was easy!</para><para><emphasis>Added June 2000:</emphasis> The May 2000 issue of C++
     Report contains a fascinating <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://lafstern.org/matt/col2_new.pdf"> article</link> by
     Matt Austern (yes, <emphasis>the</emphasis> Matt Austern) on why
     case-insensitive comparisons are not as easy as they seem, and
     why creating a class is the <emphasis>wrong</emphasis> way to go
     about it in production code.  (The GotW answer mentions one of
     the principle difficulties; his article mentions more.)
   </para><para>Basically, this is "easy" only if you ignore some things,
      things which may be too important to your program to ignore.  (I chose
      to ignore them when originally writing this entry, and am surprised
      that nobody ever called me on it...)  The GotW question and answer
      remain useful instructional tools, however.
   </para><para><emphasis>Added September 2000:</emphasis>  James Kanze provided a link to a
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.unicode.org/reports/tr21/tr21-5.html">Unicode
      Technical Report discussing case handling</link>, which provides some
      very good information.
   </para></section><section xreflabel="Arbitrary Characters" xml:id="strings.string.character_types"><info><title>Arbitrary Character Types</title></info><para>
    </para><para>The <code>std::basic_string</code> is tantalizingly general, in that
      it is parameterized on the type of the characters which it holds.
      In theory, you could whip up a Unicode character class and instantiate
      <code>std::basic_string&lt;my_unicode_char&gt;</code>, or assuming
      that integers are wider than characters on your platform, maybe just
      declare variables of type <code>std::basic_string&lt;int&gt;</code>.
   </para><para>That's the theory.  Remember however that basic_string has additional
      type parameters, which take default arguments based on the character
      type (called <code>CharT</code> here):
   </para><programlisting>
      template &lt;typename CharT,
		typename Traits = char_traits&lt;CharT&gt;,
		typename Alloc = allocator&lt;CharT&gt; &gt;
      class basic_string { .... };</programlisting><para>Now, <code>allocator&lt;CharT&gt;</code> will probably Do The Right
      Thing by default, unless you need to implement your own allocator
      for your characters.
   </para><para>But <code>char_traits</code> takes more work.  The char_traits
      template is <emphasis>declared</emphasis> but not <emphasis>defined</emphasis>.
      That means there is only
   </para><programlisting>
      template &lt;typename CharT&gt;
	struct char_traits
	{
	    static void foo (type1 x, type2 y);
	    ...
	};</programlisting><para>and functions such as char_traits&lt;CharT&gt;::foo() are not
      actually defined anywhere for the general case.  The C++ standard
      permits this, because writing such a definition to fit all possible
      CharT's cannot be done.
   </para><para>The C++ standard also requires that char_traits be specialized for
      instantiations of <code>char</code> and <code>wchar_t</code>, and it
      is these template specializations that permit entities like
      <code>basic_string&lt;char,char_traits&lt;char&gt;&gt;</code> to work.
   </para><para>If you want to use character types other than char and wchar_t,
      such as <code>unsigned char</code> and <code>int</code>, you will
      need suitable specializations for them.  For a time, in earlier
      versions of GCC, there was a mostly-correct implementation that
      let programmers be lazy but it broke under many situations, so it
      was removed.  GCC 3.4 introduced a new implementation that mostly
      works and can be specialized even for <code>int</code> and other
      built-in types.
   </para><para>If you want to use your own special character class, then you have
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot
      of work to do</link>, especially if you with to use i18n features
      (facets require traits information but don't have a traits argument).
   </para><para>Another example of how to specialize char_traits was given <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the
      mailing list</link> and at a later date was put into the file <code>
      include/ext/pod_char_traits.h</code>.  We agree
      that the way it's used with basic_string (scroll down to main())
      doesn't look nice, but that's because <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the
      nice-looking first attempt</link> turned out to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not
      be conforming C++</link>, due to the rule that CharT must be a POD.
      (See how tricky this is?)
   </para></section><section xreflabel="Tokenizing" xml:id="strings.string.token"><info><title>Tokenizing</title></info><para>
    </para><para>The Standard C (and C++) function <code>strtok()</code> leaves a lot to
      be desired in terms of user-friendliness.  It's unintuitive, it
      destroys the character string on which it operates, and it requires
      you to handle all the memory problems.  But it does let the client
      code decide what to use to break the string into pieces; it allows
      you to choose the "whitespace," so to speak.
   </para><para>A C++ implementation lets us keep the good things and fix those
      annoyances.  The implementation here is more intuitive (you only
      call it once, not in a loop with varying argument), it does not
      affect the original string at all, and all the memory allocation
      is handled for you.
   </para><para>It's called stringtok, and it's a template function. Sources are
   as below, in a less-portable form than it could be, to keep this
   example simple (for example, see the comments on what kind of
   string it will accept).
   </para><programlisting>
#include &lt;string&gt;
template &lt;typename Container&gt;
void
stringtok(Container &amp;container, string const &amp;in,
	  const char * const delimiters = " \t\n")
{
    const string::size_type len = in.length();
	  string::size_type i = 0;

    while (i &lt; len)
    {
	// Eat leading whitespace
	i = in.find_first_not_of(delimiters, i);
	if (i == string::npos)
	  return;   // Nothing left but white space

	// Find the end of the token
	string::size_type j = in.find_first_of(delimiters, i);

	// Push token
	if (j == string::npos)
	{
	  container.push_back(in.substr(i));
	  return;
	}
	else
	  container.push_back(in.substr(i, j-i));

	// Set up for next loop
	i = j + 1;
    }
}
</programlisting><para>
     The author uses a more general (but less readable) form of it for
     parsing command strings and the like.  If you compiled and ran this
     code using it:
   </para><programlisting>
   std::list&lt;string&gt;  ls;
   stringtok (ls, " this  \t is\t\n  a test  ");
   for (std::list&lt;string&gt;const_iterator i = ls.begin();
	i != ls.end(); ++i)
   {
       std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n";
   } </programlisting><para>You would see this as output:
   </para><programlisting>
   :this:
   :is:
   :a:
   :test: </programlisting><para>with all the whitespace removed.  The original <code>s</code> is still
      available for use, <code>ls</code> will clean up after itself, and
      <code>ls.size()</code> will return how many tokens there were.
   </para><para>As always, there is a price paid here, in that stringtok is not
      as fast as strtok.  The other benefits usually outweigh that, however.
   </para><para><emphasis>Added February 2001:</emphasis>  Mark Wilden pointed out that the
      standard <code>std::getline()</code> function can be used with standard
      <code>istringstreams</code> to perform
      tokenizing as well.  Build an istringstream from the input text,
      and then use std::getline with varying delimiters (the three-argument
      signature) to extract tokens into a string.
   </para></section><section xreflabel="Shrink to Fit" xml:id="strings.string.shrink"><info><title>Shrink to Fit</title></info><para>
    </para><para>From GCC 3.4 calling <code>s.reserve(res)</code> on a
      <code>string s</code> with <code>res &lt; s.capacity()</code> will
      reduce the string's capacity to <code>std::max(s.size(), res)</code>.
   </para><para>This behaviour is suggested, but not required by the standard. Prior
      to GCC 3.4 the following alternative can be used instead
   </para><programlisting>
      std::string(str.data(), str.size()).swap(str);
</programlisting><para>This is similar to the idiom for reducing
      a <code>vector</code>'s memory usage
      (see <link linkend="faq.size_equals_capacity">this FAQ
      entry</link>) but the regular copy constructor cannot be used
      because libstdc++'s <code>string</code> is Copy-On-Write in GCC 3.
   </para><para>From GCC 4.5 in <link linkend="status.iso.2011">C++11</link> mode you
      can call <code>s.shrink_to_fit()</code> to achieve the same effect as
      <code>s.reserve(s.size())</code>.
   </para></section><section xreflabel="CString (MFC)" xml:id="strings.string.Cstring"><info><title>CString (MFC)</title></info><para>
    </para><para>A common lament seen in various newsgroups deals with the Standard
      string class as opposed to the Microsoft Foundation Class called
      CString.  Often programmers realize that a standard portable
      answer is better than a proprietary nonportable one, but in porting
      their application from a Win32 platform, they discover that they
      are relying on special functions offered by the CString class.
   </para><para>Things are not as bad as they seem.  In
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this
      message</link>, Joe Buck points out a few very important things:
   </para><itemizedlist><listitem><para>The Standard <code>string</code> supports all the operations
	     that CString does, with three exceptions.
	 </para></listitem><listitem><para>Two of those exceptions (whitespace trimming and case
	     conversion) are trivial to implement.  In fact, we do so
	     on this page.
	 </para></listitem><listitem><para>The third is <code>CString::Format</code>, which allows formatting
	     in the style of <code>sprintf</code>.  This deserves some mention:
	 </para></listitem></itemizedlist><para>
      The old libg++ library had a function called form(), which did much
      the same thing.  But for a Standard solution, you should use the
      stringstream classes.  These are the bridge between the iostream
      hierarchy and the string class, and they operate with regular
      streams seamlessly because they inherit from the iostream
      hierarchy.  An quick example:
   </para><programlisting>
   #include &lt;iostream&gt;
   #include &lt;string&gt;
   #include &lt;sstream&gt;

   string f (string&amp; incoming)     // incoming is "foo  N"
   {
       istringstream   incoming_stream(incoming);
       string          the_word;
       int             the_number;

       incoming_stream &gt;&gt; the_word        // extract "foo"
		       &gt;&gt; the_number;     // extract N

       ostringstream   output_stream;
       output_stream &lt;&lt; "The word was " &lt;&lt; the_word
		     &lt;&lt; " and 3*N was " &lt;&lt; (3*the_number);

       return output_stream.str();
   } </programlisting><para>A serious problem with CString is a design bug in its memory
      allocation.  Specifically, quoting from that same message:
   </para><programlisting>
   CString suffers from a common programming error that results in
   poor performance.  Consider the following code:

   CString n_copies_of (const CString&amp; foo, unsigned n)
   {
	   CString tmp;
	   for (unsigned i = 0; i &lt; n; i++)
		   tmp += foo;
	   return tmp;
   }

   This function is O(n^2), not O(n).  The reason is that each +=
   causes a reallocation and copy of the existing string.  Microsoft
   applications are full of this kind of thing (quadratic performance
   on tasks that can be done in linear time) -- on the other hand,
   we should be thankful, as it's created such a big market for high-end
   ix86 hardware. :-)

   If you replace CString with string in the above function, the
   performance is O(n).
</programlisting><para>Joe Buck also pointed out some other things to keep in mind when
      comparing CString and the Standard string class:
   </para><itemizedlist><listitem><para>CString permits access to its internal representation; coders
	     who exploited that may have problems moving to <code>string</code>.
	 </para></listitem><listitem><para>Microsoft ships the source to CString (in the files
	     MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation
	     bug and rebuild your MFC libraries.
	     <emphasis><emphasis>Note:</emphasis> It looks like the CString shipped
	     with VC++6.0 has fixed this, although it may in fact have been
	     one of the VC++ SPs that did it.</emphasis>
	 </para></listitem><listitem><para><code>string</code> operations like this have O(n) complexity
	     <emphasis>if the implementors do it correctly</emphasis>.  The libstdc++
	     implementors did it correctly.  Other vendors might not.
	 </para></listitem><listitem><para>While parts of the SGI STL are used in libstdc++, their
	     string class is not.  The SGI <code>string</code> is essentially
	     <code>vector&lt;char&gt;</code> and does not do any reference
	     counting like libstdc++'s does.  (It is O(n), though.)
	     So if you're thinking about SGI's string or rope classes,
	     you're now looking at four possibilities:  CString, the
	     libstdc++ string, the SGI string, and the SGI rope, and this
	     is all before any allocator or traits customizations!  (More
	     choices than you can shake a stick at -- want fries with that?)
	 </para></listitem></itemizedlist></section></section><!-- Sect1 03 : Interacting with C --></chapter><!-- Chapter 05 : Localization --><chapter version="5.0" xreflabel="Localization" xml:id="std.localization"><?dbhtml filename="localization.html"?><info><title>
  Localization
  <indexterm><primary>Localization</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Section 01 : Locale --><section xreflabel="Locales" xml:id="std.localization.locales"><info><title>Locales</title></info><?dbhtml filename="locales.html"?><!--  Section 01 : locale --><section version="5.0" xreflabel="Locale" xml:id="std.localization.locales.locale"><info><title>locale</title><keywordset><keyword>ISO C++</keyword><keyword>locale</keyword></keywordset></info><para>
Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</para><section xml:id="locales.locale.req"><info><title>Requirements</title></info><para>
Class locale is non-templatized and has two distinct types nested
inside of it:
</para><blockquote><para><emphasis>
class facet
22.1.1.1.2 Class locale::facet
</emphasis></para></blockquote><para>
Facets actually implement locale functionality. For instance, a facet
called numpunct is the data object that can be used to query for the
thousands separator in the locale.
</para><para>
Literally, a facet is strictly defined:
</para><itemizedlist><listitem><para>
      Containing the following public data member:
    </para><para><code>static locale::id id;</code></para></listitem><listitem><para>
      Derived from another facet:
    </para><para><code>class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code></para></listitem></itemizedlist><para>
Of interest in this class are the memory management options explicitly
specified as an argument to facet's constructor. Each constructor of a
facet class takes a std::size_t __refs argument: if __refs == 0, the
facet is deleted when the locale containing it is destroyed. If __refs
== 1, the facet is not destroyed, even when it is no longer
referenced.
</para><blockquote><para><emphasis>
class id
22.1.1.1.3 - Class locale::id
</emphasis></para></blockquote><para>
Provides an index for looking up specific facets.
</para></section><section xml:id="locales.locale.design"><info><title>Design</title></info><para>
The major design challenge is fitting an object-orientated and
non-global locale design on top of POSIX and other relevant standards,
which include the Single Unix (nee X/Open.)
</para><para>
Because C and earlier versions of POSIX fall down so completely,
portability is an issue.
</para></section><section xml:id="locales.locale.impl"><info><title>Implementation</title></info><section xml:id="locale.impl.c"><info><title>Interacting with "C" locales</title></info><itemizedlist><listitem><para><code>locale -a</code> displays available locales.
     </para><blockquote><programlisting>
af_ZA
ar_AE
ar_AE.utf8
ar_BH
ar_BH.utf8
ar_DZ
ar_DZ.utf8
ar_EG
ar_EG.utf8
ar_IN
ar_IQ
ar_IQ.utf8
ar_JO
ar_JO.utf8
ar_KW
ar_KW.utf8
ar_LB
ar_LB.utf8
ar_LY
ar_LY.utf8
ar_MA
ar_MA.utf8
ar_OM
ar_OM.utf8
ar_QA
ar_QA.utf8
ar_SA
ar_SA.utf8
ar_SD
ar_SD.utf8
ar_SY
ar_SY.utf8
ar_TN
ar_TN.utf8
ar_YE
ar_YE.utf8
be_BY
be_BY.utf8
bg_BG
bg_BG.utf8
br_FR
bs_BA
C
ca_ES
ca_ES@euro
ca_ES.utf8
ca_ES.utf8@euro
cs_CZ
cs_CZ.utf8
cy_GB
da_DK
da_DK.iso885915
da_DK.utf8
de_AT
de_AT@euro
de_AT.utf8
de_AT.utf8@euro
de_BE
de_BE@euro
de_BE.utf8
de_BE.utf8@euro
de_CH
de_CH.utf8
de_DE
de_DE@euro
de_DE.utf8
de_DE.utf8@euro
de_LU
de_LU@euro
de_LU.utf8
de_LU.utf8@euro
el_GR
el_GR.utf8
en_AU
en_AU.utf8
en_BW
en_BW.utf8
en_CA
en_CA.utf8
en_DK
en_DK.utf8
en_GB
en_GB.iso885915
en_GB.utf8
en_HK
en_HK.utf8
en_IE
en_IE@euro
en_IE.utf8
en_IE.utf8@euro
en_IN
en_NZ
en_NZ.utf8
en_PH
en_PH.utf8
en_SG
en_SG.utf8
en_US
en_US.iso885915
en_US.utf8
en_ZA
en_ZA.utf8
en_ZW
en_ZW.utf8
es_AR
es_AR.utf8
es_BO
es_BO.utf8
es_CL
es_CL.utf8
es_CO
es_CO.utf8
es_CR
es_CR.utf8
es_DO
es_DO.utf8
es_EC
es_EC.utf8
es_ES
es_ES@euro
es_ES.utf8
es_ES.utf8@euro
es_GT
es_GT.utf8
es_HN
es_HN.utf8
es_MX
es_MX.utf8
es_NI
es_NI.utf8
es_PA
es_PA.utf8
es_PE
es_PE.utf8
es_PR
es_PR.utf8
es_PY
es_PY.utf8
es_SV
es_SV.utf8
es_US
es_US.utf8
es_UY
es_UY.utf8
es_VE
es_VE.utf8
et_EE
et_EE.utf8
eu_ES
eu_ES@euro
eu_ES.utf8
eu_ES.utf8@euro
fa_IR
fi_FI
fi_FI@euro
fi_FI.utf8
fi_FI.utf8@euro
fo_FO
fo_FO.utf8
fr_BE
fr_BE@euro
fr_BE.utf8
fr_BE.utf8@euro
fr_CA
fr_CA.utf8
fr_CH
fr_CH.utf8
fr_FR
fr_FR@euro
fr_FR.utf8
fr_FR.utf8@euro
fr_LU
fr_LU@euro
fr_LU.utf8
fr_LU.utf8@euro
ga_IE
ga_IE@euro
ga_IE.utf8
ga_IE.utf8@euro
gl_ES
gl_ES@euro
gl_ES.utf8
gl_ES.utf8@euro
gv_GB
gv_GB.utf8
he_IL
he_IL.utf8
hi_IN
hr_HR
hr_HR.utf8
hu_HU
hu_HU.utf8
id_ID
id_ID.utf8
is_IS
is_IS.utf8
it_CH
it_CH.utf8
it_IT
it_IT@euro
it_IT.utf8
it_IT.utf8@euro
iw_IL
iw_IL.utf8
ja_JP.eucjp
ja_JP.utf8
ka_GE
kl_GL
kl_GL.utf8
ko_KR.euckr
ko_KR.utf8
kw_GB
kw_GB.utf8
lt_LT
lt_LT.utf8
lv_LV
lv_LV.utf8
mi_NZ
mk_MK
mk_MK.utf8
mr_IN
ms_MY
ms_MY.utf8
mt_MT
mt_MT.utf8
nl_BE
nl_BE@euro
nl_BE.utf8
nl_BE.utf8@euro
nl_NL
nl_NL@euro
nl_NL.utf8
nl_NL.utf8@euro
nn_NO
nn_NO.utf8
no_NO
no_NO.utf8
oc_FR
pl_PL
pl_PL.utf8
POSIX
pt_BR
pt_BR.utf8
pt_PT
pt_PT@euro
pt_PT.utf8
pt_PT.utf8@euro
ro_RO
ro_RO.utf8
ru_RU
ru_RU.koi8r
ru_RU.utf8
ru_UA
ru_UA.utf8
se_NO
sk_SK
sk_SK.utf8
sl_SI
sl_SI.utf8
sq_AL
sq_AL.utf8
sr_YU
sr_YU@cyrillic
sr_YU.utf8
sr_YU.utf8@cyrillic
sv_FI
sv_FI@euro
sv_FI.utf8
sv_FI.utf8@euro
sv_SE
sv_SE.iso885915
sv_SE.utf8
ta_IN
te_IN
tg_TJ
th_TH
th_TH.utf8
tl_PH
tr_TR
tr_TR.utf8
uk_UA
uk_UA.utf8
ur_PK
uz_UZ
vi_VN
vi_VN.tcvn
wa_BE
wa_BE@euro
yi_US
zh_CN
zh_CN.gb18030
zh_CN.gbk
zh_CN.utf8
zh_HK
zh_HK.utf8
zh_TW
zh_TW.euctw
zh_TW.utf8
</programlisting></blockquote></listitem><listitem><para><code>`locale`</code> displays environmental variables that
       impact how locale("") will be deduced.
     </para><blockquote><programlisting>
LANG=en_US
LC_CTYPE="en_US"
LC_NUMERIC="en_US"
LC_TIME="en_US"
LC_COLLATE="en_US"
LC_MONETARY="en_US"
LC_MESSAGES="en_US"
LC_PAPER="en_US"
LC_NAME="en_US"
LC_ADDRESS="en_US"
LC_TELEPHONE="en_US"
LC_MEASUREMENT="en_US"
LC_IDENTIFICATION="en_US"
LC_ALL=
</programlisting></blockquote></listitem></itemizedlist><para>
From Josuttis, p. 697-698, which says, that "there is only *one*
relation (of the C++ locale mechanism) to the C locale mechanism: the
global C locale is modified if a named C++ locale object is set as the
global locale" (emphasis Paolo), that is:
</para><programlisting>std::locale::global(std::locale(""));</programlisting><para>affects the C functions as if the following call was made:</para><programlisting>std::setlocale(LC_ALL, "");</programlisting><para>
  On the other hand, there is *no* vice versa, that is, calling
  setlocale has *no* whatsoever on the C++ locale mechanism, in
  particular on the working of locale(""), which constructs the locale
  object from the environment of the running program, that is, in
  practice, the set of LC_ALL, LANG, etc. variable of the shell.
</para></section></section><section xml:id="locales.locale.future"><info><title>Future</title></info><itemizedlist><listitem><para>
       Locale initialization: at what point does _S_classic, _S_global
       get initialized? Can named locales assume this initialization
       has already taken place?
     </para></listitem><listitem><para>
       Document how named locales error check when filling data
       members. I.e., a fr_FR locale that doesn't have
       numpunct::truename(): does it use "true"? Or is it a blank
       string? What's the convention?
   </para></listitem><listitem><para>
       Explain how locale aliasing happens. When does "de_DE" use "de"
       information? What is the rule for locales composed of just an
       ISO language code (say, "de") and locales with both an ISO
       language code and ISO country code (say, "de_DE").
     </para></listitem><listitem><para>
       What should non-required facet instantiations do?  If the
       generic implementation is provided, then how to end-users
       provide specializations?
   </para></listitem></itemizedlist></section><bibliography xml:id="locales.locale.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
      The GNU C Library
    </citetitle><author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2007</year><holder>FSF</holder></copyright><pagenums>
      Chapters 6 Character Set Handling and 7 Locales and
      Internationalization
    </pagenums></biblioentry><biblioentry><citetitle>
      Correspondence
    </citetitle><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2002</year><holder></holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 14882:1998 Programming languages - C++
    </citetitle><copyright><year>1998</year><holder>ISO</holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 9899:1999 Programming languages - C
    </citetitle><copyright><year>1999</year><holder>ISO</holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://pubs.opengroup.org/onlinepubs/9699919799/">
      System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
	</link></title><copyright><year>2008</year><holder>
	The Open Group/The Institute of Electrical and Electronics
	Engineers, Inc.
      </holder></copyright></biblioentry><biblioentry><citetitle>
      The C++ Programming Language, Special Edition
    </citetitle><author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley, Inc.</holder></copyright><pagenums>Appendix D</pagenums><publisher><publishername>
	Addison Wesley
      </publishername></publisher></biblioentry><biblioentry><citetitle>
      Standard C++ IOStreams and Locales
    </citetitle><subtitle>
      Advanced Programmer's Guide and Reference
    </subtitle><author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author><author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley Longman, Inc.</holder></copyright><publisher><publishername>
	Addison Wesley Longman
      </publishername></publisher></biblioentry></bibliography></section></section><!-- Section 02 : Facet --><section xreflabel="Facets" xml:id="std.localization.facet"><info><title>Facets</title></info><?dbhtml filename="facets.html"?><!--  Section 01 : ctype --><section version="5.0" xreflabel="ctype" xml:id="std.localization.facet.ctype"><?dbhtml filename="ctype.html"?><info><title>ctype</title><keywordset><keyword>ISO C++</keyword><keyword>ctype</keyword></keywordset></info><section xml:id="facet.ctype.impl"><info><title>Implementation</title></info><section xml:id="facet.ctype.impl.spec"><info><title>Specializations</title></info><para>
For the required specialization <classname>codecvt&lt;wchar_t, char, mbstate_t&gt;</classname>,
conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the
<code>LC_CTYPE</code> category implements.
</para><para>
The two required specializations are implemented as follows:
</para><para><code>
ctype&lt;char&gt;
</code></para><para>
This is simple specialization. Implementing this was a piece of cake.
</para><para><code>
ctype&lt;wchar_t&gt;
</code></para><para>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving <function>mcsrtombs</function> for the
conversions between <type>char</type> to <type>wchar_t</type> and
<function>wcsrtombs</function> for conversions between <type>wchar_t</type>
and <type>char</type>.
</para><para>
Neither of these two required specializations deals with Unicode
characters.
</para></section></section><section xml:id="facet.ctype.future"><info><title>Future</title></info><itemizedlist><listitem><para>
   How to deal with the global locale issue?
   </para></listitem><listitem><para>
   How to deal with types other than <type>char</type>, <type>wchar_t</type>?
   </para></listitem><listitem><para>
   Overlap between codecvt/ctype: narrow/widen
   </para></listitem><listitem><para><type>mask</type> typedef in <classname>codecvt_base</classname>,
       argument types in <type>codecvt</type>.  what is know about this type?
   </para></listitem><listitem><para>
   Why mask* argument in codecvt?
   </para></listitem><listitem><para>
       Can this be made (more) generic? is there a simple way to
       straighten out the configure-time mess that is a by-product of
       this class?
   </para></listitem><listitem><para>
       Get the <type>ctype&lt;wchar_t&gt;::mask</type> stuff under control.
       Need to make some kind of static table, and not do lookup every time
       somebody hits the <code>do_is...</code> functions. Too bad we can't
       just redefine <type>mask</type> for
       <classname>ctype&lt;wchar_t&gt;</classname>
   </para></listitem><listitem><para>
       Rename abstract base class. See if just smash-overriding is a
       better approach. Clarify, add sanity to naming.
     </para></listitem></itemizedlist></section><bibliography xml:id="facet.ctype.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
      The GNU C Library
    </citetitle><author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2007</year><holder>FSF</holder></copyright><pagenums>Chapters 6  Character Set Handling and 7 Locales and Internationalization</pagenums></biblioentry><biblioentry><citetitle>
      Correspondence
    </citetitle><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2002</year><holder></holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 14882:1998 Programming languages - C++
    </citetitle><copyright><year>1998</year><holder>ISO</holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 9899:1999 Programming languages - C
    </citetitle><copyright><year>1999</year><holder>ISO</holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://unix.org/version3/ieee_std.html">
	The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
	</link></title><copyright><year>1999</year><holder>
      The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder></copyright></biblioentry><biblioentry><citetitle>
      The C++ Programming Language, Special Edition
    </citetitle><author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley, Inc.</holder></copyright><pagenums>Appendix D</pagenums><publisher><publishername>
	Addison Wesley
      </publishername></publisher></biblioentry><biblioentry><citetitle>
      Standard C++ IOStreams and Locales
    </citetitle><subtitle>
      Advanced Programmer's Guide and Reference
    </subtitle><author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author><author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley Longman, Inc.</holder></copyright><publisher><publishername>
	Addison Wesley Longman
      </publishername></publisher></biblioentry></bibliography></section><!--  Section 02 : codecvt --><section version="5.0" xreflabel="codecvt" xml:id="std.localization.facet.codecvt"><?dbhtml filename="codecvt.html"?><info><title>codecvt</title><keywordset><keyword>ISO C++</keyword><keyword>codecvt</keyword></keywordset></info><para>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
attempts to detail conversions between the implementation-defined wide
characters (hereafter referred to as <type>wchar_t</type>) and the standard
type <type>char</type> that is so beloved in classic <quote>C</quote>
(which can now be referred to as narrow characters.)  This document attempts
to describe how the GNU libstdc++ implementation deals with the conversion
between wide and narrow characters, and also presents a framework for dealing
with the huge number of other encodings that iconv can convert,
including Unicode and UTF8. Design issues and requirements are
addressed, and examples of correct usage for both the required
specializations for wide and narrow characters and the
implementation-provided extended functionality are given.
</para><section xml:id="facet.codecvt.req"><info><title>Requirements</title></info><para>
Around page 425 of the C++ Standard, this charming heading comes into view:
</para><blockquote><para>
22.2.1.5 - Template class codecvt
</para></blockquote><para>
The text around the codecvt definition gives some clues:
</para><blockquote><para><emphasis>
-1- The class <code>codecvt&lt;internT,externT,stateT&gt;</code> is for use
when converting from one codeset to another, such as from wide characters
to multibyte characters, between wide character encodings such as
Unicode and EUC.
</emphasis></para></blockquote><para>
Hmm. So, in some unspecified way, Unicode encodings and
translations between other character sets should be handled by this
class.
</para><blockquote><para><emphasis>
-2- The <type>stateT</type> argument selects the pair of codesets being mapped between.
</emphasis></para></blockquote><para>
Ah ha! Another clue...
</para><blockquote><para><emphasis>
-3- The instantiations required in the Table 51 (lib.locale.category), namely
<classname>codecvt&lt;wchar_t,char,mbstate_t&gt;</classname> and
<classname>codecvt&lt;char,char,mbstate_t&gt;</classname>, convert the
implementation-defined native character set.
<classname>codecvt&lt;char,char,mbstate_t&gt;</classname> implements a
degenerate conversion; it does not convert at all.
<classname>codecvt&lt;wchar_t,char,mbstate_t&gt;</classname> converts between
the native character sets for tiny and wide characters. Instantiations on
<type>mbstate_t</type> perform conversion between encodings known to the library
implementor.  Other encodings can be converted by specializing on a
user-defined <type>stateT</type> type. The <type>stateT</type> object can
contain any state that is useful to communicate to or from the specialized
<function>do_convert</function> member.
</emphasis></para></blockquote><para>
At this point, a couple points become clear:
</para><para>
One: The standard clearly implies that attempts to add non-required
(yet useful and widely used) conversions need to do so through the
third template parameter, <type>stateT</type>.</para><para>
Two: The required conversions, by specifying <type>mbstate_t</type> as the
third template parameter, imply an implementation strategy that is mostly
(or wholly) based on the underlying C library, and the functions
<function>mcsrtombs</function> and <function>wcsrtombs</function> in
particular.</para></section><section xml:id="facet.codecvt.design"><info><title>Design</title></info><section xml:id="codecvt.design.wchar_t_size"><info><title><type>wchar_t</type> Size</title></info><para>
      The simple implementation detail of <type>wchar_t</type>'s size seems to
      repeatedly confound people. Many systems use a two byte,
      unsigned integral type to represent wide characters, and use an
      internal encoding of Unicode or UCS2. (See AIX, Microsoft NT,
      Java, others.) Other systems, use a four byte, unsigned integral
      type to represent wide characters, and use an internal encoding
      of UCS4. (GNU/Linux systems using glibc, in particular.) The C
      programming language (and thus C++) does not specify a specific
      size for the type <type>wchar_t</type>.
    </para><para>
      Thus, portable C++ code cannot assume a byte size (or endianness) either.
    </para></section><section xml:id="codecvt.design.unicode"><info><title>Support for Unicode</title></info><para>
    Probably the most frequently asked question about code conversion
    is: "So dudes, what's the deal with Unicode strings?"
    The dude part is optional, but apparently the usefulness of
    Unicode strings is pretty widely appreciated. The Unicode character
    set (and useful encodings like UTF-8, UCS-4, ISO 8859-10,
    etc etc etc) were not mentioned in the first C++ standard. (The 2011
    standard added support for string literals with different encodings
    and some library facilities for converting between encodings, but the
    notes below have not been updated to reflect that.)
  </para><para>
    A couple of comments:
  </para><para>
    The thought that all one needs to convert between two arbitrary
    codesets is two types and some kind of state argument is
    unfortunate. In particular, encodings may be stateless. The naming
    of the third parameter as <type>stateT</type> is unfortunate, as what is
    really needed is some kind of generalized type that accounts for the
    issues that abstract encodings will need. The minimum information
    that is required includes:
  </para><itemizedlist><listitem><para>
	Identifiers for each of the codesets involved in the
	conversion. For example, using the iconv family of functions
	from the Single Unix Specification (what used to be called
	X/Open) hosted on the GNU/Linux operating system allows
	bi-directional mapping between far more than the following
	tantalizing possibilities:
      </para><para>
	(An edited list taken from <code>`iconv --list`</code> on a
	Red Hat 6.2/Intel system:
      </para><blockquote><programlisting>
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16).
</programlisting></blockquote><para>
For iconv-based implementations, string literals for each of the
encodings (i.e. "UCS-2" and "UTF-8") are necessary,
although for other,
non-iconv implementations a table of enumerated values or some other
mechanism may be required.
</para></listitem><listitem><para>
 Maximum length of the identifying string literal.
</para></listitem><listitem><para>
 Some encodings require explicit endian-ness. As such, some kind
  of endian marker or other byte-order marker will be necessary. See
  "Footnotes for C/C++ developers" in Haible for more information on
  UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
  however implementations, most notably Microsoft, vary.)
</para></listitem><listitem><para>
 Types representing the conversion state, for conversions involving
  the machinery in the "C" library, or the conversion descriptor, for
  conversions using iconv (such as the type iconv_t.)  Note that the
  conversion descriptor encodes more information than a simple encoding
  state type.
</para></listitem><listitem><para>
 Conversion descriptors for both directions of encoding. (i.e., both
  UCS-2 to UTF-8 and UTF-8 to UCS-2.)
</para></listitem><listitem><para>
 Something to indicate if the conversion requested if valid.
</para></listitem><listitem><para>
 Something to represent if the conversion descriptors are valid.
</para></listitem><listitem><para>
 Some way to enforce strict type checking on the internal and
  external types. As part of this, the size of the internal and
  external types will need to be known.
</para></listitem></itemizedlist></section><section xml:id="codecvt.design.issues"><info><title>Other Issues</title></info><para>
In addition, multi-threaded and multi-locale environments also impact
the design and requirements for code conversions. In particular, they
affect the required specialization
<classname>codecvt&lt;wchar_t, char, mbstate_t&gt;</classname>
when implemented using standard "C" functions.
</para><para>
Three problems arise, one big, one of medium importance, and one small.
</para><para>
First, the small: <function>mcsrtombs</function> and
<function>wcsrtombs</function> may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue.
</para><para>
Of medium concern, in the grand scope of things, is that the functions
used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise
incorrect. Yikes!
</para><para>
The last, and fundamental problem, is the assumption of a global
locale for all the "C" functions referenced above. For something like
C++ iostreams (where codecvt is explicitly used) the notion of
multiple locales is fundamental. In practice, most users may not run
into this limitation. However, as a quality of implementation issue,
the GNU C++ library would like to offer a solution that allows
multiple locales and or simultaneous usage with computationally
correct results. In short, libstdc++ is trying to offer, as an
option, a high-quality implementation, damn the additional complexity!
</para><para>
For the required specialization
<classname>codecvt&lt;wchar_t, char, mbstate_t&gt;</classname>,
conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements.
</para></section></section><section xml:id="facet.codecvt.impl"><info><title>Implementation</title></info><para>
The two required specializations are implemented as follows:
</para><para><code>
codecvt&lt;char, char, mbstate_t&gt;
</code></para><para>
This is a degenerate (i.e., does nothing) specialization. Implementing
this was a piece of cake.
</para><para><code>
codecvt&lt;char, wchar_t, mbstate_t&gt;
</code></para><para>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving <function>mcsrtombs</function> for the conversions
between <type>char</type> to <type>wchar_t</type> and
<function>wcsrtombs</function> for conversions between <type>wchar_t</type>
and <type>char</type>.
</para><para>
Neither of these two required specializations deals with Unicode
characters. As such, libstdc++ implements a partial specialization
of the <type>codecvt</type> class with an iconv wrapper class,
<classname>encoding_state</classname> as the third template parameter.
</para><para>
This implementation should be standards conformant. First of all, the
standard explicitly points out that instantiations on the third
template parameter, <type>stateT</type>, are the proper way to implement
non-required conversions. Second of all, the standard says (in Chapter
17) that partial specializations of required classes are A-OK. Third
of all, the requirements for the <type>stateT</type> type elsewhere in the
standard (see 21.1.2 traits typedefs) only indicate that this type be copy
constructible.
</para><para>
As such, the type <type>encoding_state</type> is defined as a non-templatized,
POD type to be used as the third type of a <type>codecvt</type> instantiation.
This type is just a wrapper class for iconv, and provides an easy interface
to iconv functionality.
</para><para>
There are two constructors for <type>encoding_state</type>:
</para><para><code>
encoding_state() : __in_desc(0), __out_desc(0)
</code></para><para>
This default constructor sets the internal encoding to some default
(currently UCS4) and the external encoding to whatever is returned by
<code>nl_langinfo(CODESET)</code>.
</para><para><code>
encoding_state(const char* __int, const char* __ext)
</code></para><para>
This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for
either argument.
</para><para>
One of the issues with iconv is that the string literals identifying
conversions are not standardized. Because of this, the thought of
mandating and/or enforcing some set of pre-determined valid
identifiers seems iffy: thus, a more practical (and non-migraine
inducing) strategy was implemented: end-users can specify any string
(subject to a pre-determined length qualifier, currently 32 bytes) for
encodings. It is up to the user to make sure that these strings are
valid on the target system.
</para><para><code>
void
_M_init()
</code></para><para>
Strangely enough, this member function attempts to open conversion
descriptors for a given encoding_state object. If the conversion
descriptors are not valid, the conversion descriptors returned will
not be valid and the resulting calls to the codecvt conversion
functions will return error.
</para><para><code>
bool
_M_good()
</code></para><para>
Provides a way to see if the given <type>encoding_state</type> object has been
properly initialized. If the string literals describing the desired
internal and external encoding are not valid, initialization will
fail, and this will return false. If the internal and external
encodings are valid, but <function>iconv_open</function> could not allocate
conversion descriptors, this will also return false. Otherwise, the object is
ready to convert and will return true.
</para><para><code>
encoding_state(const encoding_state&amp;)
</code></para><para>
As iconv allocates memory and sets up conversion descriptors, the copy
constructor can only copy the member data pertaining to the internal
and external code conversions, and not the conversion descriptors
themselves.
</para><para>
Definitions for all the required codecvt member functions are provided
for this specialization, and usage of <code>codecvt&lt;<replaceable>internal
character type</replaceable>, <replaceable>external character type</replaceable>, <replaceable>encoding_state</replaceable>&gt;</code> is consistent with other
codecvt usage.
</para></section><section xml:id="facet.codecvt.use"><info><title>Use</title></info><para>A conversion involving a string literal.</para><programlisting>
  typedef codecvt_base::result                  result;
  typedef unsigned short                        unicode_t;
  typedef unicode_t                             int_type;
  typedef char                                  ext_type;
  typedef encoding_state                          state_type;
  typedef codecvt&lt;int_type, ext_type, state_type&gt; unicode_codecvt;

  const ext_type*       e_lit = "black pearl jasmine tea";
  int                   size = strlen(e_lit);
  int_type              i_lit_base[24] =
  { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
    27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
    25856, 24832, 2560
  };
  const int_type*       i_lit = i_lit_base;
  const ext_type*       efrom_next;
  const int_type*       ifrom_next;
  ext_type*             e_arr = new ext_type[size + 1];
  ext_type*             eto_next;
  int_type*             i_arr = new int_type[size + 1];
  int_type*             ito_next;

  // construct a locale object with the specialized facet.
  locale                loc(locale::classic(), new unicode_codecvt);
  // sanity check the constructed locale has the specialized facet.
  VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
  const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
  // convert between const char* and unicode strings
  unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
  initialize_state(state01);
  result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
		     i_arr, i_arr + size, ito_next);
  VERIFY( r1 == codecvt_base::ok );
  VERIFY( !int_traits::compare(i_arr, i_lit, size) );
  VERIFY( efrom_next == e_lit + size );
  VERIFY( ito_next == i_arr + size );
</programlisting></section><section xml:id="facet.codecvt.future"><info><title>Future</title></info><itemizedlist><listitem><para>
   a. things that are sketchy, or remain unimplemented:
      do_encoding, max_length and length member functions
      are only weakly implemented. I have no idea how to do
      this correctly, and in a generic manner.  Nathan?
</para></listitem><listitem><para>
   b. conversions involving <type>std::string</type>
  </para><itemizedlist><listitem><para>
      how should operators != and == work for string of
      different/same encoding?
      </para></listitem><listitem><para>
      what is equal? A byte by byte comparison or an
      encoding then byte comparison?
      </para></listitem><listitem><para>
      conversions between narrow, wide, and unicode strings
      </para></listitem></itemizedlist></listitem><listitem><para>
   c. conversions involving std::filebuf and std::ostream
</para><itemizedlist><listitem><para>
      how to initialize the state object in a
      standards-conformant manner?
      </para></listitem><listitem><para>
      how to synchronize the "C" and "C++"
      conversion information?
      </para></listitem><listitem><para>
      wchar_t/char internal buffers and conversions between
      internal/external buffers?
      </para></listitem></itemizedlist></listitem></itemizedlist></section><bibliography xml:id="facet.codecvt.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
      The GNU C Library
    </citetitle><author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2007</year><holder>FSF</holder></copyright><pagenums>
      Chapters 6 Character Set Handling and 7 Locales and Internationalization
    </pagenums></biblioentry><biblioentry><citetitle>
      Correspondence
    </citetitle><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2002</year><holder></holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 14882:1998 Programming languages - C++
    </citetitle><copyright><year>1998</year><holder>ISO</holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 9899:1999 Programming languages - C
    </citetitle><copyright><year>1999</year><holder>ISO</holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://pubs.opengroup.org/onlinepubs/9699919799/">
      System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
	</link></title><copyright><year>2008</year><holder>
	The Open Group/The Institute of Electrical and Electronics
	Engineers, Inc.
      </holder></copyright></biblioentry><biblioentry><citetitle>
      The C++ Programming Language, Special Edition
    </citetitle><author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley, Inc.</holder></copyright><pagenums>Appendix D</pagenums><publisher><publishername>
	Addison Wesley
      </publishername></publisher></biblioentry><biblioentry><citetitle>
      Standard C++ IOStreams and Locales
    </citetitle><subtitle>
      Advanced Programmer's Guide and Reference
    </subtitle><author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author><author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley Longman, Inc.</holder></copyright><publisher><publishername>
	Addison Wesley Longman
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.lysator.liu.se/c/na1.html">
      A brief description of Normative Addendum 1
	</link></title><author><personname><surname>Feather</surname><firstname>Clive</firstname></personname></author><pagenums>Extended Character Sets</pagenums></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tldp.org/HOWTO/Unicode-HOWTO.html">
	  The Unicode HOWTO
	</link></title><author><personname><surname>Haible</surname><firstname>Bruno</firstname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.cl.cam.ac.uk/~mgk25/unicode.html">
      UTF-8 and Unicode FAQ for Unix/Linux
	</link></title><author><personname><surname>Khun</surname><firstname>Markus</firstname></personname></author></biblioentry></bibliography></section><!--  Section 03 : messages  --><section version="5.0" xreflabel="Messages" xml:id="std.localization.facet.messages"><?dbhtml filename="messages.html"?><info><title>messages</title><keywordset><keyword>ISO C++</keyword><keyword>messages</keyword></keywordset></info><para>
The <classname>std::messages</classname> facet implements message retrieval functionality
equivalent to Java's <classname>java.text.MessageFormat</classname> using either GNU <function>gettext</function>
or IEEE 1003.1-200 functions.
</para><section xml:id="facet.messages.req"><info><title>Requirements</title></info><para>
The <classname>std::messages</classname> facet is probably the most vaguely defined facet in
the standard library. It's assumed that this facility was built into
the standard library in order to convert string literals from one
locale to the other. For instance, converting the "C" locale's
<code>const char* c = "please"</code> to a German-localized <code>"bitte"</code>
during program execution.
</para><blockquote><para>
22.2.7.1 - Template class messages [lib.locale.messages]
</para></blockquote><para>
This class has three public member functions, which directly
correspond to three protected virtual member functions.
</para><para>
The public member functions are:
</para><para><code>catalog open(const string&amp;, const locale&amp;) const</code></para><para><code>string_type get(catalog, int, int, const string_type&amp;) const</code></para><para><code>void close(catalog) const</code></para><para>
While the virtual functions are:
</para><para><code>catalog do_open(const string&amp; name, const locale&amp; loc) const</code></para><blockquote><para><emphasis>
-1- Returns: A value that may be passed to <code>get()</code> to retrieve a
message, from the message catalog identified by the string <code>name</code>
according to an implementation-defined mapping. The result can be used
until it is passed to <code>close()</code>.  Returns a value less than 0 if no such
catalog can be opened.
</emphasis></para></blockquote><para><code>string_type do_get(catalog cat, int set , int msgid, const string_type&amp; dfault) const</code></para><blockquote><para><emphasis>
-3- Requires: A catalog <code>cat</code> obtained from <code>open()</code> and not yet closed.
-4- Returns: A message identified by arguments <code>set</code>, <code>msgid</code>, and <code>dfault</code>,
according to an implementation-defined mapping. If no such message can
be found, returns <code>dfault</code>.
</emphasis></para></blockquote><para><code>void do_close(catalog cat) const</code></para><blockquote><para><emphasis>
-5- Requires: A catalog cat obtained from <code>open()</code> and not yet closed.
-6- Effects: Releases unspecified resources associated with <code>cat</code>.
-7- Notes: The limit on such resources, if any, is implementation-defined.
</emphasis></para></blockquote></section><section xml:id="facet.messages.design"><info><title>Design</title></info><para>
A couple of notes on the standard.
</para><para>
First, why is <code>messages_base::catalog</code> specified as a typedef
to int? This makes sense for implementations that use
<code>catopen</code> and define <code>nl_catd</code> as int, but not for
others. Fortunately, it's not heavily used and so only a minor irritant.
This has been reported as a possible defect in the standard (LWG 2028).
</para><para>
Second, by making the member functions <code>const</code>, it is
impossible to save state in them. Thus, storing away information used
in the 'open' member function for use in 'get' is impossible. This is
unfortunate.
</para><para>
The 'open' member function in particular seems to be oddly
designed. The signature seems quite peculiar. Why specify a <code>const
string&amp; </code> argument, for instance, instead of just <code>const
char*</code>? Or, why specify a <code>const locale&amp;</code> argument that is
to be used in the 'get' member function? How, exactly, is this locale
argument useful? What was the intent? It might make sense if a locale
argument was associated with a given default message string in the
'open' member function, for instance. Quite murky and unclear, on
reflection.
</para><para>
Lastly, it seems odd that messages, which explicitly require code
conversion, don't use the codecvt facet. Because the messages facet
has only one template parameter, it is assumed that ctype, and not
codecvt, is to be used to convert between character sets.
</para><para>
It is implicitly assumed that the locale for the default message
string in 'get' is in the "C" locale. Thus, all source code is assumed
to be written in English, so translations are always from "en_US" to
other, explicitly named locales.
</para></section><section xml:id="facet.messages.impl"><info><title>Implementation</title></info><section xml:id="messages.impl.models"><info><title>Models</title></info><para>
    This is a relatively simple class, on the face of it. The standard
    specifies very little in concrete terms, so generic
    implementations that are conforming yet do very little are the
    norm. Adding functionality that would be useful to programmers and
    comparable to Java's java.text.MessageFormat takes a bit of work,
    and is highly dependent on the capabilities of the underlying
    operating system.
  </para><para>
    Three different mechanisms have been provided, selectable via
    configure flags:
  </para><itemizedlist><listitem><para>
       generic
     </para><para>
       This model does very little, and is what is used by default.
     </para></listitem><listitem><para>
       gnu
     </para><para>
       The gnu model is complete and fully tested. It's based on the
       GNU gettext package, which is part of glibc. It uses the
       functions <code>textdomain, bindtextdomain, gettext</code> to
       implement full functionality. Creating message catalogs is a
       relatively straight-forward process and is lightly documented
       below, and fully documented in gettext's distributed
       documentation.
     </para></listitem><listitem><para>
       ieee_1003.1-200x
     </para><para>
       This is a complete, though untested, implementation based on
       the IEEE standard. The functions <code>catopen, catgets,
       catclose</code> are used to retrieve locale-specific messages
       given the appropriate message catalogs that have been
       constructed for their use. Note, the script <code>
       po2msg.sed</code> that is part of the gettext distribution can
       convert gettext catalogs into catalogs that
       <code>catopen</code> can use.
   </para></listitem></itemizedlist><para>
A new, standards-conformant non-virtual member function signature was
added for 'open' so that a directory could be specified with a given
message catalog. This simplifies calling conventions for the gnu
model.
</para></section><section xml:id="messages.impl.gnu"><info><title>The GNU Model</title></info><para>
    The messages facet, because it is retrieving and converting
    between characters sets, depends on the ctype and perhaps the
    codecvt facet in a given locale. In addition, underlying "C"
    library locale support is necessary for more than just the
    <code>LC_MESSAGES</code> mask: <code>LC_CTYPE</code> is also
    necessary. To avoid any unpleasantness, all bits of the "C" mask
    (i.e. <code>LC_ALL</code>) are set before retrieving messages.
  </para><para>
    Making the message catalogs can be initially tricky, but become
    quite simple with practice. For complete info, see the gettext
    documentation. Here's an idea of what is required:
  </para><itemizedlist><listitem><para>
       Make a source file with the required string literals that need
       to be translated. See <code>intl/string_literals.cc</code> for
       an example.
     </para></listitem><listitem><para>
       Make initial catalog (see "4 Making the PO Template File" from
       the gettext docs).</para><para><code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code></para></listitem><listitem><para>Make language and country-specific locale catalogs.</para><para><code>cp libstdc++.pot fr_FR.po</code></para><para><code>cp libstdc++.pot de_DE.po</code></para></listitem><listitem><para>
       Edit localized catalogs in emacs so that strings are
       translated.
     </para><para><code>emacs fr_FR.po</code></para></listitem><listitem><para>Make the binary mo files.</para><para><code>msgfmt fr_FR.po -o fr_FR.mo</code></para><para><code>msgfmt de_DE.po -o de_DE.mo</code></para></listitem><listitem><para>Copy the binary files into the correct directory structure.</para><para><code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code></para><para><code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code></para></listitem><listitem><para>Use the new message catalogs.</para><para><code>locale loc_de("de_DE");</code></para><para><code>
   use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
   </code></para></listitem></itemizedlist></section></section><section xml:id="facet.messages.use"><info><title>Use</title></info><para>
   A simple example using the GNU model of message conversion.
 </para><programlisting>
#include &lt;iostream&gt;
#include &lt;locale&gt;
using namespace std;

void test01()
{
  typedef messages&lt;char&gt;::catalog catalog;
  const char* dir =
  "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
  const locale loc_de("de_DE");
  const messages&lt;char&gt;&amp; mssg_de = use_facet&lt;messages&lt;char&gt; &gt;(loc_de);

  catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
  string s01 = mssg_de.get(cat_de, 0, 0, "please");
  string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
  cout &lt;&lt; "please in german:" &lt;&lt; s01 &lt;&lt; '\n';
  cout &lt;&lt; "thank you in german:" &lt;&lt; s02 &lt;&lt; '\n';
  mssg_de.close(cat_de);
}
</programlisting></section><section xml:id="facet.messages.future"><info><title>Future</title></info><itemizedlist><listitem><para>
    Things that are sketchy, or remain unimplemented:
  </para><itemizedlist><listitem><para>
	  _M_convert_from_char, _M_convert_to_char are in flux,
	  depending on how the library ends up doing character set
	  conversions. It might not be possible to do a real character
	  set based conversion, due to the fact that the template
	  parameter for messages is not enough to instantiate the
	  codecvt facet (1 supplied, need at least 2 but would prefer
	  3).
	</para></listitem><listitem><para>
	  There are issues with gettext needing the global locale set
	  to extract a message. This dependence on the global locale
	  makes the current "gnu" model non MT-safe. Future versions
	  of glibc, i.e. glibc 2.3.x will fix this, and the C++ library
	  bits are already in place.
	</para></listitem></itemizedlist></listitem><listitem><para>
    Development versions of the GNU "C" library, glibc 2.3 will allow
    a more efficient, MT implementation of std::messages, and will
    allow the removal of the _M_name_messages data member. If this is
    done, it will change the library ABI. The C++ parts to support
    glibc 2.3 have already been coded, but are not in use: once this
    version of the "C" library is released, the marked parts of the
    messages implementation can be switched over to the new "C"
    library functionality.
  </para></listitem><listitem><para>
    At some point in the near future, std::numpunct will probably use
    std::messages facilities to implement truename/falsename
    correctly. This is currently not done, but entries in
    libstdc++.pot have already been made for "true" and "false" string
    literals, so all that remains is the std::numpunct coding and the
    configure/make hassles to make the installed library search its
    own catalog. Currently the libstdc++.mo catalog is only searched
    for the testsuite cases involving messages members.
  </para></listitem><listitem><para> The following member functions:</para><para><code>
	catalog
	open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
   </code></para><para><code>
   catalog
   open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
   </code></para><para>
   Don't actually return a "value less than 0 if no such catalog
   can be opened" as required by the standard in the "gnu"
   model. As of this writing, it is unknown how to query to see
   if a specified message catalog exists using the gettext
   package.
   </para></listitem></itemizedlist></section><bibliography xml:id="facet.messages.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
      The GNU C Library
    </citetitle><author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2007</year><holder>FSF</holder></copyright><pagenums>Chapters 6 Character Set Handling, and 7 Locales and Internationalization
    </pagenums></biblioentry><biblioentry><citetitle>
      Correspondence
    </citetitle><author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author><copyright><year>2002</year><holder></holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 14882:1998 Programming languages - C++
    </citetitle><copyright><year>1998</year><holder>ISO</holder></copyright></biblioentry><biblioentry><citetitle>
      ISO/IEC 9899:1999 Programming languages - C
    </citetitle><copyright><year>1999</year><holder>ISO</holder></copyright></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://pubs.opengroup.org/onlinepubs/9699919799/">
      System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
	</link></title><copyright><year>2008</year><holder>
	The Open Group/The Institute of Electrical and Electronics
	Engineers, Inc.
      </holder></copyright></biblioentry><biblioentry><citetitle>
      The C++ Programming Language, Special Edition
    </citetitle><author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley, Inc.</holder></copyright><pagenums>Appendix D</pagenums><publisher><publishername>
	Addison Wesley
      </publishername></publisher></biblioentry><biblioentry><citetitle>
      Standard C++ IOStreams and Locales
    </citetitle><subtitle>
      Advanced Programmer's Guide and Reference
    </subtitle><author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author><author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author><copyright><year>2000</year><holder>Addison Wesley Longman, Inc.</holder></copyright><publisher><publishername>
	Addison Wesley Longman
      </publishername></publisher></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oracle.com/en/java/">
	API Specifications, Java Platform
	</link></title><pagenums>java.util.Properties, java.text.MessageFormat,
java.util.Locale, java.util.ResourceBundle
    </pagenums></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/software/gettext/">
      GNU gettext tools, version 0.10.38, Native Language Support
      Library and Tools.
	</link></title></biblioentry></bibliography></section></section><!-- Section 03 : Interacting with C --></chapter><!-- Chapter 06 : Containers --><chapter version="5.0" xreflabel="Containers" xml:id="std.containers"><?dbhtml filename="containers.html"?><info><title>
  Containers
  <indexterm><primary>Containers</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Sect1 01 : Sequences --><section xreflabel="Sequences" xml:id="std.containers.sequences"><info><title>Sequences</title></info><?dbhtml filename="sequences.html"?><section xreflabel="list" xml:id="containers.sequences.list"><info><title>list</title></info><?dbhtml filename="list.html"?><section xreflabel="list::size() is O(n)" xml:id="sequences.list.size"><info><title>list::size() is O(n)</title></info><para>
     Yes it is, at least using the <link linkend="manual.intro.using.abi">old
     ABI</link>, and that's okay.  This is a decision that we preserved
     when we imported SGI's STL implementation.  The following is
     quoted from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20161222192301/http://www.sgi.com/tech/stl/FAQ.html">their FAQ</link>:
   </para><blockquote><para>
       The size() member function, for list and slist, takes time
       proportional to the number of elements in the list.  This was a
       deliberate tradeoff.  The only way to get a constant-time
       size() for linked lists would be to maintain an extra member
       variable containing the list's size.  This would require taking
       extra time to update that variable (it would make splice() a
       linear time operation, for example), and it would also make the
       list larger.  Many list algorithms don't require that extra
       word (algorithms that do require it might do better with
       vectors than with lists), and, when it is necessary to maintain
       an explicit size count, it's something that users can do
       themselves.
     </para><para>
       This choice is permitted by the C++ standard. The standard says
       that size() <quote>should</quote> be constant time, and
       <quote>should</quote> does not mean the same thing as
       <quote>shall</quote>.  This is the officially recommended ISO
       wording for saying that an implementation is supposed to do
       something unless there is a good reason not to.
      </para><para>
	One implication of linear time size(): you should never write
      </para><programlisting>
	 if (L.size() == 0)
	     ...
	 </programlisting><para>
	 Instead, you should write
	 </para><programlisting>
	 if (L.empty())
	     ...
	 </programlisting></blockquote></section></section></section><!-- Sect1 02 : Associative --><section xreflabel="Associative" xml:id="std.containers.associative"><info><title>Associative</title></info><?dbhtml filename="associative.html"?><section xreflabel="Insertion Hints" xml:id="containers.associative.insert_hints"><info><title>Insertion Hints</title></info><para>
     Section [23.1.2], Table 69, of the C++ standard lists this
     function for all of the associative containers (map, set, etc):
   </para><programlisting>
      a.insert(p,t);
</programlisting><para>
     where 'p' is an iterator into the container 'a', and 't' is the
     item to insert.  The standard says that <quote><code>t</code> is
     inserted as close as possible to the position just prior to
     <code>p</code>.</quote> (Library DR #233 addresses this topic,
     referring to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html">N1780</link>.
     Since version 4.2 GCC implements the resolution to DR 233, so
     that insertions happen as close as possible to the hint. For
     earlier releases the hint was only used as described below.
   </para><para>
     Here we'll describe how the hinting works in the libstdc++
     implementation, and what you need to do in order to take
     advantage of it.  (Insertions can change from logarithmic
     complexity to amortized constant time, if the hint is properly
     used.)  Also, since the current implementation is based on the
     SGI STL one, these points may hold true for other library
     implementations also, since the HP/SGI code is used in a lot of
     places.
   </para><para>
     In the following text, the phrases <emphasis>greater
     than</emphasis> and <emphasis>less than</emphasis> refer to the
     results of the strict weak ordering imposed on the container by
     its comparison object, which defaults to (basically)
     <quote>&lt;</quote>.  Using those phrases is semantically sloppy,
     but I didn't want to get bogged down in syntax.  I assume that if
     you are intelligent enough to use your own comparison objects,
     you are also intelligent enough to assign <quote>greater</quote>
     and <quote>lesser</quote> their new meanings in the next
     paragraph.  *grin*
   </para><para>
     If the <code>hint</code> parameter ('p' above) is equivalent to:
   </para><itemizedlist><listitem><para><code>begin()</code>, then the item being inserted should
	  have a key less than all the other keys in the container.
	  The item will be inserted at the beginning of the container,
	  becoming the new entry at <code>begin()</code>.
      </para></listitem><listitem><para><code>end()</code>, then the item being inserted should have
	  a key greater than all the other keys in the container.  The
	  item will be inserted at the end of the container, becoming
	  the new entry before <code>end()</code>.
      </para></listitem><listitem><para>
	  neither <code>begin()</code> nor <code>end()</code>, then:
	  Let <code>h</code> be the entry in the container pointed to
	  by <code>hint</code>, that is, <code>h = *hint</code>.  Then
	  the item being inserted should have a key less than that of
	  <code>h</code>, and greater than that of the item preceding
	  <code>h</code>.  The new item will be inserted between
	  <code>h</code> and <code>h</code>'s predecessor.
	  </para></listitem></itemizedlist><para>
     For <code>multimap</code> and <code>multiset</code>, the
     restrictions are slightly looser: <quote>greater than</quote>
     should be replaced by <quote>not less than</quote>and <quote>less
     than</quote> should be replaced by <quote>not greater
     than.</quote> (Why not replace greater with
     greater-than-or-equal-to?  You probably could in your head, but
     the mathematicians will tell you that it isn't the same thing.)
   </para><para>
     If the conditions are not met, then the hint is not used, and the
     insertion proceeds as if you had called <code> a.insert(t)
     </code> instead.  (<emphasis>Note </emphasis> that GCC releases
     prior to 3.0.2 had a bug in the case with <code>hint ==
     begin()</code> for the <code>map</code> and <code>set</code>
     classes.  You should not use a hint argument in those releases.)
   </para><para>
     This behavior goes well with other containers'
     <code>insert()</code> functions which take an iterator: if used,
     the new item will be inserted before the iterator passed as an
     argument, same as the other containers.
   </para><para><emphasis>Note </emphasis> also that the hint in this
     implementation is a one-shot.  The older insertion-with-hint
     routines check the immediately surrounding entries to ensure that
     the new item would in fact belong there.  If the hint does not
     point to the correct place, then no further local searching is
     done; the search begins from scratch in logarithmic time.
   </para></section><section xreflabel="bitset" xml:id="containers.associative.bitset"><info><title>bitset</title></info><?dbhtml filename="bitset.html"?><section xreflabel="Variable" xml:id="associative.bitset.size_variable"><info><title>Size Variable</title></info><para>
	No, you cannot write code of the form
      </para><!-- Careful, the leading spaces in PRE show up directly. --><programlisting>
      #include &lt;bitset&gt;

      void foo (size_t n)
      {
	  std::bitset&lt;n&gt;   bits;
	  ....
      }
</programlisting><para>
     because <code>n</code> must be known at compile time.  Your
     compiler is correct; it is not a bug.  That's the way templates
     work.  (Yes, it <emphasis>is</emphasis> a feature.)
   </para><para>
     There are a couple of ways to handle this kind of thing.  Please
     consider all of them before passing judgement.  They include, in
     no particular order:
   </para><itemizedlist><listitem><para>A very large N in <code>bitset&lt;N&gt;</code>.</para></listitem><listitem><para>A container&lt;bool&gt;.</para></listitem><listitem><para>Extremely weird solutions.</para></listitem></itemizedlist><para><emphasis>A very large N in
     <code>bitset&lt;N&gt;</code>.  </emphasis> It has been
     pointed out a few times in newsgroups that N bits only takes up
     (N/8) bytes on most systems, and division by a factor of eight is
     pretty impressive when speaking of memory.  Half a megabyte given
     over to a bitset (recall that there is zero space overhead for
     housekeeping info; it is known at compile time exactly how large
     the set is) will hold over four million bits.  If you're using
     those bits as status flags (e.g.,
     <quote>changed</quote>/<quote>unchanged</quote> flags), that's a
     <emphasis>lot</emphasis> of state.
   </para><para>
     You can then keep track of the <quote>maximum bit used</quote>
     during some testing runs on representative data, make note of how
     many of those bits really need to be there, and then reduce N to
     a smaller number.  Leave some extra space, of course.  (If you
     plan to write code like the incorrect example above, where the
     bitset is a local variable, then you may have to talk your
     compiler into allowing that much stack space; there may be zero
     space overhead, but it's all allocated inside the object.)
   </para><para><emphasis>A container&lt;bool&gt;.  </emphasis> The
     Committee made provision for the space savings possible with that
     (N/8) usage previously mentioned, so that you don't have to do
     wasteful things like <code>Container&lt;char&gt;</code> or
     <code>Container&lt;short int&gt;</code>.  Specifically,
     <code>vector&lt;bool&gt;</code> is required to be specialized for
     that space savings.
   </para><para>
     The problem is that <code>vector&lt;bool&gt;</code> doesn't
     behave like a normal vector anymore.  There have been
     journal articles which discuss the problems (the ones by Herb
     Sutter in the May and July/August 1999 issues of C++ Report cover
     it well).  Future revisions of the ISO C++ Standard will change
     the requirement for <code>vector&lt;bool&gt;</code>
     specialization.  In the meantime, <code>deque&lt;bool&gt;</code>
     is recommended (although its behavior is sane, you probably will
     not get the space savings, but the allocation scheme is different
     than that of vector).
   </para><para><emphasis>Extremely weird solutions.  </emphasis> If
     you have access to the compiler and linker at runtime, you can do
     something insane, like figuring out just how many bits you need,
     then writing a temporary source code file.  That file contains an
     instantiation of <code>bitset</code> for the required number of
     bits, inside some wrapper functions with unchanging signatures.
     Have your program then call the compiler on that file using
     Position Independent Code, then open the newly-created object
     file and load those wrapper functions.  You'll have an
     instantiation of <code>bitset&lt;N&gt;</code> for the exact
     <code>N</code> that you need at the time.  Don't forget to delete
     the temporary files.  (Yes, this <emphasis>can</emphasis> be, and
     <emphasis>has been</emphasis>, done.)
   </para><!-- I wonder if this next paragraph will get me in trouble... --><para>
     This would be the approach of either a visionary genius or a
     raving lunatic, depending on your programming and management
     style.  Probably the latter.
   </para><para>
     Which of the above techniques you use, if any, are up to you and
     your intended application.  Some time/space profiling is
     indicated if it really matters (don't just guess).  And, if you
     manage to do anything along the lines of the third category, the
     author would love to hear from you...
   </para><para>
     Also note that the implementation of bitset used in libstdc++ has
     <link linkend="manual.ext.containers.sgi">some extensions</link>.
   </para></section><section xreflabel="Type String" xml:id="associative.bitset.type_string"><info><title>Type String</title></info><para>
      </para><para>
     Bitmasks do not take char* nor const char* arguments in their
     constructors.  This is something of an accident, but you can read
     about the problem: follow the library's <quote>Links</quote> from
     the homepage, and from the C++ information <quote>defect
     reflector</quote> link, select the library issues list.  Issue
     number 116 describes the problem.
   </para><para>
     For now you can simply make a temporary string object using the
     constructor expression:
   </para><programlisting>
      std::bitset&lt;5&gt; b ( std::string("10110") );
</programlisting><para>
     instead of
   </para><programlisting>
      std::bitset&lt;5&gt; b ( "10110" );    // invalid
</programlisting></section></section></section><!-- Sect1 03 : Unordered Associative --><section xreflabel="Unordered" xml:id="std.containers.unordered"><info><title>Unordered Associative</title></info><?dbhtml filename="unordered_associative.html"?><section xreflabel="Insertion Hints" xml:id="containers.unordered.insert_hints"><info><title>Insertion Hints</title></info><para>
     Here is how the hinting works in the libstdc++ implementation of unordered
     containers, and the rationale behind this behavior.
    </para><para>
      In the following text, the phrase <emphasis>equivalent to</emphasis> refer
      to the result of the invocation of the equal predicate imposed on the
      container by its <code>key_equal</code> object, which defaults to (basically)
      <quote>==</quote>.
    </para><para>
      Unordered containers can be seen as a <code>std::vector</code> of
      <code>std::forward_list</code>. The <code>std::vector</code> represents
      the buckets and each <code>std::forward_list</code> is the list of nodes
      belonging to the same bucket. When inserting an element in such a data
      structure we first need to compute the element hash code to find the
      bucket to insert the element to, the second step depends on the uniqueness
      of elements in the container.
    </para><para>
      In the case of <code>std::unordered_set</code> and
      <code>std::unordered_map</code> you need to look through all bucket's
      elements for an equivalent one. If there is none the insertion can be
      achieved, otherwise the insertion fails. As we always need to loop though
      all bucket's elements, the hint doesn't tell us if the element is already
      present, and we don't have any constraint on where the new element is to
      be inserted, the hint won't be of any help and will then be ignored.
    </para><para>
      In the case of <code>std::unordered_multiset</code>
      and <code>std::unordered_multimap</code> equivalent elements must be
      linked together so that the <code>equal_range(const key_type&amp;)</code>
      can return the range of iterators pointing to all equivalent elements.
      This is where hinting can be used to point to another equivalent element
      already part of the container and so skip all non equivalent elements of
      the bucket. So to be useful the hint shall point to an element equivalent
      to the one being inserted. The new element will be then inserted right
      after the hint. Note that because of an implementation detail inserting
      after a node can require updating the bucket of the following node. To
      check if the next bucket is to be modified we need to compute the
      following node's hash code. So if you want your hint to be really efficient
      it should be followed by another equivalent element, the implementation
      will detect this equivalence and won't compute next element hash code.
    </para><para>
      It is highly advised to start using unordered containers hints only if you
      have a benchmark that will demonstrate the benefit of it. If you don't then do
      not use hints, it might do more harm than good.
    </para></section><section xreflabel="Hash" xml:id="containers.unordered.hash"><info><title>Hash Code</title></info><section xreflabel="Cache" xml:id="containers.unordered.cache"><info><title>Hash Code Caching Policy</title></info><para>
      The unordered containers in libstdc++ may cache the hash code for each
      element alongside the element itself. In some cases not recalculating
      the hash code every time it's needed can improve performance, but the
      additional memory overhead can also reduce performance, so whether an
      unordered associative container caches the hash code or not depends on
      the properties described below.
    </para><para>
      The C++ standard requires that <code>erase</code> and <code>swap</code>
      operations must not throw exceptions. Those operations might need an
      element's hash code, but cannot use the hash function if it could
      throw.
      This means the hash codes will be cached unless the hash function
      has a non-throwing exception specification such as <code>noexcept</code>
      or <code>throw()</code>.
    </para><para>
      If the hash function is non-throwing then libstdc++ doesn't need to
      cache the hash code for
      correctness, but might still do so for performance if computing a
      hash code is an expensive operation, as it may be for arbitrarily
      long strings.
      As an extension libstdc++ provides a trait type to describe whether
      a hash function is fast. By default hash functions are assumed to be
      fast unless the trait is specialized for the hash function and the
      trait's value is false, in which case the hash code will always be
      cached.
      The trait can be specialized for user-defined hash functions like so:
    </para><programlisting>
      #include &lt;unordered_set&gt;

      struct hasher
      {
        std::size_t operator()(int val) const noexcept
        {
          // Some very slow computation of a hash code from an int !
          ...
        }
      }

      namespace std
      {
        template&lt;&gt;
          struct __is_fast_hash&lt;hasher&gt; : std::false_type
          { };
      }
</programlisting></section></section></section><!-- Sect1 04 : Interacting with C --><section xreflabel="Interacting with C" xml:id="std.containers.c"><info><title>Interacting with C</title></info><?dbhtml filename="containers_and_c.html"?><section xreflabel="Containers vs. Arrays" xml:id="containers.c.vs_array"><info><title>Containers vs. Arrays</title></info><para>
     You're writing some code and can't decide whether to use builtin
     arrays or some kind of container.  There are compelling reasons
     to use one of the container classes, but you're afraid that
     you'll eventually run into difficulties, change everything back
     to arrays, and then have to change all the code that uses those
     data types to keep up with the change.
   </para><para>
     If your code makes use of the standard algorithms, this isn't as
     scary as it sounds.  The algorithms don't know, nor care, about
     the kind of <quote>container</quote> on which they work, since
     the algorithms are only given endpoints to work with.  For the
     container classes, these are iterators (usually
     <code>begin()</code> and <code>end()</code>, but not always).
     For builtin arrays, these are the address of the first element
     and the <link linkend="iterators.predefined.end">past-the-end</link> element.
   </para><para>
     Some very simple wrapper functions can hide all of that from the
     rest of the code.  For example, a pair of functions called
     <code>beginof</code> can be written, one that takes an array,
     another that takes a vector.  The first returns a pointer to the
     first element, and the second returns the vector's
     <code>begin()</code> iterator.
   </para><para>
     The functions should be made template functions, and should also
     be declared inline.  As pointed out in the comments in the code
     below, this can lead to <code>beginof</code> being optimized out
     of existence, so you pay absolutely nothing in terms of increased
     code size or execution time.
   </para><para>
     The result is that if all your algorithm calls look like
   </para><programlisting>
   std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);
</programlisting><para>
     then the type of foo can change from an array of ints to a vector
     of ints to a deque of ints and back again, without ever changing
     any client code.
   </para><programlisting>
// beginof
template&lt;typename T&gt;
  inline typename vector&lt;T&gt;::iterator
  beginof(vector&lt;T&gt; &amp;v)
  { return v.begin(); }

template&lt;typename T, unsigned int sz&gt;
  inline T*
  beginof(T (&amp;array)[sz]) { return array; }

// endof
template&lt;typename T&gt;
  inline typename vector&lt;T&gt;::iterator
  endof(vector&lt;T&gt; &amp;v)
  { return v.end(); }

template&lt;typename T, unsigned int sz&gt;
  inline T*
  endof(T (&amp;array)[sz]) { return array + sz; }

// lengthof
template&lt;typename T&gt;
  inline typename vector&lt;T&gt;::size_type
  lengthof(vector&lt;T&gt; &amp;v)
  { return v.size(); }

template&lt;typename T, unsigned int sz&gt;
  inline unsigned int
  lengthof(T (&amp;)[sz]) { return sz; }
</programlisting><para>
     Astute readers will notice two things at once: first, that the
     container class is still a <code>vector&lt;T&gt;</code> instead
     of a more general <code>Container&lt;T&gt;</code>.  This would
     mean that three functions for <code>deque</code> would have to be
     added, another three for <code>list</code>, and so on.  This is
     due to problems with getting template resolution correct; I find
     it easier just to give the extra three lines and avoid confusion.
   </para><para>
     Second, the line
   </para><programlisting>
    inline unsigned int lengthof (T (&amp;)[sz]) { return sz; }
</programlisting><para>
     looks just weird!  Hint:  unused parameters can be left nameless.
   </para></section></section></chapter><!-- Chapter 07 : Iterators --><chapter version="5.0" xreflabel="Iterators" xml:id="std.iterators"><?dbhtml filename="iterators.html"?><info><title>
  Iterators
  <indexterm><primary>Iterators</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Sect1 01 : Predefined --><section xreflabel="Predefined" xml:id="std.iterators.predefined"><info><title>Predefined</title></info><section xreflabel="Versus Pointers" xml:id="iterators.predefined.vs_pointers"><info><title>Iterators vs. Pointers</title></info><para>
     The following
FAQ <link linkend="faq.iterator_as_pod">entry</link> points out that
iterators are not implemented as pointers.  They are a generalization
of pointers, but they are implemented in libstdc++ as separate
classes.
   </para><para>
     Keeping that simple fact in mind as you design your code will
      prevent a whole lot of difficult-to-understand bugs.
   </para><para>
     You can think of it the other way 'round, even.  Since iterators
     are a generalization, that means
     that <emphasis>pointers</emphasis> are
      <emphasis>iterators</emphasis>, and that pointers can be used
     whenever an iterator would be.  All those functions in the
     Algorithms section of the Standard will work just as well on plain
     arrays and their pointers.
   </para><para>
     That doesn't mean that when you pass in a pointer, it gets
      wrapped into some special delegating iterator-to-pointer class
      with a layer of overhead.  (If you think that's the case
      anywhere, you don't understand templates to begin with...)  Oh,
      no; if you pass in a pointer, then the compiler will instantiate
      that template using T* as a type, and good old high-speed
      pointer arithmetic as its operations, so the resulting code will
      be doing exactly the same things as it would be doing if you had
      hand-coded it yourself (for the 273rd time).
   </para><para>
     How much overhead <emphasis>is</emphasis> there when using an
      iterator class?  Very little.  Most of the layering classes
      contain nothing but typedefs, and typedefs are
      "meta-information" that simply tell the compiler some
      nicknames; they don't create code.  That information gets passed
      down through inheritance, so while the compiler has to do work
      looking up all the names, your runtime code does not.  (This has
      been a prime concern from the beginning.)
   </para></section><section xreflabel="end() Is One Past the End" xml:id="iterators.predefined.end"><info><title>One Past the End</title></info><para>This starts off sounding complicated, but is actually very easy,
      especially towards the end.  Trust me.
   </para><para>Beginners usually have a little trouble understand the whole
      'past-the-end' thing, until they remember their early algebra classes
      (see, they <emphasis>told</emphasis> you that stuff would come in handy!) and
      the concept of half-open ranges.
   </para><para>First, some history, and a reminder of some of the funkier rules in
      C and C++ for builtin arrays.  The following rules have always been
      true for both languages:
   </para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>You can point anywhere in the array, <emphasis>or to the first element
	  past the end of the array</emphasis>.  A pointer that points to one
	  past the end of the array is guaranteed to be as unique as a
	  pointer to somewhere inside the array, so that you can compare
	  such pointers safely.
	</para></listitem><listitem><para>You can only dereference a pointer that points into an array.
	  If your array pointer points outside the array -- even to just
	  one past the end -- and you dereference it, Bad Things happen.
	</para></listitem><listitem><para>Strictly speaking, simply pointing anywhere else invokes
	  undefined behavior.  Most programs won't puke until such a
	  pointer is actually dereferenced, but the standards leave that
	  up to the platform.
	</para></listitem></orderedlist><para>The reason this past-the-end addressing was allowed is to make it
      easy to write a loop to go over an entire array, e.g.,
      while (*d++ = *s++);.
   </para><para>So, when you think of two pointers delimiting an array, don't think
      of them as indexing 0 through n-1.  Think of them as <emphasis>boundary
      markers</emphasis>:
   </para><programlisting>

   beginning            end
     |                   |
     |                   |               This is bad.  Always having to
     |                   |               remember to add or subtract one.
     |                   |               Off-by-one bugs very common here.
     V                   V
	array of N elements
     |---|---|--...--|---|---|
     | 0 | 1 |  ...  |N-2|N-1|
     |---|---|--...--|---|---|

     ^                       ^
     |                       |
     |                       |           This is good.  This is safe.  This
     |                       |           is guaranteed to work.  Just don't
     |                       |           dereference 'end'.
   beginning                end

</programlisting><para>See?  Everything between the boundary markers is chapter of the array.
      Simple.
   </para><para>Now think back to your junior-high school algebra course, when you
      were learning how to draw graphs.  Remember that a graph terminating
      with a solid dot meant, "Everything up through this point,"
      and a graph terminating with an open dot meant, "Everything up
      to, but not including, this point," respectively called closed
      and open ranges?  Remember how closed ranges were written with
      brackets, <emphasis>[a,b]</emphasis>, and open ranges were written with parentheses,
      <emphasis>(a,b)</emphasis>?
   </para><para>The boundary markers for arrays describe a <emphasis>half-open range</emphasis>,
      starting with (and including) the first element, and ending with (but
      not including) the last element:  <emphasis>[beginning,end)</emphasis>.  See, I
      told you it would be simple in the end.
   </para><para>Iterators, and everything working with iterators, follows this same
      time-honored tradition.  A container's <code>begin()</code> method returns
      an iterator referring to the first element, and its <code>end()</code>
      method returns a past-the-end iterator, which is guaranteed to be
      unique and comparable against any other iterator pointing into the
      middle of the container.
   </para><para>Container constructors, container methods, and algorithms, all take
      pairs of iterators describing a range of values on which to operate.
      All of these ranges are half-open ranges, so you pass the beginning
      iterator as the starting parameter, and the one-past-the-end iterator
      as the finishing parameter.
   </para><para>This generalizes very well.  You can operate on sub-ranges quite
      easily this way; functions accepting a <emphasis>[first,last)</emphasis> range
      don't know or care whether they are the boundaries of an entire {array,
      sequence, container, whatever}, or whether they only enclose a few
      elements from the center.  This approach also makes zero-length
      sequences very simple to recognize:  if the two endpoints compare
      equal, then the {array, sequence, container, whatever} is empty.
   </para><para>Just don't dereference <code>end()</code>.
   </para></section></section><!-- Sect1 02 : Stream --></chapter><!-- Chapter 08 : Algorithms --><chapter version="5.0" xreflabel="Algorithms" xml:id="std.algorithms"><?dbhtml filename="algorithms.html"?><info><title>
  Algorithms
  <indexterm><primary>Algorithms</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword><keyword>algorithm</keyword></keywordset></info><para>
  The neatest accomplishment of the algorithms section is that all the
  work is done via iterators, not containers directly.  This means two
  important things:
</para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>
      Anything that behaves like an iterator can be used in one of
      these algorithms.  Raw pointers make great candidates, thus
      built-in arrays are fine containers, as well as your own
      iterators.
    </para></listitem><listitem><para>
      The algorithms do not (and cannot) affect the container as a
      whole; only the things between the two iterator endpoints.  If
      you pass a range of iterators only enclosing the middle third of
      a container, then anything outside that range is inviolate.
    </para></listitem></orderedlist><para>
  Even strings can be fed through the algorithms here, although the
  string class has specialized versions of many of these functions
  (for example, <code>string::find()</code>).  Most of the examples
  on this page will use simple arrays of integers as a playground
  for algorithms, just to keep things simple.  The use of
  <emphasis>N</emphasis> as a size in the examples is to keep things
  easy to read but probably won't be valid code.  You can use wrappers
  such as those described in
  the <link linkend="std.containers">containers section</link> to keep
  real code readable.
</para><para>
  The single thing that trips people up the most is the definition
  of <emphasis>range</emphasis> used with iterators; the famous
  "past-the-end" rule that everybody loves to hate.  The
  <link linkend="std.iterators">iterators section</link> of this
    document has a complete explanation of this simple rule that seems
    to cause so much confusion.  Once you
    get <emphasis>range</emphasis> into your head (it's not that hard,
    honest!), then the algorithms are a cakewalk.
</para><!-- Sect1 01 : Non Modifying --><!-- Sect1 02 : Mutating --><section xreflabel="Mutating" xml:id="std.algorithms.mutating"><info><title>Mutating</title></info><section xreflabel="swap" xml:id="algorithms.mutating.swap"><info><title><function>swap</function></title></info><section xreflabel="Specializations" xml:id="algorithms.swap.specializations"><info><title>Specializations</title></info><para>If you call <code> std::swap(x,y); </code> where x and y are standard
      containers, then the call will automatically be replaced by a call to
      <code> x.swap(y); </code> instead.
   </para><para>This allows member functions of each container class to take over, and
      containers' swap functions should have O(1) complexity according to
      the standard.  (And while "should" allows implementations to
      behave otherwise and remain compliant, this implementation does in
      fact use constant-time swaps.)  This should not be surprising, since
      for two containers of the same type to swap contents, only some
      internal pointers to storage need to be exchanged.
   </para></section></section></section><!-- Sect1 03 : Sorting --></chapter><!-- Chapter 09 : Numerics --><chapter version="5.0" xreflabel="Numerics" xml:id="std.numerics"><?dbhtml filename="numerics.html"?><info><title>
  Numerics
  <indexterm><primary>Numerics</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Sect1 01 : Complex --><section xreflabel="complex" xml:id="std.numerics.complex"><info><title>Complex</title></info><?dbhtml filename="complex.html"?><para>
  </para><section xreflabel="complex Processing" xml:id="numerics.complex.processing"><info><title>complex Processing</title></info><para>
    </para><para>Using <code>complex&lt;&gt;</code> becomes even more comple- er, sorry,
      <emphasis>complicated</emphasis>, with the not-quite-gratuitously-incompatible
      addition of complex types to the C language.  David Tribble has
      compiled a list of C++98 and C99 conflict points; his description of
      C's new type versus those of C++ and how to get them playing together
      nicely is
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</link>.
   </para><para><code>complex&lt;&gt;</code> is intended to be instantiated with a
      floating-point type.  As long as you meet that and some other basic
      requirements, then the resulting instantiation has all of the usual
      math operators defined, as well as definitions of <code>op&lt;&lt;</code>
      and <code>op&gt;&gt;</code> that work with iostreams: <code>op&lt;&lt;</code>
      prints <code>(u,v)</code> and <code>op&gt;&gt;</code> can read <code>u</code>,
      <code>(u)</code>, and <code>(u,v)</code>.
   </para><para>As an extension to C++11 and for increased compatibility with C,
      <code>&lt;complex.h&gt;</code> includes both <code>&lt;complex&gt;</code>
      and the C99 <code>&lt;complex.h&gt;</code> (if the C library provides
      it).
   </para></section></section><!-- Sect1 02 : Generalized Operations --><section xreflabel="Generalized Ops" xml:id="std.numerics.generalized_ops"><info><title>Generalized Operations</title></info><?dbhtml filename="generalized_numeric_operations.html"?><para>
  </para><para>There are four generalized functions in the &lt;numeric&gt; header
      that follow the same conventions as those in &lt;algorithm&gt;.  Each
      of them is overloaded:  one signature for common default operations,
      and a second for fully general operations.  Their names are
      self-explanatory to anyone who works with numerics on a regular basis:
   </para><itemizedlist><listitem><para><code>accumulate</code></para></listitem><listitem><para><code>inner_product</code></para></listitem><listitem><para><code>partial_sum</code></para></listitem><listitem><para><code>adjacent_difference</code></para></listitem></itemizedlist><para>Here is a simple example of the two forms of <code>accumulate</code>.
   </para><programlisting>
   int   ar[50];
   int   someval = somefunction();

   // ...initialize members of ar to something...

   int  sum       = std::accumulate(ar,ar+50,0);
   int  sum_stuff = std::accumulate(ar,ar+50,someval);
   int  product   = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
</programlisting><para>The first call adds all the members of the array, using zero as an
      initial value for <code>sum</code>.  The second does the same, but uses
      <code>someval</code> as the starting value (thus, <code>sum_stuff == sum +
      someval</code>).  The final call uses the second of the two signatures,
      and multiplies all the members of the array; here we must obviously
      use 1 as a starting value instead of 0.
   </para><para>The other three functions have similar dual-signature forms.
   </para></section><!-- Sect1 03 : Interacting with C --><section xreflabel="Interacting with C" xml:id="std.numerics.c"><info><title>Interacting with C</title></info><?dbhtml filename="numerics_and_c.html"?><section xreflabel="Numerics vs. Arrays" xml:id="numerics.c.array"><info><title>Numerics vs. Arrays</title></info><para>One of the major reasons why FORTRAN can chew through numbers so well
      is that it is defined to be free of pointer aliasing, an assumption
      that C89 is not allowed to make, and neither is C++98.  C99 adds a new
      keyword, <code>restrict</code>, to apply to individual pointers.  The
      C++ solution is contained in the library rather than the language
      (although many vendors can be expected to add this to their compilers
      as an extension).
   </para><para>That library solution is a set of two classes, five template classes,
      and "a whole bunch" of functions.  The classes are required
      to be free of pointer aliasing, so compilers can optimize the
      daylights out of them the same way that they have been for FORTRAN.
      They are collectively called <code>valarray</code>, although strictly
      speaking this is only one of the five template classes, and they are
      designed to be familiar to people who have worked with the BLAS
      libraries before.
   </para></section><section xreflabel="C99" xml:id="numerics.c.c99"><info><title>C99</title></info><para>In addition to the other topics on this page, we'll note here some
      of the C99 features that appear in libstdc++.
   </para><para>The C99 features depend on the <code>--enable-c99</code> configure flag.
      This flag is already on by default, but it can be disabled by the
      user.  Also, the configuration machinery will disable it if the
      necessary support for C99 (e.g., header files) cannot be found.
   </para><para>As of GCC 3.0, C99 support includes classification functions
      such as <code>isnormal</code>, <code>isgreater</code>,
      <code>isnan</code>, etc.
      The functions used for 'long long' support such as <code>strtoll</code>
      are supported, as is the <code>lldiv_t</code> typedef.  Also supported
      are the wide character functions using 'long long', like
      <code>wcstoll</code>.
   </para></section></section></chapter><!-- Chapter 10 : Input Output --><chapter version="5.0" xreflabel="Input and Output" xml:id="std.io"><?dbhtml filename="io.html"?><info><title>
  Input and Output
  <indexterm><primary>Input and Output</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Sect1 01 : Iostream Objects --><section xreflabel="IO Objects" xml:id="std.io.objects"><info><title>Iostream Objects</title></info><?dbhtml filename="iostream_objects.html"?><para>To minimize the time you have to wait on the compiler, it's good to
      only include the headers you really need.  Many people simply include
      <filename class="headerfile">&lt;iostream&gt;</filename> when they don't
      need to -- and that can <emphasis>penalize your runtime as well.</emphasis>
      Here are some tips on which header to use
      for which situations, starting with the simplest.
   </para><para><emphasis><filename class="headerfile">&lt;iosfwd&gt;</filename></emphasis>
      should be included whenever you simply need the <emphasis>name</emphasis>
      of an I/O-related class, such as "<classname>ofstream</classname>" or
      "<classname>basic_streambuf</classname>".
      Like the name implies, these are forward declarations.
      (A word to all you fellow old school programmers:
      trying to forward declare classes like "<code>class istream;</code>"
      won't work.
      Look in the <filename class="headerfile">&lt;iosfwd&gt;</filename> header
      if you'd like to know why.)  For example,
   </para><programlisting>
    #include &lt;iosfwd&gt;

    class MyClass
    {
	....
	std::ifstream&amp;   input_file;
    };

    extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
</programlisting><para><emphasis><filename class="headerfile">&lt;ios&gt;</filename></emphasis>
      declares the base classes for the entire I/O stream hierarchy,
      <classname>std::ios_base</classname> and <classname>std::basic_ios&lt;charT&gt;</classname>,
      the counting types <type>std::streamoff</type> and <type>std::streamsize</type>,
      the file positioning type <type>std::fpos</type>,
      and the various manipulators like <function>std::hex</function>,
      <function>std::fixed</function>, <function>std::noshowbase</function>,
      and so forth.
   </para><para>The <classname>ios_base</classname> class is what holds the format
      flags, the state flags, and the functions which change them
      (<function>setf()</function>, <function>width()</function>,
      <function>precision()</function>, etc).
      You can also store extra data and register callback functions
      through <classname>ios_base</classname>, but that has been historically
      underused.  Anything
      which doesn't depend on the type of characters stored is consolidated
      here.
   </para><para>The class template <classname>basic_ios</classname> is the highest
      class template in the
      hierarchy; it is the first one depending on the character type, and
      holds all general state associated with that type:  the pointer to the
      polymorphic stream buffer, the facet information, etc.
   </para><para><emphasis><filename class="headerfile">&lt;streambuf&gt;</filename></emphasis>
      declares the class template <classname>basic_streambuf</classname>, and
      two standard instantiations, <type>streambuf</type> and
      <type>wstreambuf</type>.  If you need to work with the vastly useful and
      capable stream buffer classes, e.g., to create a new form of storage
      transport, this header is the one to include.
   </para><para><emphasis><filename class="headerfile">&lt;istream&gt;</filename></emphasis>
       and <emphasis><filename class="headerfile">&lt;ostream&gt;</filename></emphasis>
       are the headers to include when you are using the overloaded
      <code>&gt;&gt;</code> and <code>&lt;&lt;</code> operators,
      or any of the other abstract stream formatting functions.
      For example,
   </para><programlisting>
    #include &lt;istream&gt;

    std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
    {
       return os &lt;&lt; c.data1() &lt;&lt; c.data2();
    }
</programlisting><para>The <type>std::istream</type> and <type>std::ostream</type> classes
      are the abstract parents of
      the various concrete implementations.  If you are only using the
      interfaces, then you only need to use the appropriate interface header.
   </para><para><emphasis><filename class="headerfile">&lt;iomanip&gt;</filename></emphasis>
      provides "extractors and inserters that alter information maintained by
      class <classname>ios_base</classname> and its derived classes,"
      such as <function>std::setprecision</function> and
      <function>std::setw</function>.  If you need
      to write expressions like <code>os &lt;&lt; setw(3);</code> or
      <code>is &gt;&gt; setbase(8);</code>, you must include
      <filename class="headerfile">&lt;iomanip&gt;</filename>.
   </para><para><emphasis><filename class="headerfile">&lt;sstream&gt;</filename></emphasis>
      and <emphasis><filename class="headerfile">&lt;fstream&gt;</filename></emphasis>
      declare the six stringstream and fstream classes.  As they are the
      standard concrete descendants of <type>istream</type> and <type>ostream</type>,
      you will already know about them.
   </para><para>Finally, <emphasis><filename class="headerfile">&lt;iostream&gt;</filename></emphasis>
      provides the eight standard global objects
      (<code>cin</code>, <code>cout</code>, etc).  To do this correctly, this
      header also provides the contents of the
      <filename class="headerfile">&lt;istream&gt;</filename> and
      <filename class="headerfile">&lt;ostream&gt;</filename>
      headers, but nothing else.  The contents of this header look like:
   </para><programlisting>
    #include &lt;ostream&gt;
    #include &lt;istream&gt;

    namespace std
    {
	extern istream cin;
	extern ostream cout;
	....

	// this is explained below
	<emphasis>static ios_base::Init __foo;</emphasis>    // not its real name
    }
</programlisting><para>Now, the runtime penalty mentioned previously:  the global objects
      must be initialized before any of your own code uses them; this is
      guaranteed by the standard.  Like any other global object, they must
      be initialized once and only once.  This is typically done with a
      construct like the one above, and the nested class
      <classname>ios_base::Init</classname> is
      specified in the standard for just this reason.
   </para><para>How does it work?  Because the header is included before any of your
      code, the <emphasis>__foo</emphasis> object is constructed before any of
      your objects.  (Global objects are built in the order in which they
      are declared, and destroyed in reverse order.)  The first time the
      constructor runs, the eight stream objects are set up.
   </para><para>The <code>static</code> keyword means that each object file compiled
      from a source file containing
      <filename class="headerfile">&lt;iostream&gt;</filename> will have its own
      private copy of <emphasis>__foo</emphasis>.  There is no specified order
      of construction across object files (it's one of those pesky NP complete
      problems that make life so interesting), so one copy in each object
      file means that the stream objects are guaranteed to be set up before
      any of your code which uses them could run, thereby meeting the
      requirements of the standard.
   </para><para>The penalty, of course, is that after the first copy of
      <emphasis>__foo</emphasis> is constructed, all the others are just wasted
      processor time.  The time spent is merely for an increment-and-test
      inside a function call, but over several dozen or hundreds of object
      files, that time can add up.  (It's not in a tight loop, either.)
   </para><para>The lesson?  Only include
      <filename class="headerfile">&lt;iostream&gt;</filename> when you need
      to use one of
      the standard objects in that source file; you'll pay less startup
      time.  Only include the header files you need to in general; your
      compile times will go down when there's less parsing work to do.
   </para></section><!-- Sect1 02 : Stream Buffers --><section xreflabel="Stream Buffers" xml:id="std.io.streambufs"><info><title>Stream Buffers</title></info><?dbhtml filename="streambufs.html"?><section xreflabel="Derived streambuf Classes" xml:id="io.streambuf.derived"><info><title>Derived streambuf Classes</title></info><para>
    </para><para>Creating your own stream buffers for I/O can be remarkably easy.
      If you are interested in doing so, we highly recommend two very
      excellent books:
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://angelikalanger.com/iostreams.html">Standard C++
      IOStreams and Locales</link> by Langer and Kreft, ISBN 0-201-18395-1, and
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.josuttis.com/libbook/">The C++ Standard Library</link>
      by Nicolai Josuttis, ISBN 0-201-37926-0.  Both are published by
      Addison-Wesley, who isn't paying us a cent for saying that, honest.
   </para><para>Here is a simple example, io/outbuf1, from the Josuttis text.  It
      transforms everything sent through it to uppercase.  This version
      assumes many things about the nature of the character type being
      used (for more information, read the books or the newsgroups):
   </para><programlisting>
    #include &lt;iostream&gt;
    #include &lt;streambuf&gt;
    #include &lt;locale&gt;
    #include &lt;cstdio&gt;

    class outbuf : public std::streambuf
    {
      protected:
	/* central output function
	 * - print characters in uppercase mode
	 */
	virtual int_type overflow (int_type c) {
	    if (c != EOF) {
		// convert lowercase to uppercase
		c = std::toupper(static_cast&lt;char&gt;(c),getloc());

		// and write the character to the standard output
		if (putchar(c) == EOF) {
		    return EOF;
		}
	    }
	    return c;
	}
    };

    int main()
    {
	// create special output buffer
	outbuf ob;
	// initialize output stream with that output buffer
	std::ostream out(&amp;ob);

	out &lt;&lt; "31 hexadecimal: "
	    &lt;&lt; std::hex &lt;&lt; 31 &lt;&lt; std::endl;
	return 0;
    }
</programlisting><para>Try it yourself!  More examples can be found in 3.1.x code, in
      <filename>include/ext/*_filebuf.h</filename>, and in the article
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gabisoft.free.fr/articles/fltrsbf1.html">Filtering
      Streambufs</link>
      by James Kanze.
   </para></section><section xreflabel="Buffering" xml:id="io.streambuf.buffering"><info><title>Buffering</title></info><para>First, are you sure that you understand buffering?  Particularly
      the fact that C++ may not, in fact, have anything to do with it?
   </para><para>The rules for buffering can be a little odd, but they aren't any
      different from those of C.  (Maybe that's why they can be a bit
      odd.)  Many people think that writing a newline to an output
      stream automatically flushes the output buffer.  This is true only
      when the output stream is, in fact, a terminal and not a file
      or some other device -- and <emphasis>that</emphasis> may not even be true
      since C++ says nothing about files nor terminals.  All of that is
      system-dependent.  (The "newline-buffer-flushing only occurring
      on terminals" thing is mostly true on Unix systems, though.)
   </para><para>Some people also believe that sending <code>endl</code> down an
      output stream only writes a newline.  This is incorrect; after a
      newline is written, the buffer is also flushed.  Perhaps this
      is the effect you want when writing to a screen -- get the text
      out as soon as possible, etc -- but the buffering is largely
      wasted when doing this to a file:
   </para><programlisting>
   output &lt;&lt; "a line of text" &lt;&lt; endl;
   output &lt;&lt; some_data_variable &lt;&lt; endl;
   output &lt;&lt; "another line of text" &lt;&lt; endl; </programlisting><para>The proper thing to do in this case to just write the data out
      and let the libraries and the system worry about the buffering.
      If you need a newline, just write a newline:
   </para><programlisting>
   output &lt;&lt; "a line of text\n"
	  &lt;&lt; some_data_variable &lt;&lt; '\n'
	  &lt;&lt; "another line of text\n"; </programlisting><para>I have also joined the output statements into a single statement.
      You could make the code prettier by moving the single newline to
      the start of the quoted text on the last line, for example.
   </para><para>If you do need to flush the buffer above, you can send an
      <code>endl</code> if you also need a newline, or just flush the buffer
      yourself:
   </para><programlisting>
   output &lt;&lt; ...... &lt;&lt; flush;    // can use std::flush manipulator
   output.flush();               // or call a member fn </programlisting><para>On the other hand, there are times when writing to a file should
      be like writing to standard error; no buffering should be done
      because the data needs to appear quickly (a prime example is a
      log file for security-related information).  The way to do this is
      just to turn off the buffering <emphasis>before any I/O operations at
      all</emphasis> have been done (note that opening counts as an I/O operation):
   </para><programlisting>
   std::ofstream    os;
   std::ifstream    is;
   int   i;

   os.rdbuf()-&gt;pubsetbuf(0,0);
   is.rdbuf()-&gt;pubsetbuf(0,0);

   os.open("/foo/bar/baz");
   is.open("/qux/quux/quuux");
   ...
   os &lt;&lt; "this data is written immediately\n";
   is &gt;&gt; i;   // and this will probably cause a disk read </programlisting><para>Since all aspects of buffering are handled by a streambuf-derived
      member, it is necessary to get at that member with <code>rdbuf()</code>.
      Then the public version of <code>setbuf</code> can be called.  The
      arguments are the same as those for the Standard C I/O Library
      function (a buffer area followed by its size).
   </para><para>A great deal of this is implementation-dependent.  For example,
      <code>streambuf</code> does not specify any actions for its own
      <code>setbuf()</code>-ish functions; the classes derived from
      <code>streambuf</code> each define behavior that "makes
      sense" for that class:  an argument of (0,0) turns off buffering
      for <code>filebuf</code> but does nothing at all for its siblings
      <code>stringbuf</code> and <code>strstreambuf</code>, and specifying
      anything other than (0,0) has varying effects.
      User-defined classes derived from <code>streambuf</code> can
      do whatever they want.  (For <code>filebuf</code> and arguments for
      <code>(p,s)</code> other than zeros, libstdc++ does what you'd expect:
      the first <code>s</code> bytes of <code>p</code> are used as a buffer,
      which you must allocate and deallocate.)
   </para><para>A last reminder:  there are usually more buffers involved than
      just those at the language/library level.  Kernel buffers, disk
      buffers, and the like will also have an effect.  Inspecting and
      changing those are system-dependent.
   </para></section></section><!-- Sect1 03 : Memory-based Streams --><section xreflabel="Memory Streams" xml:id="std.io.memstreams"><info><title>Memory Based Streams</title></info><?dbhtml filename="stringstreams.html"?><section xreflabel="Compatibility strstream" xml:id="std.io.memstreams.compat"><info><title>Compatibility With strstream</title></info><para>
    </para><para>Stringstreams (defined in the header <code>&lt;sstream&gt;</code>)
      are in this author's opinion one of the coolest things since
      sliced time.  An example of their use is in the Received Wisdom
      section for Sect1 21 (Strings),
      <link linkend="strings.string.Cstring"> describing how to
      format strings</link>.
   </para><para>The quick definition is:  they are siblings of ifstream and ofstream,
      and they do for <code>std::string</code> what their siblings do for
      files.  All that work you put into writing <code>&lt;&lt;</code> and
      <code>&gt;&gt;</code> functions for your classes now pays off
      <emphasis>again!</emphasis>  Need to format a string before passing the string
      to a function?  Send your stuff via <code>&lt;&lt;</code> to an
      ostringstream.  You've read a string as input and need to parse it?
      Initialize an istringstream with that string, and then pull pieces
      out of it with <code>&gt;&gt;</code>.  Have a stringstream and need to
      get a copy of the string inside?  Just call the <code>str()</code>
      member function.
   </para><para>This only works if you've written your
      <code>&lt;&lt;</code>/<code>&gt;&gt;</code> functions correctly, though,
      and correctly means that they take istreams and ostreams as
      parameters, not i<emphasis>f</emphasis>streams and o<emphasis>f</emphasis>streams.  If they
      take the latter, then your I/O operators will work fine with
      file streams, but with nothing else -- including stringstreams.
   </para><para>If you are a user of the strstream classes, you need to update
      your code.  You don't have to explicitly append <code>ends</code> to
      terminate the C-style character array, you don't have to mess with
      "freezing" functions, and you don't have to manage the
      memory yourself.  The strstreams have been officially deprecated,
      which means that 1) future revisions of the C++ Standard won't
      support them, and 2) if you use them, people will laugh at you.
   </para></section></section><!-- Sect1 04 : File-based Streams --><section xreflabel="File Streams" xml:id="std.io.filestreams"><info><title>File Based Streams</title></info><?dbhtml filename="fstreams.html"?><section xreflabel="Copying a File" xml:id="std.io.filestreams.copying_a_file"><info><title>Copying a File</title></info><para>
  </para><para>So you want to copy a file quickly and easily, and most important,
      completely portably.  And since this is C++, you have an open
      ifstream (call it IN) and an open ofstream (call it OUT):
   </para><programlisting>
   #include &lt;fstream&gt;

   std::ifstream  IN ("input_file");
   std::ofstream  OUT ("output_file"); </programlisting><para>Here's the easiest way to get it completely wrong:
   </para><programlisting>
   OUT &lt;&lt; IN;</programlisting><para>For those of you who don't already know why this doesn't work
      (probably from having done it before), I invite you to quickly
      create a simple text file called "input_file" containing
      the sentence
   </para><programlisting>
      The quick brown fox jumped over the lazy dog.</programlisting><para>surrounded by blank lines.  Code it up and try it.  The contents
      of "output_file" may surprise you.
   </para><para>Seriously, go do it.  Get surprised, then come back.  It's worth it.
   </para><para>The thing to remember is that the <code>basic_[io]stream</code> classes
      handle formatting, nothing else.  In particular, they break up on
      whitespace.  The actual reading, writing, and storing of data is
      handled by the <code>basic_streambuf</code> family.  Fortunately, the
      <code>operator&lt;&lt;</code> is overloaded to take an ostream and
      a pointer-to-streambuf, in order to help with just this kind of
      "dump the data verbatim" situation.
   </para><para>Why a <emphasis>pointer</emphasis> to streambuf and not just a streambuf?  Well,
      the [io]streams hold pointers (or references, depending on the
      implementation) to their buffers, not the actual
      buffers.  This allows polymorphic behavior on the chapter of the buffers
      as well as the streams themselves.  The pointer is easily retrieved
      using the <code>rdbuf()</code> member function.  Therefore, the easiest
      way to copy the file is:
   </para><programlisting>
   OUT &lt;&lt; IN.rdbuf();</programlisting><para>So what <emphasis>was</emphasis> happening with OUT&lt;&lt;IN?  Undefined
      behavior, since that particular &lt;&lt; isn't defined by the Standard.
      I have seen instances where it is implemented, but the character
      extraction process removes all the whitespace, leaving you with no
      blank lines and only "Thequickbrownfox...".  With
      libraries that do not define that operator, IN (or one of IN's
      member pointers) sometimes gets converted to a void*, and the output
      file then contains a perfect text representation of a hexadecimal
      address (quite a big surprise).  Others don't compile at all.
   </para><para>Also note that none of this is specific to o<emphasis>*f*</emphasis>streams.
      The operators shown above are all defined in the parent
      basic_ostream class and are therefore available with all possible
      descendants.
   </para></section><section xreflabel="Binary Input and Output" xml:id="std.io.filestreams.binary"><info><title>Binary Input and Output</title></info><para>
    </para><para>The first and most important thing to remember about binary I/O is
      that opening a file with <code>ios::binary</code> is not, repeat
      <emphasis>not</emphasis>, the only thing you have to do.  It is not a silver
      bullet, and will not allow you to use the <code>&lt;&lt;/&gt;&gt;</code>
      operators of the normal fstreams to do binary I/O.
   </para><para>Sorry.  Them's the breaks.
   </para><para>This isn't going to try and be a complete tutorial on reading and
      writing binary files (because "binary"
      covers a lot of ground), but we will try and clear
      up a couple of misconceptions and common errors.
   </para><para>First, <code>ios::binary</code> has exactly one defined effect, no more
      and no less.  Normal text mode has to be concerned with the newline
      characters, and the runtime system will translate between (for
      example) '\n' and the appropriate end-of-line sequence (LF on Unix,
      CRLF on DOS, CR on Macintosh, etc).  (There are other things that
      normal mode does, but that's the most obvious.)  Opening a file in
      binary mode disables this conversion, so reading a CRLF sequence
      under Windows won't accidentally get mapped to a '\n' character, etc.
      Binary mode is not supposed to suddenly give you a bitstream, and
      if it is doing so in your program then you've discovered a bug in
      your vendor's compiler (or some other chapter of the C++ implementation,
      possibly the runtime system).
   </para><para>Second, using <code>&lt;&lt;</code> to write and <code>&gt;&gt;</code> to
      read isn't going to work with the standard file stream classes, even
      if you use <code>skipws</code> during reading.  Why not?  Because
      ifstream and ofstream exist for the purpose of <emphasis>formatting</emphasis>,
      not reading and writing.  Their job is to interpret the data into
      text characters, and that's exactly what you don't want to happen
      during binary I/O.
   </para><para>Third, using the <code>get()</code> and <code>put()/write()</code> member
      functions still aren't guaranteed to help you.  These are
      "unformatted" I/O functions, but still character-based.
      (This may or may not be what you want, see below.)
   </para><para>Notice how all the problems here are due to the inappropriate use
      of <emphasis>formatting</emphasis> functions and classes to perform something
      which <emphasis>requires</emphasis> that formatting not be done?  There are a
      seemingly infinite number of solutions, and a few are listed here:
   </para><itemizedlist><listitem><para><quote>Derive your own fstream-type classes and write your own
	  &lt;&lt;/&gt;&gt; operators to do binary I/O on whatever data
	  types you're using.</quote></para><para>
	  This is a Bad Thing, because while
	  the compiler would probably be just fine with it, other humans
	  are going to be confused.  The overloaded bitshift operators
	  have a well-defined meaning (formatting), and this breaks it.
	</para></listitem><listitem><para><quote>Build the file structure in memory, then
	  <code>mmap()</code> the file and copy the
	  structure.
	</quote></para><para>
	  Well, this is easy to make work, and easy to break, and is
	  pretty equivalent to using <code>::read()</code> and
	  <code>::write()</code> directly, and makes no use of the
	  iostream library at all...
	  </para></listitem><listitem><para><quote>Use streambufs, that's what they're there for.</quote></para><para>
	  While not trivial for the beginner, this is the best of all
	  solutions.  The streambuf/filebuf layer is the layer that is
	  responsible for actual I/O.  If you want to use the C++
	  library for binary I/O, this is where you start.
	</para></listitem></itemizedlist><para>How to go about using streambufs is a bit beyond the scope of this
      document (at least for now), but while streambufs go a long way,
      they still leave a couple of things up to you, the programmer.
      As an example, byte ordering is completely between you and the
      operating system, and you have to handle it yourself.
   </para><para>Deriving a streambuf or filebuf
      class from the standard ones, one that is specific to your data
      types (or an abstraction thereof) is probably a good idea, and
      lots of examples exist in journals and on Usenet.  Using the
      standard filebufs directly (either by declaring your own or by
      using the pointer returned from an fstream's <code>rdbuf()</code>)
      is certainly feasible as well.
   </para><para>One area that causes problems is trying to do bit-by-bit operations
      with filebufs.  C++ is no different from C in this respect:  I/O
      must be done at the byte level.  If you're trying to read or write
      a few bits at a time, you're going about it the wrong way.  You
      must read/write an integral number of bytes and then process the
      bytes.  (For example, the streambuf functions take and return
      variables of type <code>int_type</code>.)
   </para><para>Another area of problems is opening text files in binary mode.
      Generally, binary mode is intended for binary files, and opening
      text files in binary mode means that you now have to deal with all of
      those end-of-line and end-of-file problems that we mentioned before.
   </para><para>
      An instructive thread from comp.lang.c++.moderated delved off into
      this topic starting more or less at
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://groups.google.com/forum/#!topic/comp.std.c++/D4e0q9eVSoc">this post</link>
      and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
      and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
   </para><para>Briefly, the problems of byte ordering and type sizes mean that
      the unformatted functions like <code>ostream::put()</code> and
      <code>istream::get()</code> cannot safely be used to communicate
      between arbitrary programs, or across a network, or from one
      invocation of a program to another invocation of the same program
      on a different platform, etc.
   </para></section></section><!-- Sect1 03 : Interacting with C --><section xreflabel="Interacting with C" xml:id="std.io.c"><info><title>Interacting with C</title></info><?dbhtml filename="io_and_c.html"?><section xreflabel="Using FILE* and file descriptors" xml:id="std.io.c.FILE"><info><title>Using FILE* and file descriptors</title></info><para>
      See the <link linkend="manual.ext.io">extensions</link> for using
      <type>FILE</type> and <type>file descriptors</type> with
      <classname>ofstream</classname> and
      <classname>ifstream</classname>.
    </para></section><section xreflabel="Performance Issues" xml:id="std.io.c.sync"><info><title>Performance</title></info><para>
      Pathetic Performance? Ditch C.
    </para><para>It sounds like a flame on C, but it isn't.  Really.  Calm down.
      I'm just saying it to get your attention.
   </para><para>Because the C++ library includes the C library, both C-style and
      C++-style I/O have to work at the same time.  For example:
   </para><programlisting>
     #include &lt;iostream&gt;
     #include &lt;cstdio&gt;

     std::cout &lt;&lt; "Hel";
     std::printf ("lo, worl");
     std::cout &lt;&lt; "d!\n";
</programlisting><para>This must do what you think it does.
   </para><para>Alert members of the audience will immediately notice that buffering
      is going to make a hash of the output unless special steps are taken.
   </para><para>The special steps taken by libstdc++, at least for version 3.0,
      involve doing very little buffering for the standard streams, leaving
      most of the buffering to the underlying C library.  (This kind of
      thing is tricky to get right.)
      The upside is that correctness is ensured.  The downside is that
      writing through <code>cout</code> can quite easily lead to awful
      performance when the C++ I/O library is layered on top of the C I/O
      library (as it is for 3.0 by default).  Some patches have been applied
      which improve the situation for 3.1.
   </para><para>However, the C and C++ standard streams only need to be kept in sync
      when both libraries' facilities are in use.  If your program only uses
      C++ I/O, then there's no need to sync with the C streams.  The right
      thing to do in this case is to call
   </para><programlisting>
     #include <emphasis>any of the I/O headers such as ios, iostream, etc</emphasis>

     std::ios::sync_with_stdio(false);
</programlisting><para>You must do this before performing any I/O via the C++ stream objects.
      Once you call this, the C++ streams will operate independently of the
      (unused) C streams.  For GCC 3.x, this means that <code>cout</code> and
      company will become fully buffered on their own.
   </para><para>Note, by the way, that the synchronization requirement only applies to
      the standard streams (<code>cin</code>, <code>cout</code>,
      <code>cerr</code>,
      <code>clog</code>, and their wide-character counterparts).  File stream
      objects that you declare yourself have no such requirement and are fully
      buffered.
   </para></section></section></chapter><!-- Chapter 11 : Atomics --><chapter version="5.0" xreflabel="Atomics" xml:id="std.atomics"><?dbhtml filename="atomics.html"?><info><title>
  Atomics
  <indexterm><primary>Atomics</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword><keyword>atomic</keyword></keywordset></info><para>
  Facilities for atomic operations.
</para><!-- Sect1 01 : API --><section xml:id="std.atomics.api"><info><title>API Reference</title></info><para>
    All items are declared in the standard header
    file <filename>atomic</filename>.
  </para><para>
    Set of typedefs that map <type>int</type> to
    <classname>atomic_int</classname>, and so on for all builtin
    integral types. Global enumeration <type>memory_order</type> to
    control memory ordering. Also includes
    <classname>atomic</classname>, a class template with member
    functions such as <function>load</function> and
    <function>store</function> that is instantiable such that
    <classname>atomic_int</classname> is the base class of
    <classname>atomic&lt;int&gt;</classname>.
  </para><para>
    Full API details.
  </para><!-- Doxygen XML: api/group__atomics.xml --></section></chapter><!-- Chapter 12 : Concurrency --><chapter version="5.0" xreflabel="Concurrency" xml:id="std.concurrency"><?dbhtml filename="concurrency.html"?><info><title>
  Concurrency
  <indexterm><primary>Concurrency</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword><keyword>mutex</keyword><keyword>thread</keyword><keyword>future</keyword><keyword>condition_variable</keyword></keywordset></info><para>
  Facilities for concurrent operation, and control thereof.
</para><!-- Sect1 01 : API --><section xml:id="std.concurrency.api"><info><title>API Reference</title></info><para>
    All items are declared in one of four standard header files.
  </para><para>
    In header <filename>mutex</filename>, class
    template <classname>mutex</classname> and variants,
    class <classname>once_flag</classname>, and class
    template <classname>unique_lock</classname>.
  </para><para>
    In header <filename>condition_variable</filename>,
    classes <classname>condition_variable</classname>
    and <classname>condition_variable_any</classname>.
  </para><para>
    In header <filename>thread</filename>,
    class <classname>thread</classname> and
    namespace <code>this_thread</code>.
  </para><para>
    In header <filename>future</filename>, class
    template <classname>future</classname> and class
    template <classname>shared_future</classname>, class
    template <classname>promise</classname>,
    and <classname>packaged_task</classname>.
  </para><para>
    Full API details.
  </para><!-- Doxygen XML: api/group__concurrency.xml --></section></chapter></part><!-- Part 03 : Extensions --><part version="5.0" xreflabel="Extensions" xml:id="manual.ext"><?dbhtml filename="extensions.html"?><info><title>
  Extensions
  <indexterm><primary>Extensions</primary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><preface xml:id="manual.ext.preface"><info><title></title></info><?dbhtml filename="ext_preface.html"?><para>
  Here we will make an attempt at describing the non-Standard
  extensions to the library.  Some of these are from older versions of
  standard library components, namely SGI's STL, and some of these are
  GNU's.
</para><para><emphasis>Before</emphasis> you leap in and use any of these
extensions, be aware of two things:
</para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>
     Non-Standard means exactly that.
     </para><para>
       The behavior, and the very
       existence, of these extensions may change with little or no
       warning.  (Ideally, the really good ones will appear in the next
       revision of C++.)  Also, other platforms, other compilers, other
       versions of g++ or libstdc++ may not recognize these names, or
       treat them differently, or...
     </para></listitem><listitem><para>
       You should know how to access these headers properly.
     </para></listitem></orderedlist></preface><!-- Chapter 01 : Compile Time Checks --><chapter xreflabel="Compile Time Checks" xml:id="manual.ext.compile_checks"><info><title>Compile Time Checks</title></info><?dbhtml filename="ext_compile_checks.html"?><para>
    Also known as concept checking.
  </para><para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
      of the STL:  code which checked the template parameters of
      instantiated pieces of the STL, in order to insure that the parameters
      being used met the requirements of the standard.  For example,
      the Standard requires that types passed as template parameters to
      <code>vector</code> be <quote>Assignable</quote> (which means what you think
      it means).  The checking was done during compilation, and none of
      the code was executed at runtime.
   </para><para>Unfortunately, the size of the compiler files grew significantly
      as a result.  The checking code itself was cumbersome.  And bugs
      were found in it on more than one occasion.
   </para><para>The primary author of the checking code, Jeremy Siek, had already
      started work on a replacement implementation.  The new code has been
      formally reviewed and accepted into
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
      Boost libraries</link>, and we are pleased to incorporate it into the
      GNU C++ library.
   </para><para>The new version imposes a much smaller space overhead on the generated
      object file.  The checks are also cleaner and easier to read and
      understand.
   </para><para>They are off by default for all GCC 3.0 and all later versions.
      They can be enabled at configure time with
      <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
      You can enable them on a per-translation-unit basis with
      <link linkend="manual.intro.using.macros"><code>#define
      _GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher
      (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
      3.1, 3.2 and 3.3).
   </para><para>Please note that the concept checks only validate the requirements
   of the old C++03 standard and reject some valid code that meets the relaxed
   requirements of C++11 and later standards.
   C++11 was expected to have first-class support for template parameter
   constraints based on concepts in the core language.
   This would have obviated the need for the library-simulated concept checking
   described above, but was not part of C++11.
   C++20 adds a different model of concepts, which is now used to constrain
   some new parts of the C++20 library, e.g. the
   <filename>&lt;ranges&gt;</filename> header and the new overloads in the
   <filename>&lt;algorithm&gt;</filename> header for working with ranges.
   The old library-simulated concept checks might be removed at a future date.
   </para></chapter><!-- Chapter 02 : Debug Mode --><chapter version="5.0" xreflabel="Debug Mode" xml:id="manual.ext.debug_mode"><?dbhtml filename="debug_mode.html"?><info><title>Debug Mode</title><keywordset><keyword>C++</keyword><keyword>library</keyword><keyword>debug</keyword></keywordset></info><section xreflabel="Intro" xml:id="manual.ext.debug_mode.intro"><info><title>Intro</title></info><para>
    By default, libstdc++ is built with efficiency in mind, and
    therefore performs little or no error checking that is not
    required by the C++ standard. This means that programs that
    incorrectly use the C++ standard library will exhibit behavior
    that is not portable and may not even be predictable, because they
    tread into implementation-specific or undefined behavior. To
    detect some of these errors before they can become problematic,
    libstdc++ offers a debug mode that provides additional checking of
    library facilities, and will report errors in the use of libstdc++
    as soon as they can be detected by emitting a description of the
    problem to standard error and aborting the program.  This debug
    mode is available with GCC 3.4.0 and later versions.
  </para><para>
    The libstdc++ debug mode performs checking for many areas of the
    C++ standard, but the focus is on checking interactions among
    standard iterators, containers, and algorithms, including:
  </para><itemizedlist><listitem><para><emphasis>Safe iterators</emphasis>: Iterators keep track of the
    container whose elements they reference, so errors such as
    incrementing a past-the-end iterator or dereferencing an iterator
    that points to a container that has been destructed are diagnosed
    immediately.</para></listitem><listitem><para><emphasis>Algorithm preconditions</emphasis>: Algorithms attempt to
    validate their input parameters to detect errors as early as
    possible. For instance, the <code>set_intersection</code>
    algorithm requires that its iterator
    parameters <code>first1</code> and <code>last1</code> form a valid
    iterator range, and that the sequence
    [<code>first1</code>, <code>last1</code>) is sorted according to
    the same predicate that was passed
    to <code>set_intersection</code>; the libstdc++ debug mode will
    detect an error if the sequence is not sorted or was sorted by a
    different predicate.</para></listitem></itemizedlist></section><section xreflabel="Semantics" xml:id="manual.ext.debug_mode.semantics"><info><title>Semantics</title></info><?dbhtml filename="debug_mode_semantics.html"?><para>
  </para><para>A program that uses the C++ standard library correctly
  will maintain the same semantics under debug mode as it had with
  the normal (release) library. All functional and exception-handling
  guarantees made by the normal library also hold for the debug mode
  library, with one exception: performance guarantees made by the
  normal library may not hold in the debug mode library. For
  instance, erasing an element in a <code>std::list</code> is a
  constant-time operation in normal library, but in debug mode it is
  linear in the number of iterators that reference that particular
  list. So while your (correct) program won't change its results, it
  is likely to execute more slowly.</para><para>libstdc++ includes many extensions to the C++ standard library. In
  some cases the extensions are obvious, such as the hashed
  associative containers, whereas other extensions give predictable
  results to behavior that would otherwise be undefined, such as
  throwing an exception when a <code>std::basic_string</code> is
  constructed from a NULL character pointer. This latter category also
  includes implementation-defined and unspecified semantics, such as
  the growth rate of a vector. Use of these extensions is not
  considered incorrect, so code that relies on them will not be
  rejected by debug mode. However, use of these extensions may affect
  the portability of code to other implementations of the C++ standard
  library, and is therefore somewhat hazardous. For this reason, the
  libstdc++ debug mode offers a "pedantic" mode (similar to
  GCC's <code>-pedantic</code> compiler flag) that attempts to emulate
  the semantics guaranteed by the C++ standard. For
  instance, constructing a <code>std::basic_string</code> with a NULL
  character pointer would result in an exception under normal mode or
  non-pedantic debug mode (this is a libstdc++ extension), whereas
  under pedantic debug mode libstdc++ would signal an error. To enable
  the pedantic debug mode, compile your program with
  both <code>-D_GLIBCXX_DEBUG</code>
  and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> .
  (N.B. In GCC 3.4.x and 4.0.0, due to a bug,
  <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has
  been fixed in GCC 4.0.1 and later versions.) </para><para>The following library components provide extra debugging
  capabilities in debug mode:</para><itemizedlist><listitem><para><code>std::array</code> (no safe iterators)</para></listitem><listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem><listitem><para><code>std::bitset</code></para></listitem><listitem><para><code>std::deque</code></para></listitem><listitem><para><code>std::list</code></para></listitem><listitem><para><code>std::map</code></para></listitem><listitem><para><code>std::multimap</code></para></listitem><listitem><para><code>std::multiset</code></para></listitem><listitem><para><code>std::set</code></para></listitem><listitem><para><code>std::vector</code></para></listitem><listitem><para><code>std::unordered_map</code></para></listitem><listitem><para><code>std::unordered_multimap</code></para></listitem><listitem><para><code>std::unordered_set</code></para></listitem><listitem><para><code>std::unordered_multiset</code></para></listitem></itemizedlist><para>N.B. although there are precondition checks for some string operations,
e.g.  <code>operator[]</code>,
they will not always be run when using the <code>char</code> and
<code>wchar_t</code> specializations (<code>std::string</code> and
<code>std::wstring</code>).  This is because libstdc++ uses GCC's
<code>extern template</code> extension to provide explicit instantiations
of <code>std::string</code> and <code>std::wstring</code>, and those
explicit instantiations don't include the debug-mode checks.  If the
containing functions are inlined then the checks will run, so compiling
with <code>-O1</code> might be enough to enable them.  Alternatively
<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
of the explicit instantiations and cause the functions to be instantiated
with the debug-mode checks included, but this is unsupported and not
guaranteed to work.  For full debug-mode support you can use the
<code>__gnu_debug::basic_string</code> debugging container directly,
which always works correctly.
</para></section><section xreflabel="Using" xml:id="manual.ext.debug_mode.using"><info><title>Using</title></info><?dbhtml filename="debug_mode_using.html"?><para>
  </para><section xreflabel="Using Mode" xml:id="debug_mode.using.mode"><info><title>Using the Debug Mode</title></info><para>To use the libstdc++ debug mode, compile your application with the
  compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag
  changes the sizes and behavior of standard class templates such
  as <code>std::vector</code>, and therefore you can only link code
  compiled with debug mode and code compiled without debug mode if no
  instantiation of a container is passed between the two translation
  units.</para><para>By default, error messages are formatted to fit on lines of about
  78 characters.  The environment variable
  <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a
  different length.</para><para>Note that libstdc++ is able to produce backtraces on error.
  To enable these, compile with <code>-D_GLIBCXX_DEBUG_BACKTRACE</code>
  and then link with <option>-lstdc++exp</option>.
  These backtraces are not supported on all platforms.
</para></section><section xreflabel="Using Specific" xml:id="debug_mode.using.specific"><info><title>Using a Specific Debug Container</title></info><para>When it is not feasible to recompile your entire application, or
  only specific containers need checking, debugging containers are
  available as GNU extensions. These debugging containers are
  functionally equivalent to the standard drop-in containers used in
  debug mode, but they are available in a separate namespace as GNU
  extensions and may be used in programs compiled with either release
  mode or with debug mode. The
  following table provides the names and headers of the debugging
  containers:
</para><table frame="all" xml:id="table.debug_mode_containers"><title>Debugging Containers</title><tgroup align="left" cols="4" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Container</entry><entry>Header</entry><entry>Debug container</entry><entry>Debug header</entry></row></thead><tbody><row><entry><classname>std::bitset</classname></entry><entry><filename class="headerfile">bitset</filename></entry><entry><classname>__gnu_debug::bitset</classname></entry><entry><filename class="headerfile">&lt;debug/bitset&gt;</filename></entry></row><row><entry><classname>std::deque</classname></entry><entry><filename class="headerfile">deque</filename></entry><entry><classname>__gnu_debug::deque</classname></entry><entry><filename class="headerfile">&lt;debug/deque&gt;</filename></entry></row><row><entry><classname>std::list</classname></entry><entry><filename class="headerfile">list</filename></entry><entry><classname>__gnu_debug::list</classname></entry><entry><filename class="headerfile">&lt;debug/list&gt;</filename></entry></row><row><entry><classname>std::map</classname></entry><entry><filename class="headerfile">map</filename></entry><entry><classname>__gnu_debug::map</classname></entry><entry><filename class="headerfile">&lt;debug/map&gt;</filename></entry></row><row><entry><classname>std::multimap</classname></entry><entry><filename class="headerfile">map</filename></entry><entry><classname>__gnu_debug::multimap</classname></entry><entry><filename class="headerfile">&lt;debug/map&gt;</filename></entry></row><row><entry><classname>std::multiset</classname></entry><entry><filename class="headerfile">set</filename></entry><entry><classname>__gnu_debug::multiset</classname></entry><entry><filename class="headerfile">&lt;debug/set&gt;</filename></entry></row><row><entry><classname>std::set</classname></entry><entry><filename class="headerfile">set</filename></entry><entry><classname>__gnu_debug::set</classname></entry><entry><filename class="headerfile">&lt;debug/set&gt;</filename></entry></row><row><entry><classname>std::string</classname></entry><entry><filename class="headerfile">string</filename></entry><entry><classname>__gnu_debug::string</classname></entry><entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry></row><row><entry><classname>std::wstring</classname></entry><entry><filename class="headerfile">string</filename></entry><entry><classname>__gnu_debug::wstring</classname></entry><entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry></row><row><entry><classname>std::basic_string</classname></entry><entry><filename class="headerfile">string</filename></entry><entry><classname>__gnu_debug::basic_string</classname></entry><entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry></row><row><entry><classname>std::vector</classname></entry><entry><filename class="headerfile">vector</filename></entry><entry><classname>__gnu_debug::vector</classname></entry><entry><filename class="headerfile">&lt;debug/vector&gt;</filename></entry></row></tbody></tgroup></table><para>When compiling in C++11 mode (or newer), these
containers have additional debug capability.
</para><table frame="all" xml:id="table.debug_mode_containers_cxx11"><title>Debugging Containers C++11</title><tgroup align="left" cols="4" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Container</entry><entry>Header</entry><entry>Debug container</entry><entry>Debug header</entry></row></thead><tbody><row><entry><classname>std::forward_list</classname></entry><entry><filename class="headerfile">forward_list</filename></entry><entry><classname>__gnu_debug::forward_list</classname></entry><entry><filename class="headerfile">&lt;debug/forward_list&gt;</filename></entry></row><row><entry><classname>std::unordered_map</classname></entry><entry><filename class="headerfile">unordered_map</filename></entry><entry><classname>__gnu_debug::unordered_map</classname></entry><entry><filename class="headerfile">&lt;debug/unordered_map&gt;</filename></entry></row><row><entry><classname>std::unordered_multimap</classname></entry><entry><filename class="headerfile">unordered_map</filename></entry><entry><classname>__gnu_debug::unordered_multimap</classname></entry><entry><filename class="headerfile">&lt;debug/unordered_map&gt;</filename></entry></row><row><entry><classname>std::unordered_set</classname></entry><entry><filename class="headerfile">unordered_set</filename></entry><entry><classname>__gnu_debug::unordered_set</classname></entry><entry><filename class="headerfile">&lt;debug/unordered_set&gt;</filename></entry></row><row><entry><classname>std::unordered_multiset</classname></entry><entry><filename class="headerfile">unordered_set</filename></entry><entry><classname>__gnu_debug::unordered_multiset</classname></entry><entry><filename class="headerfile">&lt;debug/unordered_set&gt;</filename></entry></row></tbody></tgroup></table><para>Prior to GCC 11 a debug version of <classname>std::array</classname>
was available as <classname>__gnu_debug::array</classname> in the
header <filename class="headerfile">&lt;debug/array&gt;</filename>.
Because <classname>array::iterator</classname> is just a pointer,
the debug <classname>array</classname> can't check iterator operations,
it can only check direct accesses to the container.
Starting with GCC 11 all the debug capabilities are available in
<classname>std::array</classname>, without needing a separate type,
so <classname>__gnu_debug::array</classname> is just an alias for
<classname>std::array</classname>.
That alias is deprecated and may be removed in a future release.
</para></section></section><section xreflabel="Design" xml:id="manual.ext.debug_mode.design"><info><title>Design</title></info><?dbhtml filename="debug_mode_design.html"?><para>
  </para><section xreflabel="Goals" xml:id="debug_mode.design.goals"><info><title>Goals</title></info><para>
    </para><para> The libstdc++ debug mode replaces unsafe (but efficient) standard
  containers and iterators with semantically equivalent safe standard
  containers and iterators to aid in debugging user programs. The
  following goals directed the design of the libstdc++ debug mode:</para><itemizedlist><listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change
    the semantics of the standard library for all cases specified in
    the ANSI/ISO C++ standard. The essence of this constraint is that
    any valid C++ program should behave in the same manner regardless
    of whether it is compiled with debug mode or release mode. In
    particular, entities that are defined in namespace std in release
    mode should remain defined in namespace std in debug mode, so that
    legal specializations of namespace std entities will remain
    valid. A program that is not valid C++ (e.g., invokes undefined
    behavior) is not required to behave similarly, although the debug
    mode will abort with a diagnostic when it detects undefined
    behavior.</para></listitem><listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode
    must not affect the performance of the library when it is compiled
    in release mode. Performance of the libstdc++ debug mode is
    secondary (and, in fact, will be worse than the release
    mode).</para></listitem><listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to
    use. It should be easily incorporated into the user's development
    environment (e.g., by requiring only a single new compiler switch)
    and should produce reasonable diagnostics when it detects a
    problem with the user program. Usability also involves detection
    of errors when using the debug mode incorrectly, e.g., by linking
    a release-compiled object against a debug-compiled object if in
    fact the resulting program will not run correctly.</para></listitem><listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that
    users recompile at least part of their program to use debug
    mode, the amount of recompilation affects the
    detect-compile-debug turnaround time. This indirectly affects the
    usefulness of the debug mode, because debugging some applications
    may require rebuilding a large amount of code, which may not be
    feasible when the suspect code may be very localized. There are
    several levels of conformance to this requirement, each with its
    own usability and implementation characteristics. In general, the
    higher-numbered conformance levels are more usable (i.e., require
    less recompilation) but are more complicated to implement than
    the lower-numbered conformance levels.
      <orderedlist continuation="restarts" inheritnum="ignore"><listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile
	their entire application and all C++ libraries it depends on,
	including the C++ standard library that ships with the
	compiler. This must be done even if only a small part of the
	program can use debugging features.</para></listitem><listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile
	their entire application and all C++ libraries it depends
	on, but not the C++ standard library itself. This must be done
	even if only a small part of the program can use debugging
	features. This can be achieved given a full recompilation
	system by compiling two versions of the standard library when
	the compiler is installed and linking against the appropriate
	one, e.g., a multilibs approach.</para></listitem><listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the
	parts of their application and the C++ libraries it
	depends on that will use the debugging facilities
	directly. This means that any code that uses the debuggable
	standard containers would need to be recompiled, but code
	that does not use them (but may, for instance, use IOStreams)
	would not have to be recompiled.</para></listitem><listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the
	parts of their application and the C++ libraries it
	depends on where debugging should occur, and any other code
	that interacts with those containers. This means that a set of
	translation units that accesses a particular standard
	container instance may either be compiled in release mode (no
	checking) or debug mode (full checking), but must all be
	compiled in the same way; a translation unit that does not see
	that standard container instance need not be recompiled. This
	also means that a translation unit <emphasis>A</emphasis> that contains a
	particular instantiation
	(say, <code>std::vector&lt;int&gt;</code>) compiled in release
	mode can be linked against a translation unit <emphasis>B</emphasis> that
	contains the same instantiation compiled in debug mode (a
	feature not present with partial recompilation). While this
	behavior is technically a violation of the One Definition
	Rule, this ability tends to be very important in
	practice. The libstdc++ debug mode supports this level of
	recompilation. </para></listitem><listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only
	recompile the translation units where checking should occur,
	regardless of where debuggable standard containers are
	used. This has also been dubbed "<code>-g</code> mode",
	because the <code>-g</code> compiler switch works in this way,
	emitting debugging information at a per--translation-unit
	granularity. We believe that this level of recompilation is in
	fact not possible if we intend to supply safe iterators, leave
	the program semantics unchanged, and not regress in
	performance under release mode because we cannot associate
	extra information with an iterator (to form a safe iterator)
	without either reserving that space in release mode
	(performance regression) or allocating extra memory associated
	with each iterator with <code>new</code> (changes the program
	semantics).</para></listitem></orderedlist></para></listitem></itemizedlist></section><section xreflabel="Methods" xml:id="debug_mode.design.methods"><info><title>Methods</title></info><para>
    </para><para>This section provides an overall view of the design of the
  libstdc++ debug mode and details the relationship between design
  decisions and the stated design goals.</para><section xreflabel="Method Wrapper" xml:id="debug_mode.design.methods.wrappers"><info><title>The Wrapper Model</title></info><para>The libstdc++ debug mode uses a wrapper model where the
  debugging versions of library components (e.g., iterators and
  containers) form a layer on top of the release versions of the
  library components. The debugging components first verify that the
  operation is correct (aborting with a diagnostic if an error is
  found) and will then forward to the underlying release-mode
  container that will perform the actual work. This design decision
  ensures that we cannot regress release-mode performance (because the
  release-mode containers are left untouched) and partially
  enables <link linkend="methods.coexistence.link">mixing debug and
  release code</link> at link time, although that will not be
  discussed at this time.</para><para>Two types of wrappers are used in the implementation of the debug
  mode: container wrappers and iterator wrappers. The two types of
  wrappers interact to maintain relationships between iterators and
  their associated containers, which are necessary to detect certain
  types of standard library usage errors such as dereferencing
  past-the-end iterators or inserting into a container using an
  iterator from a different container.</para><section xreflabel="Method Safe Iter" xml:id="debug_mode.design.methods.safe_iter"><info><title>Safe Iterators</title></info><para>Iterator wrappers provide a debugging layer over any iterator that
  is attached to a particular container, and will manage the
  information detailing the iterator's state (singular,
  dereferenceable, etc.) and tracking the container to which the
  iterator is attached. Because iterators have a well-defined, common
  interface the iterator wrapper is implemented with the iterator
  adaptor class template <code>__gnu_debug::_Safe_iterator</code>,
  which takes two template parameters:</para><itemizedlist><listitem><para><code>Iterator</code>: The underlying iterator type, which must
    be either the <code>iterator</code> or <code>const_iterator</code>
    typedef from the sequence type this iterator can reference.</para></listitem><listitem><para><code>Sequence</code>: The type of sequence that this iterator
  references. This sequence must be a safe sequence (discussed below)
  whose <code>iterator</code> or <code>const_iterator</code> typedef
  is the type of the safe iterator.</para></listitem></itemizedlist></section><section xreflabel="Method Safe Seq" xml:id="debug_mode.design.methods.safe_seq"><info><title>Safe Sequences (Containers)</title></info><para>Container wrappers provide a debugging layer over a particular
  container type. Because containers vary greatly in the member
  functions they support and the semantics of those member functions
  (especially in the area of iterator invalidation), container
  wrappers are tailored to the container they reference, e.g., the
  debugging version of <code>std::list</code> duplicates the entire
  interface of <code>std::list</code>, adding additional semantic
  checks and then forwarding operations to the
  real <code>std::list</code> (a public base class of the debugging
  version) as appropriate. However, all safe containers inherit from
  the class template <code>__gnu_debug::_Safe_sequence</code>,
  instantiated with the type of the safe container itself (an instance
  of the curiously recurring template pattern).</para><para>The iterators of a container wrapper will be
  <link linkend="debug_mode.design.methods.safe_iter">safe
  iterators</link> that reference sequences of this type and wrap the
  iterators provided by the release-mode base class. The debugging
  container will use only the safe iterators within its own interface
  (therefore requiring the user to use safe iterators, although this
  does not change correct user code) and will communicate with the
  release-mode base class with only the underlying, unsafe,
  release-mode iterators that the base class exports.</para><para> The debugging version of <code>std::list</code> will have the
  following basic structure:</para><programlisting>
template&lt;typename _Tp, typename _Allocator = allocator&lt;_Tp&gt;
  class debug-list :
    public release-list&lt;_Tp, _Allocator&gt;,
    public __gnu_debug::_Safe_sequence&lt;debug-list&lt;_Tp, _Allocator&gt; &gt;
  {
    typedef release-list&lt;_Tp, _Allocator&gt; _Base;
    typedef debug-list&lt;_Tp, _Allocator&gt;   _Self;

  public:
    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::iterator, _Self&gt;       iterator;
    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::const_iterator, _Self&gt; const_iterator;

    // duplicate std::list interface with debugging semantics
  };
</programlisting></section></section><section xreflabel="Precondition check" xml:id="debug_mode.design.methods.precond"><info><title>Precondition Checking</title></info><para>The debug mode operates primarily by checking the preconditions of
  all standard library operations that it supports. Preconditions that
  are always checked (regardless of whether or not we are in debug
  mode) are checked via the <code>__check_xxx</code> macros defined
  and documented in the source
  file <code>include/debug/debug.h</code>. Preconditions that may or
  may not be checked, depending on the debug-mode
  macro <code>_GLIBCXX_DEBUG</code>, are checked via
  the <code>__requires_xxx</code> macros defined and documented in the
  same source file. Preconditions are validated using any additional
  information available at run-time, e.g., the containers that are
  associated with a particular iterator, the position of the iterator
  within those containers, the distance between two iterators that may
  form a valid range, etc. In the absence of suitable information,
  e.g., an input iterator that is not a safe iterator, these
  precondition checks will silently succeed.</para><para>The majority of precondition checks use the aforementioned macros,
  which have the secondary benefit of having prewritten debug
  messages that use information about the current status of the
  objects involved (e.g., whether an iterator is singular or what
  sequence it is attached to) along with some static information
  (e.g., the names of the function parameters corresponding to the
  objects involved). When not using these macros, the debug mode uses
  either the debug-mode assertion
  macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic
  cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion
  check macro that supports more advance formulation of error
  messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are
  documented more thoroughly in the debug mode source code.</para></section><section xreflabel="Coexistence" xml:id="debug_mode.design.methods.coexistence"><info><title>Release- and debug-mode coexistence</title></info><para>The libstdc++ debug mode is the first debug mode we know of that
  is able to provide the "Per-use recompilation" (4) guarantee, that
  allows release-compiled and debug-compiled code to be linked and
  executed together without causing unpredictable behavior. This
  guarantee minimizes the recompilation that users are required to
  perform, shortening the detect-compile-debug bug hunting cycle
  and making the debug mode easier to incorporate into development
  environments by minimizing dependencies.</para><para>Achieving link- and run-time coexistence is not a trivial
  implementation task. To achieve this goal we use inline namespaces and
  a complex organization of debug- and release-modes. The end result is
  that we have achieved per-use recompilation but have had to give up
  some checking of the <code>std::basic_string</code> class template
  (namely, safe iterators).</para><section xreflabel="Compile" xml:id="methods.coexistence.compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info><para>Both the release-mode components and the debug-mode
  components need to exist within a single translation unit so that
  the debug versions can wrap the release versions. However, only one
  of these components should be user-visible at any particular
  time with the standard name, e.g., <code>std::list</code>. </para><para>In release mode, we define only the release-mode version of the
  component with its standard name and do not include the debugging
  component at all. The release mode version is defined within the
  namespace <code>std</code>. Minus the namespace associations, this
  method leaves the behavior of release mode completely unchanged from
  its behavior prior to the introduction of the libstdc++ debug
  mode. Here's an example of what this ends up looking like, in
  C++.</para><programlisting>
namespace std
{
  template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
    class list
    {
      // ...
     };
} // namespace std
</programlisting><para>In debug mode we include the release-mode container (which is now
defined in the namespace <code>__cxx1998</code>) and also the
debug-mode container. The debug-mode container is defined within the
namespace <code>__debug</code>, which is associated with namespace
<code>std</code> via the C++11 namespace association language feature.  This
method allows the debug and release versions of the same component to
coexist at compile-time and link-time without causing an unreasonable
maintenance burden, while minimizing confusion. Again, this boils down
to C++ code as follows:</para><programlisting>
namespace std
{
  namespace __cxx1998
  {
    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
      class list
      {
	// ...
      };
  } // namespace __gnu_norm

  namespace __debug
  {
    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
      class list
      : public __cxx1998::list&lt;_Tp, _Alloc&gt;,
	public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
      {
	// ...
      };
  } // namespace __cxx1998

  inline namespace __debug { }
}
</programlisting></section><section xreflabel="Link" xml:id="methods.coexistence.link"><info><title>Link- and run-time coexistence of release- and
    debug-mode components</title></info><para>Because each component has a distinct and separate release and
debug implementation, there is no issue with link-time
coexistence: the separate namespaces result in different mangled
names, and thus unique linkage.</para><para>However, components that are defined and used within the C++
standard library itself face additional constraints. For instance,
some of the member functions of <code> std::moneypunct</code> return
<code>std::basic_string</code>. Normally, this is not a problem, but
with a mixed mode standard library that could be using either
debug-mode or release-mode <code> basic_string</code> objects, things
get more complicated.  As the return value of a function is not
encoded into the mangled name, there is no way to specify a
release-mode or a debug-mode string. In practice, this results in
runtime errors. A simplified example of this problem is as follows.
</para><para> Take this translation unit, compiled in debug-mode: </para><programlisting>
// -D_GLIBCXX_DEBUG
#include &lt;string&gt;

std::string test02();

std::string test01()
{
  return test02();
}

int main()
{
  test01();
  return 0;
}
</programlisting><para> ... and linked to this translation unit, compiled in release mode:</para><programlisting>
#include &lt;string&gt;

std::string
test02()
{
  return std::string("toast");
}
</programlisting><para> For this reason we cannot easily provide safe iterators for
  the <code>std::basic_string</code> class template, as it is present
  throughout the C++ standard library. For instance, locale facets
  define typedefs that include <code>basic_string</code>: in a mixed
  debug/release program, should that typedef be based on the
  debug-mode <code>basic_string</code> or the
  release-mode <code>basic_string</code>? While the answer could be
  "both", and the difference hidden via renaming a la the
  debug/release containers, we must note two things about locale
  facets:</para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>They exist as shared state: one can create a facet in one
  translation unit and access the facet via the same type name in a
  different translation unit. This means that we cannot have two
  different versions of locale facets, because the types would not be
  the same across debug/release-mode translation unit barriers.</para></listitem><listitem><para>They have virtual functions returning strings: these functions
  mangle in the same way regardless of the mangling of their return
  types (see above), and their precise signatures can be relied upon
  by users because they may be overridden in derived classes.</para></listitem></orderedlist><para>With the design of libstdc++ debug mode, we cannot effectively hide
  the differences between debug and release-mode strings from the
  user. Failure to hide the differences may result in unpredictable
  behavior, and for this reason we have opted to only
  perform <code>basic_string</code> changes that do not require ABI
  changes. The effect on users is expected to be minimal, as there are
  simple alternatives (e.g., <code>__gnu_debug::basic_string</code>),
  and the usability benefit we gain from the ability to mix debug- and
  release-compiled translation units is enormous.</para></section><section xreflabel="Alternatives" xml:id="methods.coexistence.alt"><info><title>Alternatives for Coexistence</title></info><para>The coexistence scheme above was chosen over many alternatives,
  including language-only solutions and solutions that also required
  extensions to the C++ front end. The following is a partial list of
  solutions, with justifications for our rejection of each.</para><itemizedlist><listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by
  far the simplest implementation option, where we do not allow any
  coexistence of debug- and release-compiled translation units in a
  program. This solution has an extreme negative affect on usability,
  because it is quite likely that some libraries an application
  depends on cannot be recompiled easily. This would not meet
  our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria
  well.</para></listitem><listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>:
  Partial specialization could be used to select the debug
  implementation when <code>Debug == true</code>, and the state
  of <code>_GLIBCXX_DEBUG</code> could decide whether the
  default <code>Debug</code> argument is <code>true</code>
  or <code>false</code>. This option would break conformance with the
  C++ standard in both debug <emphasis>and</emphasis> release modes. This would
  not meet our <emphasis>correctness</emphasis> criteria. </para></listitem><listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could
    reuse the <code>Allocator</code> template parameter of containers
    by adding a sentinel wrapper <code>debug&lt;&gt;</code> that
    signals the user's intention to use debugging, and pick up
    the <code>debug&lt;&gt;</code> allocator wrapper in a partial
    specialization. However, this has two drawbacks: first, there is a
    conformance issue because the default allocator would not be the
    standard-specified <code>std::allocator&lt;T&gt;</code>. Secondly
    (and more importantly), users that specify allocators instead of
    implicitly using the default allocator would not get debugging
    containers. Thus this solution fails the <emphasis>correctness</emphasis>
    criteria.</para></listitem><listitem><para><emphasis>Define debug containers in another namespace, and employ
      a <code>using</code> declaration (or directive)</emphasis>: This is an
      enticing option, because it would eliminate the need for
      the <code>link_name</code> extension by aliasing the
      templates. However, there is no true template aliasing mechanism
      in C++, because both <code>using</code> directives and using
      declarations disallow specialization. This method fails
      the <emphasis>correctness</emphasis> criteria.</para></listitem><listitem><para><emphasis> Use implementation-specific properties of anonymous
    namespaces. </emphasis>
    See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html">this post</link>.
    This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem><listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would
    allow the debug mode to effectively alias the
    namespace <code>std</code> to an internal namespace, such
    as <code>__gnu_std_debug</code>, so that it is completely
    separate from the release-mode <code>std</code> namespace. While
    this will solve some renaming problems and ensure that
    debug- and release-compiled code cannot be mixed unsafely, it ensures that
    debug- and release-compiled code cannot be mixed at all. For
    instance, the program would have two <code>std::cout</code>
    objects! This solution would fails the <emphasis>minimize
    recompilation</emphasis> requirement, because we would only be able to
    support option (1) or (2).</para></listitem><listitem><para><emphasis>Extension: use link name</emphasis>: This option
    involves complicated re-naming between debug-mode and release-mode
    components at compile time, and then a g++ extension called <emphasis>
    link name </emphasis> to recover the original names at link time. There
    are two drawbacks to this approach. One, it's very verbose,
    relying on macro renaming at compile time and several levels of
    include ordering. Two, ODR issues remained with container member
    functions taking no arguments in mixed-mode settings resulting in
    equivalent link names, <code> vector::push_back() </code> being
    one example.
    See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">proof-of-concept using link
    name</link>. </para></listitem></itemizedlist><para>Other options may exist for implementing the debug mode, many of
  which have probably been considered and others that may still be
  lurking. This list may be expanded over time to include other
  options that we could have implemented, but in all cases the full
  ramifications of the approach (as measured against the design goals
  for a libstdc++ debug mode) should be considered first. The DejaGNU
  testsuite includes some testcases that check for known problems with
  some solutions (e.g., the <code>using</code> declaration solution
  that breaks user specialization), and additional testcases will be
  added as we are able to identify other typical problem cases. These
  test cases will serve as a benchmark by which we can compare debug
  mode implementations.</para></section></section></section><section xreflabel="Other" xml:id="debug_mode.design.other"><info><title>Other Implementations</title></info><para>
    </para><para> There are several existing implementations of debug modes for C++
  standard library implementations, although none of them directly
  supports debugging for programs using libstdc++. The existing
  implementations include:</para><itemizedlist><listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</link>:
  SafeSTL was the original debugging version of the Standard Template
  Library (STL), implemented by Cay S. Horstmann on top of the
  Hewlett-Packard STL. Though it inspired much work in this area, it
  has not been kept up-to-date for use with modern compilers or C++
  standard library implementations.</para></listitem><listitem><para>STLport: STLport was a free
  implementation of the C++ standard library derived from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/">SGI implementation</link>, and
  ported to many other platforms. It included a debug mode that used a
  wrapper model (that in some ways inspired the libstdc++ debug mode
  design), although its debug mode was
  somewhat incomplete and met only the "Full user recompilation" (2)
  recompilation guarantee by requiring the user to link against a
  different library in debug mode vs. release mode.</para></listitem><listitem><para>Metrowerks CodeWarrior: The C++ standard library
  that shipped with Metrowerks CodeWarrior included a debug mode. It was
  a full debug-mode implementation (including debugging for
  CodeWarrior extensions) and was easy to use, although it met only
  the "Full recompilation" (1) recompilation
  guarantee.</para></listitem><listitem><para>The MSVC STL and LLVM libc++ implementations of the
  C++ Standard Library both include some form of debug mode.
  </para></listitem></itemizedlist></section></section></chapter><!-- Chapter 03 : Parallel Mode --><chapter version="5.0" xreflabel="Parallel Mode" xml:id="manual.ext.parallel_mode"><?dbhtml filename="parallel_mode.html"?><info><title>Parallel Mode</title><keywordset><keyword>C++</keyword><keyword>library</keyword><keyword>parallel</keyword></keywordset></info><para> The libstdc++ parallel mode is an experimental parallel
implementation of many algorithms of the C++ Standard Library.
</para><para>
Several of the standard algorithms, for instance
<function>std::sort</function>, are made parallel using OpenMP
annotations. These parallel mode constructs can be invoked by
explicit source declaration or by compiling existing sources with a
specific compiler flag.
</para><note><para>
    The parallel mode has not been kept up to date with recent C++ standards
    and so it only conforms to the C++03 requirements.
    That means that move-only predicates may not work with parallel mode
    algorithms, and for C++20 most of the algorithms cannot be used in
    <code>constexpr</code> functions.
  </para><para>
    For C++17 and above there are new overloads of the standard algorithms
    which take an execution policy argument. You should consider using those
    instead of the non-standard parallel mode extensions.
  </para></note><section xreflabel="Intro" xml:id="manual.ext.parallel_mode.intro"><info><title>Intro</title></info><para>The following library components in the include
<filename class="headerfile">numeric</filename> are included in the parallel mode:</para><itemizedlist><listitem><para><function>std::accumulate</function></para></listitem><listitem><para><function>std::adjacent_difference</function></para></listitem><listitem><para><function>std::inner_product</function></para></listitem><listitem><para><function>std::partial_sum</function></para></listitem></itemizedlist><para>The following library components in the include
<filename class="headerfile">algorithm</filename> are included in the parallel mode:</para><itemizedlist><listitem><para><function>std::adjacent_find</function></para></listitem><listitem><para><function>std::count</function></para></listitem><listitem><para><function>std::count_if</function></para></listitem><listitem><para><function>std::equal</function></para></listitem><listitem><para><function>std::find</function></para></listitem><listitem><para><function>std::find_if</function></para></listitem><listitem><para><function>std::find_first_of</function></para></listitem><listitem><para><function>std::for_each</function></para></listitem><listitem><para><function>std::generate</function></para></listitem><listitem><para><function>std::generate_n</function></para></listitem><listitem><para><function>std::lexicographical_compare</function></para></listitem><listitem><para><function>std::mismatch</function></para></listitem><listitem><para><function>std::search</function></para></listitem><listitem><para><function>std::search_n</function></para></listitem><listitem><para><function>std::transform</function></para></listitem><listitem><para><function>std::replace</function></para></listitem><listitem><para><function>std::replace_if</function></para></listitem><listitem><para><function>std::max_element</function></para></listitem><listitem><para><function>std::merge</function></para></listitem><listitem><para><function>std::min_element</function></para></listitem><listitem><para><function>std::nth_element</function></para></listitem><listitem><para><function>std::partial_sort</function></para></listitem><listitem><para><function>std::partition</function></para></listitem><listitem><para><function>std::random_shuffle</function></para></listitem><listitem><para><function>std::set_union</function></para></listitem><listitem><para><function>std::set_intersection</function></para></listitem><listitem><para><function>std::set_symmetric_difference</function></para></listitem><listitem><para><function>std::set_difference</function></para></listitem><listitem><para><function>std::sort</function></para></listitem><listitem><para><function>std::stable_sort</function></para></listitem><listitem><para><function>std::unique_copy</function></para></listitem></itemizedlist></section><section xreflabel="Semantics" xml:id="manual.ext.parallel_mode.semantics"><info><title>Semantics</title></info><?dbhtml filename="parallel_mode_semantics.html"?><para> The parallel mode STL algorithms are currently not exception-safe,
i.e. user-defined functors must not throw exceptions.
Also, the order of execution is not guaranteed for some functions, of course.
Therefore, user-defined functors should not have any concurrent side effects.
</para><para> Since the current GCC OpenMP implementation does not support
OpenMP parallel regions in concurrent threads,
it is not possible to call parallel STL algorithm in
concurrent threads, either.
It might work with other compilers, though.</para></section><section xreflabel="Using" xml:id="manual.ext.parallel_mode.using"><info><title>Using</title></info><?dbhtml filename="parallel_mode_using.html"?><section xml:id="parallel_mode.using.prereq_flags"><info><title>Prerequisite Compiler Flags</title></info><para>
  Any use of parallel functionality requires additional compiler
  and runtime support, in particular support for OpenMP. Adding this support is
  not difficult: just compile your application with the compiler
  flag <literal>-fopenmp</literal>. This will link
  in <code>libgomp</code>, the
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libgomp/">GNU Offloading and
    Multi Processing Runtime Library</link>,
  whose presence is mandatory.
</para><para>
In addition, hardware that supports atomic operations and a compiler
  capable of producing atomic operations is mandatory: GCC defaults to no
  support for atomic operations on some common hardware
  architectures. Activating atomic operations may require explicit
  compiler flags on some targets (like sparc and x86), such
  as <literal>-march=i686</literal>,
  <literal>-march=native</literal> or <literal>-mcpu=v9</literal>. See
  the GCC manual for more information.
</para></section><section xml:id="parallel_mode.using.parallel_mode"><info><title>Using Parallel Mode</title></info><para>
  To use the libstdc++ parallel mode, compile your application with
  the prerequisite flags as detailed above, and in addition
  add <constant>-D_GLIBCXX_PARALLEL</constant>. This will convert all
  use of the standard (sequential) algorithms to the appropriate parallel
  equivalents. Please note that this doesn't necessarily mean that
  everything will end up being executed in a parallel manner, but
  rather that the heuristics and settings coded into the parallel
  versions will be used to determine if all, some, or no algorithms
  will be executed using parallel variants.
</para><para>Note that the <constant>_GLIBCXX_PARALLEL</constant> define may change the
  sizes and behavior of standard class templates such as
  <function>std::search</function>, and therefore one can only link code
  compiled with parallel mode and code compiled without parallel mode
  if no instantiation of a container is passed between the two
  translation units. Parallel mode functionality has distinct linkage,
  and cannot be confused with normal mode symbols.
</para></section><section xml:id="parallel_mode.using.specific"><info><title>Using Specific Parallel Components</title></info><para>When it is not feasible to recompile your entire application, or
  only specific algorithms need to be parallel-aware, individual
  parallel algorithms can be made available explicitly. These
  parallel algorithms are functionally equivalent to the standard
  drop-in algorithms used in parallel mode, but they are available in
  a separate namespace as GNU extensions and may be used in programs
  compiled with either release mode or with parallel mode.
</para><para>An example of using a parallel version
of <function>std::sort</function>, but no other parallel algorithms, is:
</para><programlisting>
#include &lt;vector&gt;
#include &lt;parallel/algorithm&gt;

int main()
{
  std::vector&lt;int&gt; v(100);

  // ...

  // Explicitly force a call to parallel sort.
  __gnu_parallel::sort(v.begin(), v.end());
  return 0;
}
</programlisting><para>
Then compile this code with the prerequisite compiler flags
(<literal>-fopenmp</literal> and any necessary architecture-specific
flags for atomic operations.)
</para><para> The following table provides the names and headers of all the
  parallel algorithms that can be used in a similar manner:
</para><table frame="all" xml:id="table.parallel_algos"><title>Parallel Algorithms</title><tgroup align="left" cols="4" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Algorithm</entry><entry>Header</entry><entry>Parallel algorithm</entry><entry>Parallel header</entry></row></thead><tbody><row><entry><function>std::accumulate</function></entry><entry><filename class="headerfile">numeric</filename></entry><entry><function>__gnu_parallel::accumulate</function></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row><row><entry><function>std::adjacent_difference</function></entry><entry><filename class="headerfile">numeric</filename></entry><entry><function>__gnu_parallel::adjacent_difference</function></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row><row><entry><function>std::inner_product</function></entry><entry><filename class="headerfile">numeric</filename></entry><entry><function>__gnu_parallel::inner_product</function></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row><row><entry><function>std::partial_sum</function></entry><entry><filename class="headerfile">numeric</filename></entry><entry><function>__gnu_parallel::partial_sum</function></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row><row><entry><function>std::adjacent_find</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::adjacent_find</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::count</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::count</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::count_if</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::count_if</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::equal</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::equal</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::find</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::find</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::find_if</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::find_if</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::find_first_of</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::find_first_of</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::for_each</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::for_each</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::generate</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::generate</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::generate_n</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::generate_n</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::lexicographical_compare</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::lexicographical_compare</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::mismatch</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::mismatch</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::search</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::search</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::search_n</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::search_n</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::transform</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::transform</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::replace</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::replace</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::replace_if</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::replace_if</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::max_element</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::max_element</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::merge</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::merge</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::min_element</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::min_element</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::nth_element</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::nth_element</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::partial_sort</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::partial_sort</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::partition</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::partition</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::random_shuffle</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::random_shuffle</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::set_union</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::set_union</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::set_intersection</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::set_intersection</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::set_symmetric_difference</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::set_symmetric_difference</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::set_difference</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::set_difference</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::sort</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::sort</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::stable_sort</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::stable_sort</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row><row><entry><function>std::unique_copy</function></entry><entry><filename class="headerfile">algorithm</filename></entry><entry><function>__gnu_parallel::unique_copy</function></entry><entry><filename class="headerfile">parallel/algorithm</filename></entry></row></tbody></tgroup></table></section></section><section xreflabel="Design" xml:id="manual.ext.parallel_mode.design"><info><title>Design</title></info><?dbhtml filename="parallel_mode_design.html"?><para>
  </para><section xreflabel="Intro" xml:id="parallel_mode.design.intro"><info><title>Interface Basics</title></info><para>
All parallel algorithms are intended to have signatures that are
equivalent to the ISO C++ algorithms replaced. For instance, the
<function>std::adjacent_find</function> function is declared as:
</para><programlisting>
namespace std
{
  template&lt;typename _FIter&gt;
    _FIter
    adjacent_find(_FIter, _FIter);
}
</programlisting><para>
Which means that there should be something equivalent for the parallel
version. Indeed, this is the case:
</para><programlisting>
namespace std
{
  namespace __parallel
  {
    template&lt;typename _FIter&gt;
      _FIter
      adjacent_find(_FIter, _FIter);

    ...
  }
}
</programlisting><para>But.... why the ellipses?
</para><para> The ellipses in the example above represent additional overloads
required for the parallel version of the function. These additional
overloads are used to dispatch calls from the ISO C++ function
signature to the appropriate parallel function (or sequential
function, if no parallel functions are deemed worthy), based on either
compile-time or run-time conditions.
</para><para> The available signature options are specific for the different
algorithms/algorithm classes.</para><para> The general view of overloads for the parallel algorithms look like this:
</para><itemizedlist><listitem><para>ISO C++ signature</para></listitem><listitem><para>ISO C++ signature + sequential_tag argument</para></listitem><listitem><para>ISO C++ signature + algorithm-specific tag type
    (several signatures)</para></listitem></itemizedlist><para> Please note that the implementation may use additional functions
(designated with the <code>_switch</code> suffix) to dispatch from the
ISO C++ signature to the correct parallel version. Also, some of the
algorithms do not have support for run-time conditions, so the last
overload is therefore missing.
</para></section><section xreflabel="Tuning" xml:id="parallel_mode.design.tuning"><info><title>Configuration and Tuning</title></info><section xreflabel="OpenMP Environment" xml:id="parallel_mode.design.tuning.omp"><info><title>Setting up the OpenMP Environment</title></info><para>
Several aspects of the overall runtime environment can be manipulated
by standard OpenMP function calls.
</para><para>
To specify the number of threads to be used for the algorithms globally,
use the function <function>omp_set_num_threads</function>. An example:
</para><programlisting>
#include &lt;stdlib.h&gt;
#include &lt;omp.h&gt;

int main()
{
  // Explicitly set number of threads.
  const int threads_wanted = 20;
  omp_set_dynamic(false);
  omp_set_num_threads(threads_wanted);

  // Call parallel mode algorithms.

  return 0;
}
</programlisting><para>
 Some algorithms allow the number of threads being set for a particular call,
 by augmenting the algorithm variant.
 See the next section for further information.
</para><para>
Other parts of the runtime environment able to be manipulated include
nested parallelism (<function>omp_set_nested</function>), schedule kind
(<function>omp_set_schedule</function>), and others. See the OpenMP
documentation for more information.
</para></section><section xreflabel="Compile Switches" xml:id="parallel_mode.design.tuning.compile"><info><title>Compile Time Switches</title></info><para>
To force an algorithm to execute sequentially, even though parallelism
is switched on in general via the macro <constant>_GLIBCXX_PARALLEL</constant>,
add <classname>__gnu_parallel::sequential_tag()</classname> to the end
of the algorithm's argument list.
</para><para>
Like so:
</para><programlisting>
std::sort(v.begin(), v.end(), __gnu_parallel::sequential_tag());
</programlisting><para>
Some parallel algorithm variants can be excluded from compilation by
preprocessor defines. See the doxygen documentation on
<code>compiletime_settings.h</code> and <code>features.h</code> for details.
</para><para>
For some algorithms, the desired variant can be chosen at compile-time by
appending a tag object. The available options are specific to the particular
algorithm (class).
</para><para>
For the "embarrassingly parallel" algorithms, there is only one "tag object
type", the enum _Parallelism.
It takes one of the following values,
<code>__gnu_parallel::parallel_tag</code>,
<code>__gnu_parallel::balanced_tag</code>,
<code>__gnu_parallel::unbalanced_tag</code>,
<code>__gnu_parallel::omp_loop_tag</code>,
<code>__gnu_parallel::omp_loop_static_tag</code>.
This means that the actual parallelization strategy is chosen at run-time.
(Choosing the variants at compile-time will come soon.)
</para><para>
For the following algorithms in general, we have
<code>__gnu_parallel::parallel_tag</code> and
<code>__gnu_parallel::default_parallel_tag</code>, in addition to
<code>__gnu_parallel::sequential_tag</code>.
<code>__gnu_parallel::default_parallel_tag</code> chooses the default
algorithm at compiletime, as does omitting the tag.
<code>__gnu_parallel::parallel_tag</code> postpones the decision to runtime
(see next section).
For all tags, the number of threads desired for this call can optionally be
passed to the respective tag's constructor.
</para><para>
The <code>multiway_merge</code> algorithm comes with the additional choices,
<code>__gnu_parallel::exact_tag</code> and
<code>__gnu_parallel::sampling_tag</code>.
Exact and sampling are the two available splitting strategies.
</para><para>
For the <code>sort</code> and <code>stable_sort</code> algorithms, there are
several additional choices, namely
<code>__gnu_parallel::multiway_mergesort_tag</code>,
<code>__gnu_parallel::multiway_mergesort_exact_tag</code>,
<code>__gnu_parallel::multiway_mergesort_sampling_tag</code>,
<code>__gnu_parallel::quicksort_tag</code>, and
<code>__gnu_parallel::balanced_quicksort_tag</code>.
Multiway mergesort comes with the two splitting strategies for multi-way
merging. The quicksort options cannot be used for <code>stable_sort</code>.
</para></section><section xreflabel="_Settings" xml:id="parallel_mode.design.tuning.settings"><info><title>Run Time Settings and Defaults</title></info><para>
The default parallelization strategy, the choice of specific algorithm
strategy, the minimum threshold limits for individual parallel
algorithms, and aspects of the underlying hardware can be specified as
desired via manipulation
of <classname>__gnu_parallel::_Settings</classname> member data.
</para><para>
First off, the choice of parallelization strategy: serial, parallel,
or heuristically deduced. This corresponds
to <code>__gnu_parallel::_Settings::algorithm_strategy</code> and is a
value of enum <type>__gnu_parallel::_AlgorithmStrategy</type>
type. Choices
include: <type>heuristic</type>, <type>force_sequential</type>,
and <type>force_parallel</type>. The default is <type>heuristic</type>.
</para><para>
Next, the sub-choices for algorithm variant, if not fixed at compile-time.
Specific algorithms like <function>find</function> or <function>sort</function>
can be implemented in multiple ways: when this is the case,
a <classname>__gnu_parallel::_Settings</classname> member exists to
pick the default strategy. For
example, <code>__gnu_parallel::_Settings::sort_algorithm</code> can
have any values of
enum <type>__gnu_parallel::_SortAlgorithm</type>: <type>MWMS</type>, <type>QS</type>,
or <type>QS_BALANCED</type>.
</para><para>
Likewise for setting the minimal threshold for algorithm
parallelization.  Parallelism always incurs some overhead. Thus, it is
not helpful to parallelize operations on very small sets of
data. Because of this, measures are taken to avoid parallelizing below
a certain, pre-determined threshold. For each algorithm, a minimum
problem size is encoded as a variable in the
active <classname>__gnu_parallel::_Settings</classname> object.  This
threshold variable follows the following naming scheme:
<code>__gnu_parallel::_Settings::[algorithm]_minimal_n</code>.  So,
for <function>fill</function>, the threshold variable
is <code>__gnu_parallel::_Settings::fill_minimal_n</code>,
</para><para>
Finally, hardware details like L1/L2 cache size can be hardwired
via <code>__gnu_parallel::_Settings::L1_cache_size</code> and friends.
</para><para>
</para><para>
All these configuration variables can be changed by the user, if
desired.
There exists one global instance of the class <classname>_Settings</classname>,
i. e. it is a singleton. It can be read and written by calling
<code>__gnu_parallel::_Settings::get</code> and
<code>__gnu_parallel::_Settings::set</code>, respectively.
Please note that the first call return a const object, so direct manipulation
is forbidden.
See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html"><filename class="headerfile">&lt;parallel/settings.h&gt;</filename></link>
for complete details.
</para><para>
A small example of tuning the default:
</para><programlisting>
#include &lt;parallel/algorithm&gt;
#include &lt;parallel/settings.h&gt;

int main()
{
  __gnu_parallel::_Settings s;
  s.algorithm_strategy = __gnu_parallel::force_parallel;
  __gnu_parallel::_Settings::set(s);

  // Do work... all algorithms will be parallelized, always.

  return 0;
}
</programlisting></section></section><section xreflabel="Impl" xml:id="parallel_mode.design.impl"><info><title>Implementation Namespaces</title></info><para> One namespace contain versions of code that are always
explicitly sequential:
<code>__gnu_serial</code>.
</para><para> Two namespaces contain the parallel mode:
<code>std::__parallel</code> and <code>__gnu_parallel</code>.
</para><para> Parallel implementations of standard components, including
template helpers to select parallelism, are defined in <code>namespace
std::__parallel</code>. For instance, <function>std::transform</function> from <filename class="headerfile">algorithm</filename> has a parallel counterpart in
<function>std::__parallel::transform</function> from <filename class="headerfile">parallel/algorithm</filename>. In addition, these parallel
implementations are injected into <code>namespace
__gnu_parallel</code> with using declarations.
</para><para> Support and general infrastructure is in <code>namespace
__gnu_parallel</code>.
</para><para> More information, and an organized index of types and functions
related to the parallel mode on a per-namespace basis, can be found in
the generated source documentation.
</para></section></section><section xreflabel="Testing" xml:id="manual.ext.parallel_mode.test"><info><title>Testing</title></info><?dbhtml filename="parallel_mode_test.html"?><para>
    Both the normal conformance and regression tests and the
    supplemental performance tests work.
  </para><para>
    To run the conformance and regression tests with the parallel mode
    active,
  </para><screen><userinput>make check-parallel</userinput></screen><para>
    The log and summary files for conformance testing are in the
    <filename class="directory">testsuite/parallel</filename> directory.
  </para><para>
    To run the performance tests with the parallel mode active,
  </para><screen><userinput>make check-performance-parallel</userinput></screen><para>
    The result file for performance testing are in the
    <filename class="directory">testsuite</filename> directory, in the file
    <filename>libstdc++_performance.sum</filename>. In addition, the
    policy-based containers have their own visualizations, which have
    additional software dependencies than the usual bare-boned text
    file, and can be generated by using the <code>make
    doc-performance</code> rule in the testsuite's Makefile.
</para></section><bibliography xml:id="parallel_mode.biblio"><info><title>Bibliography</title></info><biblioentry><citetitle>
      Parallelization of Bulk Operations for STL Dictionaries
    </citetitle><author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author><author><personname><firstname>Leonor</firstname><surname>Frias</surname></personname></author><copyright><year>2007</year><holder></holder></copyright><publisher><publishername>
	Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS)
      </publishername></publisher></biblioentry><biblioentry><citetitle>
      The Multi-Core Standard Template Library
    </citetitle><author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author><author><personname><firstname>Peter</firstname><surname>Sanders</surname></personname></author><author><personname><firstname>Felix</firstname><surname>Putze</surname></personname></author><copyright><year>2007</year><holder></holder></copyright><publisher><publishername>
	 Euro-Par 2007: Parallel Processing. (LNCS 4641)
      </publishername></publisher></biblioentry></bibliography></chapter><!-- XXX --><!-- Allocators --><!-- Chapter 05 : __mt_alloc --><chapter version="5.0" xreflabel="mt allocator" xml:id="manual.ext.allocator.mt"><?dbhtml filename="mt_allocator.html"?><info><title>The mt_allocator</title><keywordset><keyword>ISO C++</keyword><keyword>allocator</keyword></keywordset></info><para>
</para><section xml:id="allocator.mt.intro"><info><title>Intro</title></info><para>
  The mt allocator [hereinafter referred to simply as "the allocator"]
  is a fixed size (power of two) allocator that was initially
  developed specifically to suit the needs of multi-threaded
  applications [hereinafter referred to as an MT application]. Over
  time the allocator has evolved and been improved in many ways, in
  particular it now also does a good job in single-threaded
  applications [hereinafter referred to as an ST application]. (Note:
  In this document, when referring to single-threaded applications
  this also includes applications that are compiled with gcc without
  thread support enabled. This is accomplished using ifdef's on
  __GTHREADS). This allocator is tunable, very flexible, and capable
  of high-performance.
</para><para>
  The aim of this document is to describe - from an application point of
  view - the "inner workings" of the allocator.
</para></section><section xml:id="allocator.mt.design_issues"><info><title>Design Issues</title></info><?dbhtml filename="mt_allocator_design.html"?><section xml:id="allocator.mt.overview"><info><title>Overview</title></info><para> There are three general components to the allocator: a datum
describing the characteristics of the memory pool, a policy class
containing this pool that links instantiation types to common or
individual pools, and a class inheriting from the policy class that is
the actual allocator.
</para><para>The datum describing pools characteristics is
</para><programlisting>
  template&lt;bool _Thread&gt;
    class __pool
</programlisting><para> This class is parametrized on thread support, and is explicitly
specialized for both multiple threads (with <code>bool==true</code>)
and single threads (via <code>bool==false</code>.) It is possible to
use a custom pool datum instead of the default class that is provided.
</para><para> There are two distinct policy classes, each of which can be used
with either type of underlying pool datum.
</para><programlisting>
  template&lt;bool _Thread&gt;
    struct __common_pool_policy

  template&lt;typename _Tp, bool _Thread&gt;
    struct __per_type_pool_policy
</programlisting><para> The first policy, <code>__common_pool_policy</code>, implements a
common pool. This means that allocators that are instantiated with
different types, say <code>char</code> and <code>long</code> will both
use the same pool. This is the default policy.
</para><para> The second policy, <code>__per_type_pool_policy</code>, implements
a separate pool for each instantiating type. Thus, <code>char</code>
and <code>long</code> will use separate pools. This allows per-type
tuning, for instance.
</para><para> Putting this all together, the actual allocator class is
</para><programlisting>
  template&lt;typename _Tp, typename _Poolp = __default_policy&gt;
    class __mt_alloc : public __mt_alloc_base&lt;_Tp&gt;,  _Poolp
</programlisting><para> This class has the interface required for standard library allocator
classes, namely member functions <code>allocate</code> and
<code>deallocate</code>, plus others.
</para></section></section><section xml:id="allocator.mt.impl"><info><title>Implementation</title></info><?dbhtml filename="mt_allocator_impl.html"?><section xml:id="allocator.mt.tune"><info><title>Tunable Parameters</title></info><para>Certain allocation parameters can be modified, or tuned. There
exists a nested <code>struct __pool_base::_Tune</code> that contains all
these parameters, which include settings for
</para><itemizedlist><listitem><para>Alignment</para></listitem><listitem><para>Maximum bytes before calling <code>::operator new</code> directly</para></listitem><listitem><para>Minimum bytes</para></listitem><listitem><para>Size of underlying global allocations</para></listitem><listitem><para>Maximum number of supported threads</para></listitem><listitem><para>Migration of deallocations to the global free list</para></listitem><listitem><para>Shunt for global <code>new</code> and <code>delete</code></para></listitem></itemizedlist><para>Adjusting parameters for a given instance of an allocator can only
happen before any allocations take place, when the allocator itself is
initialized. For instance:
</para><programlisting>
#include &lt;ext/mt_allocator.h&gt;

struct pod
{
  int i;
  int j;
};

int main()
{
  typedef pod value_type;
  typedef __gnu_cxx::__mt_alloc&lt;value_type&gt; allocator_type;
  typedef __gnu_cxx::__pool_base::_Tune tune_type;

  tune_type t_default;
  tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
  tune_type t_single(16, 5120, 32, 5120, 1, 10, false);

  tune_type t;
  t = allocator_type::_M_get_options();
  allocator_type::_M_set_options(t_opt);
  t = allocator_type::_M_get_options();

  allocator_type a;
  allocator_type::pointer p1 = a.allocate(128);
  allocator_type::pointer p2 = a.allocate(5128);

  a.deallocate(p1, 128);
  a.deallocate(p2, 5128);

  return 0;
}
</programlisting></section><section xml:id="allocator.mt.init"><info><title>Initialization</title></info><para>
The static variables (pointers to freelists, tuning parameters etc)
are initialized as above, or are set to the global defaults.
</para><para>
The very first allocate() call will always call the
_S_initialize_once() function.  In order to make sure that this
function is called exactly once we make use of a __gthread_once call
in MT applications and check a static bool (_S_init) in ST
applications.
</para><para>
The _S_initialize() function:
- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool
  _S_force_new to true and then returns. This will cause subsequent calls to
  allocate() to return memory directly from a new() call, and deallocate will
  only do a delete() call.
</para><para>
- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
  applications will:
  - Calculate the number of bins needed. A bin is a specific power of two size
    of bytes. I.e., by default the allocator will deal with requests of up to
    128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
    called). This means that there will be bins of the following sizes
    (in bytes): 1, 2, 4, 8, 16, 32, 64, 128.

  - Create the _S_binmap array. All requests are rounded up to the next
    "large enough" bin. I.e., a request for 29 bytes will cause a block from
    the "32 byte bin" to be returned to the application. The purpose of
    _S_binmap is to speed up the process of finding out which bin to use.
    I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes).
</para><para>
  - Create the _S_bin array. This array consists of bin_records. There will be
    as many bin_records in this array as the number of bins that we calculated
    earlier. I.e., if _S_max_bytes = 128 there will be 8 entries.
    Each bin_record is then initialized:
    - bin_record-&gt;first = An array of pointers to block_records. There will be
      as many block_records pointers as there are maximum number of threads
      (in a ST application there is only 1 thread, in a MT application there
      are _S_max_threads).
      This holds the pointer to the first free block for each thread in this
      bin. I.e., if we would like to know where the first free block of size 32
      for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ]

    The above created block_record pointers members are now initialized to
    their initial values. I.e. _S_bin[ n ].first[ n ] = NULL;
</para><para>
- Additionally a MT application will:
  - Create a list of free thread id's. The pointer to the first entry
    is stored in _S_thread_freelist_first. The reason for this approach is
    that the __gthread_self() call will not return a value that corresponds to
    the maximum number of threads allowed but rather a process id number or
    something else. So what we do is that we create a list of thread_records.
    This list is _S_max_threads long and each entry holds a size_t thread_id
    which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads.
    Each time a thread calls allocate() or deallocate() we call
    _S_get_thread_id() which looks at the value of _S_thread_key which is a
    thread local storage pointer. If this is NULL we know that this is a newly
    created thread and we pop the first entry from this list and saves the
    pointer to this record in the _S_thread_key variable. The next time
    we will get the pointer to the thread_record back and we use the
    thread_record-&gt;thread_id as identification. I.e., the first thread that
    calls allocate will get the first record in this list and thus be thread
    number 1 and will then find the pointer to its first free 32 byte block
    in _S_bin[ 5 ].first[ 1 ]
    When we create the _S_thread_key we also define a destructor
    (_S_thread_key_destr) which means that when the thread dies, this
    thread_record is returned to the front of this list and the thread id
    can then be reused if a new thread is created.
    This list is protected by a mutex (_S_thread_freelist_mutex) which is only
    locked when records are removed or added to the list.
</para><para>
  - Initialize the free and used counters of each bin_record:
    - bin_record-&gt;free = An array of size_t. This keeps track of the number
      of blocks on a specific thread's freelist in each bin. I.e., if a thread
      has 12 32-byte blocks on it's freelists and allocates one of these, this
      counter would be decreased to 11.

    - bin_record-&gt;used = An array of size_t. This keeps track of the number
      of blocks currently in use of this size by this thread. I.e., if a thread
      has made 678 requests (and no deallocations...) of 32-byte blocks this
      counter will read 678.

    The above created arrays are now initialized with their initial values.
    I.e. _S_bin[ n ].free[ n ] = 0;
</para><para>
  - Initialize the mutex of each bin_record: The bin_record-&gt;mutex
    is used to protect the global freelist. This concept of a global
    freelist is explained in more detail in the section "A multi
    threaded example", but basically this mutex is locked whenever a
    block of memory is retrieved or returned to the global freelist
    for this specific bin. This only occurs when a number of blocks
    are grabbed from the global list to a thread specific list or when
    a thread decides to return some blocks to the global freelist.
</para></section><section xml:id="allocator.mt.deallocation"><info><title>Deallocation Notes</title></info><para> Notes about deallocation. This allocator does not explicitly
release memory back to the OS, but keeps its own freelists instead.
Because of this, memory debugging programs like
valgrind or purify may notice leaks: sorry about this
inconvenience. Operating systems will reclaim allocated memory at
program termination anyway. If sidestepping this kind of noise is
desired, there are three options: use an allocator, like
<code>new_allocator</code> that releases memory while debugging, use
GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a
custom pool datum that releases resources on destruction.
</para><para>
  On systems with the function <code>__cxa_atexit</code>, the
allocator can be forced to free all memory allocated before program
termination with the member function
<code>__pool_type::_M_destroy</code>. However, because this member
function relies on the precise and exactly-conforming ordering of
static destructors, including those of a static local
<code>__pool</code> object, it should not be used, ever, on systems
that don't have the necessary underlying support. In addition, in
practice, forcing deallocation can be tricky, as it requires the
<code>__pool</code> object to be fully-constructed before the object
that uses it is fully constructed. For most (but not all) STL
containers, this works, as an instance of the allocator is constructed
as part of a container's constructor. However, this assumption is
implementation-specific, and subject to change. For an example of a
pool that frees memory, see the
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc"><filename>ext/mt_allocator/deallocate_local-6.cc</filename></link>
    example.
</para></section></section><section xml:id="allocator.mt.example_single"><info><title>Single Thread Example</title></info><?dbhtml filename="mt_allocator_ex_single.html"?><para>
Let's start by describing how the data on a freelist is laid out in memory.
This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes):
</para><programlisting>
+----------------+
| next* ---------|--+  (_S_bin[ 3 ].first[ 3 ] points here)
|                |  |
|                |  |
|                |  |
+----------------+  |
| thread_id = 3  |  |
|                |  |
|                |  |
|                |  |
+----------------+  |
| DATA           |  |  (A pointer to here is what is returned to the
|                |  |   the application when needed)
|                |  |
|                |  |
|                |  |
|                |  |
|                |  |
|                |  |
+----------------+  |
+----------------+  |
| next*          |&lt;-+  (If next == NULL it's the last one on the list)
|                |
|                |
|                |
+----------------+
| thread_id = 3  |
|                |
|                |
|                |
+----------------+
| DATA           |
|                |
|                |
|                |
|                |
|                |
|                |
|                |
+----------------+
</programlisting><para>
With this in mind we simplify things a bit for a while and say that there is
only one thread (a ST application). In this case all operations are made to
what is referred to as the global pool - thread id 0 (No thread may be
assigned this id since they span from 1 to _S_max_threads in a MT application).
</para><para>
When the application requests memory (calling allocate()) we first look at the
requested size and if this is &gt; _S_max_bytes we call new() directly and return.
</para><para>
If the requested size is within limits we start by finding out from which
bin we should serve this request by looking in _S_binmap.
</para><para>
A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of
this size on the freelist (0). If this is not NULL - fine, just remove the
block that _S_bin[ bin ].first[ 0 ] points to from the list,
update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data.
</para><para>
If the freelist is empty (the pointer is NULL) we must get memory from the
system and build us a freelist within this memory. All requests for new memory
is made in chunks of _S_chunk_size. Knowing the size of a block_record and
the bytes that this bin stores we then calculate how many blocks we can create
within this chunk, build the list, remove the first block, update the pointer
(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data.
</para><para>
Deallocation is equally simple; the pointer is casted back to a block_record
pointer, lookup which bin to use based on the size, add the block to the front
of the global freelist and update the pointer as needed
(_S_bin[ bin ].first[ 0 ]).
</para><para>
The decision to add deallocated blocks to the front of the freelist was made
after a set of performance measurements that showed that this is roughly 10%
faster than maintaining a set of "last pointers" as well.
</para></section><section xml:id="allocator.mt.example_multi"><info><title>Multiple Thread Example</title></info><?dbhtml filename="mt_allocator_ex_multi.html"?><para>
In the ST example we never used the thread_id variable present in each block.
Let's start by explaining the purpose of this in a MT application.
</para><para>
The concept of "ownership" was introduced since many MT applications
allocate and deallocate memory to shared containers from different
threads (such as a cache shared amongst all threads). This introduces
a problem if the allocator only returns memory to the current threads
freelist (I.e., there might be one thread doing all the allocation and
thus obtaining ever more memory from the system and another thread
that is getting a longer and longer freelist - this will in the end
consume all available memory).
</para><para>
Each time a block is moved from the global list (where ownership is
irrelevant), to a threads freelist (or when a new freelist is built
from a chunk directly onto a threads freelist or when a deallocation
occurs on a block which was not allocated by the same thread id as the
one doing the deallocation) the thread id is set to the current one.
</para><para>
What's the use? Well, when a deallocation occurs we can now look at
the thread id and find out if it was allocated by another thread id
and decrease the used counter of that thread instead, thus keeping the
free and used counters correct. And keeping the free and used counters
corrects is very important since the relationship between these two
variables decides if memory should be returned to the global pool or
not when a deallocation occurs.
</para><para>
When the application requests memory (calling allocate()) we first
look at the requested size and if this is &gt;_S_max_bytes we call new()
directly and return.
</para><para>
If the requested size is within limits we start by finding out from which
bin we should serve this request by looking in _S_binmap.
</para><para>
A call to _S_get_thread_id() returns the thread id for the calling thread
(and if no value has been set in _S_thread_key, a new id is assigned and
returned).
</para><para>
A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are
any blocks of this size on the current threads freelist. If this is
not NULL - fine, just remove the block that _S_bin[ bin ].first[
thread_id ] points to from the list, update _S_bin[ bin ].first[
thread_id ], update the free and used counters and return a pointer to
that blocks data.
</para><para>
If the freelist is empty (the pointer is NULL) we start by looking at
the global freelist (0). If there are blocks available on the global
freelist we lock this bins mutex and move up to block_count (the
number of blocks of this bins size that will fit into a _S_chunk_size)
or until end of list - whatever comes first - to the current threads
freelist and at the same time change the thread_id ownership and
update the counters and pointers. When the bins mutex has been
unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ]
points to from the list, update _S_bin[ bin ].first[ thread_id ],
update the free and used counters, and return a pointer to that blocks
data.
</para><para>
The reason that the number of blocks moved to the current threads
freelist is limited to block_count is to minimize the chance that a
subsequent deallocate() call will return the excess blocks to the
global freelist (based on the _S_freelist_headroom calculation, see
below).
</para><para>
However if there isn't any memory on the global pool we need to get
memory from the system - this is done in exactly the same way as in a
single threaded application with one major difference; the list built
in the newly allocated memory (of _S_chunk_size size) is added to the
current threads freelist instead of to the global.
</para><para>
The basic process of a deallocation call is simple: always add the
block to the front of the current threads freelist and update the
counters and pointers (as described earlier with the specific check of
ownership that causes the used counter of the thread that originally
allocated the block to be decreased instead of the current threads
counter).
</para><para>
And here comes the free and used counters to service. Each time a
deallocation() call is made, the length of the current threads
freelist is compared to the amount memory in use by this thread.
</para><para>
Let's go back to the example of an application that has one thread
that does all the allocations and one that deallocates. Both these
threads use say 516 32-byte blocks that was allocated during thread
creation for example.  Their used counters will both say 516 at this
point. The allocation thread now grabs 1000 32-byte blocks and puts
them in a shared container. The used counter for this thread is now
1516.
</para><para>
The deallocation thread now deallocates 500 of these blocks. For each
deallocation made the used counter of the allocating thread is
decreased and the freelist of the deallocation thread gets longer and
longer. But the calculation made in deallocate() will limit the length
of the freelist in the deallocation thread to _S_freelist_headroom %
of it's used counter.  In this case, when the freelist (given that the
_S_freelist_headroom is at it's default value of 10%) exceeds 52
(516/10) blocks will be returned to the global pool where the
allocating thread may pick them up and reuse them.
</para><para>
In order to reduce lock contention (since this requires this bins
mutex to be locked) this operation is also made in chunks of blocks
(just like when chunks of blocks are moved from the global freelist to
a threads freelist mentioned above). The "formula" used can probably
be improved to further reduce the risk of blocks being "bounced back
and forth" between freelists.
</para></section></chapter><!-- Chapter 06 : bitmap_allocator --><chapter version="5.0" xreflabel="bitmap_allocator" xml:id="manual.ext.allocator.bitmap"><?dbhtml filename="bitmap_allocator.html"?><info><title>The bitmap_allocator</title><keywordset><keyword>ISO C++</keyword><keyword>allocator</keyword></keywordset></info><para>
</para><section xml:id="allocator.bitmap.design"><info><title>Design</title></info><para>
    As this name suggests, this allocator uses a bit-map to keep track
    of the used and unused memory locations for its book-keeping
    purposes.
  </para><para>
    This allocator will make use of 1 single bit to keep track of
    whether it has been allocated or not. A bit 1 indicates free,
    while 0 indicates allocated. This has been done so that you can
    easily check a collection of bits for a free block. This kind of
    Bitmapped strategy works best for single object allocations, and
    with the STL type parameterized allocators, we do not need to
    choose any size for the block which will be represented by a
    single bit. This will be the size of the parameter around which
    the allocator has been parameterized. Thus, close to optimal
    performance will result. Hence, this should be used for node based
    containers which call the allocate function with an argument of 1.
  </para><para>
    The bitmapped allocator's internal pool is exponentially growing.
    Meaning that internally, the blocks acquired from the Free List
    Store will double every time the bitmapped allocator runs out of
    memory.
  </para><para>
    The macro <literal>__GTHREADS</literal> decides whether to use
    Mutex Protection around every allocation/deallocation. The state
    of the macro is picked up automatically from the gthr abstraction
    layer.
  </para></section><section xml:id="allocator.bitmap.impl"><info><title>Implementation</title></info><?dbhtml filename="bitmap_allocator_impl.html"?><section xreflabel="Free List Store" xml:id="bitmap.impl.free_list_store"><info><title>Free List Store</title></info><para>
    The Free List Store (referred to as FLS for the remaining part of this
    document) is the Global memory pool that is shared by all instances of
    the bitmapped allocator instantiated for any type. This maintains a
    sorted order of all free memory blocks given back to it by the
    bitmapped allocator, and is also responsible for giving memory to the
    bitmapped allocator when it asks for more.
  </para><para>
    Internally, there is a Free List threshold which indicates the
    Maximum number of free lists that the FLS can hold internally
    (cache).  Currently, this value is set at 64. So, if there are
    more than 64 free lists coming in, then some of them will be given
    back to the OS using operator delete so that at any given time the
    Free List's size does not exceed 64 entries. This is done because
    a Binary Search is used to locate an entry in a free list when a
    request for memory comes along.  Thus, the run-time complexity of
    the search would go up given an increasing size, for 64 entries
    however, lg(64) == 6 comparisons are enough to locate the correct
    free list if it exists.
  </para><para>
    Suppose the free list size has reached its threshold, then the
    largest block from among those in the list and the new block will
    be selected and given back to the OS. This is done because it
    reduces external fragmentation, and allows the OS to use the
    larger blocks later in an orderly fashion, possibly merging them
    later. Also, on some systems, large blocks are obtained via calls
    to mmap, so giving them back to free system resources becomes most
    important.
  </para><para>
    The function _S_should_i_give decides the policy that determines
    whether the current block of memory should be given to the
    allocator for the request that it has made. That's because we may
    not always have exact fits for the memory size that the allocator
    requests. We do this mainly to prevent external fragmentation at
    the cost of a little internal fragmentation. Now, the value of
    this internal fragmentation has to be decided by this function. I
    can see 3 possibilities right now. Please add more as and when you
    find better strategies.
  </para><orderedlist><listitem><para>Equal size check. Return true only when the 2 blocks are of equal
size.</para></listitem><listitem><para>Difference Threshold: Return true only when the _block_size is
greater than or equal to the _required_size, and if the _BS is &gt; _RS
by a difference of less than some THRESHOLD value, then return true,
else return false. </para></listitem><listitem><para>Percentage Threshold. Return true only when the _block_size is
greater than or equal to the _required_size, and if the _BS is &gt; _RS
by a percentage of less than some THRESHOLD value, then return true,
else return false.</para></listitem></orderedlist><para>
    Currently, (3) is being used with a value of 36% Maximum wastage per
    Super Block.
  </para></section><section xreflabel="Super Block" xml:id="bitmap.impl.super_block"><info><title>Super Block</title></info><para>
    A super block is the block of memory acquired from the FLS from
    which the bitmap allocator carves out memory for single objects
    and satisfies the user's requests. These super blocks come in
    sizes that are powers of 2 and multiples of 32
    (_Bits_Per_Block). Yes both at the same time!  That's because the
    next super block acquired will be 2 times the previous one, and
    also all super blocks have to be multiples of the _Bits_Per_Block
    value.
  </para><para>
    How does it interact with the free list store?
  </para><para>
    The super block is contained in the FLS, and the FLS is responsible for
    getting / returning Super Bocks to and from the OS using operator new
    as defined by the C++ standard.
  </para></section><section xreflabel="Super Block Data" xml:id="bitmap.impl.super_block_data"><info><title>Super Block Data Layout</title></info><para>
    Each Super Block will be of some size that is a multiple of the
    number of Bits Per Block. Typically, this value is chosen as
    Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the
    figure 8 x 4 = 32. Thus, each Super Block will be of size 32
    x Some_Value. This Some_Value is sizeof(value_type). For now, let
    it be called 'K'. Thus, finally, Super Block size is 32 x K bytes.
  </para><para>
    This value of 32 has been chosen because each size_t has 32-bits
    and Maximum use of these can be made with such a figure.
  </para><para>
    Consider a block of size 64 ints. In memory, it would look like this:
    (assume a 32-bit system where, size_t is a 32-bit entity).
  </para><table frame="all" xml:id="table.bitmap_alloc"><title>Bitmap Allocator Memory Map</title><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><tbody><row><entry>268</entry><entry>0</entry><entry>4294967295</entry><entry>4294967295</entry><entry>Data -&gt; Space for 64 ints</entry></row></tbody></tgroup></table><para>
    The first Column(268) represents the size of the Block in bytes as
    seen by the Bitmap Allocator. Internally, a global free list is
    used to keep track of the free blocks used and given back by the
    bitmap allocator.  It is this Free List Store that is responsible
    for writing and managing this information. Actually the number of
    bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) =
    272 bytes, but the first 4 bytes are an addition by the Free List
    Store, so the Bitmap Allocator sees only 268 bytes. These first 4
    bytes about which the bitmapped allocator is not aware hold the
    value 268.
  </para><para>
  What do the remaining values represent?</para><para>
    The 2nd 4 in the expression is the sizeof(size_t) because the
    Bitmapped Allocator maintains a used count for each Super Block,
    which is initially set to 0 (as indicated in the diagram). This is
    incremented every time a block is removed from this super block
    (allocated), and decremented whenever it is given back. So, when
    the used count falls to 0, the whole super block will be given
    back to the Free List Store.
  </para><para>
    The value 4294967295 represents the integer corresponding to the bit
    representation of all bits set: 11111111111111111111111111111111.
  </para><para>
    The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits
    x 2,
    which is 8-bytes, or 2 x sizeof(size_t).
  </para></section><section xreflabel="Max Wasted Percentage" xml:id="bitmap.impl.max_wasted"><info><title>Maximum Wasted Percentage</title></info><para>
    This has nothing to do with the algorithm per-se,
    only with some vales that must be chosen correctly to ensure that the
    allocator performs well in a real word scenario, and maintains a good
    balance between the memory consumption and the allocation/deallocation
    speed.
  </para><para>
    The formula for calculating the maximum wastage as a percentage:
  </para><para>
(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100.
  </para><para>
    where k is the constant overhead per node (e.g., for list, it is
    8 bytes, and for map it is 12 bytes) and c is the size of the
    base type on which the map/list is instantiated. Thus, suppose the
    type1 is int and type2 is double, they are related by the relation
    sizeof(double) == 2*sizeof(int). Thus, all types must have this
    double size relation for this formula to work properly.
  </para><para>
    Plugging-in: For List: k = 8 and c = 4 (int and double), we get:
    33.376%
  </para><para>
For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524%
  </para><para>
    Thus, knowing these values, and based on the sizeof(value_type), we may
    create a function that returns the Max_Wastage_Percentage for us to use.
  </para></section><section xreflabel="Allocate" xml:id="bitmap.impl.allocate"><info><title><function>allocate</function></title></info><para>
    The allocate function is specialized for single object allocation
    ONLY.  Thus, ONLY if n == 1, will the bitmap_allocator's
    specialized algorithm be used. Otherwise, the request is satisfied
    directly by calling operator new.
  </para><para>
    Suppose n == 1, then the allocator does the following:
  </para><orderedlist><listitem><para>
	Checks to see whether a free block exists somewhere in a region
	of memory close to the last satisfied request. If so, then that
	block is marked as allocated in the bit map and given to the
	user. If not, then (2) is executed.
    </para></listitem><listitem><para>
	Is there a free block anywhere after the current block right
	up to the end of the memory that we have? If so, that block is
	found, and the same procedure is applied as above, and
	returned to the user. If not, then (3) is executed.
    </para></listitem><listitem><para>
	Is there any block in whatever region of memory that we own
	free?  This is done by checking
      </para><itemizedlist><listitem><para>
	The use count for each super block, and if that fails then
	</para></listitem><listitem><para>
	  The individual bit-maps for each super block.
	</para></listitem></itemizedlist><para>
	Note: Here we are never touching any of the memory that the
	user will be given, and we are confining all memory accesses
	to a small region of memory! This helps reduce cache
	misses. If this succeeds then we apply the same procedure on
	that bit-map as (1), and return that block of memory to the
	user. However, if this process fails, then we resort to (4).
	</para></listitem><listitem><para>
	This process involves Refilling the internal exponentially
	growing memory pool. The said effect is achieved by calling
	_S_refill_pool which does the following:
      </para><itemizedlist><listitem><para>
	    Gets more memory from the Global Free List of the Required
	    size.
	  </para></listitem><listitem><para>
      Adjusts the size for the next call to itself.
      </para></listitem><listitem><para>
      Writes the appropriate headers in the bit-maps.
      </para></listitem><listitem><para>
	Sets the use count for that super-block just allocated to 0
	(zero).
      </para></listitem><listitem><para>
	  All of the above accounts to maintaining the basic invariant
	  for the allocator. If the invariant is maintained, we are
	  sure that all is well. Now, the same process is applied on
	  the newly acquired free blocks, which are dispatched
	  accordingly.
      </para></listitem></itemizedlist></listitem></orderedlist><para>
Thus, you can clearly see that the allocate function is nothing but a
combination of the next-fit and first-fit algorithm optimized ONLY for
single object allocations.
</para></section><section xreflabel="Deallocate" xml:id="bitmap.impl.deallocate"><info><title><function>deallocate</function></title></info><para>
    The deallocate function again is specialized for single objects ONLY.
    For all n belonging to &gt; 1, the operator delete is called without
    further ado, and the deallocate function returns.
  </para><para>
    However for n == 1, a series of steps are performed:
  </para><orderedlist><listitem><para>
      We first need to locate that super-block which holds the memory
      location given to us by the user. For that purpose, we maintain
      a static variable _S_last_dealloc_index, which holds the index
      into the vector of block pairs which indicates the index of the
      last super-block from which memory was freed. We use this
      strategy in the hope that the user will deallocate memory in a
      region close to what he/she deallocated the last time around. If
      the check for belongs_to succeeds, then we determine the bit-map
      for the given pointer, and locate the index into that bit-map,
      and mark that bit as free by setting it.
    </para></listitem><listitem><para>
      If the _S_last_dealloc_index does not point to the memory block
      that we're looking for, then we do a linear search on the block
      stored in the vector of Block Pairs. This vector in code is
      called _S_mem_blocks. When the corresponding super-block is
      found, we apply the same procedure as we did for (1) to mark the
      block as free in the bit-map.
    </para></listitem></orderedlist><para>
    Now, whenever a block is freed, the use count of that particular
    super block goes down by 1. When this use count hits 0, we remove
    that super block from the list of all valid super blocks stored in
    the vector.  While doing this, we also make sure that the basic
    invariant is maintained by making sure that _S_last_request and
    _S_last_dealloc_index point to valid locations within the vector.
  </para></section><section xreflabel="Questions" xml:id="bitmap.impl.questions"><info><title>Questions</title></info><section xreflabel="Question 1" xml:id="bitmap.impl.question.1"><info><title>1</title></info><para>
Q1) The "Data Layout" section is
cryptic. I have no idea of what you are trying to say. Layout of what?
The free-list? Each bitmap? The Super Block?
    </para><para>
      The layout of a Super Block of a given
size. In the example, a super block of size 32 x 1 is taken. The
general formula for calculating the size of a super block is
32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit
systems.
    </para></section><section xreflabel="Question 2" xml:id="bitmap.impl.question.2"><info><title>2</title></info><para>
      And since I just mentioned the
term `each bitmap', what in the world is meant by it? What does each
bitmap manage? How does it relate to the super block? Is the Super
Block a bitmap as well?
    </para><para>
      Each bitmap is part of a Super Block which is made up of 3 parts
      as I have mentioned earlier.  Re-iterating, 1. The use count,
      2. The bit-map for that Super Block. 3.  The actual memory that
      will be eventually given to the user. Each bitmap is a multiple
      of 32 in size. If there are 32 x (2^3) blocks of single objects
      to be given, there will be '32 x (2^3)' bits present.  Each 32
      bits managing the allocated / free status for 32 blocks. Since
      each size_t contains 32-bits, one size_t can manage up to 32
      blocks' status. Each bit-map is made up of a number of size_t,
      whose exact number for a super-block of a given size I have just
      mentioned.
    </para></section><section xreflabel="Question 3" xml:id="bitmap.impl.question.3"><info><title>3</title></info><para>
      How do the allocate and deallocate functions work in regard to
      bitmaps?
    </para><para>
      The allocate and deallocate functions manipulate the bitmaps and
      have nothing to do with the memory that is given to the user. As
      I have earlier mentioned, a 1 in the bitmap's bit field
      indicates free, while a 0 indicates allocated. This lets us
      check 32 bits at a time to check whether there is at lease one
      free block in those 32 blocks by testing for equality with
      (0). Now, the allocate function will given a memory block find
      the corresponding bit in the bitmap, and will reset it (i.e.,
      make it re-set (0)). And when the deallocate function is called,
      it will again set that bit after locating it to indicate that
      that particular block corresponding to this bit in the bit-map
      is not being used by anyone, and may be used to satisfy future
      requests.
    </para><para>
      e.g.: Consider a bit-map of 64-bits as represented below:
      1111111111111111111111111111111111111111111111111111111111111111
    </para><para>
      Now, when the first request for allocation of a single object
      comes along, the first block in address order is returned. And
      since the bit-maps in the reverse order to that of the address
      order, the last bit (LSB if the bit-map is considered as a
      binary word of 64-bits) is re-set to 0.
    </para><para>
      The bit-map now looks like this:
      1111111111111111111111111111111111111111111111111111111111111110
    </para></section></section><section xreflabel="Locality" xml:id="bitmap.impl.locality"><info><title>Locality</title></info><para>
    Another issue would be whether to keep the all bitmaps in a
    separate area in memory, or to keep them near the actual blocks
    that will be given out or allocated for the client. After some
    testing, I've decided to keep these bitmaps close to the actual
    blocks. This will help in 2 ways.
  </para><orderedlist><listitem><para>Constant time access for the bitmap themselves, since no kind of
look up will be needed to find the correct bitmap list or its
equivalent.</para></listitem><listitem><para>And also this would preserve the cache as far as possible.</para></listitem></orderedlist><para>
    So in effect, this kind of an allocator might prove beneficial from a
    purely cache point of view. But this allocator has been made to try and
    roll out the defects of the node_allocator, wherein the nodes get
    skewed about in memory, if they are not returned in the exact reverse
    order or in the same order in which they were allocated. Also, the
    new_allocator's book keeping overhead is too much for small objects and
    single object allocations, though it preserves the locality of blocks
    very well when they are returned back to the allocator.
  </para></section><section xreflabel="Grow Policy" xml:id="bitmap.impl.grow_policy"><info><title>Overhead and Grow Policy</title></info><para>
    Expected overhead per block would be 1 bit in memory. Also, once
    the address of the free list has been found, the cost for
    allocation/deallocation would be negligible, and is supposed to be
    constant time. For these very reasons, it is very important to
    minimize the linear time costs, which include finding a free list
    with a free block while allocating, and finding the corresponding
    free list for a block while deallocating. Therefore, I have
    decided that the growth of the internal pool for this allocator
    will be exponential as compared to linear for
    node_allocator. There, linear time works well, because we are
    mainly concerned with speed of allocation/deallocation and memory
    consumption, whereas here, the allocation/deallocation part does
    have some linear/logarithmic complexity components in it. Thus, to
    try and minimize them would be a good thing to do at the cost of a
    little bit of memory.
  </para><para>
    Another thing to be noted is the pool size will double every time
    the internal pool gets exhausted, and all the free blocks have
    been given away. The initial size of the pool would be
    sizeof(size_t) x 8 which is the number of bits in an integer,
    which can fit exactly in a CPU register. Hence, the term given is
    exponential growth of the internal pool.
  </para></section></section></chapter><!-- Containers --><!-- Chapter 07 : Policy-Based Data Structures --><chapter version="5.0" xreflabel="pbds" xml:id="manual.ext.containers.pbds"><info><title>Policy-Based Data Structures</title><keywordset><keyword>ISO C++</keyword><keyword>policy</keyword><keyword>container</keyword><keyword>data</keyword><keyword>structure</keyword><keyword>associated</keyword><keyword>tree</keyword><keyword>trie</keyword><keyword>hash</keyword><keyword>metaprogramming</keyword></keywordset></info><?dbhtml filename="policy_data_structures.html"?><!-- 2006-04-01 Ami Tavory --><!-- 2011-05-25 Benjamin Kosnik --><!-- S01: intro --><section xml:id="pbds.intro"><info><title>Intro</title></info><para>
      This is a library of policy-based elementary data structures:
      associative containers and priority queues. It is designed for
      high-performance, flexibility, semantic safety, and conformance to
      the corresponding containers in <literal>std</literal> and
      <literal>std::tr1</literal> (except for some points where it differs
      by design).
    </para><para>
    </para><section xml:id="pbds.intro.issues"><info><title>Performance Issues</title></info><para>
      </para><para>
	An attempt is made to categorize the wide variety of possible
	container designs in terms of performance-impacting factors. These
	performance factors are translated into design policies and
	incorporated into container design.
      </para><para>
	There is tension between unravelling factors into a coherent set of
	policies. Every attempt is made to make a minimal set of
	factors. However, in many cases multiple factors make for long
	template names. Every attempt is made to alias and use typedefs in
	the source files, but the generated names for external symbols can
	be large for binary files or debuggers.
      </para><para>
	In many cases, the longer names allow capabilities and behaviours
	controlled by macros to also be unamibiguously emitted as distinct
	generated names.
      </para><para>
	Specific issues found while unraveling performance factors in the
	design of associative containers and priority queues follow.
      </para><section xml:id="pbds.intro.issues.associative"><info><title>Associative</title></info><para>
	  Associative containers depend on their composite policies to a very
	  large extent. Implicitly hard-wiring policies can hamper their
	  performance and limit their functionality. An efficient hash-based
	  container, for example, requires policies for testing key
	  equivalence, hashing keys, translating hash values into positions
	  within the hash table, and determining when and how to resize the
	  table internally. A tree-based container can efficiently support
	  order statistics, i.e. the ability to query what is the order of
	  each key within the sequence of keys in the container, but only if
	  the container is supplied with a policy to internally update
	  meta-data. There are many other such examples.
	</para><para>
	  Ideally, all associative containers would share the same
	  interface. Unfortunately, underlying data structures and mapping
	  semantics differentiate between different containers. For example,
	  suppose one writes a generic function manipulating an associative
	  container.
	</para><programlisting>
	  template&lt;typename Cntnr&gt;
	  void
	  some_op_sequence(Cntnr&amp; r_cnt)
	  {
	  ...
	  }
	</programlisting><para>
	  Given this, then what can one assume about the instantiating
	  container? The answer varies according to its underlying data
	  structure. If the underlying data structure of
	  <literal>Cntnr</literal> is based on a tree or trie, then the order
	  of elements is well defined; otherwise, it is not, in general. If
	  the underlying data structure of <literal>Cntnr</literal> is based
	  on a collision-chaining hash table, then modifying
	  r_<literal>Cntnr</literal> will not invalidate its iterators' order;
	  if the underlying data structure is a probing hash table, then this
	  is not the case. If the underlying data structure is based on a tree
	  or trie, then a reference to the container can efficiently be split;
	  otherwise, it cannot, in general. If the underlying data structure
	  is a red-black tree, then splitting a reference to the container is
	  exception-free; if it is an ordered-vector tree, exceptions can be
	  thrown.
	</para></section><section xml:id="pbds.intro.issues.priority_queue"><info><title>Priority Que</title></info><para>
	  Priority queues are useful when one needs to efficiently access a
	  minimum (or maximum) value as the set of values changes.
	</para><para>
	  Most useful data structures for priority queues have a relatively
	  simple structure, as they are geared toward relatively simple
	  requirements. Unfortunately, these structures do not support access
	  to an arbitrary value, which turns out to be necessary in many
	  algorithms. Say, decreasing an arbitrary value in a graph
	  algorithm. Therefore, some extra mechanism is necessary and must be
	  invented for accessing arbitrary values. There are at least two
	  alternatives: embedding an associative container in a priority
	  queue, or allowing cross-referencing through iterators. The first
	  solution adds significant overhead; the second solution requires a
	  precise definition of iterator invalidation. Which is the next
	  point...
	</para><para>
	  Priority queues, like hash-based containers, store values in an
	  order that is meaningless and undefined externally. For example, a
	  <code>push</code> operation can internally reorganize the
	  values. Because of this characteristic, describing a priority
	  queues' iterator is difficult: on one hand, the values to which
	  iterators point can remain valid, but on the other, the logical
	  order of iterators can change unpredictably.
	</para><para>
	  Roughly speaking, any element that is both inserted to a priority
	  queue (e.g. through <code>push</code>) and removed
	  from it (e.g., through <code>pop</code>), incurs a
	  logarithmic overhead (in the amortized sense). Different underlying
	  data structures place the actual cost differently: some are
	  optimized for amortized complexity, whereas others guarantee that
	  specific operations only have a constant cost. One underlying data
	  structure might be chosen if modifying a value is frequent
	  (Dijkstra's shortest-path algorithm), whereas a different one might
	  be chosen otherwise. Unfortunately, an array-based binary heap - an
	  underlying data structure that optimizes (in the amortized sense)
	  <code>push</code> and <code>pop</code> operations, differs from the
	  others in terms of its invalidation guarantees. Other design
	  decisions also impact the cost and placement of the overhead, at the
	  expense of more difference in the kinds of operations that the
	  underlying data structure can support. These differences pose a
	  challenge when creating a uniform interface for priority queues.
	</para></section></section><section xml:id="pbds.intro.motivation"><info><title>Goals</title></info><para>
	Many fine associative-container libraries were already written,
	most notably, the C++ standard's associative containers. Why
	then write another library? This section shows some possible
	advantages of this library, when considering the challenges in
	the introduction. Many of these points stem from the fact that
	the ISO C++ process introduced associative-containers in a
	two-step process (first standardizing tree-based containers,
	only then adding hash-based containers, which are fundamentally
	different), did not standardize priority queues as containers,
	and (in our opinion) overloads the iterator concept.
      </para><section xml:id="pbds.intro.motivation.associative"><info><title>Associative</title></info><para>
	</para><section xml:id="motivation.associative.policy"><info><title>Policy Choices</title></info><para>
	    Associative containers require a relatively large number of
	    policies to function efficiently in various settings. In some
	    cases this is needed for making their common operations more
	    efficient, and in other cases this allows them to support a
	    larger set of operations
	  </para><orderedlist><listitem><para>
		Hash-based containers, for example, support look-up and
		insertion methods (<function>find</function> and
		<function>insert</function>). In order to locate elements
		quickly, they are supplied a hash functor, which instruct
		how to transform a key object into some size type; a hash
		functor might transform <constant>"hello"</constant>
		into <constant>1123002298</constant>. A hash table, though,
		requires transforming each key object into some size-type
		type in some specific domain; a hash table with a 128-long
		table might transform <constant>"hello"</constant> into
		position <constant>63</constant>. The policy by which the
		hash value is transformed into a position within the table
		can dramatically affect performance.  Hash-based containers
		also do not resize naturally (as opposed to tree-based
		containers, for example). The appropriate resize policy is
		unfortunately intertwined with the policy that transforms
		hash value into a position within the table.
	      </para></listitem><listitem><para>
		Tree-based containers, for example, also support look-up and
		insertion methods, and are primarily useful when maintaining
		order between elements is important. In some cases, though,
		one can utilize their balancing algorithms for completely
		different purposes.
	      </para><para>
		Figure A shows a tree whose each node contains two entries:
		a floating-point key, and some size-type
		<emphasis>metadata</emphasis> (in bold beneath it) that is
		the number of nodes in the sub-tree. (The root has key 0.99,
		and has 5 nodes (including itself) in its sub-tree.) A
		container based on this data structure can obviously answer
		efficiently whether 0.3 is in the container object, but it
		can also answer what is the order of 0.3 among all those in
		the container object: see <xref linkend="biblio.clrs2001"></xref>.

	      </para><para>
		As another example, Figure B shows a tree whose each node
		contains two entries: a half-open geometric line interval,
		and a number <emphasis>metadata</emphasis> (in bold beneath
		it) that is the largest endpoint of all intervals in its
		sub-tree.  (The root describes the interval <constant>[20,
		36)</constant>, and the largest endpoint in its sub-tree is
		99.) A container based on this data structure can obviously
		answer efficiently whether <constant>[3, 41)</constant> is
		in the container object, but it can also answer efficiently
		whether the container object has intervals that intersect
		<constant>[3, 41)</constant>. These types of queries are
		very useful in geometric algorithms and lease-management
		algorithms.
	      </para><para>
		It is important to note, however, that as the trees are
		modified, their internal structure changes. To maintain
		these invariants, one must supply some policy that is aware
		of these changes.  Without this, it would be better to use a
		linked list (in itself very efficient for these purposes).
	      </para></listitem></orderedlist><figure><title>Node Invariants</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_node_invariants.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Node Invariants</phrase></textobject></mediaobject></figure></section><section xml:id="motivation.associative.underlying"><info><title>Underlying Data Structures</title></info><para>
	    The standard C++ library contains associative containers based on
	    red-black trees and collision-chaining hash tables. These are
	    very useful, but they are not ideal for all types of
	    settings.
	  </para><para>
	    The figure below shows the different underlying data structures
	    currently supported in this library.
	  </para><figure><title>Underlying Associative Data Structures</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_different_underlying_dss_1.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Underlying Associative Data Structures</phrase></textobject></mediaobject></figure><para>
	    A shows a collision-chaining hash-table, B shows a probing
	    hash-table, C shows a red-black tree, D shows a splay tree, E shows
	    a tree based on an ordered vector(implicit in the order of the
	    elements), F shows a PATRICIA trie, and G shows a list-based
	    container with update policies.
	  </para><para>
	    Each of these data structures has some performance benefits, in
	    terms of speed, size or both. For now, note that vector-based trees
	    and probing hash tables manipulate memory more efficiently than
	    red-black trees and collision-chaining hash tables, and that
	    list-based associative containers are very useful for constructing
	    "multimaps".
	  </para><para>
	    Now consider a function manipulating a generic associative
	    container,
	  </para><programlisting>
	    template&lt;class Cntnr&gt;
	    int
	    some_op_sequence(Cntnr &amp;r_cnt)
	    {
	    ...
	    }
	  </programlisting><para>
	    Ideally, the underlying data structure
	    of <classname>Cntnr</classname> would not affect what can be
	    done with <varname>r_cnt</varname>.  Unfortunately, this is not
	    the case.
	  </para><para>
	    For example, if <classname>Cntnr</classname>
	    is <classname>std::map</classname>, then the function can
	    use
	  </para><programlisting>
	    std::for_each(r_cnt.find(foo), r_cnt.find(bar), foobar)
	  </programlisting><para>
	    in order to apply <classname>foobar</classname> to all
	    elements between <classname>foo</classname> and
	    <classname>bar</classname>. If
	    <classname>Cntnr</classname> is a hash-based container,
	    then this call's results are undefined.
	  </para><para>
	    Also, if <classname>Cntnr</classname> is tree-based, the type
	    and object of the comparison functor can be
	    accessed. If <classname>Cntnr</classname> is hash based, these
	    queries are nonsensical.
	  </para><para>
	    There are various other differences based on the container's
	    underlying data structure. For one, they can be constructed by,
	    and queried for, different policies. Furthermore:
	  </para><orderedlist><listitem><para>
		Containers based on C, D, E and F store elements in a
		meaningful order; the others store elements in a meaningless
		(and probably time-varying) order. By implication, only
		containers based on C, D, E and F can
		support <function>erase</function> operations taking an
		iterator and returning an iterator to the following element
		without performance loss.
	      </para></listitem><listitem><para>
		Containers based on C, D, E, and F can be split and joined
		efficiently, while the others cannot. Containers based on C
		and D, furthermore, can guarantee that this is exception-free;
		containers based on E cannot guarantee this.
	      </para></listitem><listitem><para>
		Containers based on all but E can guarantee that
		erasing an element is exception free; containers based on E
		cannot guarantee this. Containers based on all but B and E
		can guarantee that modifying an object of their type does
		not invalidate iterators or references to their elements,
		while containers based on B and E cannot. Containers based
		on C, D, and E can furthermore make a stronger guarantee,
		namely that modifying an object of their type does not
		affect the order of iterators.
	      </para></listitem></orderedlist><para>
	    A unified tag and traits system (as used for the C++ standard
	    library iterators, for example) can ease generic manipulation of
	    associative containers based on different underlying data
	    structures.
	  </para></section><section xml:id="motivation.associative.iterators"><info><title>Iterators</title></info><para>
	    Iterators are centric to the design of the standard library
	    containers, because of the container/algorithm/iterator
	    decomposition that allows an algorithm to operate on a range
	    through iterators of some sequence.  Iterators, then, are useful
	    because they allow going over a
	    specific <emphasis>sequence</emphasis>.  The standard library
	    also uses iterators for accessing a
	    specific <emphasis>element</emphasis>: when an associative
	    container returns one through <function>find</function>. The
	    standard library consistently uses the same types of iterators
	    for both purposes: going over a range, and accessing a specific
	    found element. Before the introduction of hash-based containers
	    to the standard library, this made sense (with the exception of
	    priority queues, which are discussed later).
	  </para><para>
	    Using the standard associative containers together with
	    non-order-preserving associative containers (and also because of
	    priority-queues container), there is a possible need for
	    different types of iterators for self-organizing containers:
	    the iterator concept seems overloaded to mean two different
	    things (in some cases). <!-- <remark> XXX
	    "ds_gen.html#find_range">Design::Associative
	    Containers::Data-Structure Genericity::Point-Type and Range-Type
	    Methods</remark>. -->
	  </para><section xml:id="associative.iterators.using"><info><title>Using Point Iterators for Range Operations</title></info><para>
	      Suppose <classname>cntnr</classname> is some associative
	      container, and say <varname>c</varname> is an object of
	      type <classname>cntnr</classname>. Then what will be the outcome
	      of
	    </para><programlisting>
	      std::for_each(c.find(1), c.find(5), foo);
	    </programlisting><para>
	      If <classname>cntnr</classname> is a tree-based container
	      object, then an in-order walk will
	      apply <classname>foo</classname> to the relevant elements,
	      as in the graphic below, label A. If <varname>c</varname> is
	      a hash-based container, then the order of elements between any
	      two elements is undefined (and probably time-varying); there is
	      no guarantee that the elements traversed will coincide with the
	      <emphasis>logical</emphasis> elements between 1 and 5, as in
	      label B.
	    </para><figure><title>Range Iteration in Different Data Structures</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_point_iterators_range_ops_1.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Node Invariants</phrase></textobject></mediaobject></figure><para>
	      In our opinion, this problem is not caused just because
	      red-black trees are order preserving while
	      collision-chaining hash tables are (generally) not - it
	      is more fundamental. Most of the standard's containers
	      order sequences in a well-defined manner that is
	      determined by their <emphasis>interface</emphasis>:
	      calling <function>insert</function> on a tree-based
	      container modifies its sequence in a predictable way, as
	      does calling <function>push_back</function> on a list or
	      a vector. Conversely, collision-chaining hash tables,
	      probing hash tables, priority queues, and list-based
	      containers (which are very useful for "multimaps") are
	      self-organizing data structures; the effect of each
	      operation modifies their sequences in a manner that is
	      (practically) determined by their
	      <emphasis>implementation</emphasis>.
	    </para><para>
	      Consequently, applying an algorithm to a sequence obtained from most
	      containers may or may not make sense, but applying it to a
	      sub-sequence of a self-organizing container does not.
	    </para></section><section xml:id="associative.iterators.cost"><info><title>Cost to Point Iterators to Enable Range Operations</title></info><para>
	      Suppose <varname>c</varname> is some collision-chaining
	      hash-based container object, and one calls
	    </para><programlisting>c.find(3)</programlisting><para>
	      Then what composes the returned iterator?
	    </para><para>
	      In the graphic below, label A shows the simplest (and
	      most efficient) implementation of a collision-chaining
	      hash table.  The little box marked
	      <classname>point_iterator</classname> shows an object
	      that contains a pointer to the element's node. Note that
	      this "iterator" has no way to move to the next element (
	      it cannot support
	      <function>operator++</function>). Conversely, the little
	      box marked <classname>iterator</classname> stores both a
	      pointer to the element, as well as some other
	      information (the bucket number of the element). the
	      second iterator, then, is "heavier" than the first one-
	      it requires more time and space. If we were to use a
	      different container to cross-reference into this
	      hash-table using these iterators - it would take much
	      more space. As noted above, nothing much can be done by
	      incrementing these iterators, so why is this extra
	      information needed?
	    </para><para>
	      Alternatively, one might create a collision-chaining hash-table
	      where the lists might be linked, forming a monolithic total-element
	      list, as in the graphic below, label B.  Here the iterators are as
	      light as can be, but the hash-table's operations are more
	      complicated.
	    </para><figure><title>Point Iteration in Hash Data Structures</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_point_iterators_range_ops_2.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Point Iteration in Hash Data Structures</phrase></textobject></mediaobject></figure><para>
	      It should be noted that containers based on collision-chaining
	      hash-tables are not the only ones with this type of behavior;
	      many other self-organizing data structures display it as well.
	    </para></section><section xml:id="associative.iterators.invalidation"><info><title>Invalidation Guarantees</title></info><para>Consider the following snippet:</para><programlisting>
	      it = c.find(3);
	      c.erase(5);
	    </programlisting><para>
	      Following the call to <classname>erase</classname>, what is the
	      validity of <classname>it</classname>: can it be de-referenced?
	      can it be incremented?
	    </para><para>
	      The answer depends on the underlying data structure of the
	      container. The graphic below shows three cases: A1 and A2 show
	      a red-black tree; B1 and B2 show a probing hash-table; C1 and C2
	      show a collision-chaining hash table.
	    </para><figure><title>Effect of erase in different underlying data structures</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_invalidation_guarantee_erase.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Effect of erase in different underlying data structures</phrase></textobject></mediaobject></figure><orderedlist><listitem><para>
		  Erasing 5 from A1 yields A2. Clearly, an iterator to 3 can
		  be de-referenced and incremented. The sequence of iterators
		  changed, but in a way that is well-defined by the interface.
		</para></listitem><listitem><para>
		  Erasing 5 from B1 yields B2. Clearly, an iterator to 3 is
		  not valid at all - it cannot be de-referenced or
		  incremented; the order of iterators changed in a way that is
		  (practically) determined by the implementation and not by
		  the interface.
		</para></listitem><listitem><para>
		  Erasing 5 from C1 yields C2. Here the situation is more
		  complicated. On the one hand, there is no problem in
		  de-referencing <classname>it</classname>. On the other hand,
		  the order of iterators changed in a way that is
		  (practically) determined by the implementation and not by
		  the interface.
		</para></listitem></orderedlist><para>
	      So in the standard library containers, it is not always possible
	      to express whether <varname>it</varname> is valid or not. This
	      is true also for <function>insert</function>. Again, the
	      iterator concept seems overloaded.
	    </para></section></section><!--iterators--><section xml:id="motivation.associative.functions"><info><title>Functional</title></info><para>
	  </para><para>
	    The design of the functional overlay to the underlying data
	    structures differs slightly from some of the conventions used in
	    the C++ standard.  A strict public interface of methods that
	    comprise only operations which depend on the class's internal
	    structure; other operations are best designed as external
	    functions. (See <xref linkend="biblio.meyers02both"></xref>).With this
	    rubric, the standard associative containers lack some useful
	    methods, and provide other methods which would be better
	    removed.
	  </para><section xml:id="motivation.associative.functions.erase"><info><title><function>erase</function></title></info><orderedlist><listitem><para>
		  Order-preserving standard associative containers provide the
		  method
		</para><programlisting>
		  iterator
		  erase(iterator it)
		</programlisting><para>
		  which takes an iterator, erases the corresponding
		  element, and returns an iterator to the following
		  element. Also standardd hash-based associative
		  containers provide this method. This seemingly
		  increasesgenericity between associative containers,
		  since it is possible to use
		</para><programlisting>
		  typename C::iterator it = c.begin();
		  typename C::iterator e_it = c.end();

		  while(it != e_it)
		  it = pred(*it)? c.erase(it) : ++it;
		</programlisting><para>
		  in order to erase from a container object <varname>
		  c</varname> all element which match a
		  predicate <classname>pred</classname>. However, in a
		  different sense this actually decreases genericity: an
		  integral implication of this method is that tree-based
		  associative containers' memory use is linear in the total
		  number of elements they store, while hash-based
		  containers' memory use is unbounded in the total number of
		  elements they store. Assume a hash-based container is
		  allowed to decrease its size when an element is
		  erased. Then the elements might be rehashed, which means
		  that there is no "next" element - it is simply
		  undefined. Consequently, it is possible to infer from the
		  fact that the standard library's hash-based containers
		  provide this method that they cannot downsize when
		  elements are erased. As a consequence, different code is
		  needed to manipulate different containers, assuming that
		  memory should be conserved. Therefor, this library's
		  non-order preserving associative containers omit this
		  method.
		</para></listitem><listitem><para>
		  All associative containers include a conditional-erase method
		</para><programlisting>
		  template&lt;
		  class Pred&gt;
		  size_type
		  erase_if
		  (Pred pred)
		</programlisting><para>
		  which erases all elements matching a predicate. This is probably the
		  only way to ensure linear-time multiple-item erase which can
		  actually downsize a container.
		</para></listitem><listitem><para>
		  The standard associative containers provide methods for
		  multiple-item erase of the form
		</para><programlisting>
		  size_type
		  erase(It b, It e)
		</programlisting><para>
		  erasing a range of elements given by a pair of
		  iterators. For tree-based or trie-based containers, this can
		  implemented more efficiently as a (small) sequence of split
		  and join operations. For other, unordered, containers, this
		  method isn't much better than an external loop. Moreover,
		  if <varname>c</varname> is a hash-based container,
		  then
		</para><programlisting>
		  c.erase(c.find(2), c.find(5))
		</programlisting><para>
		  is almost certain to do something
		  different than erasing all elements whose keys are between 2
		  and 5, and is likely to produce other undefined behavior.
		</para></listitem></orderedlist></section><!-- erase --><section xml:id="motivation.associative.functions.split"><info><title><function>split</function> and <function>join</function>
	      </title></info><para>
	      It is well-known that tree-based and trie-based container
	      objects can be efficiently split or joined (See
	      <xref linkend="biblio.clrs2001"></xref>). Externally splitting or
	      joining trees is super-linear, and, furthermore, can throw
	      exceptions. Split and join methods, consequently, seem good
	      choices for tree-based container methods, especially, since as
	      noted just before, they are efficient replacements for erasing
	      sub-sequences.
	    </para></section><!-- split --><section xml:id="motivation.associative.functions.insert"><info><title><function>insert</function></title></info><para>
	      The standard associative containers provide methods of the form
	    </para><programlisting>
	      template&lt;class It&gt;
	      size_type
	      insert(It b, It e);
	    </programlisting><para>
	      for inserting a range of elements given by a pair of
	      iterators. At best, this can be implemented as an external loop,
	      or, even more efficiently, as a join operation (for the case of
	      tree-based or trie-based containers). Moreover, these methods seem
	      similar to constructors taking a range given by a pair of
	      iterators; the constructors, however, are transactional, whereas
	      the insert methods are not; this is possibly confusing.
	    </para></section><!-- insert --><section xml:id="motivation.associative.functions.compare"><info><title><function>operator==</function> and <function>operator&lt;=</function>
	      </title></info><para>
	      Associative containers are parametrized by policies allowing to
	      test key equivalence: a hash-based container can do this through
	      its equivalence functor, and a tree-based container can do this
	      through its comparison functor. In addition, some standard
	      associative containers have global function operators, like
	      <function>operator==</function> and <function>operator&lt;=</function>,
	      that allow comparing entire associative containers.
	    </para><para>
	      In our opinion, these functions are better left out. To begin
	      with, they do not significantly improve over an external
	      loop. More importantly, however, they are possibly misleading -
	      <function>operator==</function>, for example, usually checks for
	      equivalence, or interchangeability, but the associative
	      container cannot check for values' equivalence, only keys'
	      equivalence; also, are two containers considered equivalent if
	      they store the same values in different order? this is an
	      arbitrary decision.
	    </para></section><!-- compare --></section><!-- functional --></section><!--associative--><section xml:id="pbds.intro.motivation.priority_queue"><info><title>Priority Queues</title></info><section xml:id="motivation.priority_queue.policy"><info><title>Policy Choices</title></info><para>
	    Priority queues are containers that allow efficiently inserting
	    values and accessing the maximal value (in the sense of the
	    container's comparison functor). Their interface
	    supports <function>push</function>
	    and <function>pop</function>. The standard
	    container <classname>std::priorityqueue</classname> indeed support
	    these methods, but little else. For algorithmic and
	    software-engineering purposes, other methods are needed:
	  </para><orderedlist><listitem><para>
		Many graph algorithms (see
		<xref linkend="biblio.clrs2001"></xref>) require increasing a
		value in a priority queue (again, in the sense of the
		container's comparison functor), or joining two
		priority-queue objects.
	      </para></listitem><listitem><para>The return type of <classname>priority_queue</classname>'s
	      <function>push</function> method is a point-type iterator, which can
	      be used for modifying or erasing arbitrary values. For
	      example:</para><programlisting>
		priority_queue&lt;int&gt; p;
		priority_queue&lt;int&gt;::point_iterator it = p.push(3);
		p.modify(it, 4);
	      </programlisting><para>These types of cross-referencing operations are necessary
	      for making priority queues useful for different applications,
	      especially graph applications.</para></listitem><listitem><para>
		It is sometimes necessary to erase an arbitrary value in a
		priority queue. For example, consider
		the <function>select</function> function for monitoring
		file descriptors:
	      </para><programlisting>
		int
		select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds,
		struct timeval *timeout);
	      </programlisting><para>
		then, as the select documentation states:
	      </para><para><quote>
		  The nfds argument specifies the range of file
		  descriptors to be tested. The select() function tests file
		descriptors in the range of 0 to nfds-1.</quote></para><para>
		It stands to reason, therefore, that we might wish to
		maintain a minimal value for <varname>nfds</varname>, and
		priority queues immediately come to mind. Note, though, that
		when a socket is closed, the minimal file description might
		change; in the absence of an efficient means to erase an
		arbitrary value from a priority queue, we might as well
		avoid its use altogether.
	      </para><para>
		The standard containers typically support iterators. It is
		somewhat unusual
		for <classname>std::priority_queue</classname> to omit them
		(See <xref linkend="biblio.meyers01stl"></xref>). One might
		ask why do priority queues need to support iterators, since
		they are self-organizing containers with a different purpose
		than abstracting sequences. There are several reasons:
	      </para><orderedlist><listitem><para>
		    Iterators (even in self-organizing containers) are
		    useful for many purposes: cross-referencing
		    containers, serialization, and debugging code that uses
		    these containers.
		  </para></listitem><listitem><para>
		    The standard library's hash-based containers support
		    iterators, even though they too are self-organizing
		    containers with a different purpose than abstracting
		    sequences.
		  </para></listitem><listitem><para>
		    In standard-library-like containers, it is natural to specify the
		    interface of operations for modifying a value or erasing
		    a value (discussed previously) in terms of a iterators.
		    It should be noted that the standard
		    containers also use iterators for accessing and
		    manipulating a specific value. In hash-based
		    containers, one checks the existence of a key by
		    comparing the iterator returned by <function>find</function> to the
		    iterator returned by <function>end</function>, and not by comparing a
		    pointer returned by <function>find</function> to <type>NULL</type>.
		  </para></listitem></orderedlist></listitem></orderedlist></section><section xml:id="motivation.priority_queue.underlying"><info><title>Underlying Data Structures</title></info><para>
	    There are three main implementations of priority queues: the
	    first employs a binary heap, typically one which uses a
	    sequence; the second uses a tree (or forest of trees), which is
	    typically less structured than an associative container's tree;
	    the third simply uses an associative container. These are
	    shown in the figure below with labels A1 and A2, B, and C.
	  </para><figure><title>Underlying Priority Queue Data Structures</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_different_underlying_dss_2.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Underlying Priority Queue Data Structures</phrase></textobject></mediaobject></figure><para>
	    No single implementation can completely replace any of the
	    others. Some have better <function>push</function>
	    and <function>pop</function> amortized performance, some have
	    better bounded (worst case) response time than others, some
	    optimize a single method at the expense of others, etc. In
	    general the "best" implementation is dictated by the specific
	    problem.
	  </para><para>
	    As with associative containers, the more implementations
	    co-exist, the more necessary a traits mechanism is for handling
	    generic containers safely and efficiently. This is especially
	    important for priority queues, since the invalidation guarantees
	    of one of the most useful data structures - binary heaps - is
	    markedly different than those of most of the others.
	  </para></section><section xml:id="motivation.priority_queue.binary_heap"><info><title>Binary Heaps</title></info><para>
	    Binary heaps are one of the most useful underlying
	    data structures for priority queues. They are very efficient in
	    terms of memory (since they don't require per-value structure
	    metadata), and have the best amortized <function>push</function> and
	    <function>pop</function> performance for primitive types like
	    <type>int</type>.
	  </para><para>
	    The standard library's <classname>priority_queue</classname>
	    implements this data structure as an adapter over a sequence,
	    typically
	    <classname>std::vector</classname>
	    or <classname>std::deque</classname>, which correspond to labels
	    A1 and A2 respectively in the graphic above.
	  </para><para>
	    This is indeed an elegant example of the adapter concept and
	    the algorithm/container/iterator decomposition. (See <xref linkend="biblio.nelson96stlpq"></xref>). There are
	    several reasons why a binary-heap priority queue
	    may be better implemented as a container instead of a
	    sequence adapter:
	  </para><orderedlist><listitem><para><classname>std::priority_queue</classname> cannot erase values
		from its adapted sequence (irrespective of the sequence
		type). This means that the memory use of
		an <classname>std::priority_queue</classname> object is always
		proportional to the maximal number of values it ever contained,
		and not to the number of values that it currently
		contains. (See <filename>performance/priority_queue_text_pop_mem_usage.cc</filename>.)
		This implementation of binary heaps acts very differently than
		other underlying data structures (See also pairing heaps).
	      </para></listitem><listitem><para>
		Some combinations of adapted sequences and value types
		are very inefficient or just don't make sense. If one uses
		<classname>std::priority_queue&lt;std::vector&lt;std::string&gt;
		&gt; &gt;</classname>, for example, then not only will each
		operation perform a logarithmic number of
		<classname>std::string</classname> assignments, but, furthermore, any
		operation (including <function>pop</function>) can render the container
		useless due to exceptions. Conversely, if one uses
		<classname>std::priority_queue&lt;std::deque&lt;int&gt; &gt;
		&gt;</classname>, then each operation uses incurs a logarithmic
		number of indirect accesses (through pointers) unnecessarily.
		It might be better to let the container make a conservative
		deduction whether to use the structure in the graphic above, labels A1 or A2.
	      </para></listitem><listitem><para>
		There does not seem to be a systematic way to determine
		what exactly can be done with the priority queue.
	      </para><orderedlist><listitem><para>
		    If <classname>p</classname> is a priority queue adapting an
		    <classname>std::vector</classname>, then it is possible to iterate over
		    all values by using <function>&amp;p.top()</function> and
		    <function>&amp;p.top() + p.size()</function>, but this will not work
		    if <varname>p</varname> is adapting an <classname>std::deque</classname>; in any
		    case, one cannot use <classname>p.begin()</classname> and
		    <classname>p.end()</classname>. If a different sequence is adapted, it
		    is even more difficult to determine what can be
		    done.
		  </para></listitem><listitem><para>
		    If <varname>p</varname> is a priority queue adapting an
		    <classname>std::deque</classname>, then the reference return by
		  </para><programlisting>
		    p.top()
		  </programlisting><para>
		    will remain valid until it is popped,
		    but if <varname>p</varname> adapts an <classname>std::vector</classname>, the
		    next <function>push</function> will invalidate it. If a different
		    sequence is adapted, it is even more difficult to
		    determine what can be done.
		  </para></listitem></orderedlist></listitem><listitem><para>
		Sequence-based binary heaps can still implement
		linear-time <function>erase</function> and <function>modify</function> operations.
		This means that if one needs to erase a small
		(say logarithmic) number of values, then one might still
		choose this underlying data structure. Using
		<classname>std::priority_queue</classname>, however, this will generally
		change the order of growth of the entire sequence of
		operations.
	      </para></listitem></orderedlist></section></section></section><!-- goals/motivation --></section><!-- intro --><!-- S02: Using --><section xml:id="containers.pbds.using"><info><title>Using</title></info><?dbhtml filename="policy_data_structures_using.html"?><section xml:id="pbds.using.prereq"><info><title>Prerequisites</title></info><para>The library contains only header files, and does not require any
      other libraries except the standard C++ library . All classes are
      defined in namespace <code>__gnu_pbds</code>. The library internally
      uses macros beginning with <code>PB_DS</code>, but
      <code>#undef</code>s anything it <code>#define</code>s (except for
      header guards). Compiling the library in an environment where macros
      beginning in <code>PB_DS</code> are defined, may yield unpredictable
      results in compilation, execution, or both.</para><para>
	Further dependencies are necessary to create the visual output
	for the performance tests. To create these graphs, an
	additional package is needed: <command>pychart</command>.
      </para></section><section xml:id="pbds.using.organization"><info><title>Organization</title></info><para>
	The various data structures are organized as follows.
      </para><itemizedlist><listitem><para>
	    Branch-Based
	  </para><itemizedlist><listitem><para><classname>basic_branch</classname>
		is an abstract base class for branched-based
		associative-containers
	      </para></listitem><listitem><para><classname>tree</classname>
		is a concrete base class for tree-based
		associative-containers
	      </para></listitem><listitem><para><classname>trie</classname>
		is a concrete base class trie-based
		associative-containers
	      </para></listitem></itemizedlist></listitem><listitem><para>
	    Hash-Based
	  </para><itemizedlist><listitem><para><classname>basic_hash_table</classname>
		is an abstract base class for hash-based
		associative-containers
	      </para></listitem><listitem><para><classname>cc_hash_table</classname>
		is a concrete collision-chaining hash-based
		associative-containers
	      </para></listitem><listitem><para><classname>gp_hash_table</classname>
		is a concrete (general) probing hash-based
		associative-containers
	      </para></listitem></itemizedlist></listitem><listitem><para>
	    List-Based
	  </para><itemizedlist><listitem><para><classname>list_update</classname>
		list-based update-policy associative container
	      </para></listitem></itemizedlist></listitem><listitem><para>
	    Heap-Based
	  </para><itemizedlist><listitem><para><classname>priority_queue</classname>
		A priority queue.
	      </para></listitem></itemizedlist></listitem></itemizedlist><para>
	The hierarchy is composed naturally so that commonality is
	captured by base classes. Thus <function>operator[]</function>
	is defined at the base of any hierarchy, since all derived
	containers support it. Conversely <function>split</function> is
	defined in <classname>basic_branch</classname>, since only
	tree-like containers support it.
      </para><para>
	In addition, there are the following diagnostics classes,
	used to report errors specific to this library's data
	structures.
      </para><figure><title>Exception Hierarchy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_exception_hierarchy.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_exception_hierarchy.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Exception Hierarchy</phrase></textobject></mediaobject></figure></section><section xml:id="pbds.using.tutorial"><info><title>Tutorial</title></info><section xml:id="pbds.using.tutorial.basic"><info><title>Basic Use</title></info><para>
	  For the most part, the policy-based containers containers in
	  namespace <literal>__gnu_pbds</literal> have the same interface as
	  the equivalent containers in the standard C++ library, except for
	  the names used for the container classes themselves. For example,
	  this shows basic operations on a collision-chaining hash-based
	  container:
	</para><programlisting>
	  #include &lt;ext/pb_ds/assoc_container.h&gt;

	  int main()
	  {
	  __gnu_pbds::cc_hash_table&lt;int, char&gt; c;
	  c[2] = 'b';
	  assert(c.find(1) == c.end());
	  };
	</programlisting><para>
	  The container is called
	  <classname>__gnu_pbds::cc_hash_table</classname> instead of
	  <classname>std::unordered_map</classname>, since <quote>unordered
	  map</quote> does not necessarily mean a hash-based map as implied by
	  the C++ library (C++11 or TR1). For example, list-based associative
	  containers, which are very useful for the construction of
	  "multimaps," are also unordered.
	</para><para>This snippet shows a red-black tree based container:</para><programlisting>
	  #include &lt;ext/pb_ds/assoc_container.h&gt;

	  int main()
	  {
	  __gnu_pbds::tree&lt;int, char&gt; c;
	  c[2] = 'b';
	  assert(c.find(2) != c.end());
	  };
	</programlisting><para>The container is called <classname>tree</classname> instead of
	<classname>map</classname> since the underlying data structures are
	being named with specificity.
	</para><para>
	  The member function naming convention is to strive to be the same as
	  the equivalent member functions in other C++ standard library
	  containers. The familiar methods are unchanged:
	  <function>begin</function>, <function>end</function>,
	  <function>size</function>, <function>empty</function>, and
	  <function>clear</function>.
	</para><para>
	  This isn't to say that things are exactly as one would expect, given
	  the container requirments and interfaces in the C++ standard.
	</para><para>
	  The names of containers' policies and policy accessors are
	  different then the usual. For example, if <type>hash_type</type> is
	some type of hash-based container, then</para><programlisting>
	  hash_type::hash_fn
	</programlisting><para>
	  gives the type of its hash functor, and if <varname>obj</varname> is
	  some hash-based container object, then
	</para><programlisting>
	  obj.get_hash_fn()
	</programlisting><para>will return a reference to its hash-functor object.</para><para>
	  Similarly, if <type>tree_type</type> is some type of tree-based
	  container, then
	</para><programlisting>
	  tree_type::cmp_fn
	</programlisting><para>
	  gives the type of its comparison functor, and if
	  <varname>obj</varname> is some tree-based container object,
	  then
	</para><programlisting>
	  obj.get_cmp_fn()
	</programlisting><para>will return a reference to its comparison-functor object.</para><para>
	  It would be nice to give names consistent with those in the existing
	  C++ standard (inclusive of TR1). Unfortunately, these standard
	  containers don't consistently name types and methods. For example,
	  <classname>std::tr1::unordered_map</classname> uses
	  <type>hasher</type> for the hash functor, but
	  <classname>std::map</classname> uses <type>key_compare</type> for
	  the comparison functor. Also, we could not find an accessor for
	  <classname>std::tr1::unordered_map</classname>'s hash functor, but
	  <classname>std::map</classname> uses <classname>compare</classname>
	  for accessing the comparison functor.
	</para><para>
	  Instead, <literal>__gnu_pbds</literal> attempts to be internally
	  consistent, and uses standard-derived terminology if possible.
	</para><para>
	  Another source of difference is in scope:
	  <literal>__gnu_pbds</literal> contains more types of associative
	  containers than the standard C++ library, and more opportunities
	  to configure these new containers, since different types of
	  associative containers are useful in different settings.
	</para><para>
	  Namespace <literal>__gnu_pbds</literal> contains different classes for
	  hash-based containers, tree-based containers, trie-based containers,
	  and list-based containers.
	</para><para>
	  Since associative containers share parts of their interface, they
	  are organized as a class hierarchy.
	</para><para>Each type or method is defined in the most-common ancestor
	in which it makes sense.
	</para><para>For example, all associative containers support iteration
	expressed in the following form:
	</para><programlisting>
	  const_iterator
	  begin() const;

	  iterator
	  begin();

	  const_iterator
	  end() const;

	  iterator
	  end();
	</programlisting><para>
	  But not all containers contain or use hash functors. Yet, both
	  collision-chaining and (general) probing hash-based associative
	  containers have a hash functor, so
	  <classname>basic_hash_table</classname> contains the interface:
	</para><programlisting>
	  const hash_fn&amp;
	  get_hash_fn() const;

	  hash_fn&amp;
	  get_hash_fn();
	</programlisting><para>
	  so all hash-based associative containers inherit the same
	  hash-functor accessor methods.
	</para></section><!--basic use --><section xml:id="pbds.using.tutorial.configuring"><info><title>
	    Configuring via Template Parameters
	  </title></info><para>
	  In general, each of this library's containers is
	  parametrized by more policies than those of the standard library. For
	  example, the standard hash-based container is parametrized as
	  follows:
	</para><programlisting>
	  template&lt;typename Key, typename Mapped, typename Hash,
	  typename Pred, typename Allocator, bool Cache_Hashe_Code&gt;
	  class unordered_map;
	</programlisting><para>
	  and so can be configured by key type, mapped type, a functor
	  that translates keys to unsigned integral types, an equivalence
	  predicate, an allocator, and an indicator whether to store hash
	  values with each entry. this library's collision-chaining
	  hash-based container is parametrized as
	</para><programlisting>
	  template&lt;typename Key, typename Mapped, typename Hash_Fn,
	  typename Eq_Fn, typename Comb_Hash_Fn,
	  typename Resize_Policy, bool Store_Hash
	  typename Allocator&gt;
	  class cc_hash_table;
	</programlisting><para>
	  and so can be configured by the first four types of
	  <classname>std::tr1::unordered_map</classname>, then a
	  policy for translating the key-hash result into a position
	  within the table, then a policy by which the table resizes,
	  an indicator whether to store hash values with each entry,
	  and an allocator (which is typically the last template
	  parameter in standard containers).
	</para><para>
	  Nearly all policy parameters have default values, so this
	  need not be considered for casual use. It is important to
	  note, however, that hash-based containers' policies can
	  dramatically alter their performance in different settings,
	  and that tree-based containers' policies can make them
	  useful for other purposes than just look-up.
	</para><para>As opposed to associative containers, priority queues have
	relatively few configuration options. The priority queue is
	parametrized as follows:</para><programlisting>
	  template&lt;typename Value_Type, typename Cmp_Fn,typename Tag,
	  typename Allocator&gt;
	  class priority_queue;
	</programlisting><para>The <classname>Value_Type</classname>, <classname>Cmp_Fn</classname>, and
	<classname>Allocator</classname> parameters are the container's value type,
	comparison-functor type, and allocator type, respectively;
	these are very similar to the standard's priority queue. The
	<classname>Tag</classname> parameter is different: there are a number of
	pre-defined tag types corresponding to binary heaps, binomial
	heaps, etc., and <classname>Tag</classname> should be instantiated
	by one of them.</para><para>Note that as opposed to the
	<classname>std::priority_queue</classname>,
	<classname>__gnu_pbds::priority_queue</classname> is not a
	sequence-adapter; it is a regular container.</para></section><section xml:id="pbds.using.tutorial.traits"><info><title>
	    Querying Container Attributes
	  </title></info><para></para><para>A containers underlying data structure
	affect their performance; Unfortunately, they can also affect
	their interface. When manipulating generically associative
	containers, it is often useful to be able to statically
	determine what they can support and what the cannot.
	</para><para>Happily, the standard provides a good solution to a similar
	problem - that of the different behavior of iterators. If
	<classname>It</classname> is an iterator, then
	</para><programlisting>
	  typename std::iterator_traits&lt;It&gt;::iterator_category
	</programlisting><para>is one of a small number of pre-defined tag classes, and
	</para><programlisting>
	  typename std::iterator_traits&lt;It&gt;::value_type
	</programlisting><para>is the value type to which the iterator "points".</para><para>
	  Similarly, in this library, if <type>C</type> is a
	  container, then <classname>container_traits</classname> is a
	  trait class that stores information about the kind of
	  container that is implemented.
	</para><programlisting>
	  typename container_traits&lt;C&gt;::container_category
	</programlisting><para>
	  is one of a small number of predefined tag structures that
	  uniquely identifies the type of underlying data structure.
	</para><para>In most cases, however, the exact underlying data
	structure is not really important, but what is important is
	one of its other attributes: whether it guarantees storing
	elements by key order, for example. For this one can
	use</para><programlisting>
	  typename container_traits&lt;C&gt;::order_preserving
	</programlisting><para>
	  Also,
	</para><programlisting>
	  typename container_traits&lt;C&gt;::invalidation_guarantee
	</programlisting><para>is the container's invalidation guarantee. Invalidation
	guarantees are especially important regarding priority queues,
	since in this library's design, iterators are practically the
	only way to manipulate them.</para></section><section xml:id="pbds.using.tutorial.point_range_iteration"><info><title>
	    Point and Range Iteration
	  </title></info><para></para><para>This library differentiates between two types of methods
	and iterators: point-type, and range-type. For example,
	<function>find</function> and <function>insert</function> are point-type methods, since
	they each deal with a specific element; their returned
	iterators are point-type iterators. <function>begin</function> and
	<function>end</function> are range-type methods, since they are not used to
	find a specific element, but rather to go over all elements in
	a container object; their returned iterators are range-type
	iterators.
	</para><para>Most containers store elements in an order that is
	determined by their interface. Correspondingly, it is fine that
	their point-type iterators are synonymous with their range-type
	iterators. For example, in the following snippet
	</para><programlisting>
	  std::for_each(c.find(1), c.find(5), foo);
	</programlisting><para>
	  two point-type iterators (returned by <function>find</function>) are used
	  for a range-type purpose - going over all elements whose key is
	  between 1 and 5.
	</para><para>
	  Conversely, the above snippet makes no sense for
	  self-organizing containers - ones that order (and reorder)
	  their elements by implementation. It would be nice to have a
	  uniform iterator system that would allow the above snippet to
	  compile only if it made sense.
	</para><para>
	  This could trivially be done by specializing
	  <function>std::for_each</function> for the case of iterators returned by
	  <classname>std::tr1::unordered_map</classname>, but this would only solve the
	  problem for one algorithm and one container. Fundamentally, the
	  problem is that one can loop using a self-organizing
	  container's point-type iterators.
	</para><para>
	  This library's containers define two families of
	  iterators: <type>point_const_iterator</type> and
	  <type>point_iterator</type> are the iterator types returned by
	  point-type methods; <type>const_iterator</type> and
	  <type>iterator</type> are the iterator types returned by range-type
	  methods.
	</para><programlisting>
	  class &lt;- some container -&gt;
	  {
	  public:
	  ...

	  typedef &lt;- something -&gt; const_iterator;

	  typedef &lt;- something -&gt; iterator;

	  typedef &lt;- something -&gt; point_const_iterator;

	  typedef &lt;- something -&gt; point_iterator;

	  ...

	  public:
	  ...

	  const_iterator begin () const;

	  iterator begin();

	  point_const_iterator find(...) const;

	  point_iterator find(...);
	  };
	</programlisting><para>For
	containers whose interface defines sequence order , it
	is very simple: point-type and range-type iterators are exactly
	the same, which means that the above snippet will compile if it
	is used for an order-preserving associative container.
	</para><para>
	  For self-organizing containers, however, (hash-based
	  containers as a special example), the preceding snippet will
	  not compile, because their point-type iterators do not support
	  <function>operator++</function>.
	</para><para>In any case, both for order-preserving and self-organizing
	containers, the following snippet will compile:
	</para><programlisting>
	  typename Cntnr::point_iterator it = c.find(2);
	</programlisting><para>
	  because a range-type iterator can always be converted to a
	  point-type iterator.
	</para><para>Distingushing between iterator types also
	raises the point that a container's iterators might have
	different invalidation rules concerning their de-referencing
	abilities and movement abilities. This now corresponds exactly
	to the question of whether point-type and range-type iterators
	are valid. As explained above, <classname>container_traits</classname> allows
	querying a container for its data structure attributes. The
	iterator-invalidation guarantees are certainly a property of
	the underlying data structure, and so
	</para><programlisting>
	  container_traits&lt;C&gt;::invalidation_guarantee
	</programlisting><para>
	  gives one of three pre-determined types that answer this
	  query.
	</para></section></section><!-- tutorial --><section xml:id="pbds.using.examples"><info><title>Examples</title></info><para>
	Additional code examples are provided in the source
	distribution, as part of the regression and performance
	testsuite.
      </para><section xml:id="pbds.using.examples.basic"><info><title>Intermediate Use</title></info><itemizedlist><listitem><para>
	      Basic use of maps:
	      <filename>basic_map.cc</filename>
	    </para></listitem><listitem><para>
	      Basic use of sets:
	      <filename>basic_set.cc</filename>
	    </para></listitem><listitem><para>
	      Conditionally erasing values from an associative container object:
	      <filename>erase_if.cc</filename>
	    </para></listitem><listitem><para>
	      Basic use of multimaps:
	      <filename>basic_multimap.cc</filename>
	    </para></listitem><listitem><para>
	      Basic use of multisets:
	      <filename>basic_multiset.cc</filename>
	    </para></listitem><listitem><para>
	      Basic use of priority queues:
	      <filename>basic_priority_queue.cc</filename>
	    </para></listitem><listitem><para>
	      Splitting and joining priority queues:
	      <filename>priority_queue_split_join.cc</filename>
	    </para></listitem><listitem><para>
	      Conditionally erasing values from a priority queue:
	      <filename>priority_queue_erase_if.cc</filename>
	    </para></listitem></itemizedlist></section><section xml:id="pbds.using.examples.query"><info><title>Querying with <classname>container_traits</classname> </title></info><itemizedlist><listitem><para>
	      Using <classname>container_traits</classname> to query
	      about underlying data structure behavior:
	      <filename>assoc_container_traits.cc</filename>
	    </para></listitem><listitem><para>
	      A non-compiling example showing wrong use of finding keys in
	      hash-based containers: <filename>hash_find_neg.cc</filename>
	    </para></listitem><listitem><para>
	      Using <classname>container_traits</classname>
	      to query about underlying data structure behavior:
	      <filename>priority_queue_container_traits.cc</filename>
	    </para></listitem></itemizedlist></section><section xml:id="pbds.using.examples.container"><info><title>By Container Method</title></info><para></para><section xml:id="pbds.using.examples.container.hash"><info><title>Hash-Based</title></info><section xml:id="pbds.using.examples.container.hash.resize"><info><title>size Related</title></info><itemizedlist><listitem><para>
		  Setting the initial size of a hash-based container
		  object:
		  <filename>hash_initial_size.cc</filename>
		</para></listitem><listitem><para>
		  A non-compiling example showing how not to resize a
		  hash-based container object:
		  <filename>hash_resize_neg.cc</filename>
		</para></listitem><listitem><para>
		  Resizing the size of a hash-based container object:
		  <filename>hash_resize.cc</filename>
		</para></listitem><listitem><para>
		  Showing an illegal resize of a hash-based container
		  object:
		  <filename>hash_illegal_resize.cc</filename>
		</para></listitem><listitem><para>
		  Changing the load factors of a hash-based container
		  object: <filename>hash_load_set_change.cc</filename>
		</para></listitem></itemizedlist></section><section xml:id="pbds.using.examples.container.hash.hashor"><info><title>Hashing Function Related</title></info><para></para><itemizedlist><listitem><para>
		  Using a modulo range-hashing function for the case of an
		  unknown skewed key distribution:
		  <filename>hash_mod.cc</filename>
		</para></listitem><listitem><para>
		  Writing a range-hashing functor for the case of a known
		  skewed key distribution:
		  <filename>shift_mask.cc</filename>
		</para></listitem><listitem><para>
		  Storing the hash value along with each key:
		  <filename>store_hash.cc</filename>
		</para></listitem><listitem><para>
		  Writing a ranged-hash functor:
		  <filename>ranged_hash.cc</filename>
		</para></listitem></itemizedlist></section></section><section xml:id="pbds.using.examples.container.branch"><info><title>Branch-Based</title></info><section xml:id="pbds.using.examples.container.branch.split"><info><title>split or join Related</title></info><itemizedlist><listitem><para>
		  Joining two tree-based container objects:
		  <filename>tree_join.cc</filename>
		</para></listitem><listitem><para>
		  Splitting a PATRICIA trie container object:
		  <filename>trie_split.cc</filename>
		</para></listitem><listitem><para>
		  Order statistics while joining two tree-based container
		  objects:
		  <filename>tree_order_statistics_join.cc</filename>
		</para></listitem></itemizedlist></section><section xml:id="pbds.using.examples.container.branch.invariants"><info><title>Node Invariants</title></info><itemizedlist><listitem><para>
		  Using trees for order statistics:
		  <filename>tree_order_statistics.cc</filename>
		</para></listitem><listitem><para>
		  Augmenting trees to support operations on line
		  intervals:
		  <filename>tree_intervals.cc</filename>
		</para></listitem></itemizedlist></section><section xml:id="pbds.using.examples.container.branch.trie"><info><title>trie</title></info><itemizedlist><listitem><para>
		  Using a PATRICIA trie for DNA strings:
		  <filename>trie_dna.cc</filename>
		</para></listitem><listitem><para>
		  Using a PATRICIA
		  trie for finding all entries whose key matches a given prefix:
		  <filename>trie_prefix_search.cc</filename>
		</para></listitem></itemizedlist></section></section><section xml:id="pbds.using.examples.container.priority_queue"><info><title>Priority Queues</title></info><itemizedlist><listitem><para>
		Cross referencing an associative container and a priority
		queue: <filename>priority_queue_xref.cc</filename>
	      </para></listitem><listitem><para>
		Cross referencing a vector and a priority queue using a
		very simple version of Dijkstra's shortest path
		algorithm:
		<filename>priority_queue_dijkstra.cc</filename>
	      </para></listitem></itemizedlist></section></section></section></section><!-- using --><!-- S03: Design --><section xml:id="containers.pbds.design"><info><title>Design</title></info><?dbhtml filename="policy_data_structures_design.html"?><para></para><section xml:id="pbds.design.concepts"><info><title>Concepts</title></info><section xml:id="pbds.design.concepts.null_type"><info><title>Null Policy Classes</title></info><para>
	Associative containers are typically parametrized by various
	policies. For example, a hash-based associative container is
	parametrized by a hash-functor, transforming each key into an
	non-negative numerical type. Each such value is then further mapped
	into a position within the table. The mapping of a key into a
	position within the table is therefore a two-step process.
      </para><para>
	In some cases, instantiations are redundant. For example, when the
	keys are integers, it is possible to use a redundant hash policy,
	which transforms each key into its value.
      </para><para>
	In some other cases, these policies are irrelevant.  For example, a
	hash-based associative container might transform keys into positions
	within a table by a different method than the two-step method
	described above. In such a case, the hash functor is simply
	irrelevant.
      </para><para>
	When a policy is either redundant or irrelevant, it can be replaced
	by <classname>null_type</classname>.
      </para><para>
	For example, a <emphasis>set</emphasis> is an associative
	container with one of its template parameters (the one for the
	mapped type) replaced with <classname>null_type</classname>. Other
	places simplifications are made possible with this technique
	include node updates in tree and trie data structures, and hash
	and probe functions for hash data structures.
      </para></section><section xml:id="pbds.design.concepts.associative_semantics"><info><title>Map and Set Semantics</title></info><section xml:id="concepts.associative_semantics.set_vs_map"><info><title>
	    Distinguishing Between Maps and Sets
	  </title></info><para>
	  Anyone familiar with the standard knows that there are four kinds
	  of associative containers: maps, sets, multimaps, and
	  multisets. The map datatype associates each key to
	  some data.
	</para><para>
	  Sets are associative containers that simply store keys -
	  they do not map them to anything. In the standard, each map class
	  has a corresponding set class. E.g.,
	  <classname>std::map&lt;int, char&gt;</classname> maps each
	  <classname>int</classname> to a <classname>char</classname>, but
	  <classname>std::set&lt;int, char&gt;</classname> simply stores
	  <classname>int</classname>s. In this library, however, there are no
	  distinct classes for maps and sets. Instead, an associative
	  container's <classname>Mapped</classname> template parameter is a policy: if
	  it is instantiated by <classname>null_type</classname>, then it
	  is a "set"; otherwise, it is a "map". E.g.,
	</para><programlisting>
	  cc_hash_table&lt;int, char&gt;
	</programlisting><para>
	  is a "map" mapping each <type>int</type> value to a <type>
	  char</type>, but
	</para><programlisting>
	  cc_hash_table&lt;int, null_type&gt;
	</programlisting><para>
	  is a type that uniquely stores <type>int</type> values.
	</para><para>Once the <classname>Mapped</classname> template parameter is instantiated
	by <classname>null_type</classname>, then
	the "set" acts very similarly to the standard's sets - it does not
	map each key to a distinct <classname>null_type</classname> object. Also,
	, the container's <type>value_type</type> is essentially
	its <type>key_type</type> - just as with the standard's sets
	.</para><para>
	  The standard's multimaps and multisets allow, respectively,
	  non-uniquely mapping keys and non-uniquely storing keys. As
	  discussed, the
	  reasons why this might be necessary are 1) that a key might be
	  decomposed into a primary key and a secondary key, 2) that a
	  key might appear more than once, or 3) any arbitrary
	  combination of 1)s and 2)s. Correspondingly,
	  one should use 1) "maps" mapping primary keys to secondary
	  keys, 2) "maps" mapping keys to size types, or 3) any arbitrary
	  combination of 1)s and 2)s. Thus, for example, an
	  <classname>std::multiset&lt;int&gt;</classname> might be used to store
	  multiple instances of integers, but using this library's
	  containers, one might use
	</para><programlisting>
	  tree&lt;int, size_t&gt;
	</programlisting><para>
	  i.e., a <classname>map</classname> of <type>int</type>s to
	  <type>size_t</type>s.
	</para><para>
	  These "multimaps" and "multisets" might be confusing to
	  anyone familiar with the standard's <classname>std::multimap</classname> and
	  <classname>std::multiset</classname>, because there is no clear
	  correspondence between the two. For example, in some cases
	  where one uses <classname>std::multiset</classname> in the standard, one might use
	  in this library a "multimap" of "multisets" - i.e., a
	  container that maps primary keys each to an associative
	  container that maps each secondary key to the number of times
	  it occurs.
	</para><para>
	  When one uses a "multimap," one should choose with care the
	  type of container used for secondary keys.
	</para></section><!-- map vs set --><section xml:id="concepts.associative_semantics.multi"><info><title>Alternatives to <classname>std::multiset</classname> and <classname>std::multimap</classname></title></info><para>
	  Brace onself: this library does not contain containers like
	  <classname>std::multimap</classname> or
	  <classname>std::multiset</classname>. Instead, these data
	  structures can be synthesized via manipulation of the
	  <classname>Mapped</classname> template parameter.
	</para><para>
	  One maps the unique part of a key - the primary key, into an
	  associative-container of the (originally) non-unique parts of
	  the key - the secondary key. A primary associative-container
	  is an associative container of primary keys; a secondary
	  associative-container is an associative container of
	  secondary keys.
	</para><para>
	  Stepping back a bit, and starting in from the beginning.
	</para><para>
	  Maps (or sets) allow mapping (or storing) unique-key values.
	  The standard library also supplies associative containers which
	  map (or store) multiple values with equivalent keys:
	  <classname>std::multimap</classname>, <classname>std::multiset</classname>,
	  <classname>std::tr1::unordered_multimap</classname>, and
	  <classname>unordered_multiset</classname>. We first discuss how these might
	  be used, then why we think it is best to avoid them.
	</para><para>
	  Suppose one builds a simple bank-account application that
	  records for each client (identified by an <classname>std::string</classname>)
	  and account-id (marked by an <type>unsigned long</type>) -
	  the balance in the account (described by a
	  <type>float</type>). Suppose further that ordering this
	  information is not useful, so a hash-based container is
	  preferable to a tree based container. Then one can use
	</para><programlisting>
	  std::tr1::unordered_map&lt;std::pair&lt;std::string, unsigned long&gt;, float, ...&gt;
	</programlisting><para>
	  which hashes every combination of client and account-id. This
	  might work well, except for the fact that it is now impossible
	  to efficiently list all of the accounts of a specific client
	  (this would practically require iterating over all
	  entries). Instead, one can use
	</para><programlisting>
	  std::tr1::unordered_multimap&lt;std::pair&lt;std::string, unsigned long&gt;, float, ...&gt;
	</programlisting><para>
	  which hashes every client, and decides equivalence based on
	  client only. This will ensure that all accounts belonging to a
	  specific user are stored consecutively.
	</para><para>
	  Also, suppose one wants an integers' priority queue
	  (a container that supports <function>push</function>,
	  <function>pop</function>, and <function>top</function> operations, the last of which
	  returns the largest <type>int</type>) that also supports
	  operations such as <function>find</function> and <function>lower_bound</function>. A
	  reasonable solution is to build an adapter over
	  <classname>std::set&lt;int&gt;</classname>. In this adapter,
	  <function>push</function> will just call the tree-based
	  associative container's <function>insert</function> method; <function>pop</function>
	  will call its <function>end</function> method, and use it to return the
	  preceding element (which must be the largest). Then this might
	  work well, except that the container object cannot hold
	  multiple instances of the same integer (<function>push(4)</function>,
	  will be a no-op if <constant>4</constant> is already in the
	  container object). If multiple keys are necessary, then one
	  might build the adapter over an
	  <classname>std::multiset&lt;int&gt;</classname>.
	</para><para>
	  The standard library's non-unique-mapping containers are useful
	  when (1) a key can be decomposed in to a primary key and a
	  secondary key, (2) a key is needed multiple times, or (3) any
	  combination of (1) and (2).
	</para><para>
	  The graphic below shows how the standard library's container
	  design works internally; in this figure nodes shaded equally
	  represent equivalent-key values. Equivalent keys are stored
	  consecutively using the properties of the underlying data
	  structure: binary search trees (label A) store equivalent-key
	  values consecutively (in the sense of an in-order walk)
	  naturally; collision-chaining hash tables (label B) store
	  equivalent-key values in the same bucket, the bucket can be
	  arranged so that equivalent-key values are consecutive.
	</para><figure><title>Non-unique Mapping Standard Containers</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_embedded_lists_1.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Non-unique Mapping Standard Containers</phrase></textobject></mediaobject></figure><para>
	  Put differently, the standards' non-unique mapping
	  associative-containers are associative containers that map
	  primary keys to linked lists that are embedded into the
	  container. The graphic below shows again the two
	  containers from the first graphic above, this time with
	  the embedded linked lists of the grayed nodes marked
	  explicitly.
	</para><figure xml:id="fig.pbds_embedded_lists_2"><title>
	    Effect of embedded lists in
	    <classname>std::multimap</classname>
	  </title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_embedded_lists_2.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>
		Effect of embedded lists in
		<classname>std::multimap</classname>
	      </phrase></textobject></mediaobject></figure><para>
	  These embedded linked lists have several disadvantages.
	</para><orderedlist><listitem><para>
	      The underlying data structure embeds the linked lists
	      according to its own consideration, which means that the
	      search path for a value might include several different
	      equivalent-key values. For example, the search path for the
	      the black node in either of the first graphic, labels A or B,
	      includes more than a single gray node.
	    </para></listitem><listitem><para>
	      The links of the linked lists are the underlying data
	      structures' nodes, which typically are quite structured.  In
	      the case of tree-based containers (the grapic above, label
	      B), each "link" is actually a node with three pointers (one
	      to a parent and two to children), and a
	      relatively-complicated iteration algorithm. The linked
	      lists, therefore, can take up quite a lot of memory, and
	      iterating over all values equal to a given key (through the
	      return value of the standard
	      library's <function>equal_range</function>) can be
	      expensive.
	    </para></listitem><listitem><para>
	      The primary key is stored multiply; this uses more memory.
	    </para></listitem><listitem><para>
	      Finally, the interface of this design excludes several
	      useful underlying data structures. Of all the unordered
	      self-organizing data structures, practically only
	      collision-chaining hash tables can (efficiently) guarantee
	      that equivalent-key values are stored consecutively.
	    </para></listitem></orderedlist><para>
	  The above reasons hold even when the ratio of secondary keys to
	  primary keys (or average number of identical keys) is small, but
	  when it is large, there are more severe problems:
	</para><orderedlist><listitem><para>
	      The underlying data structures order the links inside each
	      embedded linked-lists according to their internal
	      considerations, which effectively means that each of the
	      links is unordered. Irrespective of the underlying data
	      structure, searching for a specific value can degrade to
	      linear complexity.
	    </para></listitem><listitem><para>
	      Similarly to the above point, it is impossible to apply
	      to the secondary keys considerations that apply to primary
	      keys. For example, it is not possible to maintain secondary
	      keys by sorted order.
	    </para></listitem><listitem><para>
	      While the interface "understands" that all equivalent-key
	      values constitute a distinct list (through
	      <function>equal_range</function>), the underlying data
	      structure typically does not. This means that operations such
	      as erasing from a tree-based container all values whose keys
	      are equivalent to a a given key can be super-linear in the
	      size of the tree; this is also true also for several other
	      operations that target a specific list.
	    </para></listitem></orderedlist><para>
	  In this library, all associative containers map
	  (or store) unique-key values. One can (1) map primary keys to
	  secondary associative-containers (containers of
	  secondary keys) or non-associative containers (2) map identical
	  keys to a size-type representing the number of times they
	  occur, or (3) any combination of (1) and (2). Instead of
	  allowing multiple equivalent-key values, this library
	  supplies associative containers based on underlying
	  data structures that are suitable as secondary
	  associative-containers.
	</para><para>
	  In the figure below, labels A and B show the equivalent
	  underlying data structures in this library, as mapped to the
	  first graphic above. Labels A and B, respectively. Each shaded
	  box represents some size-type or secondary
	  associative-container.
	</para><figure><title>Non-unique Mapping Containers</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_embedded_lists_3.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Non-unique Mapping Containers</phrase></textobject></mediaobject></figure><para>
	  In the first example above, then, one would use an associative
	  container mapping each user to an associative container which
	  maps each application id to a start time (see
	  <filename>example/basic_multimap.cc</filename>); in the second
	  example, one would use an associative container mapping
	  each <classname>int</classname> to some size-type indicating the
	  number of times it logically occurs
	  (see <filename>example/basic_multiset.cc</filename>.
	</para><para>
	  See the discussion in list-based container types for containers
	  especially suited as secondary associative-containers.
	</para></section></section><!-- map and set semantics --><section xml:id="pbds.design.concepts.iterator_semantics"><info><title>Iterator Semantics</title></info><section xml:id="concepts.iterator_semantics.point_and_range"><info><title>Point and Range Iterators</title></info><para>
	  Iterator concepts are bifurcated in this design, and are
	  comprised of point-type and range-type iteration.
	</para><para>
	  A point-type iterator is an iterator that refers to a specific
	  element as returned through an
	  associative-container's <function>find</function> method.
	</para><para>
	  A range-type iterator is an iterator that is used to go over a
	  sequence of elements, as returned by a container's
	  <function>find</function> method.
	</para><para>
	  A point-type method is a method that
	  returns a point-type iterator; a range-type method is a method
	  that returns a range-type iterator.
	</para><para>For most containers, these types are synonymous; for
	self-organizing containers, such as hash-based containers or
	priority queues, these are inherently different (in any
	implementation, including that of C++ standard library
	components), but in this design, it is made explicit. They are
	distinct types.
	</para></section><section xml:id="concepts.iterator_semantics.both"><info><title>Distinguishing Point and Range Iterators</title></info><para>When using this library, is necessary to differentiate
	between two types of methods and iterators: point-type methods and
	iterators, and range-type methods and iterators. Each associative
	container's interface includes the methods:</para><programlisting>
	  point_const_iterator
	  find(const_key_reference r_key) const;

	  point_iterator
	  find(const_key_reference r_key);

	  std::pair&lt;point_iterator,bool&gt;
	  insert(const_reference r_val);
	</programlisting><para>The relationship between these iterator types varies between
	container types. The figure below
	shows the most general invariant between point-type and
	range-type iterators: In <emphasis>A</emphasis> <literal>iterator</literal>, can
	always be converted to <literal>point_iterator</literal>. In <emphasis>B</emphasis>
	shows invariants for order-preserving containers: point-type
	iterators are synonymous with range-type iterators.
	Orthogonally,  <emphasis>C</emphasis>shows invariants for "set"
	containers: iterators are synonymous with const iterators.</para><figure><title>Point Iterator Hierarchy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_point_iterator_hierarchy.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Point Iterator Hierarchy</phrase></textobject></mediaobject></figure><para>Note that point-type iterators in self-organizing containers
	(hash-based associative containers) lack movement
	operators, such as <literal>operator++</literal> - in fact, this
	is the reason why this library differentiates from the standard C++ librarys
	design on this point.</para><para>Typically, one can determine an iterator's movement
	capabilities using
	<literal>std::iterator_traits&lt;It&gt;iterator_category</literal>,
	which is a <literal>struct</literal> indicating the iterator's
	movement capabilities. Unfortunately, none of the standard predefined
	categories reflect a pointer's <emphasis>not</emphasis> having any
	movement capabilities whatsoever. Consequently,
	<literal>pb_ds</literal> adds a type
	<literal>trivial_iterator_tag</literal> (whose name is taken from
	a concept in C++ standardese, which is the category of iterators
	with no movement capabilities.) All other standard C++ library
	tags, such as <literal>forward_iterator_tag</literal> retain their
	common use.</para></section><section xml:id="pbds.design.concepts.invalidation"><info><title>Invalidation Guarantees</title></info><para>
	  If one manipulates a container object, then iterators previously
	  obtained from it can be invalidated. In some cases a
	  previously-obtained iterator cannot be de-referenced; in other cases,
	  the iterator's next or previous element might have changed
	  unpredictably. This corresponds exactly to the question whether a
	  point-type or range-type iterator (see previous concept) is valid or
	  not. In this design, one can query a container (in compile time) about
	  its invalidation guarantees.
	</para><para>
	  Given three different types of associative containers, a modifying
	  operation (in that example, <function>erase</function>) invalidated
	  iterators in three different ways: the iterator of one container
	  remained completely valid - it could be de-referenced and
	  incremented; the iterator of a different container could not even be
	  de-referenced; the iterator of the third container could be
	  de-referenced, but its "next" iterator changed unpredictably.
	</para><para>
	  Distinguishing between find and range types allows fine-grained
	  invalidation guarantees, because these questions correspond exactly
	  to the question of whether point-type iterators and range-type
	  iterators are valid. The graphic below shows tags corresponding to
	  different types of invalidation guarantees.
	</para><figure><title>Invalidation Guarantee Tags Hierarchy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_invalidation_tag_hierarchy.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_invalidation_tag_hierarchy.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Invalidation Guarantee Tags Hierarchy</phrase></textobject></mediaobject></figure><itemizedlist><listitem><para><classname>basic_invalidation_guarantee</classname>
	      corresponds to a basic guarantee that a point-type iterator,
	      a found pointer, or a found reference, remains valid as long
	      as the container object is not modified.
	    </para></listitem><listitem><para><classname>point_invalidation_guarantee</classname>
	      corresponds to a guarantee that a point-type iterator, a
	      found pointer, or a found reference, remains valid even if
	      the container object is modified.
	    </para></listitem><listitem><para><classname>range_invalidation_guarantee</classname>
	      corresponds to a guarantee that a range-type iterator remains
	      valid even if the container object is modified.
	    </para></listitem></itemizedlist><para>To find the invalidation guarantee of a
	container, one can use</para><programlisting>
	  typename container_traits&lt;Cntnr&gt;::invalidation_guarantee
	</programlisting><para>Note that this hierarchy corresponds to the logic it
	represents: if a container has range-invalidation guarantees,
	then it must also have find invalidation guarantees;
	correspondingly, its invalidation guarantee (in this case
	<classname>range_invalidation_guarantee</classname>)
	can be cast to its base class (in this case <classname>point_invalidation_guarantee</classname>).
	This means that this this hierarchy can be used easily using
	standard metaprogramming techniques, by specializing on the
	type of <literal>invalidation_guarantee</literal>.</para><para>
	  These types of problems were addressed, in a more general
	  setting, in <xref linkend="biblio.meyers96more"></xref> - Item 2. In
	  our opinion, an invalidation-guarantee hierarchy would solve
	  these problems in all container types - not just associative
	  containers.
	</para></section></section><!-- iterator semantics --><section xml:id="pbds.design.concepts.genericity"><info><title>Genericity</title></info><para>
	The design attempts to address the following problem of
	data-structure genericity. When writing a function manipulating
	a generic container object, what is the behavior of the object?
	Suppose one writes
      </para><programlisting>
	template&lt;typename Cntnr&gt;
	void
	some_op_sequence(Cntnr &amp;r_container)
	{
	...
	}
</programlisting><para>
	then one needs to address the following questions in the body
	of <function>some_op_sequence</function>:
      </para><itemizedlist><listitem><para>
	    Which types and methods does <literal>Cntnr</literal> support?
	    Containers based on hash tables can be queries for the
	    hash-functor type and object; this is meaningless for tree-based
	    containers. Containers based on trees can be split, joined, or
	    can erase iterators and return the following iterator; this
	    cannot be done by hash-based containers.
	  </para></listitem><listitem><para>
	    What are the exception and invalidation guarantees
	    of <literal>Cntnr</literal>? A container based on a probing
	    hash-table invalidates all iterators when it is modified; this
	    is not the case for containers based on node-based
	    trees. Containers based on a node-based tree can be split or
	    joined without exceptions; this is not the case for containers
	    based on vector-based trees.
	  </para></listitem><listitem><para>
	    How does the container maintain its elements? Tree-based and
	    Trie-based containers store elements by key order; others,
	    typically, do not. A container based on a splay trees or lists
	    with update policies "cache" "frequently accessed" elements;
	    containers based on most other underlying data structures do
	    not.
	  </para></listitem><listitem><para>
	    How does one query a container about characteristics and
	    capabilities? What is the relationship between two different
	    data structures, if anything?
	  </para></listitem></itemizedlist><para>The remainder of this section explains these issues in
      detail.</para><section xml:id="concepts.genericity.tag"><info><title>Tag</title></info><para>
	  Tags are very useful for manipulating generic types. For example, if
	  <literal>It</literal> is an iterator class, then <literal>typename
	  It::iterator_category</literal> or <literal>typename
	  std::iterator_traits&lt;It&gt;::iterator_category</literal> will
	  yield its category, and <literal>typename
	  std::iterator_traits&lt;It&gt;::value_type</literal> will yield its
	  value type.
	</para><para>
	  This library contains a container tag hierarchy corresponding to the
	  diagram below.
	</para><figure><title>Container Tag Hierarchy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_container_tag_hierarchy.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_container_tag_hierarchy.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Container Tag Hierarchy</phrase></textobject></mediaobject></figure><para>
	  Given any container <type>Cntnr</type>, the tag of
	  the underlying data structure can be found via <literal>typename
	  Cntnr::container_category</literal>.
	</para></section><!-- tag --><section xml:id="concepts.genericity.traits"><info><title>Traits</title></info><para></para><para>Additionally, a traits mechanism can be used to query a
	container type for its attributes. Given any container
	<literal>Cntnr</literal>, then <literal>&lt;Cntnr&gt;</literal>
	is a traits class identifying the properties of the
	container.</para><para>To find if a container can throw when a key is erased (which
	is true for vector-based trees, for example), one can
	use
	</para><programlisting>container_traits&lt;Cntnr&gt;::erase_can_throw</programlisting><para>
	  Some of the definitions in <classname>container_traits</classname>
	  are dependent on other
	  definitions. If <classname>container_traits&lt;Cntnr&gt;::order_preserving</classname>
	  is <constant>true</constant> (which is the case for containers
	  based on trees and tries), then the container can be split or
	  joined; in this
	  case, <classname>container_traits&lt;Cntnr&gt;::split_join_can_throw</classname>
	  indicates whether splits or joins can throw exceptions (which is
	  true for vector-based trees);
	  otherwise <classname>container_traits&lt;Cntnr&gt;::split_join_can_throw</classname>
	  will yield a compilation error. (This is somewhat similar to a
	  compile-time version of the COM model).
	</para></section><!-- traits --></section><!-- genericity --></section><!-- concepts --><section xml:id="pbds.design.container"><info><title>By Container</title></info><!-- hash --><section xml:id="pbds.design.container.hash"><info><title>hash</title></info><!--

// hash policies
/// general terms / background
/// range hashing policies
/// ranged-hash policies
/// implementation

// resize policies
/// general
/// size policies
/// trigger policies
/// implementation

// policy interactions
/// probe/size/trigger
/// hash/trigger
/// eq/hash/storing hash values
/// size/load-check trigger
      --><section xml:id="container.hash.interface"><info><title>Interface</title></info><para>
	  The collision-chaining hash-based container has the
	following declaration.</para><programlisting>
	  template&lt;
	  typename Key,
	  typename Mapped,
	  typename Hash_Fn = std::hash&lt;Key&gt;,
	  typename Eq_Fn = std::equal_to&lt;Key&gt;,
	  typename Comb_Hash_Fn =  direct_mask_range_hashing&lt;&gt;
	  typename Resize_Policy = default explained below.
	  bool Store_Hash = false,
	  typename Allocator = std::allocator&lt;char&gt; &gt;
	  class cc_hash_table;
	</programlisting><para>The parameters have the following meaning:</para><orderedlist><listitem><para><classname>Key</classname> is the key type.</para></listitem><listitem><para><classname>Mapped</classname> is the mapped-policy.</para></listitem><listitem><para><classname>Hash_Fn</classname> is a key hashing functor.</para></listitem><listitem><para><classname>Eq_Fn</classname> is a key equivalence functor.</para></listitem><listitem><para><classname>Comb_Hash_Fn</classname> is a range-hashing_functor;
	  it describes how to translate hash values into positions
	  within the table. </para></listitem><listitem><para><classname>Resize_Policy</classname> describes how a container object
	  should change its internal size. </para></listitem><listitem><para><classname>Store_Hash</classname> indicates whether the hash value
	  should be stored with each entry. </para></listitem><listitem><para><classname>Allocator</classname> is an allocator
	  type.</para></listitem></orderedlist><para>The probing hash-based container has the following
	declaration.</para><programlisting>
	  template&lt;
	  typename Key,
	  typename Mapped,
	  typename Hash_Fn = std::hash&lt;Key&gt;,
	  typename Eq_Fn = std::equal_to&lt;Key&gt;,
	  typename Comb_Probe_Fn = direct_mask_range_hashing&lt;&gt;
	  typename Probe_Fn = default explained below.
	  typename Resize_Policy = default explained below.
	  bool Store_Hash = false,
	  typename Allocator =  std::allocator&lt;char&gt; &gt;
	  class gp_hash_table;
	</programlisting><para>The parameters are identical to those of the
	collision-chaining container, except for the following.</para><orderedlist><listitem><para><classname>Comb_Probe_Fn</classname> describes how to transform a probe
	  sequence into a sequence of positions within the table.</para></listitem><listitem><para><classname>Probe_Fn</classname> describes a probe sequence policy.</para></listitem></orderedlist><para>Some of the default template values depend on the values of
	other parameters, and are explained below.</para></section><section xml:id="container.hash.details"><info><title>Details</title></info><section xml:id="container.hash.details.hash_policies"><info><title>Hash Policies</title></info><section xml:id="details.hash_policies.general"><info><title>General</title></info><para>Following is an explanation of some functions which hashing
	    involves. The graphic below illustrates the discussion.</para><figure><title>Hash functions, ranged-hash functions, and
	      range-hashing functions</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_ranged_hash_range_hashing_fns.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Hash functions, ranged-hash functions, and
		  range-hashing functions</phrase></textobject></mediaobject></figure><para>Let U be a domain (e.g., the integers, or the
	    strings of 3 characters). A hash-table algorithm needs to map
	    elements of U "uniformly" into the range [0,..., m -
	    1] (where m is a non-negative integral value, and
	    is, in general, time varying). I.e., the algorithm needs
	    a ranged-hash function</para><para>
	      f : U × Z<subscript>+</subscript> → Z<subscript>+</subscript>
	    </para><para>such that for any u in U ,</para><para>0 ≤ f(u, m) ≤ m - 1</para><para>and which has "good uniformity" properties (say
	    <xref linkend="biblio.knuth98sorting"></xref>.)
	    One
	    common solution is to use the composition of the hash
	    function</para><para>h : U → Z<subscript>+</subscript> ,</para><para>which maps elements of U into the non-negative
	    integrals, and</para><para>g : Z<subscript>+</subscript> × Z<subscript>+</subscript> →
	    Z<subscript>+</subscript>,</para><para>which maps a non-negative hash value, and a non-negative
	    range upper-bound into a non-negative integral in the range
	    between 0 (inclusive) and the range upper bound (exclusive),
	    i.e., for any r in Z<subscript>+</subscript>,</para><para>0 ≤ g(r, m) ≤ m - 1</para><para>The resulting ranged-hash function, is</para><!-- ranged_hash_composed_of_hash_and_range_hashing --><equation><title>Ranged Hash Function</title><mathphrase>
		f(u , m) = g(h(u), m)
	      </mathphrase></equation><para>From the above, it is obvious that given g and
	    h, f can always be composed (however the converse
	    is not true). The standard's hash-based containers allow specifying
	    a hash function, and use a hard-wired range-hashing function;
	    the ranged-hash function is implicitly composed.</para><para>The above describes the case where a key is to be mapped
	    into a single position within a hash table, e.g.,
	    in a collision-chaining table. In other cases, a key is to be
	    mapped into a sequence of positions within a table,
	    e.g., in a probing table. Similar terms apply in this
	    case: the table requires a ranged probe function,
	    mapping a key into a sequence of positions withing the table.
	    This is typically achieved by composing a hash function
	    mapping the key into a non-negative integral type, a
	    probe function transforming the hash value into a
	    sequence of hash values, and a range-hashing function
	    transforming the sequence of hash values into a sequence of
	    positions.</para></section><section xml:id="details.hash_policies.range"><info><title>Range Hashing</title></info><para>Some common choices for range-hashing functions are the
	    division, multiplication, and middle-square methods (<xref linkend="biblio.knuth98sorting"></xref>), defined
	    as</para><equation><title>Range-Hashing, Division Method</title><mathphrase>
		g(r, m) = r mod m
	      </mathphrase></equation><para>g(r, m) = ⌈ u/v ( a r mod v ) ⌉</para><para>and</para><para>g(r, m) = ⌈ u/v ( r<superscript>2</superscript> mod v ) ⌉</para><para>respectively, for some positive integrals u and
	    v (typically powers of 2), and some a. Each of
	    these range-hashing functions works best for some different
	    setting.</para><para>The division method (see above) is a
	    very common choice. However, even this single method can be
	    implemented in two very different ways. It is possible to
	    implement using the low
	    level % (modulo) operation (for any m), or the
	    low level &amp; (bit-mask) operation (for the case where
	    m is a power of 2), i.e.,</para><equation><title>Division via Prime Modulo</title><mathphrase>
		g(r, m) = r % m
	      </mathphrase></equation><para>and</para><equation><title>Division via Bit Mask</title><mathphrase>
		g(r, m) = r &amp; m - 1, (with m =
		2<superscript>k</superscript> for some k)
	      </mathphrase></equation><para>respectively.</para><para>The % (modulo) implementation has the advantage that for
	    m a prime far from a power of 2, g(r, m) is
	    affected by all the bits of r (minimizing the chance of
	    collision). It has the disadvantage of using the costly modulo
	    operation. This method is hard-wired into SGI's implementation
	    .</para><para>The &amp; (bit-mask) implementation has the advantage of
	    relying on the fast bit-wise and operation. It has the
	    disadvantage that for g(r, m) is affected only by the
	    low order bits of r. This method is hard-wired into
	    Dinkumware's implementation.</para></section><section xml:id="details.hash_policies.ranged"><info><title>Ranged Hash</title></info><para>In cases it is beneficial to allow the
	    client to directly specify a ranged-hash hash function. It is
	    true, that the writer of the ranged-hash function cannot rely
	    on the values of m having specific numerical properties
	    suitable for hashing (in the sense used in <xref linkend="biblio.knuth98sorting"></xref>), since
	    the values of m are determined by a resize policy with
	    possibly orthogonal considerations.</para><para>There are two cases where a ranged-hash function can be
	    superior. The firs is when using perfect hashing: the
	    second is when the values of m can be used to estimate
	    the "general" number of distinct values required. This is
	    described in the following.</para><para>Let</para><para>
	      s = [ s<subscript>0</subscript>,..., s<subscript>t - 1</subscript>]
	    </para><para>be a string of t characters, each of which is from
	    domain S. Consider the following ranged-hash
	    function:</para><equation><title>
		A Standard String Hash Function
	      </title><mathphrase>
		f<subscript>1</subscript>(s, m) = ∑ <subscript>i =
		0</subscript><superscript>t - 1</superscript> s<subscript>i</subscript> a<superscript>i</superscript> mod m
	      </mathphrase></equation><para>where a is some non-negative integral value. This is
	    the standard string-hashing function used in SGI's
	    implementation (with a = 5). Its advantage is that
	    it takes into account all of the characters of the string.</para><para>Now assume that s is the string representation of a
	    of a long DNA sequence (and so S = {'A', 'C', 'G',
	    'T'}). In this case, scanning the entire string might be
	    prohibitively expensive. A possible alternative might be to use
	    only the first k characters of the string, where</para><para>|S|<superscript>k</superscript> ≥ m ,</para><para>i.e., using the hash function</para><equation><title>
		Only k String DNA Hash
	      </title><mathphrase>
		f<subscript>2</subscript>(s, m) = ∑ <subscript>i
		= 0</subscript><superscript>k - 1</superscript> s<subscript>i</subscript> a<superscript>i</superscript> mod m
	      </mathphrase></equation><para>requiring scanning over only</para><para>k = log<subscript>4</subscript>( m )</para><para>characters.</para><para>Other more elaborate hash-functions might scan k
	    characters starting at a random position (determined at each
	    resize), or scanning k random positions (determined at
	    each resize), i.e., using</para><para>f<subscript>3</subscript>(s, m) = ∑ <subscript>i =
	    r</subscript>0<superscript>r<subscript>0</subscript> + k - 1</superscript> s<subscript>i</subscript>
	    a<superscript>i</superscript> mod m ,</para><para>or</para><para>f<subscript>4</subscript>(s, m) = ∑ <subscript>i = 0</subscript><superscript>k -
	    1</superscript> s<subscript>r</subscript>i a<superscript>r<subscript>i</subscript></superscript> mod
	    m ,</para><para>respectively, for r<subscript>0</subscript>,..., r<subscript>k-1</subscript>
	    each in the (inclusive) range [0,...,t-1].</para><para>It should be noted that the above functions cannot be
	    decomposed as per a ranged hash composed of hash and range hashing.</para></section><section xml:id="details.hash_policies.implementation"><info><title>Implementation</title></info><para>This sub-subsection describes the implementation of
	    the above in this library. It first explains range-hashing
	    functions in collision-chaining tables, then ranged-hash
	    functions in collision-chaining tables, then probing-based
	    tables, and finally lists the relevant classes in this
	    library.</para><section xml:id="hash_policies.implementation.collision-chaining"><info><title>
		Range-Hashing and Ranged-Hashes in Collision-Chaining Tables
	      </title></info><para><classname>cc_hash_table</classname> is
	      parametrized by <classname>Hash_Fn</classname> and <classname>Comb_Hash_Fn</classname>, a
	      hash functor and a combining hash functor, respectively.</para><para>In general, <classname>Comb_Hash_Fn</classname> is considered a
	      range-hashing functor. <classname>cc_hash_table</classname>
	      synthesizes a ranged-hash function from <classname>Hash_Fn</classname> and
	      <classname>Comb_Hash_Fn</classname>. The figure below shows an <classname>insert</classname> sequence
	      diagram for this case. The user inserts an element (point A),
	      the container transforms the key into a non-negative integral
	      using the hash functor (points B and C), and transforms the
	      result into a position using the combining functor (points D
	      and E).</para><figure><title>Insert hash sequence diagram</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_range_hashing_seq_diagram.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Insert hash sequence diagram</phrase></textobject></mediaobject></figure><para>If <classname>cc_hash_table</classname>'s
	      hash-functor, <classname>Hash_Fn</classname> is instantiated by <classname>null_type</classname> , then <classname>Comb_Hash_Fn</classname> is taken to be
	      a ranged-hash function. The graphic below shows an <function>insert</function> sequence
	      diagram. The user inserts an element (point A), the container
	      transforms the key into a position using the combining functor
	      (points B and C).</para><figure><title>Insert hash sequence diagram with a null policy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_range_hashing_seq_diagram2.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Insert hash sequence diagram with a null policy</phrase></textobject></mediaobject></figure></section><section xml:id="hash_policies.implementation.probe"><info><title>
		Probing tables
	      </title></info><para><classname>gp_hash_table</classname> is parametrized by
	      <classname>Hash_Fn</classname>, <classname>Probe_Fn</classname>,
	      and <classname>Comb_Probe_Fn</classname>. As before, if
	      <classname>Hash_Fn</classname> and <classname>Probe_Fn</classname>
	      are both <classname>null_type</classname>, then
	      <classname>Comb_Probe_Fn</classname> is a ranged-probe
	      functor. Otherwise, <classname>Hash_Fn</classname> is a hash
	      functor, <classname>Probe_Fn</classname> is a functor for offsets
	      from a hash value, and <classname>Comb_Probe_Fn</classname>
	      transforms a probe sequence into a sequence of positions within
	      the table.</para></section><section xml:id="hash_policies.implementation.predefined"><info><title>
		Pre-Defined Policies
	      </title></info><para>This library contains some pre-defined classes
	      implementing range-hashing and probing functions:</para><orderedlist><listitem><para><classname>direct_mask_range_hashing</classname>
		and <classname>direct_mod_range_hashing</classname>
		are range-hashing functions based on a bit-mask and a modulo
		operation, respectively.</para></listitem><listitem><para><classname>linear_probe_fn</classname>, and
		<classname>quadratic_probe_fn</classname> are
		a linear probe and a quadratic probe function,
		respectively.</para></listitem></orderedlist><para>
		The graphic below shows the relationships.
	      </para><figure><title>Hash policy class diagram</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_policy_cd.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Hash policy class diagram</phrase></textobject></mediaobject></figure></section></section><!-- impl --></section><section xml:id="container.hash.details.resize_policies"><info><title>Resize Policies</title></info><section xml:id="resize_policies.general"><info><title>General</title></info><para>Hash-tables, as opposed to trees, do not naturally grow or
	    shrink. It is necessary to specify policies to determine how
	    and when a hash table should change its size. Usually, resize
	    policies can be decomposed into orthogonal policies:</para><orderedlist><listitem><para>A size policy indicating how a hash table
	      should grow (e.g., it should multiply by powers of
	      2).</para></listitem><listitem><para>A trigger policy indicating when a hash
	      table should grow (e.g., a load factor is
	      exceeded).</para></listitem></orderedlist></section><section xml:id="resize_policies.size"><info><title>Size Policies</title></info><para>Size policies determine how a hash table changes size. These
	    policies are simple, and there are relatively few sensible
	    options. An exponential-size policy (with the initial size and
	    growth factors both powers of 2) works well with a mask-based
	    range-hashing function, and is the
	    hard-wired policy used by Dinkumware. A
	    prime-list based policy works well with a modulo-prime range
	    hashing function and is the hard-wired policy used by SGI's
	    implementation.</para></section><section xml:id="resize_policies.trigger"><info><title>Trigger Policies</title></info><para>Trigger policies determine when a hash table changes size.
	    Following is a description of two policies: load-check
	    policies, and collision-check policies.</para><para>Load-check policies are straightforward. The user specifies
	    two factors, Α<subscript>min</subscript> and
	    Α<subscript>max</subscript>, and the hash table maintains the
	    invariant that</para><para>Α<subscript>min</subscript> ≤ (number of
	    stored elements) / (hash-table size) ≤
	    Α<subscript>max</subscript>
            <!-- <remark>load factor min max</remark> -->
            </para><para>Collision-check policies work in the opposite direction of
	    load-check policies. They focus on keeping the number of
	    collisions moderate and hoping that the size of the table will
	    not grow very large, instead of keeping a moderate load-factor
	    and hoping that the number of collisions will be small. A
	    maximal collision-check policy resizes when the longest
	    probe-sequence grows too large.</para><para>Consider the graphic below. Let the size of the hash table
	    be denoted by m, the length of a probe sequence be denoted by k,
	    and some load factor be denoted by Α. We would like to
	    calculate the minimal length of k, such that if there were Α
	    m elements in the hash table, a probe sequence of length k would
	    be found with probability at most 1/m.</para><figure><title>Balls and bins</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_balls_and_bins.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Balls and bins</phrase></textobject></mediaobject></figure><para>Denote the probability that a probe sequence of length
	    k appears in bin i by p<subscript>i</subscript>, the
	    length of the probe sequence of bin i by
	    l<subscript>i</subscript>, and assume uniform distribution. Then</para><equation><title>
		Probability of Probe Sequence of Length k
	      </title><mathphrase>
		p<subscript>1</subscript> =
	      </mathphrase></equation><para>P(l<subscript>1</subscript> ≥ k) =</para><para>
	      P(l<subscript>1</subscript> ≥ α ( 1 + k / α - 1) ≤ (a)
	    </para><para>
	      e ^ ( - ( α ( k / α - 1 )<superscript>2</superscript> ) /2)
	    </para><para>where (a) follows from the Chernoff bound (<xref linkend="biblio.motwani95random"></xref>). To
	    calculate the probability that some bin contains a probe
	    sequence greater than k, we note that the
	    l<subscript>i</subscript> are negatively-dependent
	    (<xref linkend="biblio.dubhashi98neg"></xref>)
	    . Let
	    I(.) denote the indicator function. Then</para><equation><title>
		Probability Probe Sequence in Some Bin
	      </title><mathphrase>
		P( exists<subscript>i</subscript> l<subscript>i</subscript> ≥ k ) =
	      </mathphrase></equation><para>P ( ∑ <subscript>i = 1</subscript><superscript>m</superscript>
	    I(l<subscript>i</subscript> ≥ k) ≥ 1 ) =</para><para>P ( ∑ <subscript>i = 1</subscript><superscript>m</superscript> I (
	    l<subscript>i</subscript> ≥ k ) ≥ m p<subscript>1</subscript> ( 1 + 1 / (m
	    p<subscript>1</subscript>) - 1 ) ) ≤ (a)</para><para>e ^ ( ( - m p<subscript>1</subscript> ( 1 / (m p<subscript>1</subscript>)
	    - 1 ) <superscript>2</superscript> ) / 2 ) ,</para><para>where (a) follows from the fact that the Chernoff bound can
	    be applied to negatively-dependent variables (<xref linkend="biblio.dubhashi98neg"></xref>). Inserting the first probability
	    equation into the second one, and equating with 1/m, we
	    obtain</para><para>k ~ √ ( 2 α ln 2 m ln(m) )
	    ) .</para></section><section xml:id="resize_policies.impl"><info><title>Implementation</title></info><para>This sub-subsection describes the implementation of the
	    above in this library. It first describes resize policies and
	    their decomposition into trigger and size policies, then
	    describes pre-defined classes, and finally discusses controlled
	    access the policies' internals.</para><section xml:id="resize_policies.impl.decomposition"><info><title>Decomposition</title></info><para>Each hash-based container is parametrized by a
	      <classname>Resize_Policy</classname> parameter; the container derives
	      <classname>public</classname>ly from <classname>Resize_Policy</classname>. For
	      example:</para><programlisting>
		cc_hash_table&lt;typename Key,
		typename Mapped,
		...
		typename Resize_Policy
		...&gt; : public Resize_Policy
	      </programlisting><para>As a container object is modified, it continuously notifies
	      its <classname>Resize_Policy</classname> base of internal changes
	      (e.g., collisions encountered and elements being
	      inserted). It queries its <classname>Resize_Policy</classname> base whether
	      it needs to be resized, and if so, to what size.</para><para>The graphic below shows a (possible) sequence diagram
	      of an insert operation. The user inserts an element; the hash
	      table notifies its resize policy that a search has started
	      (point A); in this case, a single collision is encountered -
	      the table notifies its resize policy of this (point B); the
	      container finally notifies its resize policy that the search
	      has ended (point C); it then queries its resize policy whether
	      a resize is needed, and if so, what is the new size (points D
	      to G); following the resize, it notifies the policy that a
	      resize has completed (point H); finally, the element is
	      inserted, and the policy notified (point I).</para><figure><title>Insert resize sequence diagram</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_insert_resize_sequence_diagram1.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Insert resize sequence diagram</phrase></textobject></mediaobject></figure><para>In practice, a resize policy can be usually orthogonally
	      decomposed to a size policy and a trigger policy. Consequently,
	      the library contains a single class for instantiating a resize
	      policy: <classname>hash_standard_resize_policy</classname>
	      is parametrized by <classname>Size_Policy</classname> and
	      <classname>Trigger_Policy</classname>, derives <classname>public</classname>ly from
	      both, and acts as a standard delegate (<xref linkend="biblio.gof"></xref>)
	      to these policies.</para><para>The two graphics immediately below show sequence diagrams
	      illustrating the interaction between the standard resize policy
	      and its trigger and size policies, respectively.</para><figure><title>Standard resize policy trigger sequence
		diagram</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_insert_resize_sequence_diagram2.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Standard resize policy trigger sequence
		    diagram</phrase></textobject></mediaobject></figure><figure><title>Standard resize policy size sequence
		diagram</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_insert_resize_sequence_diagram3.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Standard resize policy size sequence
		    diagram</phrase></textobject></mediaobject></figure></section><section xml:id="resize_policies.impl.predefined"><info><title>Predefined Policies</title></info><para>The library includes the following
	      instantiations of size and trigger policies:</para><orderedlist><listitem><para><classname>hash_load_check_resize_trigger</classname>
		implements a load check trigger policy.</para></listitem><listitem><para><classname>cc_hash_max_collision_check_resize_trigger</classname>
		implements a collision check trigger policy.</para></listitem><listitem><para><classname>hash_exponential_size_policy</classname>
		implements an exponential-size policy (which should be used
		with mask range hashing).</para></listitem><listitem><para><classname>hash_prime_size_policy</classname>
		implementing a size policy based on a sequence of primes
		(which should
		be used with mod range hashing</para></listitem></orderedlist><para>The graphic below gives an overall picture of the resize-related
	      classes. <classname>basic_hash_table</classname>
	      is parametrized by <classname>Resize_Policy</classname>, which it subclasses
	      publicly. This class is currently instantiated only by <classname>hash_standard_resize_policy</classname>.
	      <classname>hash_standard_resize_policy</classname>
	      itself is parametrized by <classname>Trigger_Policy</classname> and
	      <classname>Size_Policy</classname>. Currently, <classname>Trigger_Policy</classname> is
	      instantiated by <classname>hash_load_check_resize_trigger</classname>,
	      or <classname>cc_hash_max_collision_check_resize_trigger</classname>;
	      <classname>Size_Policy</classname> is instantiated by <classname>hash_exponential_size_policy</classname>,
	      or <classname>hash_prime_size_policy</classname>.</para></section><section xml:id="resize_policies.impl.internals"><info><title>Controling Access to Internals</title></info><para>There are cases where (controlled) access to resize
	      policies' internals is beneficial. E.g., it is sometimes
	      useful to query a hash-table for the table's actual size (as
	      opposed to its <function>size()</function> - the number of values it
	      currently holds); it is sometimes useful to set a table's
	      initial size, externally resize it, or change load factors.</para><para>Clearly, supporting such methods both decreases the
	      encapsulation of hash-based containers, and increases the
	      diversity between different associative-containers' interfaces.
	      Conversely, omitting such methods can decrease containers'
	      flexibility.</para><para>In order to avoid, to the extent possible, the above
	      conflict, the hash-based containers themselves do not address
	      any of these questions; this is deferred to the resize policies,
	      which are easier to change or replace. Thus, for example,
	      neither <classname>cc_hash_table</classname> nor
	      <classname>gp_hash_table</classname>
	      contain methods for querying the actual size of the table; this
	      is deferred to <classname>hash_standard_resize_policy</classname>.</para><para>Furthermore, the policies themselves are parametrized by
	      template arguments that determine the methods they support
	      (
	      <xref linkend="biblio.alexandrescu01modern"></xref>
	      shows techniques for doing so). <classname>hash_standard_resize_policy</classname>
	      is parametrized by <classname>External_Size_Access</classname> that
	      determines whether it supports methods for querying the actual
	      size of the table or resizing it. <classname>hash_load_check_resize_trigger</classname>
	      is parametrized by <classname>External_Load_Access</classname> that
	      determines whether it supports methods for querying or
	      modifying the loads. <classname>cc_hash_max_collision_check_resize_trigger</classname>
	      is parametrized by <classname>External_Load_Access</classname> that
	      determines whether it supports methods for querying the
	      load.</para><para>Some operations, for example, resizing a container at
	      run time, or changing the load factors of a load-check trigger
	      policy, require the container itself to resize. As mentioned
	      above, the hash-based containers themselves do not contain
	      these types of methods, only their resize policies.
	      Consequently, there must be some mechanism for a resize policy
	      to manipulate the hash-based container. As the hash-based
	      container is a subclass of the resize policy, this is done
	      through virtual methods. Each hash-based container has a
	      <classname>private</classname> <classname>virtual</classname> method:</para><programlisting>
		virtual void
		do_resize
		(size_type new_size);
	      </programlisting><para>which resizes the container. Implementations of
	      <classname>Resize_Policy</classname> can export public methods for resizing
	      the container externally; these methods internally call
	      <classname>do_resize</classname> to resize the table.</para></section></section></section><!-- resize policies --><section xml:id="container.hash.details.policy_interaction"><info><title>Policy Interactions</title></info><para>
	  </para><para>Hash-tables are unfortunately especially susceptible to
	  choice of policies. One of the more complicated aspects of this
	  is that poor combinations of good policies can form a poor
	  container. Following are some considerations.</para><section xml:id="policy_interaction.probesizetrigger"><info><title>probe/size/trigger</title></info><para>Some combinations do not work well for probing containers.
	    For example, combining a quadratic probe policy with an
	    exponential size policy can yield a poor container: when an
	    element is inserted, a trigger policy might decide that there
	    is no need to resize, as the table still contains unused
	    entries; the probe sequence, however, might never reach any of
	    the unused entries.</para><para>Unfortunately, this library cannot detect such problems at
	    compilation (they are halting reducible). It therefore defines
	    an exception class <classname>insert_error</classname> to throw an
	    exception in this case.</para></section><section xml:id="policy_interaction.hashtrigger"><info><title>hash/trigger</title></info><para>Some trigger policies are especially susceptible to poor
	    hash functions. Suppose, as an extreme case, that the hash
	    function transforms each key to the same hash value. After some
	    inserts, a collision detecting policy will always indicate that
	    the container needs to grow.</para><para>The library, therefore, by design, limits each operation to
	    one resize. For each <classname>insert</classname>, for example, it queries
	    only once whether a resize is needed.</para></section><section xml:id="policy_interaction.eqstorehash"><info><title>equivalence functors/storing hash values/hash</title></info><para><classname>cc_hash_table</classname> and
	    <classname>gp_hash_table</classname> are
	    parametrized by an equivalence functor and by a
	    <classname>Store_Hash</classname> parameter. If the latter parameter is
	    <classname>true</classname>, then the container stores with each entry
	    a hash value, and uses this value in case of collisions to
	    determine whether to apply a hash value. This can lower the
	    cost of collision for some types, but increase the cost of
	    collisions for other types.</para><para>If a ranged-hash function or ranged probe function is
	    directly supplied, however, then it makes no sense to store the
	    hash value with each entry. This library's container will
	    fail at compilation, by design, if this is attempted.</para></section><section xml:id="policy_interaction.sizeloadtrigger"><info><title>size/load-check trigger</title></info><para>Assume a size policy issues an increasing sequence of sizes
	    a, a q, a q<superscript>1</superscript>, a q<superscript>2</superscript>, ... For
	    example, an exponential size policy might issue the sequence of
	    sizes 8, 16, 32, 64, ...</para><para>If a load-check trigger policy is used, with loads
	    α<subscript>min</subscript> and α<subscript>max</subscript>,
	    respectively, then it is a good idea to have:</para><orderedlist><listitem><para>α<subscript>max</subscript> ~ 1 / q</para></listitem><listitem><para>α<subscript>min</subscript> &lt; 1 / (2 q)</para></listitem></orderedlist><para>This will ensure that the amortized hash cost of each
	    modifying operation is at most approximately 3.</para><para>α<subscript>min</subscript> ~ α<subscript>max</subscript> is, in
	    any case, a bad choice, and α<subscript>min</subscript> &gt;
	    α <subscript>max</subscript> is horrendous.</para></section></section></section><!-- details --></section><!-- hash --><!-- tree --><section xml:id="pbds.design.container.tree"><info><title>tree</title></info><section xml:id="container.tree.interface"><info><title>Interface</title></info><para>The tree-based container has the following declaration:</para><programlisting>
	  template&lt;
	  typename Key,
	  typename Mapped,
	  typename Cmp_Fn = std::less&lt;Key&gt;,
	  typename Tag = rb_tree_tag,
	  template&lt;
	  typename Const_Node_Iterator,
	  typename Node_Iterator,
	  typename Cmp_Fn_,
	  typename Allocator_&gt;
	  class Node_Update = null_node_update,
	  typename Allocator = std::allocator&lt;char&gt; &gt;
	  class tree;
	</programlisting><para>The parameters have the following meaning:</para><orderedlist><listitem><para><classname>Key</classname> is the key type.</para></listitem><listitem><para><classname>Mapped</classname> is the mapped-policy.</para></listitem><listitem><para><classname>Cmp_Fn</classname> is a key comparison functor</para></listitem><listitem><para><classname>Tag</classname> specifies which underlying data structure
	  to use.</para></listitem><listitem><para><classname>Node_Update</classname> is a policy for updating node
	  invariants.</para></listitem><listitem><para><classname>Allocator</classname> is an allocator
	  type.</para></listitem></orderedlist><para>The <classname>Tag</classname> parameter specifies which underlying
	data structure to use. Instantiating it by <classname>rb_tree_tag</classname>, <classname>splay_tree_tag</classname>, or
	<classname>ov_tree_tag</classname>,
	specifies an underlying red-black tree, splay tree, or
	ordered-vector tree, respectively; any other tag is illegal.
	Note that containers based on the former two contain more types
	and methods than the latter (e.g.,
	<classname>reverse_iterator</classname> and <classname>rbegin</classname>), and different
	exception and invalidation guarantees.</para></section><section xml:id="container.tree.details"><info><title>Details</title></info><section xml:id="container.tree.node"><info><title>Node Invariants</title></info><para>Consider the two trees in the graphic below, labels A and B. The first
	  is a tree of floats; the second is a tree of pairs, each
	  signifying a geometric line interval. Each element in a tree is referred to as a node of the tree. Of course, each of
	  these trees can support the usual queries: the first can easily
	  search for <classname>0.4</classname>; the second can easily search for
	  <classname>std::make_pair(10, 41)</classname>.</para><para>Each of these trees can efficiently support other queries.
	  The first can efficiently determine that the 2rd key in the
	  tree is <constant>0.3</constant>; the second can efficiently determine
	  whether any of its intervals overlaps
	  <programlisting>std::make_pair(29,42)</programlisting> (useful in geometric
	  applications or distributed file systems with leases, for
	  example).  It should be noted that an <classname>std::set</classname> can
	  only solve these types of problems with linear complexity.</para><para>In order to do so, each tree stores some metadata in
	  each node, and maintains node invariants (see <xref linkend="biblio.clrs2001"></xref>.) The first stores in
	  each node the size of the sub-tree rooted at the node; the
	  second stores at each node the maximal endpoint of the
	  intervals at the sub-tree rooted at the node.</para><figure><title>Tree node invariants</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_node_invariants.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Tree node invariants</phrase></textobject></mediaobject></figure><para>Supporting such trees is difficult for a number of
	  reasons:</para><orderedlist><listitem><para>There must be a way to specify what a node's metadata
	    should be (if any).</para></listitem><listitem><para>Various operations can invalidate node
	    invariants.  The graphic below shows how a right rotation,
	    performed on A, results in B, with nodes x and y having
	    corrupted invariants (the grayed nodes in C). The graphic shows
	    how an insert, performed on D, results in E, with nodes x and y
	    having corrupted invariants (the grayed nodes in F). It is not
	    feasible to know outside the tree the effect of an operation on
	    the nodes of the tree.</para></listitem><listitem><para>The search paths of standard associative containers are
	    defined by comparisons between keys, and not through
	    metadata.</para></listitem><listitem><para>It is not feasible to know in advance which methods trees
	    can support. Besides the usual <classname>find</classname> method, the
	    first tree can support a <classname>find_by_order</classname> method, while
	    the second can support an <classname>overlaps</classname> method.</para></listitem></orderedlist><figure><title>Tree node invalidation</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_node_invalidations.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Tree node invalidation</phrase></textobject></mediaobject></figure><para>These problems are solved by a combination of two means:
	  node iterators, and template-template node updater
	  parameters.</para><section xml:id="container.tree.node.iterators"><info><title>Node Iterators</title></info><para>Each tree-based container defines two additional iterator
	    types, <classname>const_node_iterator</classname>
	    and <classname>node_iterator</classname>.
	    These iterators allow descending from a node to one of its
	    children. Node iterator allow search paths different than those
	    determined by the comparison functor. The <classname>tree</classname>
	    supports the methods:</para><programlisting>
	      const_node_iterator
	      node_begin() const;

	      node_iterator
	      node_begin();

	      const_node_iterator
	      node_end() const;

	      node_iterator
	      node_end();
	    </programlisting><para>The first pairs return node iterators corresponding to the
	    root node of the tree; the latter pair returns node iterators
	    corresponding to a just-after-leaf node.</para></section><section xml:id="container.tree.node.updator"><info><title>Node Updator</title></info><para>The tree-based containers are parametrized by a
	    <classname>Node_Update</classname> template-template parameter. A
	    tree-based container instantiates
	    <classname>Node_Update</classname> to some
	    <classname>node_update</classname> class, and publicly subclasses
	    <classname>node_update</classname>. The graphic below shows this
	    scheme, as well as some predefined policies (which are explained
	    below).</para><figure><title>A tree and its update policy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_node_updator_policy_cd.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>A tree and its update policy</phrase></textobject></mediaobject></figure><para><classname>node_update</classname> (an instantiation of
	    <classname>Node_Update</classname>) must define <classname>metadata_type</classname> as
	    the type of metadata it requires. For order statistics,
	    e.g., <classname>metadata_type</classname> might be <classname>size_t</classname>.
	    The tree defines within each node a <classname>metadata_type</classname>
	    object.</para><para><classname>node_update</classname> must also define the following method
	    for restoring node invariants:</para><programlisting>
	      void
	      operator()(node_iterator nd_it, const_node_iterator end_nd_it)
	    </programlisting><para>In this method, <varname>nd_it</varname> is a
	    <classname>node_iterator</classname> corresponding to a node whose
	    A) all descendants have valid invariants, and B) its own
	    invariants might be violated; <classname>end_nd_it</classname> is
	    a <classname>const_node_iterator</classname> corresponding to a
	    just-after-leaf node. This method should correct the node
	    invariants of the node pointed to by
	    <classname>nd_it</classname>. For example, say node x in the
	    graphic below label A has an invalid invariant, but its' children,
	    y and z have valid invariants. After the invocation, all three
	    nodes should have valid invariants, as in label B.</para><figure><title>Restoring node invariants</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_restoring_node_invariants.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Restoring node invariants</phrase></textobject></mediaobject></figure><para>When a tree operation might invalidate some node invariant,
	    it invokes this method in its <classname>node_update</classname> base to
	    restore the invariant. For example, the graphic below shows
	    an <function>insert</function> operation (point A); the tree performs some
	    operations, and calls the update functor three times (points B,
	    C, and D). (It is well known that any <function>insert</function>,
	    <function>erase</function>, <function>split</function> or <function>join</function>, can restore
	    all node invariants by a small number of node invariant updates (<xref linkend="biblio.clrs2001"></xref>)
	    .</para><figure><title>Insert update sequence</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_update_seq_diagram.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Insert update sequence</phrase></textobject></mediaobject></figure><para>To complete the description of the scheme, three questions
	    need to be answered:</para><orderedlist><listitem><para>How can a tree which supports order statistics define a
	      method such as <classname>find_by_order</classname>?</para></listitem><listitem><para>How can the node updater base access methods of the
	      tree?</para></listitem><listitem><para>How can the following cyclic dependency be resolved?
	      <classname>node_update</classname> is a base class of the tree, yet it
	      uses node iterators defined in the tree (its child).</para></listitem></orderedlist><para>The first two questions are answered by the fact that
	    <classname>node_update</classname> (an instantiation of
	    <classname>Node_Update</classname>) is a <emphasis>public</emphasis> base class
	    of the tree. Consequently:</para><orderedlist><listitem><para>Any public methods of
	      <classname>node_update</classname> are automatically methods of
	      the tree (<xref linkend="biblio.alexandrescu01modern"></xref>).
	      Thus an order-statistics node updater,
	      <classname>tree_order_statistics_node_update</classname> defines
	      the <function>find_by_order</function> method; any tree
	      instantiated by this policy consequently supports this method as
	      well.</para></listitem><listitem><para>In C++, if a base class declares a method as
	      <literal>virtual</literal>, it is
	      <literal>virtual</literal> in its subclasses. If
	      <classname>node_update</classname> needs to access one of the
	      tree's methods, say the member function
	      <function>end</function>, it simply declares that method as
	      <literal>virtual</literal> abstract.</para></listitem></orderedlist><para>The cyclic dependency is solved through template-template
	    parameters. <classname>Node_Update</classname> is parametrized by
	    the tree's node iterators, its comparison functor, and its
	    allocator type. Thus, instantiations of
	    <classname>Node_Update</classname> have all information
	    required.</para><para>This library assumes that constructing a metadata object and
	    modifying it are exception free. Suppose that during some method,
	    say <classname>insert</classname>, a metadata-related operation
	    (e.g., changing the value of a metadata) throws an exception. Ack!
	    Rolling back the method is unusually complex.</para><para>Previously, a distinction was made between redundant
	    policies and null policies. Node invariants show a
	    case where null policies are required.</para><para>Assume a regular tree is required, one which need not
	    support order statistics or interval overlap queries.
	    Seemingly, in this case a redundant policy - a policy which
	    doesn't affect nodes' contents would suffice. This, would lead
	    to the following drawbacks:</para><orderedlist><listitem><para>Each node would carry a useless metadata object, wasting
	      space.</para></listitem><listitem><para>The tree cannot know if its
	      <classname>Node_Update</classname> policy actually modifies a
	      node's metadata (this is halting reducible). In the graphic
	      below, assume the shaded node is inserted. The tree would have
	      to traverse the useless path shown to the root, applying
	      redundant updates all the way.</para></listitem></orderedlist><figure><title>Useless update path</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_rationale_null_node_updator.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Useless update path</phrase></textobject></mediaobject></figure><para>A null policy class, <classname>null_node_update</classname>
	    solves both these problems. The tree detects that node
	    invariants are irrelevant, and defines all accordingly.</para></section></section><section xml:id="container.tree.details.split"><info><title>Split and Join</title></info><para>Tree-based containers support split and join methods.
	  It is possible to split a tree so that it passes
	  all nodes with keys larger than a given key to a different
	  tree. These methods have the following advantages over the
	  alternative of externally inserting to the destination
	  tree and erasing from the source tree:</para><orderedlist><listitem><para>These methods are efficient - red-black trees are split
	    and joined in poly-logarithmic complexity; ordered-vector
	    trees are split and joined at linear complexity. The
	    alternatives have super-linear complexity.</para></listitem><listitem><para>Aside from orders of growth, these operations perform
	    few allocations and de-allocations. For red-black trees, allocations are not performed,
	    and the methods are exception-free. </para></listitem></orderedlist></section></section><!-- details --></section><!-- tree --><!-- trie --><section xml:id="pbds.design.container.trie"><info><title>Trie</title></info><section xml:id="container.trie.interface"><info><title>Interface</title></info><para>The trie-based container has the following declaration:</para><programlisting>
	  template&lt;typename Key,
	  typename Mapped,
	  typename Cmp_Fn = std::less&lt;Key&gt;,
	  typename Tag = pat_trie_tag,
	  template&lt;typename Const_Node_Iterator,
	  typename Node_Iterator,
	  typename E_Access_Traits_,
	  typename Allocator_&gt;
	  class Node_Update = null_node_update,
	  typename Allocator = std::allocator&lt;char&gt; &gt;
	  class trie;
	</programlisting><para>The parameters have the following meaning:</para><orderedlist><listitem><para><classname>Key</classname> is the key type.</para></listitem><listitem><para><classname>Mapped</classname> is the mapped-policy.</para></listitem><listitem><para><classname>E_Access_Traits</classname> is described in below.</para></listitem><listitem><para><classname>Tag</classname> specifies which underlying data structure
	  to use, and is described shortly.</para></listitem><listitem><para><classname>Node_Update</classname> is a policy for updating node
	  invariants. This is described below.</para></listitem><listitem><para><classname>Allocator</classname> is an allocator
	  type.</para></listitem></orderedlist><para>The <classname>Tag</classname> parameter specifies which underlying
	data structure to use. Instantiating it by <classname>pat_trie_tag</classname>, specifies an
	underlying PATRICIA trie (explained shortly); any other tag is
	currently illegal.</para><para>Following is a description of a (PATRICIA) trie
	(this implementation follows <xref linkend="biblio.okasaki98mereable"></xref> and
	<xref linkend="biblio.filliatre2000ptset"></xref>).
	</para><para>A (PATRICIA) trie is similar to a tree, but with the
	following differences:</para><orderedlist><listitem><para>It explicitly views keys as a sequence of elements.
	  E.g., a trie can view a string as a sequence of
	  characters; a trie can view a number as a sequence of
	  bits.</para></listitem><listitem><para>It is not (necessarily) binary. Each node has fan-out n
	  + 1, where n is the number of distinct
	  elements.</para></listitem><listitem><para>It stores values only at leaf nodes.</para></listitem><listitem><para>Internal nodes have the properties that A) each has at
	  least two children, and B) each shares the same prefix with
	  any of its descendant.</para></listitem></orderedlist><para>A (PATRICIA) trie has some useful properties:</para><orderedlist><listitem><para>It can be configured to use large node fan-out, giving it
	  very efficient find performance (albeit at insertion
	  complexity and size).</para></listitem><listitem><para>It works well for common-prefix keys.</para></listitem><listitem><para>It can support efficiently queries such as which
	  keys match a certain prefix. This is sometimes useful in file
	  systems and routers, and for "type-ahead" aka predictive text matching
	  on mobile devices.</para></listitem></orderedlist></section><section xml:id="container.trie.details"><info><title>Details</title></info><section xml:id="container.trie.details.etraits"><info><title>Element Access Traits</title></info><para>A trie inherently views its keys as sequences of elements.
	  For example, a trie can view a string as a sequence of
	  characters. A trie needs to map each of n elements to a
	  number in {0, n - 1}. For example, a trie can map a
	  character <varname>c</varname> to
	  <programlisting>static_cast&lt;size_t&gt;(c)</programlisting>.</para><para>Seemingly, then, a trie can assume that its keys support
	  (const) iterators, and that the <classname>value_type</classname> of this
	  iterator can be cast to a <classname>size_t</classname>. There are several
	  reasons, though, to decouple the mechanism by which the trie
	  accesses its keys' elements from the trie:</para><orderedlist><listitem><para>In some cases, the numerical value of an element is
	    inappropriate. Consider a trie storing DNA strings. It is
	    logical to use a trie with a fan-out of 5 = 1 + |{'A', 'C',
	    'G', 'T'}|. This requires mapping 'T' to 3, though.</para></listitem><listitem><para>In some cases the keys' iterators are different than what
	    is needed. For example, a trie can be used to search for
	    common suffixes, by using strings'
	    <classname>reverse_iterator</classname>. As another example, a trie mapping
	    UNICODE strings would have a huge fan-out if each node would
	    branch on a UNICODE character; instead, one can define an
	    iterator iterating over 8-bit (or less) groups.</para></listitem></orderedlist><para>trie is,
	  consequently, parametrized by <classname>E_Access_Traits</classname> -
	  traits which instruct how to access sequences' elements.
	  <classname>string_trie_e_access_traits</classname>
	  is a traits class for strings. Each such traits define some
	  types, like:</para><programlisting>
	    typename E_Access_Traits::const_iterator
	  </programlisting><para>is a const iterator iterating over a key's elements. The
	  traits class must also define methods for obtaining an iterator
	  to the first and last element of a key.</para><para>The graphic below shows a
	  (PATRICIA) trie resulting from inserting the words: "I wish
	  that I could ever see a poem lovely as a trie" (which,
	  unfortunately, does not rhyme).</para><para>The leaf nodes contain values; each internal node contains
	  two <classname>typename E_Access_Traits::const_iterator</classname>
	  objects, indicating the maximal common prefix of all keys in
	  the sub-tree. For example, the shaded internal node roots a
	  sub-tree with leafs "a" and "as". The maximal common prefix is
	  "a". The internal node contains, consequently, to const
	  iterators, one pointing to <varname>'a'</varname>, and the other to
	  <varname>'s'</varname>.</para><figure><title>A PATRICIA trie</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_pat_trie.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>A PATRICIA trie</phrase></textobject></mediaobject></figure></section><section xml:id="container.trie.details.node"><info><title>Node Invariants</title></info><para>Trie-based containers support node invariants, as do
	  tree-based containers. There are two minor
	  differences, though, which, unfortunately, thwart sharing them
	  sharing the same node-updating policies:</para><orderedlist><listitem><para>A trie's <classname>Node_Update</classname> template-template
	      parameter is parametrized by <classname>E_Access_Traits</classname>, while
	      a tree's <classname>Node_Update</classname> template-template parameter is
	    parametrized by <classname>Cmp_Fn</classname>.</para></listitem><listitem><para>Tree-based containers store values in all nodes, while
	    trie-based containers (at least in this implementation) store
	    values in leafs.</para></listitem></orderedlist><para>The graphic below shows the scheme, as well as some predefined
	  policies (which are explained below).</para><figure><title>A trie and its update policy</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_trie_node_updator_policy_cd.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>A trie and its update policy</phrase></textobject></mediaobject></figure><para>This library offers the following pre-defined trie node
	  updating policies:</para><orderedlist><listitem><para><classname>trie_order_statistics_node_update</classname>
		supports order statistics.
	      </para></listitem><listitem><para><classname>trie_prefix_search_node_update</classname>
	    supports searching for ranges that match a given prefix.</para></listitem><listitem><para><classname>null_node_update</classname>
	    is the null node updater.</para></listitem></orderedlist></section><section xml:id="container.trie.details.split"><info><title>Split and Join</title></info><para>Trie-based containers support split and join methods; the
	  rationale is equal to that of tree-based containers supporting
	  these methods.</para></section></section><!-- details --></section><!-- trie --><!-- list_update --><section xml:id="pbds.design.container.list"><info><title>List</title></info><section xml:id="container.list.interface"><info><title>Interface</title></info><para>The list-based container has the following declaration:</para><programlisting>
	  template&lt;typename Key,
	  typename Mapped,
	  typename Eq_Fn = std::equal_to&lt;Key&gt;,
	  typename Update_Policy = move_to_front_lu_policy&lt;&gt;,
	  typename Allocator = std::allocator&lt;char&gt; &gt;
	  class list_update;
	</programlisting><para>The parameters have the following meaning:</para><orderedlist><listitem><para><classname>Key</classname> is the key type.
	    </para></listitem><listitem><para><classname>Mapped</classname> is the mapped-policy.
	    </para></listitem><listitem><para><classname>Eq_Fn</classname> is a key equivalence functor.
	    </para></listitem><listitem><para><classname>Update_Policy</classname> is a policy updating positions in
	      the list based on access patterns. It is described in the
	      following subsection.
	    </para></listitem><listitem><para><classname>Allocator</classname> is an allocator type.
	    </para></listitem></orderedlist><para>A list-based associative container is a container that
	stores elements in a linked-list. It does not order the elements
	by any particular order related to the keys.  List-based
	containers are primarily useful for creating "multimaps". In fact,
	list-based containers are designed in this library expressly for
	this purpose.</para><para>List-based containers might also be useful for some rare
	cases, where a key is encapsulated to the extent that only
	key-equivalence can be tested. Hash-based containers need to know
	how to transform a key into a size type, and tree-based containers
	need to know if some key is larger than another.  List-based
	associative containers, conversely, only need to know if two keys
	are equivalent.</para><para>Since a list-based associative container does not order
	elements by keys, is it possible to order the list in some
	useful manner? Remarkably, many on-line competitive
	algorithms exist for reordering lists to reflect access
	prediction. (See <xref linkend="biblio.motwani95random"></xref> and <xref linkend="biblio.andrew04mtf"></xref>).
	</para></section><section xml:id="container.list.details"><info><title>Details</title></info><para>
	</para><section xml:id="container.list.details.ds"><info><title>Underlying Data Structure</title></info><para>The graphic below shows a
	  simple list of integer keys. If we search for the integer 6, we
	  are paying an overhead: the link with key 6 is only the fifth
	  link; if it were the first link, it could be accessed
	  faster.</para><figure><title>A simple list</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_simple_list.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>A simple list</phrase></textobject></mediaobject></figure><para>List-update algorithms reorder lists as elements are
	  accessed. They try to determine, by the access history, which
	  keys to move to the front of the list. Some of these algorithms
	  require adding some metadata alongside each entry.</para><para>For example, in the graphic below label A shows the counter
	  algorithm. Each node contains both a key and a count metadata
	  (shown in bold). When an element is accessed (e.g. 6) its count is
	  incremented, as shown in label B. If the count reaches some
	  predetermined value, say 10, as shown in label C, the count is set
	  to 0 and the node is moved to the front of the list, as in label
	  D.
	  </para><figure><title>The counter algorithm</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_list_update.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>The counter algorithm</phrase></textobject></mediaobject></figure></section><section xml:id="container.list.details.policies"><info><title>Policies</title></info><para>this library allows instantiating lists with policies
	  implementing any algorithm moving nodes to the front of the
	  list (policies implementing algorithms interchanging nodes are
	  unsupported).</para><para>Associative containers based on lists are parametrized by a
	  <classname>Update_Policy</classname> parameter. This parameter defines the
	  type of metadata each node contains, how to create the
	  metadata, and how to decide, using this metadata, whether to
	  move a node to the front of the list. A list-based associative
	  container object derives (publicly) from its update policy.
	  </para><para>An instantiation of <classname>Update_Policy</classname> must define
	  internally <classname>update_metadata</classname> as the metadata it
	  requires. Internally, each node of the list contains, besides
	  the usual key and data, an instance of <classname>typename
	  Update_Policy::update_metadata</classname>.</para><para>An instantiation of <classname>Update_Policy</classname> must define
	  internally two operators:</para><programlisting>
	    update_metadata
	    operator()();

	    bool
	    operator()(update_metadata &amp;);
	  </programlisting><para>The first is called by the container object, when creating a
	  new node, to create the node's metadata. The second is called
	  by the container object, when a node is accessed (
	  when a find operation's key is equivalent to the key of the
	  node), to determine whether to move the node to the front of
	  the list.
	  </para><para>The library contains two predefined implementations of
	  list-update policies. The first
	  is <classname>lu_counter_policy</classname>, which implements the
	  counter algorithm described above. The second is
	  <classname>lu_move_to_front_policy</classname>,
	  which unconditionally move an accessed element to the front of
	  the list. The latter type is very useful in this library,
	  since there is no need to associate metadata with each element.
	  (See <xref linkend="biblio.andrew04mtf"></xref>
	  </para></section><section xml:id="container.list.details.mapped"><info><title>Use in Multimaps</title></info><para>In this library, there are no equivalents for the standard's
	  multimaps and multisets; instead one uses an associative
	  container mapping primary keys to secondary keys.</para><para>List-based containers are especially useful as associative
	  containers for secondary keys. In fact, they are implemented
	  here expressly for this purpose.</para><para>To begin with, these containers use very little per-entry
	  structure memory overhead, since they can be implemented as
	  singly-linked lists. (Arrays use even lower per-entry memory
	  overhead, but they are less flexible in moving around entries,
	  and have weaker invalidation guarantees).</para><para>More importantly, though, list-based containers use very
	  little per-container memory overhead. The memory overhead of an
	  empty list-based container is practically that of a pointer.
	  This is important for when they are used as secondary
	  associative-containers in situations where the average ratio of
	  secondary keys to primary keys is low (or even 1).</para><para>In order to reduce the per-container memory overhead as much
	  as possible, they are implemented as closely as possible to
	  singly-linked lists.</para><orderedlist><listitem><para>
		List-based containers do not store internally the number
		of values that they hold. This means that their <function>size</function>
		method has linear complexity (just like <classname>std::list</classname>).
		Note that finding the number of equivalent-key values in a
		standard multimap also has linear complexity (because it must be
		done,  via <function>std::distance</function> of the
		multimap's <function>equal_range</function> method), but usually with
		higher constants.
	      </para></listitem><listitem><para>
		Most associative-container objects each hold a policy
		object (a hash-based container object holds a
		hash functor). List-based containers, conversely, only have
		class-wide policy objects.
	      </para></listitem></orderedlist></section></section><!-- details --></section><!-- list --><!-- priority_queue --><section xml:id="pbds.design.container.priority_queue"><info><title>Priority Queue</title></info><section xml:id="container.priority_queue.interface"><info><title>Interface</title></info><para>The priority queue container has the following
	declaration:
	</para><programlisting>
	  template&lt;typename  Value_Type,
	  typename  Cmp_Fn = std::less&lt;Value_Type&gt;,
	  typename  Tag = pairing_heap_tag,
	  typename  Allocator = std::allocator&lt;char &gt; &gt;
	  class priority_queue;
	</programlisting><para>The parameters have the following meaning:</para><orderedlist><listitem><para><classname>Value_Type</classname> is the value type.</para></listitem><listitem><para><classname>Cmp_Fn</classname> is a value comparison functor</para></listitem><listitem><para><classname>Tag</classname> specifies which underlying data structure
	  to use.</para></listitem><listitem><para><classname>Allocator</classname> is an allocator
	  type.</para></listitem></orderedlist><para>The <classname>Tag</classname> parameter specifies which underlying
	data structure to use. Instantiating it by<classname>pairing_heap_tag</classname>,<classname>binary_heap_tag</classname>,
	<classname>binomial_heap_tag</classname>,
	<classname>rc_binomial_heap_tag</classname>,
	or <classname>thin_heap_tag</classname>,
	specifies, respectively,
	an underlying pairing heap (<xref linkend="biblio.fredman86pairing"></xref>),
	binary heap (<xref linkend="biblio.clrs2001"></xref>),
	binomial heap (<xref linkend="biblio.clrs2001"></xref>),
	a binomial heap with a redundant binary counter (<xref linkend="biblio.maverick_lowerbounds"></xref>),
	or a thin heap (<xref linkend="biblio.kt99fat_heaps"></xref>).
	</para><para>
	  As mentioned in the tutorial,
	  <classname>__gnu_pbds::priority_queue</classname> shares most of the
	  same interface with <classname>std::priority_queue</classname>.
	  E.g. if <varname>q</varname> is a priority queue of type
	  <classname>Q</classname>, then <function>q.top()</function> will
	  return the "largest" value in the container (according to
	  <classname>typename
	  Q::cmp_fn</classname>). <classname>__gnu_pbds::priority_queue</classname>
	  has a larger (and very slightly different) interface than
	  <classname>std::priority_queue</classname>, however, since typically
	  <classname>push</classname> and <classname>pop</classname> are deemed
	insufficient for manipulating priority-queues. </para><para>Different settings require different priority-queue
	implementations which are described in later; see traits
	discusses ways to differentiate between the different traits of
	different implementations.</para></section><section xml:id="container.priority_queue.details"><info><title>Details</title></info><section xml:id="container.priority_queue.details.iterators"><info><title>Iterators</title></info><para>There are many different underlying-data structures for
	  implementing priority queues. Unfortunately, most such
	  structures are oriented towards making <function>push</function> and
	  <function>top</function> efficient, and consequently don't allow efficient
	  access of other elements: for instance, they cannot support an efficient
	  <function>find</function> method. In the use case where it
	  is important to both access and "do something with" an
	  arbitrary value, one would be out of luck. For example, many graph algorithms require
	  modifying a value (typically increasing it in the sense of the
	  priority queue's comparison functor).</para><para>In order to access and manipulate an arbitrary value in a
	  priority queue, one needs to reference the internals of the
	  priority queue from some form of an associative container -
	  this is unavoidable. Of course, in order to maintain the
	  encapsulation of the priority queue, this needs to be done in a
	  way that minimizes exposure to implementation internals.</para><para>In this library the priority queue's <function>insert</function>
	  method returns an iterator, which if valid can be used for subsequent <function>modify</function> and
	  <function>erase</function> operations. This both preserves the priority
	  queue's encapsulation, and allows accessing arbitrary values (since the
	  returned iterators from the <function>push</function> operation can be
	  stored in some form of associative container).</para><para>Priority queues' iterators present a problem regarding their
	  invalidation guarantees. One assumes that calling
	  <function>operator++</function> on an iterator will associate it
	  with the "next" value. Priority-queues are
	  self-organizing: each operation changes what the "next" value
	  means. Consequently, it does not make sense that <function>push</function>
	  will return an iterator that can be incremented - this can have
	  no possible use. Also, as in the case of hash-based containers,
	  it is awkward to define if a subsequent <function>push</function> operation
	  invalidates a prior returned iterator: it invalidates it in the
	  sense that its "next" value is not related to what it
	  previously considered to be its "next" value. However, it might not
	  invalidate it, in the sense that it can be
	  de-referenced and used for <function>modify</function> and <function>erase</function>
	  operations.</para><para>Similarly to the case of the other unordered associative
	  containers, this library uses a distinction between
	  point-type and range type iterators. A priority queue's <classname>iterator</classname> can always be
	  converted to a <classname>point_iterator</classname>, and a
	  <classname>const_iterator</classname> can always be converted to a
	  <classname>point_const_iterator</classname>.</para><para>The following snippet demonstrates manipulating an arbitrary
	  value:</para><programlisting>
	    // A priority queue of integers.
	    priority_queue&lt;int &gt; p;

	    // Insert some values into the priority queue.
	    priority_queue&lt;int &gt;::point_iterator it = p.push(0);

	    p.push(1);
	    p.push(2);

	    // Now modify a value.
	    p.modify(it, 3);

	    assert(p.top() == 3);
	  </programlisting><para>It should be noted that an alternative design could embed an
	  associative container in a priority queue. Could, but most
	  probably should not. To begin with, it should be noted that one
	  could always encapsulate a priority queue and an associative
	  container mapping values to priority queue iterators with no
	  performance loss. One cannot, however, "un-encapsulate" a priority
	  queue embedding an associative container, which might lead to
	  performance loss. Assume, that one needs to associate each value
	  with some data unrelated to priority queues. Then using
	  this library's design, one could use an
	  associative container mapping each value to a pair consisting of
	  this data and a priority queue's iterator. Using the embedded
	  method would need to use two associative containers. Similar
	  problems might arise in cases where a value can reside
	  simultaneously in many priority queues.</para></section><section xml:id="container.priority_queue.details.d"><info><title>Underlying Data Structure</title></info><para>There are three main implementations of priority queues: the
	  first employs a binary heap, typically one which uses a
	  sequence; the second uses a tree (or forest of trees), which is
	  typically less structured than an associative container's tree;
	  the third simply uses an associative container. These are
	  shown in the graphic below, in labels A1 and A2, label B, and label C.</para><figure><title>Underlying Priority-Queue Data-Structures.</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_different_underlying_dss.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Underlying Priority-Queue Data-Structures.</phrase></textobject></mediaobject></figure><para>Roughly speaking, any value that is both pushed and popped
	  from a priority queue must incur a logarithmic expense (in the
	  amortized sense). Any priority queue implementation that would
	  avoid this, would violate known bounds on comparison-based
	  sorting (see <xref linkend="biblio.clrs2001"></xref> and <xref linkend="biblio.brodal96priority"></xref>).
	  </para><para>Most implementations do
	  not differ in the asymptotic amortized complexity of
	  <function>push</function> and <function>pop</function> operations, but they differ in
	  the constants involved, in the complexity of other operations
	  (e.g., <function>modify</function>), and in the worst-case
	  complexity of single operations. In general, the more
	  "structured" an implementation (i.e., the more internal
	  invariants it possesses) - the higher its amortized complexity
	  of <function>push</function> and <function>pop</function> operations.</para><para>This library implements different algorithms using a
	  single class: <classname>priority_queue</classname>.
	  Instantiating the <classname>Tag</classname> template parameter, "selects"
	  the implementation:</para><orderedlist><listitem><para>
	      Instantiating <classname>Tag = binary_heap_tag</classname> creates
	      a binary heap of the form in represented in the graphic with labels A1 or A2. The former is internally
	      selected by priority_queue
	      if <classname>Value_Type</classname> is instantiated by a primitive type
	      (e.g., an <type>int</type>); the latter is
	      internally selected for all other types (e.g.,
	      <classname>std::string</classname>). This implementations is relatively
	      unstructured, and so has good <classname>push</classname> and <classname>pop</classname>
	      performance; it is the "best-in-kind" for primitive
	      types, e.g., <type>int</type>s. Conversely, it has
	      high worst-case performance, and can support only linear-time
	    <function>modify</function> and <function>erase</function> operations.</para></listitem><listitem><para>Instantiating <classname>Tag =
	    pairing_heap_tag</classname> creates a pairing heap of the form
	    in represented by label B in the graphic above. This
	    implementations too is relatively unstructured, and so has good
	    <function>push</function> and <function>pop</function>
	    performance; it is the "best-in-kind" for non-primitive types,
	    e.g., <classname>std:string</classname>s. It also has very good
	    worst-case <function>push</function> and
	    <function>join</function> performance (O(1)), but has high
	    worst-case <function>pop</function>
	    complexity.</para></listitem><listitem><para>Instantiating <classname>Tag =
	    binomial_heap_tag</classname> creates a binomial heap of the
	    form repsented by label B in the graphic above. This
	    implementations is more structured than a pairing heap, and so
	    has worse <function>push</function> and <function>pop</function>
	    performance. Conversely, it has sub-linear worst-case bounds for
	    <function>pop</function>, e.g., and so it might be preferred in
	    cases where responsiveness is important.</para></listitem><listitem><para>Instantiating <classname>Tag =
	    rc_binomial_heap_tag</classname> creates a binomial heap of the
	    form represented in label B above, accompanied by a redundant
	    counter which governs the trees. This implementations is
	    therefore more structured than a binomial heap, and so has worse
	    <function>push</function> and <function>pop</function>
	    performance. Conversely, it guarantees O(1)
	    <function>push</function> complexity, and so it might be
	    preferred in cases where the responsiveness of a binomial heap
	    is insufficient.</para></listitem><listitem><para>Instantiating <classname>Tag =
	    thin_heap_tag</classname> creates a thin heap of the form
	    represented by the label B in the graphic above. This
	    implementations too is more structured than a pairing heap, and
	    so has worse <function>push</function> and
	    <function>pop</function> performance. Conversely, it has better
	    worst-case and identical amortized complexities than a Fibonacci
	    heap, and so might be more appropriate for some graph
	    algorithms.</para></listitem></orderedlist><para>Of course, one can use any order-preserving associative
	  container as a priority queue, as in the graphic above label C, possibly by creating an adapter class
	  over the associative container (much as
	  <classname>std::priority_queue</classname> can adapt <classname>std::vector</classname>).
	  This has the advantage that no cross-referencing is necessary
	  at all; the priority queue itself is an associative container.
	  Most associative containers are too structured to compete with
	  priority queues in terms of <function>push</function> and <function>pop</function>
	  performance.</para></section><section xml:id="container.priority_queue.details.traits"><info><title>Traits</title></info><para>It would be nice if all priority queues could
	  share exactly the same behavior regardless of implementation. Sadly, this is not possible. Just one for instance is in join operations: joining
	  two binary heaps might throw an exception (not corrupt
	  any of the heaps on which it operates), but joining two pairing
	  heaps is exception free.</para><para>Tags and traits are very useful for manipulating generic
	  types. <classname>__gnu_pbds::priority_queue</classname>
	  publicly defines <classname>container_category</classname> as one of the tags. Given any
	  container <classname>Cntnr</classname>, the tag of the underlying
	  data structure can be found via <classname>typename
	  Cntnr::container_category</classname>; this is one of the possible tags shown in the graphic below.
	  </para><figure><title>Priority-Queue Data-Structure Tags.</title><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_tag_hierarchy.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Priority-Queue Data-Structure Tags.</phrase></textobject></mediaobject></figure><para>Additionally, a traits mechanism can be used to query a
	  container type for its attributes. Given any container
	  <classname>Cntnr</classname>, then <programlisting>__gnu_pbds::container_traits&lt;Cntnr&gt;</programlisting>
	  is a traits class identifying the properties of the
	  container.</para><para>To find if a container might throw if two of its objects are
	  joined, one can use
	  <programlisting>
	    container_traits&lt;Cntnr&gt;::split_join_can_throw
	  </programlisting>
	  </para><para>
	    Different priority-queue implementations have different invalidation guarantees. This is
	    especially important, since there is no way to access an arbitrary
	    value of priority queues except for iterators. Similarly to
	    associative containers, one can use
	    <programlisting>
	      container_traits&lt;Cntnr&gt;::invalidation_guarantee
	    </programlisting>
	  to get the invalidation guarantee type of a priority queue.</para><para>It is easy to understand from the graphic above, what <classname>container_traits&lt;Cntnr&gt;::invalidation_guarantee</classname>
	  will be for different implementations. All implementations of
	  type represented by label B have <classname>point_invalidation_guarantee</classname>:
	  the container can freely internally reorganize the nodes -
	  range-type iterators are invalidated, but point-type iterators
	  are always valid. Implementations of type represented by labels A1 and A2 have <classname>basic_invalidation_guarantee</classname>:
	  the container can freely internally reallocate the array - both
	  point-type and range-type iterators might be invalidated.</para><para>
	    This has major implications, and constitutes a good reason to avoid
	    using binary heaps. A binary heap can perform <function>modify</function>
	    or <function>erase</function> efficiently given a valid point-type
	    iterator. However, in order to supply it with a valid point-type
	    iterator, one needs to iterate (linearly) over all
	    values, then supply the relevant iterator (recall that a
	    range-type iterator can always be converted to a point-type
	    iterator). This means that if the number of <function>modify</function> or
	    <function>erase</function> operations is non-negligible (say
	    super-logarithmic in the total sequence of operations) - binary
	    heaps will perform badly.
	  </para></section></section><!-- details --></section><!-- priority_queue --></section><!-- container --></section><!-- design --><!-- S04: Test --><section version="5.0" xreflabel="Test" xml:id="pbds.test"><info><title>Testing</title></info><?dbhtml filename="policy_based_data_structures_test.html"?><!-- S01 regression --><section xml:id="pbds.test.regression"><info><title>Regression</title></info><para>The library contains a single comprehensive regression test.
    For a given container type in this library, the test creates
    an object of the container type and an object of the
    corresponding standard type (e.g., <classname>std::set</classname>). It
    then performs a random sequence of methods with random
    arguments (e.g., inserts, erases, and so forth) on both
    objects. At each operation, the test checks the return value of
    the method, and optionally both compares this library's
    object with the standard's object as well as performing other
    consistency checks on this library's object (e.g.,
    order preservation, when applicable, or node invariants, when
    applicable).</para><para>Additionally, the test integrally checks exception safety
    and resource leaks. This is done as follows. A special
    allocator type, written for the purpose of the test, both
    randomly throws an exceptions when allocations are performed,
    and tracks allocations and de-allocations. The exceptions thrown
    at allocations simulate memory-allocation failures; the
    tracking mechanism checks for memory-related bugs (e.g.,
    resource leaks and multiple de-allocations). Both
    this library's containers and the containers' value-types are
    configured to use this allocator.</para><para>For granularity, the test is split into the
    several sources, each checking only some containers.</para><para>For more details, consult the files in
    <filename class="directory">testsuite/ext/pb_ds/regression</filename>.
    </para></section><!-- S02 performance --><section xml:id="pbds.test.performance"><info><title>Performance</title></info><section xml:id="performance.hash"><info><title>Hash-Based</title></info><para></para><!-- 01 <a href="hash_text_find_find_timing_test"> --><section xml:id="performance.hash.text_find"><info><title>
	  Text <function>find</function>
	</title></info><para></para><section xml:id="hash.text_find.info"><info><title>
	    Description
	  </title></info><para>
	    This test inserts a number of values with keys from an
	    arbitrary text (<xref linkend="biblio.wickland96thirty"></xref>) into a container,
	    then performs a series of finds using
	    <function>find</function> . It measures the average
	    time for <function>find</function> as a function of
	  the number of values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/text_find_timing_test.cc</filename>
	  </para><para>
	    And uses the data file:
	    <filename>filethirty_years_among_the_dead_preproc.txt</filename>
	  </para><para>The test checks the effect of different range-hashing
	  functions, trigger policies, and cache-hashing policies.
	  </para></section><section xml:id="hash.text_find.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for the native
	  and collision-chaining hash types the function
	  applied being a text find timing test using
	  <function>find</function>.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_text_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_text_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_sth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.text_find.observations"><info><title>
	    Observations
	  </title></info><para>In this setting, the range-hashing scheme affects performance
	  more than other policies. As the results show, containers using
	  mod-based range-hashing (including the native hash-based container,
	  which is currently hard-wired to this scheme) have lower performance
	  than those using mask-based range-hashing. A modulo-based
	  range-hashing scheme's main benefit is that it takes into account
	  all hash-value bits. Standard string hash-functions are designed to
	  create hash values that are nearly-uniform as is (<xref linkend="biblio.knuth98sorting"></xref>).</para><para>Trigger policies, i.e. the load-checks constants, affect
	  performance to a lesser extent.</para><para>Perhaps surprisingly, storing the hash value alongside each
	  entry affects performance only marginally, at least in this
	  library's implementation. (Unfortunately, it was not possible to run
	  the tests with <classname>std::tr1::unordered_map</classname> 's
	  <classname>cache_hash_code = true</classname> , as it appeared to
	  malfuntion.)</para></section></section><!-- 02 <a href="hash_int_find_timing_test"> --><section xml:id="performance.hash.int_find"><info><title>
	  Integer <function>find</function>
	</title></info><para></para><section xml:id="hash.int_find.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with uniform
	  integer keys into a container, then performs a series of finds
	  using <function>find</function>. It measures the average time
	  for <function>find</function> as a function of the number of values
	  inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/random_int_find_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying
	  hash-tables,
	  range-hashing functions, and trigger policies.</para></section><section xml:id="hash.int_find.results"><info><title>
	    Results
	  </title></info><para>
	    There are two sets of results for this type, one for
	    collision-chaining hashes, and one for general-probe hashes.
	  </para><para>The first graphic below shows the results for the native and
	  collision-chaining hash types. The function applied being a random
	  integer timing test using <function>find</function>.
	  </para><!-- results graphic 01 --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>
	  </para><para>
	  </para><para>And the second graphic shows the results for the native and
	  general-probe hash types. The function applied being a random
	  integer timing test using <function>find</function>.
	  </para><!-- results graphic 02 --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mod_quadp_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>gp_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>quadratic_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mask_linp_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      gp_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>linear_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.int_find.observations"><info><title>
	    Observations
	  </title></info><para>In this setting, the choice of underlying hash-table affects
	  performance most, then the range-hashing scheme and, only finally,
	  other policies.</para><para>When comparing probing and chaining containers, it is
	  apparent that the probing containers are less efficient than the
	  collision-chaining containers (
	  <classname>std::tr1::unordered_map</classname> uses
	  collision-chaining) in this case.</para><para>Hash-Based Integer Subscript Insert Timing Test shows
	  a different case, where the situation is reversed;
	  </para><para>Within each type of hash-table, the range-hashing scheme
	  affects performance more than other policies; Hash-Based Text
	  <function>find</function> Find Timing Test also shows this. In the
	  above graphics should be noted that
	  <classname>std::tr1::unordered_map</classname> are hard-wired
	  currently to mod-based schemes.
	  </para></section></section><!-- 03 <a href="hash_int_subscript_find_test"> --><section xml:id="performance.hash.int_subscript_find"><info><title>
	  Integer Subscript <function>find</function>
	</title></info><para></para><section xml:id="hash.int_subscript_find.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with uniform
	  integer keys into a container, then performs a series of finds
	  using <function>operator[]</function>. It measures the average time
	  for <function>operator[]</function> as a function of the number of
	  values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/random_int_subscript_find_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying
	  hash-tables, range-hashing functions, and trigger policies.</para></section><section xml:id="hash.int_subscript_find.results"><info><title>
	    Results
	  </title></info><para>
	    There are two sets of results for this type, one for
	    collision-chaining hashes, and one for general-probe hashes.
	  </para><para>The first graphic below shows the results for the native
	  and collision-chaining hash types, using as the function
	  applied an integer subscript timing test with
	  <function>find</function>.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_subscript_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_subscript_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>
	  </para><para>
	  </para><para>And the second graphic shows the results for the native and
	  general-probe hash types. The function applied being a random
	  integer timing test using <function>find</function>.
	  </para><!-- results graphic 02 --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_subscript_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_subscript_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mod_quadp_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>gp_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>quadratic_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mask_linp_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      gp_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>linear_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.int_subscript_find.observations"><info><title>
	    Observations
	  </title></info><para>This test shows similar results to Hash-Based
	  Integer <classname>find</classname> Find Timing test.</para></section></section><!-- 04 <a href="hash_random_int_subscript_insert_timing_test"> --><section xml:id="performance.hash.int_subscript_insert"><info><title>
	  Integer Subscript <function>insert</function>
	</title></info><para></para><section xml:id="hash.int_subscript_insert.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with uniform i.i.d.
	  integer keys into a container, using
	  <function>operator[]</function>. It measures the average time for
	  <function>operator[]</function> as a function of the number of
	  values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/random_int_subscript_insert_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying
	  hash-tables.</para></section><section xml:id="hash.int_subscript_insert.results"><info><title>
	    Results
	  </title></info><para>
	    There are two sets of results for this type, one for
	    collision-chaining hashes, and one for general-probe hashes.
	  </para><para>The first graphic below shows the results for the native
	  and collision-chaining hash types, using as the function
	  applied an integer subscript timing test with
	  <function>insert</function>.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_subscript_insert.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_cc_hash_int_subscript_insert.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>
	  </para><para>
	  </para><para>And the second graphic shows the results for the native and
	  general-probe hash types. The function applied being a random
	  integer timing test using <function>find</function>.
	  </para><!-- results graphic 02 --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_subscript_insert.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_gp_hash_int_subscript_insert.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mod_quadp_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>gp_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>quadratic_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mask_linp_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      gp_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>linear_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.int_subscript_insert.observations"><info><title>
	    Observations
	  </title></info><para>In this setting, as in Hash-Based Text
	  <function>find</function> Find Timing test and Hash-Based
	  Integer <function>find</function> Find Timing test , the choice
	  of underlying hash-table underlying hash-table affects performance
	  most, then the range-hashing scheme, and
	  finally any other policies.</para><para>There are some differences, however:</para><orderedlist><listitem><para>In this setting, probing tables function sometimes more
	    efficiently than collision-chaining tables.
	    This is explained shortly.</para></listitem><listitem><para>The performance graphs have a "saw-tooth" shape. The
	    average insert time rises and falls. As values are inserted
	    into the container, the load factor grows larger. Eventually,
	    a resize occurs. The reallocations and rehashing are
	    relatively expensive. After this, the load factor is smaller
	    than before.</para></listitem></orderedlist><para>Collision-chaining containers use indirection for greater
	  flexibility; probing containers store values contiguously, in
	  an array (see Figure Motivation::Different
	  underlying data structures A and B, respectively). It
	  follows that for simple data types, probing containers access
	  their allocator less frequently than collision-chaining
	  containers, (although they still have less efficient probing
	  sequences). This explains why some probing containers fare
	  better than collision-chaining containers in this case.</para><para>
	    Within each type of hash-table, the range-hashing scheme affects
	    performance more than other policies. This is similar to the
	    situation in Hash-Based Text
	    <function>find</function> Find Timing Test and Hash-Based
	    Integer <function>find</function> Find Timing Test.
	    Unsurprisingly, however, containers with lower α<subscript>max</subscript> perform worse in this case,
	  since more re-hashes are performed.</para></section></section><!-- 05 <a href="hash_zlob_random_int_find_find_timing_test"> --><!-- 05 <a href="hash_zlob_random_int_find_find_timing_test"> --><section xml:id="performance.hash.zlob_int_find"><info><title>
	  Integer <function>find</function> with Skewed-Distribution
	</title></info><para></para><section xml:id="hash.zlob_int_find.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with a markedly
	  non-uniform integer keys into a container, then performs
	  a series of finds using <function>find</function>. It measures the average
	  time for <function>find</function> as a function of the number of values in
	  the containers. The keys are generated as follows. First, a
	  uniform integer is created. Then it is then shifted left 8 bits.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/hash_zlob_random_int_find_timing.cc</filename>
	  </para><para>The test checks the effect of different range-hashing
	  functions and trigger policies.</para></section><section xml:id="hash.zlob_int_find.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for the native, collision-chaining, and general-probing hash types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_zlob_int_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_zlob_int_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mod_quadp_prime_1div2_nsth_map
		  </entry></row><row><entry morerows="3" valign="top"><classname>gp_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>quadratic_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.zlob_int_find.observations"><info><title>
	    Observations
	  </title></info><para>In this setting, the distribution of keys is so skewed that
	  the underlying hash-table type affects performance marginally.
	  (This is in contrast with Hash-Based Text
	  <function>find</function> Find Timing Test, Hash-Based
	  Integer <function>find</function> Find Timing Test, Hash-Based
	  Integer Subscript Find Timing Test and Hash-Based
	  Integer Subscript Insert Timing Test.)</para><para>The range-hashing scheme affects performance dramatically. A
	  mask-based range-hashing scheme effectively maps all values
	  into the same bucket. Access degenerates into a search within
	  an unordered linked-list. In the graphic above, it should be noted that
	  <classname>std::tr1::unordered_map</classname> is hard-wired currently to mod-based and mask-based schemes,
	  respectively.</para><para>When observing the settings of this test, it is apparent
	  that the keys' distribution is far from natural. One might ask
	  if the test is not contrived to show that, in some cases,
	  mod-based range hashing does better than mask-based range
	  hashing. This is, in fact just the case. A
	  more natural case in which mod-based range hashing is better was not encountered.
	  Thus the inescapable conclusion: real-life key distributions are handled better
	  with an appropriate hash function and a mask-based
	  range-hashing function. (<filename>pb_ds/example/hash_shift_mask.cc</filename>
	  shows an example of handling this a-priori known skewed
	  distribution with a mask-based range-hashing function). If hash
	  performance is bad, a χ<superscript>2</superscript> test can be used
	  to check how to transform it into a more uniform
	  distribution.</para><para>For this reason, this library's default range-hashing
	  function is mask-based.</para></section></section><!-- 06 <a href="hash_random_int_erase_mem_usage_test"> --><!-- 06 <a href="hash_random_int_erase_mem_usage_test"> --><section xml:id="performance.hash.erase_mem"><info><title>
	  Erase Memory Use
	</title></info><para></para><section xml:id="hash.erase_mem.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of uniform integer keys
	  into a container, then erases all keys except one. It measures
	  the final size of the container.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/hash_random_int_erase_mem_usage.cc</filename>
	  </para><para>The test checks how containers adjust internally as their
	  logical size decreases.</para></section><section xml:id="hash.erase_mem.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for the native, collision-chaining, and general-probing hash types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_int_erase_mem.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_hash_int_erase_mem.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="5" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    n_hash_map_ncah
		  </entry></row><row><entry><classname>std::tr1::unordered_map</classname></entry><entry><classname>cache_hash_code</classname></entry><entry><constant>false</constant></entry><entry nameend="c5" namest="c4"></entry></row><!-- hash 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mod_prime_1div1_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mod_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_prime_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/1
		  </entry></row><!-- hash 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    cc_hash_mask_exp_1div2_nsth_map
		  </entry></row><row><entry morerows="2" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row><!-- hash 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c5" namest="c1">
		    gp_hash_mask_linp_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>gp_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry><classname>Probe_Fn</classname></entry><entry><classname>linear_probe_fn</classname></entry><entry nameend="c5" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="hash.erase_mem.observations"><info><title>
	    Observations
	  </title></info><para>The standard's hash-based containers act very differently than trees in
	  this respect. When erasing numerous keys from an standard
	  associative-container, the resulting memory user varies greatly
	  depending on whether the container is tree-based or hash-based.
	  This is a fundamental consequence of the standard's interface for
	  associative containers, and it is not due to a specific
	  implementation.</para></section></section></section><section xml:id="performance.branch"><info><title>Branch-Based</title></info><para></para><!-- 01 <a href="tree_text_insert_timing_test"> --><section xml:id="performance.branch.text_insert"><info><title>
	  Text <function>insert</function>
	</title></info><para></para><section xml:id="branch.text_insert.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an arbitrary
	  text ([wickland96thirty]) into a container
	  using <function>insert</function> . It measures the average time
	  for <function>insert</function> as a function of the number of
	  values inserted.</para><para>The test checks the effect of different underlying
	  data structures.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/tree_text_insert_timing.cc</filename>
	  </para></section><section xml:id="branch.text_insert.results"><info><title>
	    Results
	  </title></info><para>The three graphics below show the results for the native
	  tree and this library's node-based trees, the native tree and
	  this library's vector-based trees, and the native tree
	  and this library's PATRICIA-trie, respectively.
	  </para><para>The graphic immediately below shows the results for the
	  native tree type and several node-based tree types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_node.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_node.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject><para>
	      The abbreviated names in the legend of the graphic above are
	      instantiated with the types in the following table.
	    </para></informalfigure><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_map
		  </entry></row><row><entry><classname>std::map</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    splay_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>splay_tree_tag</classname></entry></row><row><entry><classname>Node_update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rb_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry></row><row><entry><classname>Node_update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the
	  native tree type and a vector-based tree type.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_vector.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_vector.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_map
		  </entry></row><row><entry><classname>std::map</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    ov_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>ov_tree_tag</classname></entry></row><row><entry><classname>Node_update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the
	  native tree type and a PATRICIA trie type.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_trie.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_insert_trie.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_map
		  </entry></row><row><entry><classname>std::map</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pat_trie_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pat_trie_tag</classname></entry></row><row><entry><classname>Node_update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="branch.text_insert.observations"><info><title>
	    Observations
	  </title></info><para>Observing the first graphic implies that for this setting, a splay tree
	  (<classname>tree</classname> with <classname>Tag
	  </classname> = <classname>splay_tree_tag</classname>) does not do
	  well. See also the Branch-Based
	  Text <function>find</function> Find Timing Test. The two
	  red-black trees perform better.</para><para>Observing the second graphic, an ordered-vector tree
	  (<classname>tree</classname> with <classname>Tag
	  </classname> = <classname>ov_tree_tag</classname>) performs
	  abysmally. Inserting into this type of tree has linear complexity
	  [ austern00noset].</para><para>Observing the third and last graphic, A PATRICIA trie
	  (<classname>trie</classname> with <classname>Tag
	  </classname> = <classname>pat_trie_tag</classname>) has abysmal
	  performance, as well. This is not that surprising, since a
	  large-fan-out PATRICIA trie works like a hash table with
	  collisions resolved by a sub-trie. Each time a collision is
	  encountered, a new "hash-table" is built A large fan-out PATRICIA
	  trie, however, doe does well in look-ups (see Branch-Based
	  Text <function>find</function> Find Timing Test). It may be
	  beneficial in semi-static settings.</para></section></section><!-- 02 <a href="tree_text_find_find_timing_test"> --><section xml:id="performance.branch.text_find"><info><title>
	  Text <function>find</function>
	</title></info><para></para><section xml:id="branch.text_find.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([wickland96thirty]) into
	  a container, then performs a series of finds using
	  <function>find</function>. It measures the average time
	  for <function>find</function> as a function of the number of
	  values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/text_find_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying
	  data structures.</para></section><section xml:id="branch.text_find.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native tree type and several other tree types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_map
		  </entry></row><row><entry><classname>std::map</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    splay_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>splay_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rb_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    ov_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>ov_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pat_trie_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pat_trie_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="branch.text_find.observations"><info><title>
	    Observations
	  </title></info><para>For this setting, a splay tree (<classname>tree</classname>
	  with <classname>Tag
	  </classname> = <classname>splay_tree_tag</classname>) does not do
	  well. This is possibly due to two reasons:</para><orderedlist><listitem><para>A splay tree is not guaranteed to be balanced [motwani95random]. If a
	    splay tree contains n nodes, its average root-leaf
	    path can be m &gt;&gt; log(n).</para></listitem><listitem><para>Assume a specific root-leaf search path has length
	    m, and the search-target node has distance m'
	    from the root. A red-black tree will require m + 1
	    comparisons to find the required node; a splay tree will
	    require 2 m' comparisons. A splay tree, consequently,
	    can perform many more comparisons than a red-black tree.</para></listitem></orderedlist><para>An ordered-vector tree (<classname>tree</classname>
	  with <classname>Tag</classname> =  <classname>ov_tree_tag</classname>), a red-black
	  tree (<classname>tree</classname>
	  with <classname>Tag</classname>  = <classname>rb_tree_tag</classname>), and the
	  native red-black tree all share approximately the same
	  performance.</para><para>An ordered-vector tree is slightly slower than red-black
	  trees, since it requires, in order to find a key, more math
	  operations than they do. Conversely, an ordered-vector tree
	  requires far lower space than the others. ([austern00noset], however,
	  seems to have an implementation that is also faster than a
	  red-black tree).</para><para>A PATRICIA trie (<classname>trie</classname>
	  with <classname>Tag</classname> = <classname>pat_trie_tag</classname>) has good
	  look-up performance, due to its large fan-out in this case. In
	  this setting, a PATRICIA trie has look-up performance comparable
	  to a hash table (see Hash-Based Text
	  <classname>find</classname> Timing Test), but it is order
	  preserving. This is not that surprising, since a large-fan-out
	  PATRICIA trie works like a hash table with collisions resolved
	  by a sub-trie. A large-fan-out PATRICIA trie does not do well on
	  modifications (see Tree-Based and Trie-Based
	  Text Insert Timing Test). Therefore, it is possibly beneficial in
	  semi-static settings.</para></section></section><!-- 03 <a href="tree_text_lor_find_find_timing_test"> --><section xml:id="performance.branch.text_lor_find"><info><title>
	  Text <function>find</function> with Locality-of-Reference
	</title></info><para></para><section xml:id="branch.text_lor_find.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([wickland96thirty]) into
	  a container, then performs a series of finds using
	  <function>find</function>. It is different than Tree-Based and
	  Trie-Based Text <function>find</function> Find Timing Test in the
	  sequence of finds it performs: this test performs multiple
	  <function>find</function>s on the same key before moving on to the next
	  key. It measures the average time for <function>find</function> as a
	  function of the number of values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/tree_text_lor_find_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying
	  data structures in a locality-of-reference setting.</para></section><section xml:id="branch.text_lor_find.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native tree type and several other tree types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_lor_find.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_text_lor_find.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_map
		  </entry></row><row><entry><classname>std::map</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    splay_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>splay_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rb_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    ov_tree_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>ov_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pat_trie_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pat_trie_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="branch.text_lor_find.observations"><info><title>
	    Observations
	  </title></info><para>For this setting, an ordered-vector tree
	  (<classname>tree</classname> with <classname>Tag</classname>
	  = <classname>ov_tree_tag</classname>), a red-black tree
	  (<classname>tree</classname> with <classname>Tag</classname>
	  = <classname>rb_tree_tag</classname>), and the native red-black
	  tree all share approximately the same performance.</para><para>A splay tree (<classname>tree</classname>
	  with <classname>Tag</classname> = <classname>splay_tree_tag</classname>) does
	  much better, since each (successful) find "bubbles" the
	  corresponding node to the root of the tree.</para></section></section><!-- 04 <a href="tree_split_join_timing_test"> --><section xml:id="performance.branch.split_join"><info><title><function>split</function> and <function>join</function>
	</title></info><para></para><section xml:id="branch.split_join.info"><info><title>
	    Description
	  </title></info><para>This test a container, inserts into a number of values, splits
	  the container at the median, and joins the two containers. (If the
	  containers are one of this library's trees,
	  it splits and joins with the <function>split</function> and
	  <function>join</function> method; otherwise, it uses the <function>erase</function> and
	  <function>insert</function> methods.) It measures the time for splitting
	  and joining the containers as a function of the number of
	  values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/tree_split_join_timing.cc</filename>
	  </para><para>The test checks the performance difference of <function>join</function>
	  as opposed to a sequence of <function>insert</function> operations; by
	  implication, this test checks the most efficient way to erase a
	  sub-sequence from a tree-like-based container, since this can
	  always be performed by a small sequence of splits and joins.
	  </para></section><section xml:id="branch.split_join.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native tree type and several other tree types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_split_join.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_split_join.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_set
		  </entry></row><row><entry><classname>std::set</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    splay_tree_set
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>splay_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rb_tree_set
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    ov_tree_set
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>ov_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row><!-- branch 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pat_trie_map
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pat_trie_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="branch.split_join.observations"><info><title>
	    Observations
	  </title></info><para>In this test, the native red-black trees must be split and
	  joined externally, through a sequence of <function>erase</function> and
	  <function>insert</function> operations. This is clearly
	  super-linear, and it is not that surprising that the cost is
	  high.</para><para>This library's tree-based containers use in this test the
	  <function>split</function> and <function>join</function> methods,
	  which have lower complexity: the <function>join</function> method
	  of a splay tree (<classname>tree</classname>
	  with <classname>Tag </classname>
	  = <classname>splay_tree_tag</classname>) is quadratic in the
	  length of the longest root-leaf path, and linear in the total
	  number of elements; the <function>join</function> method of a
	  red-black tree (<classname>tree</classname>
	  with <classname>Tag </classname>
	  = <classname>rb_tree_tag</classname>) or an ordered-vector tree
	  (<classname>tree</classname> with <classname>Tag </classname>
	  = <classname>ov_tree_tag</classname>) is linear in the number of
	  elements.</para><para>Asides from orders of growth, this library's trees access their
	  allocator very little in these operations, and some of them do not
	  access it at all. This leads to lower constants in their
	  complexity, and, for some containers, to exception-free splits and
	  joins (which can be determined
	  via <classname>container_traits</classname>).</para><para>It is important to note that <function>split</function> and
	  <function>join</function> are not esoteric methods - they are the most
	  efficient means of erasing a contiguous range of values from a
	  tree based container.</para></section></section><!-- 05 <a href="tree_order_statistics_timing_test"> --><section xml:id="performance.branch.order_statistics"><info><title>
	  Order-Statistics
	</title></info><para></para><section xml:id="branch.order_statistics.info"><info><title>
	    Description
	  </title></info><para>This test creates a container, inserts random integers into the
	  the container, and then checks the order-statistics of the
	  container's values. (If the container is one of this
	  library's trees, it does this with
	  the <function>order_of_key</function> method of
	  <classname>tree_order_statistics_node_update</classname>
	  ; otherwise, it uses the <function>find</function> method and
	  <function>std::distance</function>.) It measures the average
	  time for such queries as a function of the number of values
	  inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/tree_order_statistics_timing.cc</filename>
	  </para><para>The test checks the performance difference of policies based
	  on node-invariant as opposed to a external functions.</para></section><section xml:id="branch.order_statistics.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native tree type and several other tree types.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_order_statistics.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_tree_order_statistics.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_set
		  </entry></row><row><entry><classname>std::set</classname></entry><entry nameend="c3" namest="c2"></entry></row><!-- branch 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    splay_tree_ost_set
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>splay_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>tree_order_statistics_node_update</classname></entry></row><!-- branch 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rb_tree_ost_set
		  </entry></row><row><entry morerows="1" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>tree_order_statistics_node_update</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="branch.order_statistics.observations"><info><title>
	    Observations
	  </title></info><para>In this test, the native red-black tree can support
	  order-statistics queries only externally, by performing a
	  <classname>find</classname> (alternatively, <classname>lower_bound</classname> or
	  <classname>upper_bound</classname> ) and then using <classname>std::distance</classname> .
	  This is clearly linear, and it is not that surprising that the
	  cost is high.</para><para>This library's tree-based containers use in this test the
	  <classname>order_of_key</classname> method of <classname>tree_order_statistics_node_update</classname>.
	  This method has only linear complexity in the length of the
	  root-node path. Unfortunately, the average path of a splay tree
	  (<classname>tree</classname>
	  with <classname>Tag =</classname> <classname>splay_tree_tag</classname> ) can
	  be higher than logarithmic; the longest path of a red-black
	  tree (<classname>tree</classname>
	  with <classname>Tag =</classname> <classname>rb_tree_tag</classname> ) is
	  logarithmic in the number of elements. Consequently, the splay
	  tree has worse performance than the red-black tree.</para></section></section></section><!-- branch --><section xml:id="performance.multimap"><info><title>Multimap</title></info><para></para><!-- 01 <a href="multimap_text_find_timing_test_small"> --><section xml:id="performance.multimap.text_find_small"><info><title>
	  Text <function>find</function> with Small Secondary-to-Primary Key Ratios
	</title></info><para></para><section xml:id="multimap.text_find_small.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform i.i.d.integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key (see Motivation::Associative
	  Containers::Alternative to Multiple Equivalent Keys). There
	  are 400 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges from 1 to 5.</para><para>The test measures the average find-time as a function of the
	  number of values inserted. For this library's containers, it
	  finds the secondary key from a container obtained from finding
	  a primary key. For the native multimaps, it searches a range
	  obtained using <classname>std::equal_range</classname> on a primary key.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_find_timing_small.cc</filename>
	  </para><para>The test checks the find-time scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_find_small.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_find_small.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section><!-- 02 <a href="multimap_text_find_timing_test_large"> --><section xml:id="performance.multimap.text_find_large"><info><title>
	  Text <function>find</function> with Large Secondary-to-Primary Key Ratios
	</title></info><para></para><section xml:id="multimap.text_find_large.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key. There
	  are 400 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges from 1 to 5.</para><para>The test measures the average find-time as a function of the
	  number of values inserted. For this library's containers, it
	  finds the secondary key from a container obtained from finding
	  a primary key. For the native multimaps, it searches a range
	  obtained using <classname>std::equal_range</classname> on a primary key.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_find_timing_large.cc</filename>
	  </para><para>The test checks the find-time scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_find_large.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_find_large.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section><!-- 03 <a href="multimap_text_insert_timing_test_small"> --><section xml:id="performance.multimap.text_insert_small"><info><title>
	  Text <function>insert</function> with Small
	  Secondary-to-Primary Key Ratios
	</title></info><para></para><section xml:id="multimap.text_insert_small.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key. There
	  are 400 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges from 1 to 5.</para><para>The test measures the average insert-time as a function of
	  the number of values inserted. For this library's containers,
	  it inserts a primary key into the primary associative
	  container, then a secondary key into the secondary associative
	  container. For the native multimaps, it obtains a range using
	  <classname>std::equal_range</classname>, and inserts a value only if it was
	  not contained already.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_insert_timing_small.cc</filename>
	  </para><para>The test checks the insert-time scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_insert_small.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_small_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_small_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_small_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_insert_small.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section><!-- 04 <a href="multimap_text_insert_timing_test_large"> --><section xml:id="performance.multimap.text_insert_large"><info><title>
	  Text <function>insert</function> with Small
	  Secondary-to-Primary Key Ratios
	</title></info><para></para><section xml:id="multimap.text_insert_large.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key. There
	  are 400 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges from 1 to 5.</para><para>The test measures the average insert-time as a function of
	  the number of values inserted. For this library's containers,
	  it inserts a primary key into the primary associative
	  container, then a secondary key into the secondary associative
	  container. For the native multimaps, it obtains a range using
	  <classname>std::equal_range</classname>, and inserts a value only if it was
	  not contained already.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_insert_timing_large.cc</filename>
	  </para><para>The test checks the insert-time scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_insert_large.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_large_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_large_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_insert_large.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section><!-- 05 <a href="multimap_text_insert_mem_usage_test_small"> --><section xml:id="performance.multimap.text_insert_mem_small"><info><title>
	  Text <function>insert</function> with Small
	  Secondary-to-Primary Key Ratios Memory Use
	</title></info><para></para><section xml:id="multimap.text_insert_mem_small.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key. There
	  are 100 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges to about 20.</para><para>The test measures the memory use as a function of the number
	  of values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_insert_mem_usage_small.cc</filename>
	  </para><para>The test checks the memory scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_insert_mem_small.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_mem_small_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_mem_small_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_insert_mem_small.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section><!-- 06 <a href="multimap_text_insert_mem_usage_test_large"> --><section xml:id="performance.multimap.text_insert_mem_large"><info><title>
	  Text <function>insert</function> with Small
	  Secondary-to-Primary Key Ratios Memory Use
	</title></info><para></para><section xml:id="multimap.text_insert_mem_large.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of pairs into a container. The
	  first item of each pair is a string from an arbitrary text
	  ([wickland96thirty]), and
	  the second is a uniform integer. The container is a
	  "multimap" - it considers the first member of each pair as a
	  primary key, and the second member of each pair as a secondary
	  key. There
	  are 100 distinct primary keys, and the ratio of secondary keys
	  to primary keys ranges to about 20.</para><para>The test measures the memory use as a function of the number
	  of values inserted.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/multimap_text_insert_mem_usage_large.cc</filename>
	  </para><para>The test checks the memory scalability of different
	  "multimap" designs.</para></section><section xml:id="multimap.text_insert_mem_large.results"><info><title>
	    Results
	  </title></info><para>The graphic below show the results for "multimaps" which
	  use a tree-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_mem_large_s2p_tree.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_insert_mem_large_s2p_tree.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_mmap
		  </entry></row><row><entry><classname>std::multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="2" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="4" valign="top"><classname>tree</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rb_tree_tag</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry><classname>Node_Update</classname></entry><entry><classname>null_node_update</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable><para>The graphic below show the results for "multimaps" which
	  use a hash-based container for primary keys.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.png" format="PNG" scale="100"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_multimap_text_find_large_s2p_hash.pdf" format="PDF" scale="33"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="7" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><colspec colname="c7"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    n_hash_mmap
		  </entry></row><row><entry><classname>std::tr1::unordered_multimap</classname></entry><entry nameend="c7" namest="c2"></entry></row><!-- multimap 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_lu_mtf_set
		  </entry></row><row><entry morerows="3" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry><classname>Mapped</classname></entry><entry><classname>list_update</classname></entry><entry><classname>Update_Policy</classname></entry><entry><classname>lu_move_to_front_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><!-- multimap 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c7" namest="c1">
		    rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set
		  </entry></row><row><entry morerows="5" valign="top"><classname>
		      cc_hash_table
		    </classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c4"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="2" valign="top"><classname>Mapped</classname></entry><entry morerows="2" valign="top"><classname>cc_hash_table</classname></entry><entry><classname>Comb_Hash_Fn</classname></entry><entry><classname>direct_mask_range_hashing</classname></entry><entry nameend="c7" namest="c6"></entry></row><row><entry morerows="1" valign="top"><classname>Resize_Policy</classname></entry><entry morerows="1" valign="top"><classname>hash_standard_resize_policy</classname></entry><entry><classname>Size_Policy</classname></entry><entry><classname>hash_exponential_size_policy</classname></entry></row><row><entry valign="top"><classname>Trigger_Policy</classname></entry><entry><classname>hash_load_check_resize_trigger</classname> with
		    α<subscript>min</subscript> = 1/8 and α<subscript>max</subscript> = 1/2
		  </entry></row></tbody></tgroup></informaltable></section><section xml:id="multimap.text_insert_mem_large.observations"><info><title>
	    Observations
	  </title></info><para>See Observations::Mapping-Semantics
	  Considerations.</para></section></section></section><!-- multimap --><section xml:id="performance.priority_queue"><info><title>Priority Queue</title></info><!-- 01 <a href="priority_queue_text_push_timing_test"> --><section xml:id="performance.priority_queue.text_push"><info><title>
	  Text <function>push</function>
	</title></info><para></para><section xml:id="priority_queue.text_push.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  a container using <function>push</function>. It measures the average time
	  for <function>push</function> as a function of the number of values
	  pushed.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_push_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.text_push.results"><info><title>
	    Results
	  </title></info><para>The two graphics below show the results for the native
	  priority_queues and this library's priority_queues.
	  </para><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_push.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_push.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the binary-heap
	  based native priority queues and this library's pairing-heap
	  priority_queue data structures.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_push.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_push.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_push.observations"><info><title>
	    Observations
	  </title></info><para>Pairing heaps (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>pairing_heap_tag</classname>)
	  are the most suited for sequences of <function>push</function> and
	  <function>pop</function> operations of non-primitive types (e.g.
	  <classname>std::string</classname>s). (See Priority Queue
	  Text <function>push</function> and <function>pop</function> Timing Test.) They are
	  less constrained than binomial heaps, e.g., and since
	  they are node-based, they outperform binary heaps. (See
	  Priority
	  Queue Random Integer <function>push</function> Timing Test for the case
	  of primitive types.)</para><para>The standard's priority queues do not seem to perform well in
	  this case: the <classname>std::vector</classname> implementation needs to
	  perform a logarithmic sequence of string operations for each
	  operation, and the deque implementation is possibly hampered by
	  its need to manipulate a relatively-complex type (deques
	  support a O(1) <function>push_front</function>, even though it is
	  not used by <classname>std::priority_queue</classname>.)</para></section></section><!-- 02 <a href="priority_queue_text_push_pop_timing_test"> --><section xml:id="performance.priority_queue.text_push_pop"><info><title>
	  Text <function>push</function> and <function>pop</function>
	</title></info><para></para><section xml:id="priority_queue.text_push_pop.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  a container using <classname>push</classname> , then removes them using
	  <classname>pop</classname> . It measures the average time for <classname>push</classname>
	  as a function of the number of values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_push_pop_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.text_push_pop.results"><info><title>
	    Results
	  </title></info><para>The two graphics below show the results for the native
	  priority_queues and this library's priority_queues.
	  </para><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_push_pop.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_push_pop.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the native priority
	  queues and this library's pairing-heap priority_queue data
	  structures.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_push_pop.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_push_pop.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname> adapting <classname>std::vector</classname>
		  </entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_push_pop.observations"><info><title>
	    Observations
	  </title></info><para>These results are very similar to Priority Queue Text
	  <function>push</function> Timing Test. As stated there, pairing heaps
	  (<classname>priority_queue</classname> with
	  <classname>Tag</classname>
	  = <classname>pairing_heap_tag</classname>) are most suited
	  for <function>push</function> and <function>pop</function>
	  sequences of non-primitive types such as strings. Observing these
	  two tests, one can note that a pairing heap outperforms the others
	  in terms of <function>push</function> operations, but equals
	  binary heaps (<classname>priority_queue</classname> with
	  <classname>Tag</classname>
	  = <classname>binary_heap_tag</classname>) if the number
	  of <function>push</function> and <function>pop</function>
	  operations is equal. As the number of <function>pop</function>
	  operations is at most equal to the number
	  of <function>push</function> operations, pairing heaps are better
	  in this case. See Priority Queue Random
	  Integer <function>push</function> and <function>pop</function>
	  Timing Test for a case which is different.</para></section></section><!-- 03 <a href="priority_queue_random_int_push_timing_test"> --><section xml:id="performance.priority_queue.int_push"><info><title>
	  Integer <function>push</function>
	</title></info><para></para><section xml:id="priority_queue.int_push.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with integer keys
	  into a container using <function>push</function>. It
	  measures the average time for <function>push</function> as a
	  function of the number of values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_random_int_push_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.int_push.results"><info><title>
	    Results
	  </title></info><para>The two graphics below show the results for the native
	  priority_queues and this library's priority_queues.
	  </para><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_int_push.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_int_push.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the binary-heap
	  based native priority queues and this library's
	  priority_queue data structures.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_binary_priority_queue_int_push.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_binary_priority_queue_int_push.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname> adapting <classname>std::vector</classname>
		  </entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.int_push.observations"><info><title>
	    Observations
	  </title></info><para>Binary heaps are the most suited for sequences of
	  <function>push</function> and <function>pop</function> operations of primitive types
	  (e.g. <type>int</type>s). They are less constrained
	  than any other type, and since it is very efficient to store
	  such types in arrays, they outperform even pairing heaps. (See
	  Priority
	  Queue Text <function>push</function> Timing Test for the case of
	  non-primitive types.)</para></section></section><!-- 04 "priority_queue_random_int_push_pop_timing_test" --><section xml:id="performance.priority_queue.int_push_pop"><info><title>
	  Integer <function>push</function>
	</title></info><para></para><section xml:id="priority_queue.int_push_pop.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with integer keys
	  into a container using <function>push</function> , then removes them
	  using <function>pop</function> . It measures the average time for
	  <function>push</function> and <function>pop</function> as a function
	  of the number of values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_random_int_push_pop_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.int_push_pop.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_int_push_pop.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_int_push_pop.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.int_push_pop.observations"><info><title>
	    Observations
	  </title></info><para>Binary heaps are the most suited for sequences of
	  <function>push</function> and <function>pop</function> operations of primitive types
	  (e.g. <type>int</type>s). This is explained in
	  Priority
	  Queue Random Int <function>push</function> Timing Test. (See Priority Queue
	  Text <function>push</function> Timing Test for the case of primitive
	  types.)</para><para>At first glance it seems that the standard's vector-based
	  priority queue is approximately on par with this
	  library's corresponding priority queue. There are two
	  differences however:</para><orderedlist><listitem><para>The standard's priority queue does not downsize the underlying
	    vector (or deque) as the priority queue becomes smaller
	    (see Priority Queue
	    Text <function>pop</function> Memory Use Test). It is therefore
	    gaining some speed at the expense of space.</para></listitem><listitem><para>From Priority Queue Random
	    Integer <function>push</function> and <function>pop</function>
	    Timing Test, it seems that the standard's priority queue is
	    slower in terms of <function>push</function> operations. Since
	    the number of
	    <function>pop</function> operations is at most that of <function>push</function>
	    operations, the test here is the "best" for the standard's
	    priority queue.</para></listitem></orderedlist></section></section><!-- 05 <a href="priority_queue_text_pop_mem_usage_test"> --><section xml:id="performance.priority_queue.text_pop"><info><title>
	  Text <function>pop</function> Memory Use
	</title></info><para></para><section xml:id="priority_queue.text_pop.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  a container, then pops them until only one is left in the
	  container. It measures the memory use as a function of the
	  number of values pushed to the container.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_pop_mem_usage.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.text_pop.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_pop_mem.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_pop_mem.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_pop.observations"><info><title>
	    Observations
	  </title></info><para>The priority queue implementations (excluding the standard's) use
	  memory proportionally to the number of values they hold:
	  node-based implementations (e.g., a pairing heap) do so
	  naturally; this library's binary heap de-allocates memory when
	  a certain lower threshold is exceeded.</para><para>Note from Priority Queue Text <function>push</function>
	  and <function>pop</function> Timing Test and Priority Queue
	  Random Integer <function>push</function>
	  and <function>pop</function> Timing Test that this does not
	  impede performance compared to the standard's priority
	  queues.</para><para>See Hash-Based Erase
	  Memory Use Test for a similar phenomenon regarding priority
	  queues.</para></section></section><!-- 06 <a href="priority_queue_text_join_timing_test"> --><section xml:id="performance.priority_queue.text_join"><info><title>
	  Text <function>join</function>
	</title></info><para></para><section xml:id="priority_queue.text_join.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  two containers, then merges the containers. It uses
	  <function>join</function> for this library's priority queues; for
	  the standard's priority queues, it successively pops values from
	  one container and pushes them into the other. The test measures
	  the average time as a function of the number of values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_join_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures.
	  </para></section><section xml:id="priority_queue.text_join.results"><info><title>
	    Results
	  </title></info><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_join.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_join.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_join.observations"><info><title>
	    Observations
	  </title></info><para>In this test the node-based heaps perform <function>join</function> in
	  either logarithmic or constant time. The binary heap requires
	  linear time, since the well-known heapify algorithm [clrs2001] is linear.</para><para>It would be possible to apply the heapify algorithm to the
	  standard containers, if they would support iteration (which they
	  don't). Barring iterators, it is still somehow possible to perform
	  linear-time merge on a <classname>std::vector</classname>-based
	  standard priority queue, using <function>top()</function>
	  and <function>size()</function> (since they are enough to expose
	  the underlying array), but this is impossible for
	  a <classname>std::deque</classname>-based standard priority queue.
	  Without heapify, the cost is super-linear.</para></section></section><!-- 07 <a href="priority_queue_text_push_timing_test"> --><section xml:id="performance.priority_queue.text_modify_up"><info><title>
	  Text <function>modify</function> Up
	</title></info><para></para><section xml:id="priority_queue.text_modify_up.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  into a container then modifies each one "up" (i.e., it
	  makes it larger). It uses <function>modify</function> for this library's
	  priority queues; for the standard's priority queues, it pops values
	  from a container until it reaches the value that should be
	  modified, then pushes values back in. It measures the average
	  time for <function>modify</function> as a function of the number of
	  values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_modify_up_timing.cc</filename>
	  </para><para>The test checks the effect of different underlying data
	  structures for graph algorithms settings.  Note that making an
	  arbitrary value larger (in the sense of the priority queue's
	  comparison functor) corresponds to decrease-key in standard graph
	  algorithms [clrs2001].
	  </para></section><section xml:id="priority_queue.text_modify_up.results"><info><title>
	    Results
	  </title></info><para>The two graphics below show the results for the native
	  priority_queues and this library's priority_queues.
	  </para><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_modify_up.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_modify_up.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the
	  native priority queues and this library's pairing and thin heap
	  priority_queue data structures.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_modify_up_thin.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_modify_up_thin.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_modify_up.observations"><info><title>
	    Observations
	  </title></info><para>As noted above, increasing an arbitrary value (in the sense of
	  the priority queue's comparison functor) is very common in
	  graph-related algorithms. In this case, a thin heap
	  (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>thin_heap_tag</classname>)
	  outperforms a pairing heap (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>pairing_heap_tag</classname>).
	  Conversely, Priority Queue Text
	  <function>push</function> Timing Test, Priority Queue
	  Text <function>push</function> and <function>pop</function> Timing Test, Priority
	  Queue Random Integer <function>push</function> Timing Test, and
	  Priority
	  Queue Random Integer <function>push</function> and <function>pop</function> Timing
	  Test show that the situation is reversed for other
	  operations. It is not clear when to prefer one of these two
	  different types.</para><para>In this test this library's binary heaps
	  effectively perform modify in linear time. As explained in
	  Priority Queue Design::Traits, given a valid point-type iterator,
	  a binary heap can perform
	  <function>modify</function> logarithmically. The problem is that binary
	  heaps invalidate their find iterators with each modifying
	  operation, and so the only way to obtain a valid point-type
	  iterator is to iterate using a range-type iterator until
	  finding the appropriate value, then use the range-type iterator
	  for the <function>modify</function> operation.</para><para>The explanation for the standard's priority queues' performance
	  is similar to that in Priority Queue Text
	  <function>join</function> Timing Test.</para></section></section><!-- 08 <a href="priority_queue_text_modify_down_timing_test"> --><section xml:id="performance.priority_queue.text_modify_down"><info><title>
	  Text <function>modify</function> Down
	</title></info><para></para><section xml:id="priority_queue.text_modify_down.info"><info><title>
	    Description
	  </title></info><para>This test inserts a number of values with keys from an
	  arbitrary text ([ wickland96thirty ]) into
	  into a container then modifies each one "down" (i.e., it
	  makes it smaller). It uses <function>modify</function> for this library's
	  priority queues; for the standard's priority queues, it pops values
	  from a container until it reaches the value that should be
	  modified, then pushes values back in. It measures the average
	  time for <function>modify</function> as a function of the number of
	  values.</para><para>
	    It uses the test file:
	    <filename>performance/ext/pb_ds/priority_queue_text_modify_down_timing.cc</filename>
	  </para><para>The main purpose of this test is to contrast Priority Queue
	  Text <classname>modify</classname> Up Timing Test.</para></section><section xml:id="priority_queue.text_modify_down.results"><info><title>
	    Results
	  </title></info><para>The two graphics below show the results for the native
	  priority_queues and this library's priority_queues.
	  </para><para>The graphic immediately below shows the results for the
	  native priority_queue type instantiated with different underlying
	  container types versus several different versions of library's
	  priority_queues.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_modify_down.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_priority_queue_text_modify_down.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- native 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_vector
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::vector</classname></entry></row><!-- native 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    n_pq_deque
		  </entry></row><row><entry><classname>std::priority_queue</classname></entry><entry><classname>Sequence</classname></entry><entry><classname>std::deque</classname></entry></row><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binary_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binary_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>binomial_heap_tag</classname></entry></row><!-- priority_queue 03 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    rc_binomial_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>rc_binomial_heap_tag</classname></entry></row><!-- priority_queue 04 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 05 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable><para>The graphic below shows the results for the
	  native priority queues and this library's pairing and thin heap
	  priority_queue data structures.
	  </para><!-- results graphic --><informalfigure><mediaobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_modify_down_thin.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/pbds_pairing_priority_queue_text_modify_down_thin.png" format="PNG" scale="100"></imagedata></imageobject></mediaobject></informalfigure><para>
	    The abbreviated names in the legend of the graphic above are
	    instantiated with the types in the following table.
	  </para><informaltable frame="all"><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry><emphasis>Name/Instantiating Type</emphasis></entry><entry><emphasis>Parameter</emphasis></entry><entry><emphasis>Details</emphasis></entry></row></thead><tbody><!-- priority_queue 01 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    thin_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>thin_heap_tag</classname></entry></row><!-- priority_queue 02 --><row><?dbhtml bgcolor="#B0B0B0" ?><entry nameend="c3" namest="c1">
		    pairing_heap
		  </entry></row><row><entry><classname>priority_queue</classname></entry><entry><classname>Tag</classname></entry><entry><classname>pairing_heap_tag</classname></entry></row></tbody></tgroup></informaltable></section><section xml:id="priority_queue.text_modify_down.observations"><info><title>
	    Observations
	  </title></info><para>Most points in these results are similar to Priority Queue
	  Text <function>modify</function> Up Timing Test.</para><para>It is interesting to note, however, that as opposed to that
	  test, a thin heap (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>thin_heap_tag</classname>) is
	  outperformed by a pairing heap (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>pairing_heap_tag</classname>).
	  In this case, both heaps essentially perform an <function>erase</function>
	  operation followed by a <function>push</function> operation. As the other
	  tests show, a pairing heap is usually far more efficient than a
	  thin heap, so this is not surprising.</para><para>Most algorithms that involve priority queues increase values
	  (in the sense of the priority queue's comparison functor), and
	  so Priority Queue
	  Text <classname>modify</classname> Up Timing Test - is more interesting
	  than this test.</para></section></section></section><!-- priority_queue --><section xml:id="pbds.test.performance.observations"><info><title>Observations</title></info><section xml:id="observations.associative"><info><title>Associative</title></info><section xml:id="observations.associative.underlying"><info><title>
	    Underlying Data-Structure Families
	  </title></info><para>In general, hash-based containers have better timing performance
	  than containers based on different underlying-data structures. The
	  main reason to choose a tree-based or trie-based container is if a
	  byproduct of the tree-like structure is required: either
	  order-preservation, or the ability to utilize node invariants. If
	  memory-use is the major factor, an ordered-vector tree gives
	  optimal results (albeit with high modificiation costs), and a
	  list-based container gives reasonable results.</para></section><section xml:id="observations.associative.hash"><info><title>
	    Hash-Based Containers
	  </title></info><para>Hash-based containers are typically either collision
	  chaining or probing. Collision-chaining
	  containers are more flexible internally, and so offer better
	  timing performance. Probing containers, if used for simple
	  value-types, manage memory more efficiently (they perform far
	  fewer allocation-related calls). In general, therefore, a
	  collision-chaining table should be used. A probing container,
	  conversely, might be used efficiently for operations such as
	  eliminating duplicates in a sequence, or counting the number of
	  occurrences within a sequence. Probing containers might be more
	  useful also in multithreaded applications where each thread
	  manipulates a hash-based container: in the standard, allocators have
	  class-wise semantics (see [meyers96more] - Item 10); a
	  probing container might incur less contention in this case.</para></section><section xml:id="observations.associative.hash_policies"><info><title>
	    Hash Policies
	  </title></info><para>In hash-based containers, the range-hashing scheme seems to
	  affect performance more than other considerations. In most
	  settings, a mask-based scheme works well (or can be made to
	  work well). If the key-distribution can be estimated a-priori,
	  a simple hash function can produce nearly uniform hash-value
	  distribution. In many other cases (e.g., text hashing,
	  floating-point hashing), the hash function is powerful enough
	  to generate hash values with good uniformity properties
	  [knuth98sorting];
	  a modulo-based scheme, taking into account all bits of the hash
	  value, appears to overlap the hash function in its effort.</para><para>The range-hashing scheme determines many of the other
	  policies. A mask-based scheme works
	  well with an exponential-size policy; for
	  probing-based containers, it goes well with a linear-probe
	  function.</para><para>An orthogonal consideration is the trigger policy. This
	  presents difficult tradeoffs. E.g., different load
	  factors in a load-check trigger policy yield a
	  space/amortized-cost tradeoff.</para></section><section xml:id="observations.associative.branch"><info><title>
	    Branch-Based Containers
	  </title></info><para>In general, there are several families of tree-based
	  underlying data structures: balanced node-based trees
	  (e.g., red-black or AVL trees), high-probability
	  balanced node-based trees (e.g., random treaps or
	  skip-lists), competitive node-based trees (e.g., splay
	  trees), vector-based "trees", and tries. (Additionally, there
	  are disk-residing or network-residing trees, such as B-Trees
	  and their numerous variants. An interface for this would have
	  to deal with the execution model and ACID guarantees; this is
	  out of the scope of this library.) Following are some
	  observations on their application to different settings.</para><para>Of the balanced node-based trees, this library includes a
	  red-black tree, as does standard (in
	  practice). This type of tree is the "workhorse" of tree-based
	  containers: it offers both reasonable modification and
	  reasonable lookup time. Unfortunately, this data structure
	  stores a huge amount of metadata. Each node must contain,
	  besides a value, three pointers and a boolean. This type might
	  be avoided if space is at a premium [austern00noset].</para><para>High-probability balanced node-based trees suffer the
	  drawbacks of deterministic balanced trees. Although they are
	  fascinating data structures, preliminary tests with them showed
	  their performance was worse than red-black trees. The library
	  does not contain any such trees, therefore.</para><para>Competitive node-based trees have two drawbacks. They are
	  usually somewhat unbalanced, and they perform a large number of
	  comparisons. Balanced trees perform one comparison per each
	  node they encounter on a search path; a splay tree performs two
	  comparisons. If the keys are complex objects, e.g.,
	  <classname>std::string</classname>, this can increase the running time.
	  Conversely, such trees do well when there is much locality of
	  reference. It is difficult to determine in which case to prefer
	  such trees over balanced trees. This library includes a splay
	  tree.</para><para>Ordered-vector trees use very little space
	  [austern00noset].
	  They do not have any other advantages (at least in this
	  implementation).</para><para>Large-fan-out PATRICIA tries have excellent lookup
	  performance, but they do so through maintaining, for each node,
	  a miniature "hash-table". Their space efficiency is low, and
	  their modification performance is bad. These tries might be
	  used for semi-static settings, where order preservation is
	  important. Alternatively, red-black trees cross-referenced with
	  hash tables can be used. [okasaki98mereable]
	  discusses small-fan-out PATRICIA tries for integers, but the
	  cited results seem to indicate that the amortized cost of
	  maintaining such trees is higher than that of balanced trees.
	  Moderate-fan-out trees might be useful for sequences where each
	  element has a limited number of choices, e.g., DNA
	  strings.</para></section><section xml:id="observations.associative.mapping_semantics"><info><title>
	    Mapping-Semantics
	  </title></info><para>Different mapping semantics were discussed in the introduction and design sections.Here
	  the focus will be on the case where a keys can be composed into
	  primary keys and secondary keys. (In the case where some keys
	  are completely identical, it is trivial that one should use an
	  associative container mapping values to size types.) In this
	  case there are (at least) five possibilities:</para><orderedlist><listitem><para>Use an associative container that allows equivalent-key
	    values (such as <classname>std::multimap</classname>)</para></listitem><listitem><para>Use a unique-key value associative container that maps
	    each primary key to some complex associative container of
	    secondary keys, say a tree-based or hash-based container.
	    </para></listitem><listitem><para>Use a unique-key value associative container that maps
	    each primary key to some simple associative container of
	    secondary keys, say a list-based container.</para></listitem><listitem><para>Use a unique-key value associative container that maps
	    each primary key to some non-associative container
	    (e.g., <classname>std::vector</classname>)</para></listitem><listitem><para>Use a unique-key value associative container that takes
	    into account both primary and secondary keys.</para></listitem></orderedlist><para>Stated simply: there is a simple answer for this. (Excluding
	  option 1, which should be avoided in all cases).</para><para>If the expected ratio of secondary keys to primary keys is
	  small, then 3 and 4 seem reasonable. Both types of secondary
	  containers are relatively lightweight (in terms of memory use
	  and construction time), and so creating an entire container
	  object for each primary key is not too expensive. Option 4
	  might be preferable to option 3 if changing the secondary key
	  of some primary key is frequent - one cannot modify an
	  associative container's key, and the only possibility,
	  therefore, is erasing the secondary key and inserting another
	  one instead; a non-associative container, conversely, can
	  support in-place modification. The actual cost of erasing a
	  secondary key and inserting another one depends also on the
	  allocator used for secondary associative-containers (The tests
	  above used the standard allocator, but in practice one might
	  choose to use, e.g., [boost_pool]). Option 2 is
	  definitely an overkill in this case. Option 1 loses out either
	  immediately (when there is one secondary key per primary key)
	  or almost immediately after that. Option 5 has the same
	  drawbacks as option 2, but it has the additional drawback that
	  finding all values whose primary key is equivalent to some key,
	  might be linear in the total number of values stored (for
	  example, if using a hash-based container).</para><para>If the expected ratio of secondary keys to primary keys is
	  large, then the answer is more complicated. It depends on the
	  distribution of secondary keys to primary keys, the
	  distribution of accesses according to primary keys, and the
	  types of operations most frequent.</para><para>To be more precise, assume there are m primary keys,
	  primary key i is mapped to n<subscript>i</subscript>
	  secondary keys, and each primary key is mapped, on average, to
	  n secondary keys (i.e.,
	  E(n<subscript>i</subscript>) = n).</para><para>Suppose one wants to find a specific pair of primary and
	  secondary keys. Using 1 with a tree based container
	  (<classname>std::multimap</classname>), the expected cost is
	  E(Θ(log(m) + n<subscript>i</subscript>)) = Θ(log(m) +
	  n); using 1 with a hash-based container
	  (<classname>std::tr1::unordered_multimap</classname>), the expected cost is
	  Θ(n). Using 2 with a primary hash-based container
	  and secondary hash-based containers, the expected cost is
	  O(1); using 2 with a primary tree-based container and
	  secondary tree-based containers, the expected cost is (using
	  the Jensen inequality [motwani95random])
	  E(O(log(m) + log(n<subscript>i</subscript>)) = O(log(m)) +
	  E(O(log(n<subscript>i</subscript>)) = O(log(m)) + O(log(n)),
	  assuming that primary keys are accessed equiprobably. 3 and 4
	  are similar to 1, but with lower constants. Using 5 with a
	  hash-based container, the expected cost is O(1); using 5
	  with a tree based container, the cost is
	  E(Θ(log(mn))) = Θ(log(m) +
	  log(n)).</para><para>Suppose one needs the values whose primary key matches some
	  given key. Using 1 with a hash-based container, the expected
	  cost is Θ(n), but the values will not be ordered
	  by secondary keys (which may or may not be required); using 1
	  with a tree-based container, the expected cost is
	  Θ(log(m) + n), but with high constants; again the
	  values will not be ordered by secondary keys. 2, 3, and 4 are
	  similar to 1, but typically with lower constants (and,
	  additionally, if one uses a tree-based container for secondary
	  keys, they will be ordered). Using 5 with a hash-based
	  container, the cost is Θ(mn).</para><para>Suppose one wants to assign to a primary key all secondary
	  keys assigned to a different primary key. Using 1 with a
	  hash-based container, the expected cost is Θ(n),
	  but with very high constants; using 1 with a tree-based
	  container, the cost is Θ(nlog(mn)). Using 2, 3,
	  and 4, the expected cost is Θ(n), but typically
	  with far lower costs than 1. 5 is similar to 1.</para></section></section><section xml:id="observations.priority_queue"><info><title>Priority_Queue</title></info><section xml:id="observations.priority_queue.complexity"><info><title>Complexity</title></info><para>The following table shows the complexities of the different
	  underlying data structures in terms of orders of growth. It is
	  interesting to note that this table implies something about the
	  constants of the operations as well (see Amortized <function>push</function>
	  and <function>pop</function> operations).</para><informaltable frame="all"><tgroup align="left" cols="6" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><colspec colname="c5"></colspec><colspec colname="c6"></colspec><thead><row><entry></entry><entry><emphasis><function>push</function></emphasis></entry><entry><emphasis><function>pop</function></emphasis></entry><entry><emphasis><function>modify</function></emphasis></entry><entry><emphasis><function>erase</function></emphasis></entry><entry><emphasis><function>join</function></emphasis></entry></row></thead><tbody><row><entry><classname>std::priority_queue</classname></entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(log(n)) Worst
		  </entry><entry>
		    Θ(n log(n)) Worst
		    <subscript>[std note 1]</subscript>
		  </entry><entry>
		    Θ(n log(n))
		    <subscript>[std note 2]</subscript>
		  </entry><entry>
		    Θ(n log(n))
		    <subscript>[std note 1]</subscript>
		  </entry></row><row><entry><classname>priority_queue</classname>
		    &lt;<classname>Tag</classname> =
		    <classname>pairing_heap_tag</classname>&gt;
		  </entry><entry>
		    O(1)
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    O(1)
		  </entry></row><row><entry><classname>priority_queue</classname>
		    &lt;<classname>Tag</classname> =
		    <classname>binary_heap_tag</classname>&gt;
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(n)
		  </entry><entry>
		    Θ(n)
		  </entry><entry>
		    Θ(n)
		  </entry></row><row><entry><classname>priority_queue</classname>
		    &lt;<classname>Tag</classname> =
		    <classname>binomial_heap_tag</classname>&gt;
		  </entry><entry>
		    Θ(log(n)) worst
		    O(1) amortized
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry></row><row><entry><classname>priority_queue</classname>
		    &lt;<classname>Tag</classname> =
		    <classname>rc_binomial_heap_tag</classname>&gt;
		  </entry><entry>
		    O(1)
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry><entry>
		    Θ(log(n))
		  </entry></row><row><entry><classname>priority_queue</classname>&lt;<classname>Tag</classname> =
		    <classname>thin_heap_tag</classname>&gt;
		  </entry><entry>
		    O(1)
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(log(n)) worst
		    O(1) amortized,
		    or Θ(log(n)) amortized
		    <subscript>[thin_heap_note]</subscript>
		  </entry><entry>
		    Θ(n) worst
		    Θ(log(n)) amortized
		  </entry><entry>
		    Θ(n)
		  </entry></row></tbody></tgroup></informaltable><para>[std note 1] This
	  is not a property of the algorithm, but rather due to the fact
	  that the standard's priority queue implementation does not support
	  iterators (and consequently the ability to access a specific
	  value inside it). If the priority queue is adapting an
	  <classname>std::vector</classname>, then it is still possible to reduce this
	  to Θ(n) by adapting over the standard's adapter and
	  using the fact that <function>top</function> returns a reference to the
	  first value; if, however, it is adapting an
	  <classname>std::deque</classname>, then this is impossible.</para><para>[std note 2] As
	  with [std note 1], this is not a
	  property of the algorithm, but rather the standard's implementation.
	  Again, if the priority queue is adapting an
	  <classname>std::vector</classname> then it is possible to reduce this to
	  Θ(n), but with a very high constant (one must call
	  <function>std::make_heap</function> which is an expensive linear
	  operation); if the priority queue is adapting an
	  <classname>std::deque</classname>, then this is impossible.</para><para>[thin_heap_note] A thin heap has
	  Θ(log(n)) worst case <function>modify</function> time
	  always, but the amortized time depends on the nature of the
	  operation: I) if the operation increases the key (in the sense
	  of the priority queue's comparison functor), then the amortized
	  time is O(1), but if II) it decreases it, then the
	  amortized time is the same as the worst case time. Note that
	  for most algorithms, I) is important and II) is not.</para></section><section xml:id="observations.priority_queue.amortized_ops"><info><title>
	    Amortized <function>push</function>
	    and <function>pop</function> operations
	  </title></info><para>In many cases, a priority queue is needed primarily for
	  sequences of <function>push</function> and <function>pop</function> operations. All of
	  the underlying data structures have the same amortized
	  logarithmic complexity, but they differ in terms of
	  constants.</para><para>The table above shows that the different data structures are
	  "constrained" in some respects. In general, if a data structure
	  has lower worst-case complexity than another, then it will
	  perform slower in the amortized sense. Thus, for example a
	  redundant-counter binomial heap (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>rc_binomial_heap_tag</classname>)
	  has lower worst-case <function>push</function> performance than a binomial
	  heap (<classname>priority_queue</classname>
	  with <classname>Tag</classname> = <classname>binomial_heap_tag</classname>),
	  and so its amortized <function>push</function> performance is slower in
	  terms of constants.</para><para>As the table shows, the "least constrained" underlying
	  data structures are binary heaps and pairing heaps.
	  Consequently, it is not surprising that they perform best in
	  terms of amortized constants.</para><orderedlist><listitem><para>Pairing heaps seem to perform best for non-primitive
	    types (e.g., <classname>std::string</classname>s), as shown by
	    Priority
	    Queue Text <function>push</function> Timing Test and Priority
	    Queue Text <function>push</function> and <function>pop</function> Timing
	    Test</para></listitem><listitem><para>binary heaps seem to perform best for primitive types
	    (e.g., <type>int</type>s), as shown by Priority
	    Queue Random Integer <function>push</function> Timing Test and
	    Priority
	    Queue Random Integer <function>push</function> and <function>pop</function> Timing
	    Test.</para></listitem></orderedlist></section><section xml:id="observations.priority_queue.graphs"><info><title>
	    Graph Algorithms
	  </title></info><para>In some graph algorithms, a decrease-key operation is
	  required [clrs2001];
	  this operation is identical to <function>modify</function> if a value is
	  increased (in the sense of the priority queue's comparison
	  functor). The table above and Priority Queue
	  Text <function>modify</function> Up Timing Test show that a thin heap
	  (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>thin_heap_tag</classname>)
	  outperforms a pairing heap (<classname>priority_queue</classname> with
	  <classname>Tag</classname> = <classname>Tag</classname> = <classname>pairing_heap_tag</classname>),
	  but the rest of the tests show otherwise.</para><para>This makes it difficult to decide which implementation to use in
	  this case. Dijkstra's shortest-path algorithm, for example, requires
	  Θ(n) <function>push</function> and <function>pop</function> operations
	  (in the number of vertices), but O(n<superscript>2</superscript>)
	  <function>modify</function> operations, which can be in practice Θ(n)
	  as well. It is difficult to find an a-priori characterization of
	  graphs in which the actual number of <function>modify</function>
	  operations will dwarf the number of <function>push</function> and
	  <function>pop</function> operations.</para></section></section><!-- priority_queue --></section></section><!-- performance --></section><!-- S05: Reference/Acknowledgments --><section xml:id="pbds.ack"><info><title>Acknowledgments</title></info><?dbhtml filename="policy_data_structures_ack.html"?><para>
      Written by Ami Tavory and Vladimir Dreizin (IBM Haifa Research
      Laboratories), and Benjamin Kosnik (Red Hat).
    </para><para>
      This library was partially written at IBM's Haifa Research Labs.
      It is based heavily on policy-based design and uses many useful
      techniques from Modern C++ Design: Generic Programming and Design
      Patterns Applied by Andrei Alexandrescu.
    </para><para>
      Two ideas are borrowed from the SGI-STL implementation:
    </para><orderedlist><listitem><para>
	  The prime-based resize policies use a list of primes taken from
	  the SGI-STL implementation.
	</para></listitem><listitem><para>
	  The red-black trees contain both a root node and a header node
	  (containing metadata), connected in a way that forward and
	  reverse iteration can be performed efficiently.
	</para></listitem></orderedlist><para>
      Some test utilities borrow ideas from
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/timer/">boost::timer</link>.
    </para><para>
      We would like to thank Scott Meyers for useful comments (without
      attributing to him any flaws in the design or implementation of the
      library).
    </para><para>We would like to thank Matt Austern for the suggestion to
    include tries.</para></section><!-- S06: Biblio --><bibliography version="5.0" xreflabel="Bibliography" xml:id="pbds.biblio"><info><title>Bibliography</title></info><!-- 01 --><biblioentry xml:id="biblio.abrahams97exception"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1075.pdf">
	  STL Exception Handling Contract
	</link></title><date>1997</date><author><personname><firstname>
	    Dave
	  </firstname><surname>
	    Abrahams
	  </surname></personname></author><publisher><publishername>
	  ISO SC22/WG21
	</publishername></publisher></biblioentry><!-- 02 --><biblioentry xml:id="biblio.alexandrescu01modern"><title>
	Modern C++ Design: Generic Programming and Design Patterns Applied
      </title><date>
	2001
      </date><author><personname><firstname>
	    Andrei
	  </firstname><surname>
	    Alexandrescu
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 03 --><biblioentry xml:id="biblio.andrew04mtf"><title>
	MTF, Bit, and COMB: A Guide to Deterministic and Randomized
	Algorithms for the List Update Problem
      </title><authorgroup><author><personname><firstname>
	      K.
	    </firstname><surname>
	      Andrew
	    </surname></personname></author><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Gleich
	    </surname></personname></author></authorgroup></biblioentry><!-- 04 --><biblioentry xml:id="biblio.austern00noset"><title>
	Why You Shouldn't Use set - and What You Should Use Instead
      </title><date>
	April, 2000
      </date><author><personname><firstname>
	    Matthew
	  </firstname><surname>
	    Austern
	  </surname></personname></author><publisher><publishername>
	  C++ Report
	</publishername></publisher></biblioentry><!-- 05 --><biblioentry xml:id="biblio.austern01htprop"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/JTC1/sc22/wg21/docs/papers/2001/n1326.html">
	  A Proposal to Add Hashtables to the Standard Library
	</link></title><date>
	2001
      </date><author><personname><firstname>
	    Matthew
	  </firstname><surname>
	    Austern
	  </surname></personname></author><publisher><publishername>
	  ISO SC22/WG21
	</publishername></publisher></biblioentry><!-- 06 --><biblioentry xml:id="biblio.austern98segmentedit"><title>
	Segmented iterators and hierarchical algorithms
      </title><date>
	April, 1998
      </date><author><personname><firstname>
	    Matthew
	  </firstname><surname>
	    Austern
	  </surname></personname></author><publisher><publishername>
	  Generic Programming
	</publishername></publisher></biblioentry><!-- 07 --><biblioentry xml:id="biblio.dawestimer"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/timer/">
	  Boost Timer Library
	</link></title><author><personname><firstname>
	    Beeman
	  </firstname><surname>
	    Dawes
	  </surname></personname></author><publisher><publishername>
	  Boost
	</publishername></publisher></biblioentry><!-- 08 --><biblioentry xml:id="biblio.clearypool"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/pool/">
	  Boost Pool Library
	</link></title><author><personname><firstname>
	    Stephen
	  </firstname><surname>
	    Cleary
	  </surname></personname></author><publisher><publishername>
	  Boost
	</publishername></publisher></biblioentry><!-- 09 --><biblioentry xml:id="biblio.maddocktraits"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/type_traits/">
	  Boost Type Traits Library
	</link></title><authorgroup><author><personname><firstname>
	      Maddock
	    </firstname><surname>
	      John
	    </surname></personname></author><author><personname><firstname>
	      Stephen
	    </firstname><surname>
	      Cleary
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Boost
	</publishername></publisher></biblioentry><!-- 10 --><biblioentry xml:id="biblio.brodal96priority"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://dl.acm.org/doi/10.5555/313852.313883">
	  Worst-case efficient priority queues
	</link></title><author><personname><firstname>
	    Gerth
	  </firstname><surname>
	    Stolting Brodal
	  </surname></personname></author></biblioentry><!-- 11 --><biblioentry xml:id="biblio.bulkamayheweff"><title>
	Efficient C++ Programming Techniques
      </title><date>
	1997
      </date><authorgroup><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Bulka
	    </surname></personname></author><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Mayhew
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 12 --><biblioentry xml:id="biblio.clrs2001"><title>
	Introduction to Algorithms, 2nd edition
      </title><date>
	2001
      </date><authorgroup><author><personname><firstname>
	      T. H.
	    </firstname><surname>
	      Cormen
	    </surname></personname></author><author><personname><firstname>
	      C. E.
	    </firstname><surname>
	      Leiserson
	    </surname></personname></author><author><personname><firstname>
	      R. L.
	    </firstname><surname>
	      Rivest
	    </surname></personname></author><author><personname><firstname>
	      C.
	    </firstname><surname>
	      Stein
	    </surname></personname></author></authorgroup><publisher><publishername>
	  MIT Press
	</publishername></publisher></biblioentry><!-- 13 --><biblioentry xml:id="biblio.dubhashi98neg"><title>
	Balls and bins: A study in negative dependence
      </title><date>
	1998
      </date><authorgroup><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Dubashi
	    </surname></personname></author><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Ranjan
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Random Structures and Algorithms 13
	</publishername></publisher></biblioentry><!-- 14 --><biblioentry xml:id="biblio.fagin79extendible"><title>
	Extendible hashing - a fast access method for dynamic files
      </title><date>
	1979
      </date><authorgroup><author><personname><firstname>
	      R.
	    </firstname><surname>
	      Fagin
	    </surname></personname></author><author><personname><firstname>
	      J.
	    </firstname><surname>
	      Nievergelt
	    </surname></personname></author><author><personname><firstname>
	      N.
	    </firstname><surname>
	      Pippenger
	    </surname></personname></author><author><personname><firstname>
	      H. R.
	    </firstname><surname>
	      Strong
	    </surname></personname></author></authorgroup><publisher><publishername>
	  ACM Trans. Database Syst. 4
	</publishername></publisher></biblioentry><!-- 15 --><biblioentry xml:id="biblio.filliatre2000ptset"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cristal.inria.fr/~frisch/icfp06_contest/advtr/applyOmatic/ptset.ml">
	  Ptset: Sets of integers implemented as Patricia trees
	</link></title><date>
	2000
      </date><author><personname><firstname>
	    Jean-Christophe
	  </firstname><surname>
	    Filliatre
	  </surname></personname></author></biblioentry><!-- 16 --><biblioentry xml:id="biblio.fredman86pairing"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.cmu.edu/~sleator/papers/pairing-heaps.pdf">
	  The pairing heap: a new form of self-adjusting heap
	</link></title><date>
	1986
      </date><authorgroup><author><personname><firstname>
	      M. L.
	    </firstname><surname>
	      Fredman
	    </surname></personname></author><author><personname><firstname>
	      R.
	    </firstname><surname>
	      Sedgewick
	    </surname></personname></author><author><personname><firstname>
	      D. D.
	    </firstname><surname>
	      Sleator
	    </surname></personname></author><author><personname><firstname>
	      R. E.
	    </firstname><surname>
	      Tarjan
	    </surname></personname></author></authorgroup></biblioentry><!-- 17 --><biblioentry xml:id="biblio.gof"><title>
	Design Patterns - Elements of Reusable Object-Oriented Software
      </title><date>
	1995
      </date><authorgroup><author><personname><firstname>
	      E.
	    </firstname><surname>
	      Gamma
	    </surname></personname></author><author><personname><firstname>
	      R.
	    </firstname><surname>
	      Helm
	    </surname></personname></author><author><personname><firstname>
	      R.
	    </firstname><surname>
	      Johnson
	    </surname></personname></author><author><personname><firstname>
	      J.
	    </firstname><surname>
	      Vlissides
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 18 --><biblioentry xml:id="biblio.garg86order"><title>
	Order-preserving key transformations
      </title><date>
	1986
      </date><authorgroup><author><personname><firstname>
	      A. K.
	    </firstname><surname>
	      Garg
	    </surname></personname></author><author><personname><firstname>
	      C. C.
	    </firstname><surname>
	      Gotlieb
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Trans. Database Syst. 11
	</publishername></publisher></biblioentry><!-- 19 --><biblioentry xml:id="biblio.hyslop02making"><title>
	Making a real hash of things
      </title><date>
	May 2002
      </date><authorgroup><author><personname><firstname>
	      J.
	    </firstname><surname>
	      Hyslop
	    </surname></personname></author><author><personname><firstname>
	      Herb
	    </firstname><surname>
	      Sutter
	    </surname></personname></author></authorgroup><publisher><publishername>
	  C++ Report
	</publishername></publisher></biblioentry><!-- 20 --><biblioentry xml:id="biblio.jossutis01stl"><title>
	The C++ Standard Library - A Tutorial and Reference
      </title><date>
	2001
      </date><author><personname><firstname>
	    N. M.
	  </firstname><surname>
	    Jossutis
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 21 --><biblioentry xml:id="biblio.kt99fat_heaps"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.cs.princeton.edu/research/techreps/293">
	  New Heap Data Structures
	</link></title><date>
	1999
      </date><authorgroup><author><personname><firstname>
	      Haim
	    </firstname><surname>
	      Kaplan
	    </surname></personname></author><author><personname><firstname>
	      Robert E.
	    </firstname><surname>
	      Tarjan
	    </surname></personname></author></authorgroup></biblioentry><!-- 22 --><biblioentry xml:id="biblio.kleft00sets"><title>
	Are Set Iterators Mutable or Immutable?
      </title><date>
	October 2000
      </date><authorgroup><author><personname><firstname>
	      Angelika
	    </firstname><surname>
	      Langer
	    </surname></personname></author><author><personname><firstname>
	      Klaus
	    </firstname><surname>
	      Kleft
	    </surname></personname></author></authorgroup><publisher><publishername>
	  C/C++ Users Jornal
	</publishername></publisher></biblioentry><!-- 23 --><biblioentry xml:id="biblio.knuth98sorting"><title>
	The Art of Computer Programming - Sorting and Searching
      </title><date>
	1998
      </date><author><personname><firstname>
	    D. E.
	  </firstname><surname>
	    Knuth
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 24 --><biblioentry xml:id="biblio.liskov98data"><title>
	Data abstraction and hierarchy
      </title><date>
	May 1998
      </date><author><personname><firstname>
	    B.
	  </firstname><surname>
	    Liskov
	  </surname></personname></author><publisher><publishername>
	  SIGPLAN Notices 23
	</publishername></publisher></biblioentry><!-- 25 --><biblioentry xml:id="biblio.litwin80lh"><title>
	Linear hashing: A new tool for file and table addressing
      </title><date>
	June 1980
      </date><author><personname><firstname>
	    W.
	  </firstname><surname>
	    Litwin
	  </surname></personname></author><publisher><publishername>
	  Proceedings of International Conference on Very Large Data Bases
	</publishername></publisher></biblioentry><!-- 26 --><biblioentry xml:id="biblio.maverick_lowerbounds"><title>
	Deamortization - Part 2: Binomial Heaps
      </title><date>
	2005
      </date><author><personname><firstname>
	    Maverick
	  </firstname><surname>
	    Woo
	  </surname></personname></author></biblioentry><!-- 27 --><biblioentry xml:id="biblio.meyers96more"><title>
	More Effective C++: 35 New Ways to Improve Your Programs and Designs
      </title><date>
	1996
      </date><author><personname><firstname>
	    Scott
	  </firstname><surname>
	    Meyers
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 28 --><biblioentry xml:id="biblio.meyers00nonmember"><title>
	How Non-Member Functions Improve Encapsulation
      </title><date>
	2000
      </date><author><personname><firstname>
	    Scott
	  </firstname><surname>
	    Meyers
	  </surname></personname></author><publisher><publishername>
	  C/C++ Users Journal
	</publishername></publisher></biblioentry><!-- 29 --><biblioentry xml:id="biblio.meyers01stl"><title>
	Effective STL: 50 Specific Ways to Improve Your Use of the Standard Template Library
      </title><date>
	2001
      </date><author><personname><firstname>
	    Scott
	  </firstname><surname>
	    Meyers
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 30 --><biblioentry xml:id="biblio.meyers02both"><title>
	Class Template, Member Template - or Both?
      </title><date>
	2003
      </date><author><personname><firstname>
	    Scott
	  </firstname><surname>
	    Meyers
	  </surname></personname></author><publisher><publishername>
	  C/C++ Users Journal
	</publishername></publisher></biblioentry><!-- 31 --><biblioentry xml:id="biblio.motwani95random"><title>
	Randomized Algorithms
      </title><date>
	2003
      </date><authorgroup><author><personname><firstname>
	      R.
	    </firstname><surname>
	      Motwani
	    </surname></personname></author><author><personname><firstname>
	      P.
	    </firstname><surname>
	      Raghavan
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Cambridge University Press
	</publishername></publisher></biblioentry><!-- 32 --><biblioentry xml:id="biblio.mscom"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://learn.microsoft.com/en-us/windows/win32/com/the-component-object-model">
	  The Component Object Model
	</link></title><publisher><publishername>
	  Microsoft
	</publishername></publisher></biblioentry><!-- 33 --><biblioentry xml:id="biblio.musser95rationale"><title>
	Rationale for Adding Hash Tables to the C++ Standard Template Library
      </title><date>
	1995
      </date><author><personname><firstname>
	    David R.
	  </firstname><surname>
	    Musser
	  </surname></personname></author></biblioentry><!-- 35 --><biblioentry xml:id="biblio.musser96stltutorial"><title>
	STL Tutorial and Reference Guide
      </title><date>
	1996
      </date><authorgroup><author><personname><firstname>
	      David R.
	    </firstname><surname>
	      Musser
	    </surname></personname></author><author><personname><firstname>
	      A.
	    </firstname><surname>
	      Saini
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 36 --><biblioentry xml:id="biblio.nelson96stlpq"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20240806213010/https://marknelson.us/posts/1996/01/01/priority-queues.html">Priority Queues and the STL
	</link></title><date>
	January 1996
      </date><author><personname><firstname>
	    Mark
	  </firstname><surname>
	    Nelson
	  </surname></personname></author><publisher><publishername>
	  Dr. Dobbs Journal
	</publishername></publisher></biblioentry><!-- 37 --><biblioentry xml:id="biblio.okasaki98mereable"><title>
	Fast mergeable integer maps
      </title><date>
	September 1998
      </date><authorgroup><author><personname><firstname>
	      C.
	    </firstname><surname>
	      Okasaki
	    </surname></personname></author><author><personname><firstname>
	      A.
	    </firstname><surname>
	      Gill
	    </surname></personname></author></authorgroup><publisher><publishername>
	  In Workshop on ML
	</publishername></publisher></biblioentry><!-- 38 --><biblioentry xml:id="biblio.sgi_stl"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/">
	  Standard Template Library Programmer's Guide
	</link></title><author><personname><firstname>
	    Matt
	  </firstname><surname>
	    Austern
	  </surname></personname></author><publisher><publishername>
	  SGI
	</publishername></publisher></biblioentry><!-- 39 --><biblioentry xml:id="biblio.select_man"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html">
	  select
	</link></title></biblioentry><!-- 40 --><biblioentry xml:id="biblio.sleator84amortized"><title>
	Amortized Efficiency of List Update Problems
      </title><date>
	1984
      </date><authorgroup><author><personname><firstname>
	      D. D.
	    </firstname><surname>
	      Sleator
	    </surname></personname></author><author><personname><firstname>
	      R. E.
	    </firstname><surname>
	      Tarjan
	    </surname></personname></author></authorgroup><publisher><publishername>
	  ACM Symposium on Theory of Computing
	</publishername></publisher></biblioentry><!-- 41 --><biblioentry xml:id="biblio.sleator85self"><title>
	Self-Adjusting Binary Search Trees
      </title><date>
	1985
      </date><authorgroup><author><personname><firstname>
	      D. D.
	    </firstname><surname>
	      Sleator
	    </surname></personname></author><author><personname><firstname>
	      R. E.
	    </firstname><surname>
	      Tarjan
	    </surname></personname></author></authorgroup><publisher><publishername>
	  ACM Symposium on Theory of Computing
	</publishername></publisher></biblioentry><!-- 42 --><biblioentry xml:id="biblio.stepanov94standard"><title>
	The Standard Template Library
      </title><date>
	1984
      </date><authorgroup><author><personname><firstname>
	      A. A.
	    </firstname><surname>
	      Stepanov
	    </surname></personname></author><author><personname><firstname>
	      M.
	    </firstname><surname>
	      Lee
	    </surname></personname></author></authorgroup></biblioentry><!-- 43 --><biblioentry xml:id="biblio.stroustrup97cpp"><title>
	The C++ Programming Langugage
      </title><date>
	1997
      </date><author><personname><firstname>
	    Bjarne
	  </firstname><surname>
	    Stroustrup
	  </surname></personname></author><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 44 --><biblioentry xml:id="biblio.vandevoorde2002cpptemplates"><title>
	C++ Templates: The Complete Guide
      </title><date>
	2002
      </date><authorgroup><author><personname><firstname>
	      D.
	    </firstname><surname>
	      Vandevoorde
	    </surname></personname></author><author><personname><firstname>
	      N. M.
	    </firstname><surname>
	      Josuttis
	    </surname></personname></author></authorgroup><publisher><publishername>
	  Addison-Wesley Publishing Company
	</publishername></publisher></biblioentry><!-- 45 --><biblioentry xml:id="biblio.wickland96thirty"><title>
	Thirty Years Among the Dead
      </title><date>
	1996
      </date><author><personname><firstname>
	    C. A.
	  </firstname><surname>
	    Wickland
	  </surname></personname></author><publisher><publishername>
	  National Psychological Institute
	</publishername></publisher></biblioentry></bibliography></chapter><!-- Chapter 08 : HP/SGI --><chapter xreflabel="Containers" xml:id="manual.ext.containers"><info><title>HP/SGI Extensions</title></info><?dbhtml filename="ext_containers.html"?><section xreflabel="SGI ext" xml:id="manual.ext.containers.sgi"><info><title>Backwards Compatibility</title></info><para>A few extensions and nods to backwards-compatibility have
    been made with containers.  Those dealing with older SGI-style
    allocators are dealt with elsewhere.  The remaining ones all deal
    with bits:
    </para><para>The old pre-standard <code>bit_vector</code> class is
    present for backwards compatibility.  It is simply a typedef for
    the <code>vector&lt;bool&gt;</code> specialization.
    </para><para>The <code>bitset</code> class has a number of extensions, described in the
   rest of this item.  First, we'll mention that this implementation of
   <code>bitset&lt;N&gt;</code> is specialized for cases where N number of
   bits will fit into a single word of storage.  If your choice of N is
   within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
   of the operations will be faster.
</para><para>There are
   versions of single-bit test, set, reset, and flip member functions which
   do no range-checking.  If we call them member functions of an instantiation
   of <code>bitset&lt;N&gt;</code>, then their names and signatures are:
</para><programlisting>
   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos, int val);
   bitset&lt;N&gt;&amp;   _Unchecked_reset (size_t pos);
   bitset&lt;N&gt;&amp;   _Unchecked_flip  (size_t pos);
   bool         _Unchecked_test  (size_t pos);
</programlisting><para>Note that these may in fact be removed in the future, although we have
   no present plans to do so (and there doesn't seem to be any immediate
   reason to).
</para><para>The member function <code>operator[]</code> on a const bitset returns
   a bool, and for a non-const bitset returns a <code>reference</code> (a
   nested type).  No range-checking is done on the index argument, in keeping
   with other containers' <code>operator[]</code> requirements.
</para><para>Finally, two additional searching functions have been added.  They return
   the index of the first "on" bit, and the index of the first
   "on" bit that is after <code>prev</code>, respectively:
</para><programlisting>
   size_t _Find_first() const;
   size_t _Find_next (size_t prev) const;</programlisting><para>The same caveat given for the _Unchecked_* functions applies here also.
</para></section><section xreflabel="SGI ext dep" xml:id="manual.ext.containers.deprecated_sgi"><info><title>Deprecated</title></info><?dbhtml filename="ext_sgi.html"?><para>
     The SGI hashing classes <classname>hash_set</classname> and
     <classname>hash_set</classname> have been deprecated by the
     unordered_set, unordered_multiset, unordered_map,
     unordered_multimap containers in TR1 and C++11, and
     may be removed in future releases.
   </para><para>The SGI headers</para><programlisting>
     &lt;hash_map&gt;
     &lt;hash_set&gt;
     &lt;rope&gt;
     &lt;slist&gt;
     &lt;rb_tree&gt;
</programlisting><para>are all here;
      <filename class="headerfile">&lt;backwards/hash_map&gt;</filename> and
      <filename class="headerfile">&lt;backwards/hash_set&gt;</filename>
      are deprecated but available as backwards-compatible extensions,
      as discussed further below.
      <filename class="headerfile">&lt;ext/rope&gt;</filename> is the SGI
      specialization for large strings ("rope," "large strings," get it? Love
      that geeky humor.)
      <filename class="headerfile">&lt;ext/slist&gt;</filename> (superseded in
      C++11 by <filename class="headerfile">&lt;forward_list&gt;</filename>)
      is a singly-linked list, for when the doubly-linked <code>list&lt;&gt;</code>
      is too much space overhead, and
      <filename class="headerfile">&lt;ext/rb_tree&gt;</filename> exposes the
      red-black tree classes used in the implementation of the standard maps
      and sets.
   </para><para>Each of the associative containers map, multimap, set, and multiset
      have a counterpart which uses a
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171230172024/http://www.sgi.com/tech/stl/HashFunction.html">hashing
      function</link> to do the arranging, instead of a strict weak ordering
      function.  The classes take as one of their template parameters a
      function object that will return the hash value; by default, an
      instantiation of
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171230172200/http://www.sgi.com/tech/stl/hash.html">hash</link>.
      You should specialize this functor for your class, or define your own,
      before trying to use one of the hashing classes.
   </para><para>The hashing classes support all the usual associative container
      functions, as well as some extra constructors specifying the number
      of buckets, etc.
   </para><para>Why would you want to use a hashing class instead of the
      <quote>normal</quote>implementations?  Matt Austern writes:
   </para><blockquote><para><emphasis>[W]ith a well chosen hash function, hash tables
       generally provide much better average-case performance than
       binary search trees, and much worse worst-case performance.  So
       if your implementation has hash_map, if you don't mind using
       nonstandard components, and if you aren't scared about the
       possibility of pathological cases, you'll probably get better
       performance from hash_map.
     </emphasis></para></blockquote><para>
      The deprecated hash tables are superseded by the standard unordered
      associative containers defined in the ISO C++ 2011 standard in the
      headers <filename class="headerfile">&lt;unordered_map&gt;</filename>
      and <filename class="headerfile">&lt;unordered_set&gt;</filename>.
   </para></section></chapter><!-- Chapter 09 : Utilities --><chapter xreflabel="Utilities" xml:id="manual.ext.util"><info><title>Utilities</title></info><?dbhtml filename="ext_utilities.html"?><para>
    The <filename class="headerfile">&lt;functional&gt;</filename> header
    contains many additional functors
    and helper functions, extending section 20.3.  They are
    implemented in the file stl_function.h:
  </para><itemizedlist><listitem><para><code>identity_element</code> for addition and multiplication.
  </para></listitem><listitem><para>The functor <code>identity</code>, whose <code>operator()</code>
      returns the argument unchanged.
  </para></listitem><listitem><para>Composition functors <code>unary_function</code> and
      <code>binary_function</code>, and their helpers <code>compose1</code>
      and <code>compose2</code>.
    </para></listitem><listitem><para><code>select1st</code> and <code>select2nd</code>, to strip pairs.
  </para></listitem><listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem><listitem><para>A set of functors/functions which always return the same result.  They
      are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
      <code>constant_unary_fun</code>, <code>constant0</code>,
      <code>constant1</code>, and <code>constant2</code>. </para></listitem><listitem><para>The class <code>subtractive_rng</code>. </para></listitem><listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
      <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem></itemizedlist><para>
  20.4.1 can use several different allocators; they are described on the
   main extensions page.
</para><para>
  20.4.3 is extended with a special version of
  <code>get_temporary_buffer</code> taking a second argument.  The
  argument is a pointer, which is ignored, but can be used to specify
  the template type (instead of using explicit function template
  arguments like the standard version does).  That is, in addition to
</para><programlisting>
get_temporary_buffer&lt;int&gt;(5);
</programlisting><para>
you can also use
</para><programlisting>
get_temporary_buffer(5, (int*)0);
</programlisting><para>
  A class <code>temporary_buffer</code> is given in stl_tempbuf.h.
</para><para>
  The specialized algorithms of section 20.4.4 are extended with
  <code>uninitialized_copy_n</code>.
</para></chapter><!-- Chapter 10 : Algorithms --><chapter xreflabel="Algorithms" xml:id="manual.ext.algorithms"><info><title>Algorithms</title></info><?dbhtml filename="ext_algorithms.html"?><para>25.1.6 (count, count_if) is extended with two more versions of count
   and count_if.  The standard versions return their results.  The
   additional signatures return void, but take a final parameter by
   reference to which they assign their results, e.g.,
</para><programlisting>
   void count (first, last, value, n);</programlisting><para>25.2 (mutating algorithms) is extended with two families of signatures,
   random_sample and random_sample_n.
</para><para>25.2.1 (copy) is extended with
</para><programlisting>
   copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting><para>which copies the first 'count' elements at 'first' into 'result'.
</para><para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
   predicates.  Look in the doxygen-generated pages for notes on these.
</para><itemizedlist><listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem><listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
	nondescending order.</para></listitem></itemizedlist><para>25.3.8 (lexicographical_compare) is extended with
</para><programlisting>
   lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
				 _InputIter2 first2, _InputIter2 last2)</programlisting><para>which does... what?
</para></chapter><!-- Chapter 11 : Numerics --><chapter xreflabel="Numerics" xml:id="manual.ext.numerics"><info><title>Numerics</title></info><?dbhtml filename="ext_numerics.html"?><para>26.4, the generalized numeric operations such as <code>accumulate</code>,
   are extended with the following functions:
</para><programlisting>
   power (x, n);
   power (x, n, monoid_operation);</programlisting><para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where
   <code>n &gt;= 0</code>.  In the
   case of <code>n == 0</code>, returns the identity element for the
   monoid operation.  The two-argument signature uses multiplication (for
   a true "power" implementation), but addition is supported as well.
   The operation functor must be associative.
</para><para>The <code>iota</code> function wins the award for Extension With the
   Coolest Name (the name comes from Ken Iverson's APL language.)  As
   described in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20170201044840/http://www.sgi.com/tech/stl/iota.html">SGI
   documentation</link>, it "assigns sequentially increasing values to a range.
   That is, it assigns <code>value</code> to <code>*first</code>,
   <code>value + 1</code> to<code> *(first + 1)</code> and so on."
</para><programlisting>
   void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting><para>The <code>iota</code> function is included in the ISO C++ 2011 standard.
</para></chapter><!-- Chapter 12 : Iterators --><chapter xreflabel="Iterators" xml:id="manual.ext.iterators"><info><title>Iterators</title></info><?dbhtml filename="ext_iterators.html"?><para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
   original HP STL implementation (the language wasn't rich enough at the
   time).  For backwards compatibility, base classes are provided which
   declare the same nested typedefs:
</para><itemizedlist><listitem><para>input_iterator</para></listitem><listitem><para>output_iterator</para></listitem><listitem><para>forward_iterator</para></listitem><listitem><para>bidirectional_iterator</para></listitem><listitem><para>random_access_iterator</para></listitem></itemizedlist><para>24.3.4 describes iterator operation <code>distance</code>, which takes
   two iterators and returns a result.  It is extended by another signature
   which takes two iterators and a reference to a result.  The result is
   modified, and the function returns nothing.
</para></chapter><!-- Chapter 13 : IO --><chapter xreflabel="IO" xml:id="manual.ext.io"><info><title>Input and Output</title></info><?dbhtml filename="ext_io.html"?><para>
    Extensions allowing <code>filebuf</code>s to be constructed from
    "C" types like  FILE*s and file descriptors.
  </para><section xreflabel="Derived filebufs" xml:id="manual.ext.io.filebuf_derived"><info><title>Derived filebufs</title></info><para>The v2 library included non-standard extensions to construct
      <code>std::filebuf</code>s from C stdio types such as
      <code>FILE*</code>s and POSIX file descriptors.
      Today the recommended way to use stdio types with libstdc++
      IOStreams is via the <code>stdio_filebuf</code> class (see below),
      but earlier releases provided slightly different mechanisms.
   </para><itemizedlist><listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature:
	<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
	</code>
	 This comes in very handy in a number of places, such as
	 attaching Unix sockets, pipes, and anything else which uses file
	 descriptors, into the IOStream buffering classes.  The three
	 arguments are as follows:
	 <itemizedlist><listitem><para><code>__c_file_type*      F   </code>
	      // the __c_file_type typedef usually boils down to stdio's FILE
	  </para></listitem><listitem><para><code>ios_base::openmode  M   </code>
	      // same as all the other uses of openmode
	  </para></listitem><listitem><para><code>int_type            B   </code>
	      // buffer size, defaults to BUFSIZ if not specified
	  </para></listitem></itemizedlist>
	 For those wanting to use file descriptors instead of FILE*'s, I
	 invite you to contemplate the mysteries of C's <code>fdopen()</code>.
     </para></listitem><listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
	 back an old extension:  the <code>fd()</code> member function.  The
	 integer returned from this function can be used for whatever file
	 descriptors can be used for on your platform.  Naturally, the
	 library cannot track what you do on your own with a file descriptor,
	 so if you perform any I/O directly, don't expect the library to be
	 aware of it.
     </para></listitem><listitem><para>Beginning with 3.1, the extra
	 <classname>basic_filebuf</classname> constructor and
	 the <code>fd()</code> function were removed from the standard
	 filebuf.  Instead,
	 <filename class="headerfile">&lt;ext/stdio_filebuf.h&gt;</filename>
	 contains a derived class template called
	 <classname>__gnu_cxx::stdio_filebuf</classname>.
	 This class can be constructed from a C <code>FILE*</code> or a file
	 descriptor, and provides the <code>fd()</code> function.
     </para></listitem></itemizedlist></section></chapter><!-- Chapter 14 : Demangling --><chapter xreflabel="Demangling" xml:id="manual.ext.demangle"><info><title>Demangling</title></info><?dbhtml filename="ext_demangling.html"?><para>
    Transforming C++ ABI identifiers (like RTTI symbols) into the
    original C++ source identifiers is called
    <quote>demangling.</quote>
  </para><para>
    If you have read the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">source
    documentation for <code>namespace abi</code></link> then you are
    aware of the cross-vendor C++ ABI in use by GCC.  One of the
    exposed functions is used for demangling,
    <code>abi::__cxa_demangle</code>.
  </para><para>
    In programs like <command>c++filt</command>, the linker, and other tools
    have the ability to decode C++ ABI names, and now so can you.
  </para><para>
    (The function itself might use different demanglers, but that's the
    whole point of abstract interfaces.  If we change the implementation,
    you won't notice.)
  </para><para>
    Probably the only time you'll be interested in demangling at runtime
    is when you're seeing <code>typeid</code> strings in RTTI.  For example:
  </para><programlisting>
#include &lt;iostream&gt;
#include &lt;cstdlib&gt;
#include &lt;cxxabi.h&gt;

struct empty { };

template &lt;typename T, int N&gt;
  struct bar { };

int main()
{
  int     status;
  char   *realname;

  // typeid
  bar&lt;empty,17&gt;          u;
  const std::type_info  &amp;ti = typeid(u);

  realname = abi::__cxa_demangle(ti.name(), NULL, NULL, &amp;status);
  std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
  std::free(realname);
}
</programlisting><para>
     This prints
   </para><screen><computeroutput>
      3barI5emptyLi17EE       =&gt; bar&lt;empty, 17&gt;       : 0
   </computeroutput></screen><para>
     The demangler interface is described in the source documentation
     linked to above.  It is actually written in C, so you don't need to
     be writing C++ in order to demangle C++.  (That also means we have to
     use crummy memory management facilities, so don't forget to
     <code>free()</code> the returned char array.)
   </para></chapter><!-- Chapter 15 : Concurrency --><chapter version="5.0" xreflabel="Concurrency Extensions" xml:id="manual.ext.concurrency"><?dbhtml filename="ext_concurrency.html"?><info><title>Concurrency</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><section xreflabel="Design" xml:id="manual.ext.concurrency.design"><info><title>Design</title></info><section xreflabel="Threads API" xml:id="manual.ext.concurrency.design.threads"><info><title>Interface to Locks and Mutexes</title></info><para>The file <filename class="headerfile">&lt;ext/concurrence.h&gt;</filename>
contains all the higher-level
constructs for playing with threads. In contrast to the atomics layer,
the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
</para><para>
These types can be used in a portable manner, regardless of the
specific environment. They are carefully designed to provide optimum
efficiency and speed, abstracting out underlying thread calls and
accesses when compiling for single-threaded situations (even on hosts
that support multiple threads.)
</para><para>The enumerated type <code>_Lock_policy</code> details the set of
available locking
policies: <code>_S_single</code>, <code>_S_mutex</code>,
and <code>_S_atomic</code>.
</para><itemizedlist><listitem><para><code>_S_single</code></para><para>Indicates single-threaded code that does not need locking.
</para></listitem><listitem><para><code>_S_mutex</code></para><para>Indicates multi-threaded code using thread-layer abstractions.
</para></listitem><listitem><para><code>_S_atomic</code></para><para>Indicates multi-threaded code using atomic operations.
</para></listitem></itemizedlist><para>The compile-time constant <code>__default_lock_policy</code> is set
to one of the three values above, depending on characteristics of the
host environment and the current compilation flags.
</para><para>Two more datatypes make up the rest of the
interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
</para><para>The scoped lock idiom is well-discussed within the C++
community. This version takes a <code>__mutex</code> reference, and
locks it during construction of <code>__scoped_lock</code> and
unlocks it during destruction. This is an efficient way of locking
critical sections, while retaining exception-safety.
These types have been superseded in the ISO C++ 2011 standard by the
mutex and lock types defined in the header
<filename class="headerfile">&lt;mutex&gt;</filename>.
</para></section><section xreflabel="Atomic API" xml:id="manual.ext.concurrency.design.atomics"><info><title>Interface to Atomic Functions</title></info><para>
Two functions and one type form the base of atomic support.
</para><para>The type <code>_Atomic_word</code> is a signed integral type
supporting atomic operations.
</para><para>
The two functions functions are:
</para><programlisting>
_Atomic_word
__exchange_and_add_dispatch(volatile _Atomic_word*, int);

void
__atomic_add_dispatch(volatile _Atomic_word*, int);
</programlisting><para>Both of these functions are declared in the header file
&lt;ext/atomicity.h&gt;, and are in <code>namespace __gnu_cxx</code>.
</para><itemizedlist><listitem><para><code>
__exchange_and_add_dispatch
</code></para><para>Adds the second argument's value to the first argument. Returns the old value.
</para></listitem><listitem><para><code>
__atomic_add_dispatch
</code></para><para>Adds the second argument's value to the first argument. Has no return value.
</para></listitem></itemizedlist><para>
These functions forward to one of several specialized helper
functions, depending on the circumstances. For instance,
</para><para><code>
__exchange_and_add_dispatch
</code></para><para>
Calls through to either of:
</para><itemizedlist><listitem><para><code>__exchange_and_add</code></para><para>Multi-thread version. Inlined if compiler-generated builtin atomics
can be used, otherwise resolved at link time to a non-builtin code
sequence.
</para></listitem><listitem><para><code>__exchange_and_add_single</code></para><para>Single threaded version. Inlined.</para></listitem></itemizedlist><para>However, only <code>__exchange_and_add_dispatch</code>
and <code>__atomic_add_dispatch</code> should be used. These functions
can be used in a portable manner, regardless of the specific
environment. They are carefully designed to provide optimum efficiency
and speed, abstracting out atomic accesses when they are not required
(even on hosts that support compiler intrinsics for atomic
operations.)
</para><para>
In addition, there are two macros
</para><para><code>
_GLIBCXX_READ_MEM_BARRIER
</code></para><para><code>
_GLIBCXX_WRITE_MEM_BARRIER
</code></para><para>
Which expand to the appropriate write and read barrier required by the
host hardware and operating system.
</para></section></section><section xreflabel="Implementation" xml:id="manual.ext.concurrency.impl"><info><title>Implementation</title></info><?dbhtml filename="ext_concurrency_impl.html"?><section xreflabel="Atomic F" xml:id="manual.ext.concurrency.impl.atomic_fallbacks"><info><title>Using Built-in Atomic Functions</title></info><para>The functions for atomic operations described above are either
implemented via compiler intrinsics (if the underlying host is
capable) or by library fallbacks.</para><para>Compiler intrinsics (builtins) are always preferred.  However, as
the compiler builtins for atomics are not universally implemented,
using them directly is problematic, and can result in undefined
function calls.
</para><para>Prior to GCC 4.7 the older <code>__sync</code> intrinsics were used.
An example of an undefined symbol from the use
of <code>__sync_fetch_and_add</code> on an unsupported host is a
missing reference to <code>__sync_fetch_and_add_4</code>.
</para><para>Current releases use the newer <code>__atomic</code> intrinsics,
which are implemented by library calls if the hardware doesn't support them.
Undefined references to functions like
<code>__atomic_is_lock_free</code> should be resolved by linking to
<filename class="libraryfile">libatomic</filename>, which is usually
installed alongside libstdc++.
</para><para>In addition, on some hosts the compiler intrinsics are enabled
conditionally, via the <code>-march</code> command line flag. This makes
usage vary depending on the target hardware and the flags used during
compile.
</para><para><remark>
Incomplete/inconsistent. This is only C++11.
</remark></para><para>
If builtins are possible for bool-sized integral types,
<code>ATOMIC_BOOL_LOCK_FREE</code> will be defined.
If builtins are possible for int-sized integral types,
<code>ATOMIC_INT_LOCK_FREE</code> will be defined.
</para><para>For the following hosts, intrinsics are enabled by default.
</para><itemizedlist><listitem><para>alpha</para></listitem><listitem><para>ia64</para></listitem><listitem><para>powerpc</para></listitem><listitem><para>s390</para></listitem></itemizedlist><para>For others, some form of <code>-march</code> may work. On
non-ancient x86 hardware, <code>-march=native</code> usually does the
trick.</para><para> For hosts without compiler intrinsics, but with capable
hardware, hand-crafted assembly is selected. This is the case for the following hosts:
</para><itemizedlist><listitem><para>cris</para></listitem><listitem><para>hppa</para></listitem><listitem><para>i386</para></listitem><listitem><para>i486</para></listitem><listitem><para>m48k</para></listitem><listitem><para>mips</para></listitem><listitem><para>sparc</para></listitem></itemizedlist><para>And for the rest, a simulated atomic lock via pthreads.
</para><para>Detailed information about compiler intrinsics for atomic operations can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html"> documentation</link>.
</para><para> More details on the library fallbacks from the porting <link linkend="internals.thread_safety">section</link>.
</para></section><section xreflabel="Pthread" xml:id="manual.ext.concurrency.impl.thread"><info><title>Thread Abstraction</title></info><para>A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract
the thread interface for GCC. This layer is called "gthread," and is
comprised of one header file that wraps the host's default thread layer with
a POSIX-like interface.
</para><para> The file &lt;gthr-default.h&gt; points to the deduced wrapper for
the current host. In libstdc++ implementation files,
&lt;bits/gthr.h&gt; is used to select the proper gthreads file.
</para><para>Within libstdc++ sources, all calls to underlying thread functionality
use this layer. More detail as to the specific interface can be found in the source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html">documentation</link>.
</para><para>By design, the gthread layer is interoperable with the types,
functions, and usage found in the usual &lt;pthread.h&gt; file,
including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
etc.
</para></section></section><section xreflabel="Use" xml:id="manual.ext.concurrency.use"><info><title>Use</title></info><?dbhtml filename="ext_concurrency_use.html"?><para>Typical usage of the last two constructs is demonstrated as follows:
</para><programlisting>
#include &lt;ext/concurrence.h&gt;

namespace
{
  __gnu_cxx::__mutex safe_base_mutex;
} // anonymous namespace

namespace other
{
  void
  foo()
  {
    __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
    for (int i = 0; i &lt; max;  ++i)
      {
	_Safe_iterator_base* __old = __iter;
	__iter = __iter-&lt;_M_next;
	__old-&lt;_M_detach_single();
      }
}
</programlisting><para>In this sample code, an anonymous namespace is used to keep
the <code>__mutex</code> private to the compilation unit,
and <code>__scoped_lock</code> is used to guard access to the critical
section within the for loop, locking the mutex on creation and freeing
the mutex as control moves out of this block.
</para><para>Several exception classes are used to keep track of
concurrence-related errors. These classes
are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
and <code>__concurrence_broadcast_error</code>.
</para></section></chapter></part><!-- Part 04 : Appendices --><part xreflabel="Appendices" xml:id="appendix"><info><title>
  Appendices
</title></info><?dbhtml filename="appendix.html"?><!-- Appendix A --><appendix version="5.0" xreflabel="Contributing" xml:id="appendix.contrib"><?dbhtml filename="appendix_contributing.html"?><info><title>
  Contributing
  <indexterm><primary>Appendix</primary><secondary>Contributing</secondary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><para>
  The GNU C++ Library is part of GCC and follows the same development model,
  so the general rules for
  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html">contributing
  to GCC</link> apply. Active
  contributors are assigned maintainership responsibility, and given
  write access to the source repository. First-time contributors
  should follow this procedure:
</para><section xreflabel="Contributor Checklist" xml:id="contrib.list"><info><title>Contributor Checklist</title></info><section xml:id="list.reading"><info><title>Reading</title></info><itemizedlist><listitem><para>
	  Get and read the relevant sections of the C++ language
	  specification. Copies of the full ISO 14882 standard are
	  available on line via the ISO mirror site for committee
	  members. Non-members, or those who have not paid for the
	  privilege of sitting on the committee and sustained their
	  two meeting commitment for voting rights, may get a copy of
	  the standard from their respective national standards
	  organization. In the USA, this national standards
	  organization is
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ansi.org">ANSI</link>.
	  (And if you've already registered with them you can <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://webstore.ansi.org/standards/iso/isoiec148822014">buy
	  the standard on-line</link>.)
	</para></listitem><listitem><para>
	  The library working group bugs, and known defects, can
	  be obtained here:
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/">https://www.open-std.org/jtc1/sc22/wg21</link>
	</para></listitem><listitem><para>
	  Peruse
	  the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/">GNU
	  Coding Standards</link>, and chuckle when you hit the part
	  about <quote>Using Languages Other Than C</quote>.
	</para></listitem><listitem><para>
	  Be familiar with the extensions that preceded these
	  general GNU rules. These style issues for libstdc++ can be
	  found in <link linkend="contrib.coding_style">Coding Style</link>.
      </para></listitem><listitem><para>
	  And last but certainly not least, read the
	  library-specific information found in
          <link linkend="appendix.porting">Porting and Maintenance</link>.
      </para></listitem></itemizedlist></section><section xml:id="list.copyright"><info><title>Assignment</title></info><para>
      See the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html#legal">legal prerequisites</link> for all GCC contributions.
    </para><para>
      Historically, the libstdc++ assignment form added the following
      question:
    </para><para><quote>
	Which Belgian comic book character is better, Tintin or Asterix, and
	why?
      </quote></para><para>
      While not strictly necessary, humoring the maintainers and answering
      this question would be appreciated.
    </para><para>
      Please contact
      Jonathan Wakely at <email>jwakely+assign@redhat.com</email>
      if you are confused about the assignment or have general licensing
      questions. When requesting an assignment form from
      <email>assign@gnu.org</email>, please CC the libstdc++
      maintainer above so that progress can be monitored.
    </para></section><section xml:id="list.getting"><info><title>Getting Sources</title></info><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Getting write access
	(look for "Write after approval")</link></para></section><section xml:id="list.patches"><info><title>Submitting Patches</title></info><para>
      Every patch must have several pieces of information before it can be
      properly evaluated. Ideally (and to ensure the fastest possible
      response from the maintainers) it would have all of these pieces:
    </para><itemizedlist><listitem><para>
	  A description of the bug and how your patch fixes this
	  bug. For new features a description of the feature and your
	  implementation.
	</para></listitem><listitem><para>
	  A ChangeLog entry as part of the Git commit message. Check
	  some recent commits for format and content. The
	  <filename>contrib/mklog.py</filename> script can be used to
	  generate a ChangeLog template for commit messages. See
	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Read-write Git access</link>
	  for scripts and aliases that are useful here.
	</para></listitem><listitem><para>
	  A testsuite submission or sample program that will
	  easily and simply show the existing error or test new
	  functionality.
	</para></listitem><listitem><para>
	  The patch itself. If you are using the Git repository use
	  <command>git show</command> or <command>git format-patch</command>
	  to produce a patch;
	  otherwise, use <command>diff -cp OLD NEW</command>. If your
	  version of diff does not support these options, then get the
	  latest version of GNU diff.
	</para></listitem><listitem><para>
	  When you have all these pieces, bundle them up in a
	  mail message and send it to libstdc++@gcc.gnu.org. All
	  patches and related discussion should be sent to the
	  libstdc++ mailing list. In common with the rest of GCC,
	  patches should also be sent to the gcc-patches mailing list.
	  So you could send your email To:libstdc++@gcc.gnu.org and
	  Cc:gcc-patches@gcc.gnu.org for example.
	</para></listitem></itemizedlist></section></section><section xreflabel="Source Organization" xml:id="contrib.organization"><info><title>Directory Layout and Source Conventions</title></info><?dbhtml filename="source_organization.html"?><para>
    The <filename class="directory">libstdc++-v3</filename> directory in the
    GCC sources contains the files needed to create the GNU C++ Library.
  </para><para>
It has subdirectories:
</para><variablelist><varlistentry><term><filename class="directory">doc</filename></term><listitem>
    Files in HTML and text format that document usage, quirks of the
    implementation, and contributor checklists.
    </listitem></varlistentry><varlistentry><term><filename class="directory">include</filename></term><listitem>
    All header files for the C++ library are within this directory,
    modulo specific runtime-related files that are in the libsupc++
    directory.

    <variablelist><varlistentry><term><filename class="directory">include/std</filename></term><listitem>
      Files meant to be found by <code>#include &lt;name&gt;</code> directives
      in standard-conforming user programs.
      </listitem></varlistentry><varlistentry><term><filename class="directory">include/c</filename></term><listitem>
      Headers intended to directly include standard C headers.
      [NB: this can be enabled via <option>--enable-cheaders=c</option>]
      </listitem></varlistentry><varlistentry><term><filename class="directory">include/c_global</filename></term><listitem>
      Headers intended to include standard C headers in
      the global namespace, and put select names into the <code>std::</code>
      namespace.  [NB: this is the default, and is the same as
      <option>--enable-cheaders=c_global</option>]
      </listitem></varlistentry><varlistentry><term><filename class="directory">include/c_std</filename></term><listitem>
      Headers intended to include standard C headers
      already in namespace std, and put select names into the <code>std::</code>
      namespace.  [NB: this is the same as
      <option>--enable-cheaders=c_std</option>]
      </listitem></varlistentry><varlistentry><term><filename class="directory">include/bits</filename></term><listitem>
      Files included by standard headers and by other files in
      the bits directory.
      </listitem></varlistentry><varlistentry><term><filename class="directory">include/backward</filename></term><listitem>
      Headers provided for backward compatibility, such as
      <filename class="headerfile">&lt;backward/hash_map&gt;</filename>.
      They are not used in this library.
    </listitem></varlistentry><varlistentry><term><filename class="directory">include/ext</filename></term><listitem>
      Headers that define extensions to the standard library.  No
      standard header refers to any of them, in theory (there are some
      exceptions).
    </listitem></varlistentry><varlistentry><term><filename class="directory">include/debug</filename>,
      <filename class="directory">include/parallel</filename>, and
    </term><listitem>
      Headers that implement the Debug Mode and Parallel Mode extensions.
    </listitem></varlistentry></variablelist>
  </listitem></varlistentry><varlistentry><term><filename class="directory">scripts</filename></term><listitem>
    Scripts that are used during the configure, build, make, or test
    process.
    </listitem></varlistentry><varlistentry><term><filename class="directory">src</filename></term><listitem>
    Files that are used in constructing the library, but are not
    installed.

    <variablelist><varlistentry><term><filename class="directory">src/c++98</filename></term><listitem>
    Source files compiled using <option>-std=gnu++98</option>.
      </listitem></varlistentry><varlistentry><term><filename class="directory">src/c++11</filename></term><listitem>
    Source files compiled using <option>-std=gnu++11</option>.
      </listitem></varlistentry><varlistentry><term><filename class="directory">src/filesystem</filename></term><listitem>
    Source files for the Filesystem TS.
      </listitem></varlistentry><varlistentry><term><filename class="directory">src/shared</filename></term><listitem>
    Source code included by other files under both
    <filename class="directory">src/c++98</filename> and
    <filename class="directory">src/c++11</filename>
      </listitem></varlistentry></variablelist>
  </listitem></varlistentry><varlistentry><term><filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename></term><listitem>
    Test programs are here, and may be used to begin to exercise the
    library.  Support for "make check" and "make check-install" is
    complete, and runs through all the subdirectories here when this
    command is issued from the build directory.  Please note that
    "make check" requires DejaGnu 1.4 or later to be installed,
    or for extra <link linkend="test.run.permutations">permutations</link>
    DejaGnu 1.5.3 or later.
    </listitem></varlistentry></variablelist><para>
Other subdirectories contain variant versions of certain files
that are meant to be copied or linked by the configure script.
Currently these are:
<literallayout><filename class="directory">config/abi</filename><filename class="directory">config/allocator</filename><filename class="directory">config/cpu</filename><filename class="directory">config/io</filename><filename class="directory">config/locale</filename><filename class="directory">config/os</filename></literallayout>
</para><para>
In addition, a subdirectory holds the convenience library libsupc++.
</para><variablelist><varlistentry><term><filename class="directory">libsupc++</filename></term><listitem>
    Contains the runtime library for C++, including exception
    handling and memory allocation and deallocation, RTTI, terminate
    handlers, etc.
  </listitem></varlistentry></variablelist><para>
Note that glibc also has a <filename class="directory">bits/</filename>
subdirectory.  We need to be careful not to collide with names in its
<filename class="directory">bits/</filename> directory. For example
<filename class="headerfile">&lt;bits/std_mutex.h&gt;</filename> has to be
renamed from <filename class="headerfile">&lt;bits/mutex.h&gt;</filename>.
Another solution would be to rename <filename class="directory">bits</filename>
to (e.g.) <filename class="directory">cppbits</filename>.
</para><para>
In files throughout the system, lines marked with an "XXX" indicate
a bug or incompletely-implemented feature.  Lines marked "XXX MT"
indicate a place that may require attention for multi-thread safety.
</para></section><section xreflabel="Coding Style" xml:id="contrib.coding_style"><info><title>Coding Style</title></info><?dbhtml filename="source_code_style.html"?><para>
  </para><section xml:id="coding_style.bad_identifiers"><info><title>Bad Identifiers</title></info><!-- BADNAMES --><para>
      Identifiers that conflict and should be avoided.
    </para><literallayout class="normal">
      This is the list of names <quote>reserved to the
      implementation</quote> that have been claimed by certain
      compilers and system headers of interest, and should not be used
      in the library. It will grow, of course.  We generally are
      interested in names that are not all-caps, except for those like
      "_T"

      For Solaris:
      _B
      _C
      _L
      _N
      _P
      _S
      _U
      _X
      _E1
      ..
      _E24

      Irix adds:
      _A
      _G

      MS adds:
      _T
      __deref

      BSD adds:
      __used
      __unused
      __inline
      _Complex
      __istype
      __maskrune
      __tolower
      __toupper
      __wchar_t
      __wint_t
      _res
      _res_ext
      __tg_*

      VxWorks adds:
      _C2

      For GCC:

      [Note that this list is out of date. It applies to the old
      name-mangling; in G++ 3.0 and higher a different name-mangling is
      used. In addition, many of the bugs relating to G++ interpreting
      these names as operators have been fixed.]

      The full set of __* identifiers (combined from gcc/cp/lex.c and
      gcc/cplus-dem.c) that are either old or new, but are definitely
      recognized by the demangler, is:

      __aa
      __aad
      __ad
      __addr
      __adv
      __aer
      __als
      __alshift
      __amd
      __ami
      __aml
      __amu
      __aor
      __apl
      __array
      __ars
      __arshift
      __as
      __bit_and
      __bit_ior
      __bit_not
      __bit_xor
      __call
      __cl
      __cm
      __cn
      __co
      __component
      __compound
      __cond
      __convert
      __delete
      __dl
      __dv
      __eq
      __er
      __ge
      __gt
      __indirect
      __le
      __ls
      __lt
      __max
      __md
      __method_call
      __mi
      __min
      __minus
      __ml
      __mm
      __mn
      __mult
      __mx
      __ne
      __negate
      __new
      __nop
      __nt
      __nw
      __oo
      __op
      __or
      __pl
      __plus
      __postdecrement
      __postincrement
      __pp
      __pt
      __rf
      __rm
      __rs
      __sz
      __trunc_div
      __trunc_mod
      __truth_andif
      __truth_not
      __truth_orif
      __vc
      __vd
      __vn

      SGI badnames:
      __builtin_alloca
      __builtin_fsqrt
      __builtin_sqrt
      __builtin_fabs
      __builtin_dabs
      __builtin_cast_f2i
      __builtin_cast_i2f
      __builtin_cast_d2ll
      __builtin_cast_ll2d
      __builtin_copy_dhi2i
      __builtin_copy_i2dhi
      __builtin_copy_dlo2i
      __builtin_copy_i2dlo
      __add_and_fetch
      __sub_and_fetch
      __or_and_fetch
      __xor_and_fetch
      __and_and_fetch
      __nand_and_fetch
      __mpy_and_fetch
      __min_and_fetch
      __max_and_fetch
      __fetch_and_add
      __fetch_and_sub
      __fetch_and_or
      __fetch_and_xor
      __fetch_and_and
      __fetch_and_nand
      __fetch_and_mpy
      __fetch_and_min
      __fetch_and_max
      __lock_test_and_set
      __lock_release
      __lock_acquire
      __compare_and_swap
      __synchronize
      __high_multiply
      __unix
      __sgi
      __linux__
      __i386__
      __i486__
      __cplusplus
      __embedded_cplusplus
      // long double conversion members mangled as __opr
      // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
      __opr
    </literallayout></section><section xml:id="coding_style.example"><info><title>By Example</title></info><literallayout class="normal">
      This library is written to appropriate C++ coding standards. As such,
      it is intended to precede the recommendations of the GNU Coding
      Standard, which can be referenced in full here:

      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/standards.html#Formatting">https://www.gnu.org/prep/standards/standards.html#Formatting</link>

      The rest of this is also interesting reading, but skip the "Design
      Advice" part.

      The GCC coding conventions are here, and are also useful:
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/codingconventions.html">https://gcc.gnu.org/codingconventions.html</link>

      In addition, because it doesn't seem to be stated explicitly anywhere
      else, there is an 80 column source limit.

      <filename>ChangeLog</filename> entries for member functions should use the
      classname::member function name syntax as follows:

<code>
1999-04-15  Dennis Ritchie  &lt;dr@att.com&gt;

      * src/basic_file.cc (__basic_file::open): Fix thinko in
      _G_HAVE_IO_FILE_OPEN bits.
</code>

      Notable areas of divergence from what may be previous local practice
      (particularly for GNU C) include:

      01. Pointers and references
      <code>
        char* p = "flop";
        char&amp; c = *p;
          -NOT-
        char *p = "flop";  // wrong
        char &amp;c = *p;      // wrong
      </code>

      Reason: In C++, definitions are mixed with executable code. Here,
      <code>p</code> is being initialized, not <code>*p</code>.  This is near-universal
      practice among C++ programmers; it is normal for C hackers
      to switch spontaneously as they gain experience.

      02. Operator names and parentheses
      <code>
        operator==(type)
          -NOT-
        operator == (type)  // wrong
      </code>

      Reason: The <code>==</code> is part of the function name. Separating
      it makes the declaration look like an expression.

      03. Function names and parentheses
      <code>
        void mangle()
          -NOT-
        void mangle ()  // wrong
      </code>

      Reason: no space before parentheses (except after a control-flow
      keyword) is near-universal practice for C++. It identifies the
      parentheses as the function-call operator or declarator, as
      opposed to an expression or other overloaded use of parentheses.

      04. Template function indentation
      <code>
        template&lt;typename T&gt;
          void
          template_function(args)
          { }
          -NOT-
        template&lt;class T&gt;
        void template_function(args) {};
      </code>

      Reason: In class definitions, without indentation whitespace is
      needed both above and below the declaration to distinguish
      it visually from other members. (Also, re: "typename"
      rather than "class".)  <code>T</code> often could be <code>int</code>, which is
      not a class. ("class", here, is an anachronism.)

      05. Template class indentation
      <code>
        template&lt;typename _CharT, typename _Traits&gt;
          class basic_ios : public ios_base
          {
          public:
            // Types:
          };
          -NOT-
        template&lt;class _CharT, class _Traits&gt;
        class basic_ios : public ios_base
          {
          public:
            // Types:
          };
          -NOT-
        template&lt;class _CharT, class _Traits&gt;
          class basic_ios : public ios_base
        {
          public:
            // Types:
        };
      </code>

      06. Enumerators
      <code>
        enum
        {
          space = _ISspace,
          print = _ISprint,
          cntrl = _IScntrl
        };
          -NOT-
        enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
      </code>

      07. Member initialization lists
      All one line, separate from class name.

      <code>
        gribble::gribble()
        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
        { }
          -NOT-
        gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
        { }
      </code>

      08. Try/Catch blocks
      <code>
        try
          {
            //
          }
        catch (...)
          {
            //
          }
          -NOT-
        try {
          //
        } catch(...) {
          //
        }
      </code>

      09. Member functions declarations and definitions
      Keywords such as extern, static, export, explicit, inline, etc
      go on the line above the function name. Thus

      <code>
      virtual int
      foo()
      -NOT-
      virtual int foo()
      </code>

      Reason: GNU coding conventions dictate return types for functions
      are on a separate line than the function name and parameter list
      for definitions. For C++, where we have member functions that can
      be either inline definitions or declarations, keeping to this
      standard allows all member function names for a given class to be
      aligned to the same margin, increasing readability.


      10. Invocation of member functions with "this-&gt;"
      For non-uglified names, use <code>this-&gt;name</code> to call the function.

      <code>
      this-&gt;sync()
      -NOT-
      sync()
      </code>

      Reason: Koenig lookup.

      11. Namespaces
      <code>
      namespace std
      {
        blah blah blah;
      } // namespace std

      -NOT-

      namespace std {
        blah blah blah;
      } // namespace std
      </code>

      12. Spacing under protected and private in class declarations:
      space above, none below
      i.e.

      <code>
      public:
        int foo;

      -NOT-
      public:

        int foo;
      </code>

      13. Spacing WRT return statements.
      no extra spacing before returns, no parenthesis
      i.e.

      <code>
      }
      return __ret;

      -NOT-
      }

      return __ret;

      -NOT-

      }
      return (__ret);
      </code>


      14. Location of global variables.
      All global variables of class type, whether in the "user visible"
      space (e.g., <code>cin</code>) or the implementation namespace, must be defined
      as a character array with the appropriate alignment and then later
      re-initialized to the correct value.

      This is due to startup issues on certain platforms, such as AIX.
      For more explanation and examples, see <filename>src/globals.cc</filename>. All such
      variables should be contained in that file, for simplicity.

      15. Exception abstractions
      Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow
      C++ programmers to use this library with <literal>-fno-exceptions</literal>.  (Even if
      that is rarely advisable, it's a necessary evil for backwards
      compatibility.)

      16. Exception error messages
      All start with the name of the function where the exception is
      thrown, and then (optional) descriptive text is added. Example:

      <code>
      __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
      </code>

      Reason: The verbose terminate handler prints out <code>exception::what()</code>,
      as well as the typeinfo for the thrown exception. As this is the
      default terminate handler, by putting location info into the
      exception string, a very useful error message is printed out for
      uncaught exceptions. So useful, in fact, that non-programmers can
      give useful error messages, and programmers can intelligently
      speculate what went wrong without even using a debugger.

      17. The doxygen style guide to comments is a separate document,
      see index.

      The library currently has a mixture of GNU-C and modern C++ coding
      styles. The GNU C usages will be combed out gradually.

      Name patterns:

      For nonstandard names appearing in Standard headers, we are constrained
      to use names that begin with underscores. This is called "uglification".
      The convention is:

      Local and argument names:  <literal>__[a-z].*</literal>

      Examples:  <code>__count  __ix  __s1</code>

      Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal>

      Examples:  <code>_Helper  _CharT  _Nm</code>

      Member data and function names: <literal>_M_.*</literal>

      Examples:  <code>_M_num_elements  _M_initialize ()</code>

      Static data and function members, constants, and enumerations: <literal>_S_.*</literal>

      Examples: <code>_S_max_elements  _S_default_value</code>

      Don't use names in the same scope that differ only in the prefix,
      e.g. _S_top and _M_top. See <link linkend="coding_style.bad_identifiers">BADNAMES</link> for a list of forbidden names.
      (The most tempting of these seem to be and "_T" and "_N".)

      Names must never have "__" internally; it would confuse name
      unmanglers on some targets. Also, never use "__[0-9]", same reason.

      --------------------------

      [BY EXAMPLE]
      <code>

      #ifndef  _HEADER_
      #define  _HEADER_ 1

      namespace std
      {
        class gribble
        {
        public:
          gribble() throw();

          gribble(const gribble&amp;);

          explicit
          gribble(int __howmany);

          gribble&amp;
          operator=(const gribble&amp;);

          virtual
          ~gribble() throw ();

          // Start with a capital letter, end with a period.
          inline void
          public_member(const char* __arg) const;

          // In-class function definitions should be restricted to one-liners.
          int
          one_line() { return 0 }

          int
          two_lines(const char* arg)
          { return strchr(arg, 'a'); }

          inline int
          three_lines();  // inline, but defined below.

          // Note indentation.
          template&lt;typename _Formal_argument&gt;
            void
            public_template() const throw();

          template&lt;typename _Iterator&gt;
            void
            other_template();

        private:
          class _Helper;

          int _M_private_data;
          int _M_more_stuff;
          _Helper* _M_helper;
          int _M_private_function();

          enum _Enum
            {
              _S_one,
              _S_two
            };

          static void
          _S_initialize_library();
        };

        // More-or-less-standard language features described by lack, not presence.
      # ifndef _G_NO_LONGLONG
        extern long long _G_global_with_a_good_long_name;  // avoid globals!
      # endif

        // Avoid in-class inline definitions, define separately;
        // likewise for member class definitions:
        inline int
        gribble::public_member() const
        { int __local = 0; return __local; }

        class gribble::_Helper
        {
          int _M_stuff;

          friend class gribble;
        };
      }

      // Names beginning with "__": only for arguments and
      //   local variables; never use "__" in a type name, or
      //   within any name; never use "__[0-9]".

      #endif /* _HEADER_ */


      namespace std
      {
        template&lt;typename T&gt;  // notice: "typename", not "class", no space
          long_return_value_type&lt;with_many, args&gt;
          function_name(char* pointer,               // "char *pointer" is wrong.
                        char* argument,
                        const Reference&amp; ref)
          {
            // int a_local;  /* wrong; see below. */
            if (test)
            {
              nested code
            }

            int a_local = 0;  // declare variable at first use.

            //  char a, b, *p;   /* wrong */
            char a = 'a';
            char b = a + 1;
            char* c = "abc";  // each variable goes on its own line, always.

            // except maybe here...
            for (unsigned i = 0, mask = 1; mask; ++i, mask &lt;&lt;= 1) {
              // ...
            }
          }

        gribble::gribble()
        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
        { }

        int
        gribble::three_lines()
        {
          // doesn't fit in one line.
        }
      } // namespace std
      </code>
    </literallayout></section></section><section xreflabel="Design Notes" xml:id="contrib.design_notes"><info><title>Design Notes</title></info><?dbhtml filename="source_design_notes.html"?><para>
  </para><literallayout class="normal">

    The Library
    -----------

    This paper is covers two major areas:

    - Features and policies not mentioned in the standard that
    the quality of the library implementation depends on, including
    extensions and "implementation-defined" features;

    - Plans for required but unimplemented library features and
    optimizations to them.

    Overhead
    --------

    The standard defines a large library, much larger than the standard
    C library. A naive implementation would suffer substantial overhead
    in compile time, executable size, and speed, rendering it unusable
    in many (particularly embedded) applications. The alternative demands
    care in construction, and some compiler support, but there is no
    need for library subsets.

    What are the sources of this overhead?  There are four main causes:

    - The library is specified almost entirely as templates, which
    with current compilers must be included in-line, resulting in
    very slow builds as tens or hundreds of thousands of lines
    of function definitions are read for each user source file.
    Indeed, the entire SGI STL, as well as the dos Reis valarray,
    are provided purely as header files, largely for simplicity in
    porting. Iostream/locale is (or will be) as large again.

    - The library is very flexible, specifying a multitude of hooks
    where users can insert their own code in place of defaults.
    When these hooks are not used, any time and code expended to
    support that flexibility is wasted.

    - Templates are often described as causing to "code bloat". In
    practice, this refers (when it refers to anything real) to several
    independent processes. First, when a class template is manually
    instantiated in its entirely, current compilers place the definitions
    for all members in a single object file, so that a program linking
    to one member gets definitions of all. Second, template functions
    which do not actually depend on the template argument are, under
    current compilers, generated anew for each instantiation, rather
    than being shared with other instantiations. Third, some of the
    flexibility mentioned above comes from virtual functions (both in
    regular classes and template classes) which current linkers add
    to the executable file even when they manifestly cannot be called.

    - The library is specified to use a language feature, exceptions,
    which in the current gcc compiler ABI imposes a run time and
    code space cost to handle the possibility of exceptions even when
    they are not used. Under the new ABI (accessed with -fnew-abi),
    there is a space overhead and a small reduction in code efficiency
    resulting from lost optimization opportunities associated with
    non-local branches associated with exceptions.

    What can be done to eliminate this overhead?  A variety of coding
    techniques, and compiler, linker and library improvements and
    extensions may be used, as covered below. Most are not difficult,
    and some are already implemented in varying degrees.

    Overhead: Compilation Time
    --------------------------

    Providing "ready-instantiated" template code in object code archives
    allows us to avoid generating and optimizing template instantiations
    in each compilation unit which uses them. However, the number of such
    instantiations that are useful to provide is limited, and anyway this
    is not enough, by itself, to minimize compilation time. In particular,
    it does not reduce time spent parsing conforming headers.

    Quicker header parsing will depend on library extensions and compiler
    improvements.  One approach is some variation on the techniques
    previously marketed as "pre-compiled headers", now standardized as
    support for the "export" keyword. "Exported" template definitions
    can be placed (once) in a "repository" -- really just a library, but
    of template definitions rather than object code -- to be drawn upon
    at link time when an instantiation is needed, rather than placed in
    header files to be parsed along with every compilation unit.

    Until "export" is implemented we can put some of the lengthy template
    definitions in #if guards or alternative headers so that users can skip
    over the full definitions when they need only the ready-instantiated
    specializations.

    To be precise, this means that certain headers which define
    templates which users normally use only for certain arguments
    can be instrumented to avoid exposing the template definitions
    to the compiler unless a macro is defined. For example, in
    &lt;string&gt;, we might have:

    template &lt;class _CharT, ... &gt; class basic_string {
    ... // member declarations
    };
    ... // operator declarations

    #ifdef _STRICT_ISO_
    # if _G_NO_TEMPLATE_EXPORT
    #   include &lt;bits/std_locale.h&gt;  // headers needed by definitions
    #   ...
    #   include &lt;bits/string.tcc&gt;  // member and global template definitions.
    # endif
    #endif

    Users who compile without specifying a strict-ISO-conforming flag
    would not see many of the template definitions they now see, and rely
    instead on ready-instantiated specializations in the library. This
    technique would be useful for the following substantial components:
    string, locale/iostreams, valarray. It would *not* be useful or
    usable with the following: containers, algorithms, iterators,
    allocator. Since these constitute a large (though decreasing)
    fraction of the library, the benefit the technique offers is
    limited.

    The language specifies the semantics of the "export" keyword, but
    the gcc compiler does not yet support it. When it does, problems
    with large template inclusions can largely disappear, given some
    minor library reorganization, along with the need for the apparatus
    described above.

    Overhead: Flexibility Cost
    --------------------------

    The library offers many places where users can specify operations
    to be performed by the library in place of defaults. Sometimes
    this seems to require that the library use a more-roundabout, and
    possibly slower, way to accomplish the default requirements than
    would be used otherwise.

    The primary protection against this overhead is thorough compiler
    optimization, to crush out layers of inline function interfaces.
    Kuck &amp; Associates has demonstrated the practicality of this kind
    of optimization.

    The second line of defense against this overhead is explicit
    specialization. By defining helper function templates, and writing
    specialized code for the default case, overhead can be eliminated
    for that case without sacrificing flexibility. This takes full
    advantage of any ability of the optimizer to crush out degenerate
    code.

    The library specifies many virtual functions which current linkers
    load even when they cannot be called. Some minor improvements to the
    compiler and to ld would eliminate any such overhead by simply
    omitting virtual functions that the complete program does not call.
    A prototype of this work has already been done. For targets where
    GNU ld is not used, a "pre-linker" could do the same job.

    The main areas in the standard interface where user flexibility
    can result in overhead are:

    - Allocators:  Containers are specified to use user-definable
    allocator types and objects, making tuning for the container
    characteristics tricky.

    - Locales: the standard specifies locale objects used to implement
    iostream operations, involving many virtual functions which use
    streambuf iterators.

    - Algorithms and containers: these may be instantiated on any type,
    frequently duplicating code for identical operations.

    - Iostreams and strings: users are permitted to use these on their
    own types, and specify the operations the stream must use on these
    types.

    Note that these sources of overhead are _avoidable_. The techniques
    to avoid them are covered below.

    Code Bloat
    ----------

    In the SGI STL, and in some other headers, many of the templates
    are defined "inline" -- either explicitly or by their placement
    in class definitions -- which should not be inline. This is a
    source of code bloat. Matt had remarked that he was relying on
    the compiler to recognize what was too big to benefit from inlining,
    and generate it out-of-line automatically. However, this also can
    result in code bloat except where the linker can eliminate the extra
    copies.

    Fixing these cases will require an audit of all inline functions
    defined in the library to determine which merit inlining, and moving
    the rest out of line. This is an issue mainly in clauses 23, 25, and
    27. Of course it can be done incrementally, and we should generally
    accept patches that move large functions out of line and into ".tcc"
    files, which can later be pulled into a repository. Compiler/linker
    improvements to recognize very large inline functions and move them
    out-of-line, but shared among compilation units, could make this
    work unnecessary.

    Pre-instantiating template specializations currently produces large
    amounts of dead code which bloats statically linked programs. The
    current state of the static library, libstdc++.a, is intolerable on
    this account, and will fuel further confused speculation about a need
    for a library "subset". A compiler improvement that treats each
    instantiated function as a separate object file, for linking purposes,
    would be one solution to this problem. An alternative would be to
    split up the manual instantiation files into dozens upon dozens of
    little files, each compiled separately, but an abortive attempt at
    this was done for &lt;string&gt; and, though it is far from complete, it
    is already a nuisance. A better interim solution (just until we have
    "export") is badly needed.

    When building a shared library, the current compiler/linker cannot
    automatically generate the instantiations needed. This creates a
    miserable situation; it means any time something is changed in the
    library, before a shared library can be built someone must manually
    copy the declarations of all templates that are needed by other parts
    of the library to an "instantiation" file, and add it to the build
    system to be compiled and linked to the library. This process is
    readily automated, and should be automated as soon as possible.
    Users building their own shared libraries experience identical
    frustrations.

    Sharing common aspects of template definitions among instantiations
    can radically reduce code bloat. The compiler could help a great
    deal here by recognizing when a function depends on nothing about
    a template parameter, or only on its size, and giving the resulting
    function a link-name "equate" that allows it to be shared with other
    instantiations. Implementation code could take advantage of the
    capability by factoring out code that does not depend on the template
    argument into separate functions to be merged by the compiler.

    Until such a compiler optimization is implemented, much can be done
    manually (if tediously) in this direction. One such optimization is
    to derive class templates from non-template classes, and move as much
    implementation as possible into the base class. Another is to partial-
    specialize certain common instantiations, such as vector&lt;T*&gt;, to share
    code for instantiations on all types T. While these techniques work,
    they are far from the complete solution that a compiler improvement
    would afford.

    Overhead: Expensive Language Features
    -------------------------------------

    The main "expensive" language feature used in the standard library
    is exception support, which requires compiling in cleanup code with
    static table data to locate it, and linking in library code to use
    the table. For small embedded programs the amount of such library
    code and table data is assumed by some to be excessive. Under the
    "new" ABI this perception is generally exaggerated, although in some
    cases it may actually be excessive.

    To implement a library which does not use exceptions directly is
    not difficult given minor compiler support (to "turn off" exceptions
    and ignore exception constructs), and results in no great library
    maintenance difficulties. To be precise, given "-fno-exceptions",
    the compiler should treat "try" blocks as ordinary blocks, and
    "catch" blocks as dead code to ignore or eliminate. Compiler
    support is not strictly necessary, except in the case of "function
    try blocks"; otherwise the following macros almost suffice:

    #define throw(X)
    #define try      if (true)
    #define catch(X) else if (false)

    However, there may be a need to use function try blocks in the
    library implementation, and use of macros in this way can make
    correct diagnostics impossible. Furthermore, use of this scheme
    would require the library to call a function to re-throw exceptions
    from a try block. Implementing the above semantics in the compiler
    is preferable.

    Given the support above (however implemented) it only remains to
    replace code that "throws" with a call to a well-documented "handler"
    function in a separate compilation unit which may be replaced by
    the user. The main source of exceptions that would be difficult
    for users to avoid is memory allocation failures, but users can
    define their own memory allocation primitives that never throw.
    Otherwise, the complete list of such handlers, and which library
    functions may call them, would be needed for users to be able to
    implement the necessary substitutes. (Fortunately, they have the
    source code.)

    Opportunities
    -------------

    The template capabilities of C++ offer enormous opportunities for
    optimizing common library operations, well beyond what would be
    considered "eliminating overhead". In particular, many operations
    done in Glibc with macros that depend on proprietary language
    extensions can be implemented in pristine Standard C++. For example,
    the chapter 25 algorithms, and even C library functions such as strchr,
    can be specialized for the case of static arrays of known (small) size.

    Detailed optimization opportunities are identified below where
    the component where they would appear is discussed. Of course new
    opportunities will be identified during implementation.

    Unimplemented Required Library Features
    ---------------------------------------

    The standard specifies hundreds of components, grouped broadly by
    chapter. These are listed in excruciating detail in the CHECKLIST
    file.

    17 general
    18 support
    19 diagnostics
    20 utilities
    21 string
    22 locale
    23 containers
    24 iterators
    25 algorithms
    26 numerics
    27 iostreams
    Annex D  backward compatibility

    Anyone participating in implementation of the library should obtain
    a copy of the standard, ISO 14882.  People in the U.S. can obtain an
    electronic copy for US$18 from ANSI's web site. Those from other
    countries should visit http://www.iso.org/ to find out the location
    of their country's representation in ISO, in order to know who can
    sell them a copy.

    The emphasis in the following sections is on unimplemented features
    and optimization opportunities.

    Chapter 17  General
    -------------------

    Chapter 17 concerns overall library requirements.

    The standard doesn't mention threads. A multi-thread (MT) extension
    primarily affects operators new and delete (18), allocator (20),
    string (21), locale (22), and iostreams (27). The common underlying
    support needed for this is discussed under chapter 20.

    The standard requirements on names from the C headers create a
    lot of work, mostly done. Names in the C headers must be visible
    in the std:: and sometimes the global namespace; the names in the
    two scopes must refer to the same object. More stringent is that
    Koenig lookup implies that any types specified as defined in std::
    really are defined in std::. Names optionally implemented as
    macros in C cannot be macros in C++. (An overview may be read at
    &lt;http://www.cantrip.org/cheaders.html&gt;). The scripts "inclosure"
    and "mkcshadow", and the directories shadow/ and cshadow/, are the
    beginning of an effort to conform in this area.

    A correct conforming definition of C header names based on underlying
    C library headers, and practical linking of conforming namespaced
    customer code with third-party C libraries depends ultimately on
    an ABI change, allowing namespaced C type names to be mangled into
    type names as if they were global, somewhat as C function names in a
    namespace, or C++ global variable names, are left unmangled. Perhaps
    another "extern" mode, such as 'extern "C-global"' would be an
    appropriate place for such type definitions. Such a type would
    affect mangling as follows:

    namespace A {
    struct X {};
    extern "C-global" {  // or maybe just 'extern "C"'
    struct Y {};
    };
    }
    void f(A::X*);  // mangles to f__FPQ21A1X
    void f(A::Y*);  // mangles to f__FP1Y

    (It may be that this is really the appropriate semantics for regular
    'extern "C"', and 'extern "C-global"', as an extension, would not be
    necessary.) This would allow functions declared in non-standard C headers
    (and thus fixable by neither us nor users) to link properly with functions
    declared using C types defined in properly-namespaced headers. The
    problem this solves is that C headers (which C++ programmers do persist
    in using) frequently forward-declare C struct tags without including
    the header where the type is defined, as in

    struct tm;
    void munge(tm*);

    Without some compiler accommodation, munge cannot be called by correct
    C++ code using a pointer to a correctly-scoped tm* value.

    The current C headers use the preprocessor extension "#include_next",
    which the compiler complains about when run "-pedantic".
    (Incidentally, it appears that "-fpedantic" is currently ignored,
    probably a bug.)  The solution in the C compiler is to use
    "-isystem" rather than "-I", but unfortunately in g++ this seems
    also to wrap the whole header in an 'extern "C"' block, so it's
    unusable for C++ headers. The correct solution appears to be to
    allow the various special include-directory options, if not given
    an argument, to affect subsequent include-directory options additively,
    so that if one said

    -pedantic -iprefix $(prefix) \
    -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \
    -iwithprefix -I g++-v3/ext

    the compiler would search $(prefix)/g++-v3 and not report
    pedantic warnings for files found there, but treat files in
    $(prefix)/g++-v3/ext pedantically. (The undocumented semantics
    of "-isystem" in g++ stink. Can they be rescinded?  If not it
    must be replaced with something more rationally behaved.)

    All the C headers need the treatment above; in the standard these
    headers are mentioned in various clauses. Below, I have only
    mentioned those that present interesting implementation issues.

    The components identified as "mostly complete", below, have not been
    audited for conformance. In many cases where the library passes
    conformance tests we have non-conforming extensions that must be
    wrapped in #if guards for "pedantic" use, and in some cases renamed
    in a conforming way for continued use in the implementation regardless
    of conformance flags.

    The STL portion of the library still depends on a header
    stl/bits/stl_config.h full of #ifdef clauses. This apparatus
    should be replaced with autoconf/automake machinery.

    The SGI STL defines a type_traits&lt;&gt; template, specialized for
    many types in their code including the built-in numeric and
    pointer types and some library types, to direct optimizations of
    standard functions. The SGI compiler has been extended to generate
    specializations of this template automatically for user types,
    so that use of STL templates on user types can take advantage of
    these optimizations. Specializations for other, non-STL, types
    would make more optimizations possible, but extending the gcc
    compiler in the same way would be much better. Probably the next
    round of standardization will ratify this, but probably with
    changes, so it probably should be renamed to place it in the
    implementation namespace.

    The SGI STL also defines a large number of extensions visible in
    standard headers. (Other extensions that appear in separate headers
    have been sequestered in subdirectories ext/ and backward/.)  All
    these extensions should be moved to other headers where possible,
    and in any case wrapped in a namespace (not std!), and (where kept
    in a standard header) girded about with macro guards. Some cannot be
    moved out of standard headers because they are used to implement
    standard features.  The canonical method for accommodating these
    is to use a protected name, aliased in macro guards to a user-space
    name. Unfortunately C++ offers no satisfactory template typedef
    mechanism, so very ad-hoc and unsatisfactory aliasing must be used
    instead.

    Implementation of a template typedef mechanism should have the highest
    priority among possible extensions, on the same level as implementation
    of the template "export" feature.

    Chapter 18  Language support
    ----------------------------

    Headers: &lt;limits&gt; &lt;new&gt; &lt;typeinfo&gt; &lt;exception&gt;
    C headers: &lt;cstddef&gt; &lt;climits&gt; &lt;cfloat&gt;  &lt;cstdarg&gt; &lt;csetjmp&gt;
    &lt;ctime&gt;   &lt;csignal&gt; &lt;cstdlib&gt; (also 21, 25, 26)

    This defines the built-in exceptions, rtti, numeric_limits&lt;&gt;,
    operator new and delete. Much of this is provided by the
    compiler in its static runtime library.

    Work to do includes defining numeric_limits&lt;&gt; specializations in
    separate files for all target architectures. Values for integer types
    except for bool and wchar_t are readily obtained from the C header
    &lt;limits.h&gt;, but values for the remaining numeric types (bool, wchar_t,
    float, double, long double) must be entered manually. This is
    largely dog work except for those members whose values are not
    easily deduced from available documentation. Also, this involves
    some work in target configuration to identify the correct choice of
    file to build against and to install.

    The definitions of the various operators new and delete must be
    made thread-safe, which depends on a portable exclusion mechanism,
    discussed under chapter 20.  Of course there is always plenty of
    room for improvements to the speed of operators new and delete.

    &lt;cstdarg&gt;, in Glibc, defines some macros that gcc does not allow to
    be wrapped into an inline function. Probably this header will demand
    attention whenever a new target is chosen. The functions atexit(),
    exit(), and abort() in cstdlib have different semantics in C++, so
    must be re-implemented for C++.

    Chapter 19  Diagnostics
    -----------------------

    Headers: &lt;stdexcept&gt;
    C headers: &lt;cassert&gt; &lt;cerrno&gt;

    This defines the standard exception objects, which are "mostly complete".
    Cygnus has a version, and now SGI provides a slightly different one.
    It makes little difference which we use.

    The C global name "errno", which C allows to be a variable or a macro,
    is required in C++ to be a macro. For MT it must typically result in
    a function call.

    Chapter 20  Utilities
    ---------------------
    Headers: &lt;utility&gt; &lt;functional&gt; &lt;memory&gt;
    C header: &lt;ctime&gt; (also in 18)

    SGI STL provides "mostly complete" versions of all the components
    defined in this chapter. However, the auto_ptr&lt;&gt; implementation
    is known to be wrong. Furthermore, the standard definition of it
    is known to be unimplementable as written. A minor change to the
    standard would fix it, and auto_ptr&lt;&gt; should be adjusted to match.

    Multi-threading affects the allocator implementation, and there must
    be configuration/installation choices for different users' MT
    requirements. Anyway, users will want to tune allocator options
    to support different target conditions, MT or no.

    The primitives used for MT implementation should be exposed, as an
    extension, for users' own work. We need cross-CPU "mutex" support,
    multi-processor shared-memory atomic integer operations, and single-
    processor uninterruptible integer operations, and all three configurable
    to be stubbed out for non-MT use, or to use an appropriately-loaded
    dynamic library for the actual runtime environment, or statically
    compiled in for cases where the target architecture is known.

    Chapter 21  String
    ------------------
    Headers: &lt;string&gt;
    C headers: &lt;cctype&gt; &lt;cwctype&gt; &lt;cstring&gt; &lt;cwchar&gt; (also in 27)
    &lt;cstdlib&gt; (also in 18, 25, 26)

    We have "mostly-complete" char_traits&lt;&gt; implementations. Many of the
    char_traits&lt;char&gt; operations might be optimized further using existing
    proprietary language extensions.

    We have a "mostly-complete" basic_string&lt;&gt; implementation. The work
    to manually instantiate char and wchar_t specializations in object
    files to improve link-time behavior is extremely unsatisfactory,
    literally tripling library-build time with no commensurate improvement
    in static program link sizes. It must be redone. (Similar work is
    needed for some components in clauses 22 and 27.)

    Other work needed for strings is MT-safety, as discussed under the
    chapter 20 heading.

    The standard C type mbstate_t from &lt;cwchar&gt; and used in char_traits&lt;&gt;
    must be different in C++ than in C, because in C++ the default constructor
    value mbstate_t() must be the "base" or "ground" sequence state.
    (According to the likely resolution of a recently raised Core issue,
    this may become unnecessary. However, there are other reasons to
    use a state type not as limited as whatever the C library provides.)
    If we might want to provide conversions from (e.g.) internally-
    represented EUC-wide to externally-represented Unicode, or vice-
    versa, the mbstate_t we choose will need to be more accommodating
    than what might be provided by an underlying C library.

    There remain some basic_string template-member functions which do
    not overload properly with their non-template brethren. The infamous
    hack akin to what was done in vector&lt;&gt; is needed, to conform to
    23.1.1 para 10. The CHECKLIST items for basic_string marked 'X',
    or incomplete, are so marked for this reason.

    Replacing the string iterators, which currently are simple character
    pointers, with class objects would greatly increase the safety of the
    client interface, and also permit a "debug" mode in which range,
    ownership, and validity are rigorously checked. The current use of
    raw pointers as string iterators is evil. vector&lt;&gt; iterators need the
    same treatment. Note that the current implementation freely mixes
    pointers and iterators, and that must be fixed before safer iterators
    can be introduced.

    Some of the functions in &lt;cstring&gt; are different from the C version.
    generally overloaded on const and non-const argument pointers. For
    example, in &lt;cstring&gt; strchr is overloaded. The functions isupper
    etc. in &lt;cctype&gt; typically implemented as macros in C are functions
    in C++, because they are overloaded with others of the same name
    defined in &lt;locale&gt;.

    Many of the functions required in &lt;cwctype&gt; and &lt;cwchar&gt; cannot be
    implemented using underlying C facilities on intended targets because
    such facilities only partly exist.

    Chapter 22  Locale
    ------------------
    Headers: &lt;locale&gt;
    C headers: &lt;clocale&gt;

    We have a "mostly complete" class locale, with the exception of
    code for constructing, and handling the names of, named locales.
    The ways that locales are named (particularly when categories
    (e.g. LC_TIME, LC_COLLATE) are different) varies among all target
    environments. This code must be written in various versions and
    chosen by configuration parameters.

    Members of many of the facets defined in &lt;locale&gt; are stubs. Generally,
    there are two sets of facets: the base class facets (which are supposed
    to implement the "C" locale) and the "byname" facets, which are supposed
    to read files to determine their behavior. The base ctype&lt;&gt;, collate&lt;&gt;,
    and numpunct&lt;&gt; facets are "mostly complete", except that the table of
    bitmask values used for "is" operations, and corresponding mask values,
    are still defined in libio and just included/linked. (We will need to
    implement these tables independently, soon, but should take advantage
    of libio where possible.)  The num_put&lt;&gt;::put members for integer types
    are "mostly complete".

    A complete list of what has and has not been implemented may be
    found in CHECKLIST. However, note that the current definition of
    codecvt&lt;wchar_t,char,mbstate_t&gt; is wrong. It should simply write
    out the raw bytes representing the wide characters, rather than
    trying to convert each to a corresponding single "char" value.

    Some of the facets are more important than others. Specifically,
    the members of ctype&lt;&gt;, numpunct&lt;&gt;, num_put&lt;&gt;, and num_get&lt;&gt; facets
    are used by other library facilities defined in &lt;string&gt;, &lt;istream&gt;,
    and &lt;ostream&gt;, and the codecvt&lt;&gt; facet is used by basic_filebuf&lt;&gt;
    in &lt;fstream&gt;, so a conforming iostream implementation depends on
    these.

    The "long long" type eventually must be supported, but code mentioning
    it should be wrapped in #if guards to allow pedantic-mode compiling.

    Performance of num_put&lt;&gt; and num_get&lt;&gt; depend critically on
    caching computed values in ios_base objects, and on extensions
    to the interface with streambufs.

    Specifically: retrieving a copy of the locale object, extracting
    the needed facets, and gathering data from them, for each call to
    (e.g.) operator&lt;&lt; would be prohibitively slow.  To cache format
    data for use by num_put&lt;&gt; and num_get&lt;&gt; we have a _Format_cache&lt;&gt;
    object stored in the ios_base::pword() array. This is constructed
    and initialized lazily, and is organized purely for utility. It
    is discarded when a new locale with different facets is imbued.

    Using only the public interfaces of the iterator arguments to the
    facet functions would limit performance by forbidding "vector-style"
    character operations. The streambuf iterator optimizations are
    described under chapter 24, but facets can also bypass the streambuf
    iterators via explicit specializations and operate directly on the
    streambufs, and use extended interfaces to get direct access to the
    streambuf internal buffer arrays. These extensions are mentioned
    under chapter 27. These optimizations are particularly important
    for input parsing.

    Unused virtual members of locale facets can be omitted, as mentioned
    above, by a smart linker.

    Chapter 23  Containers
    ----------------------
    Headers: &lt;deque&gt; &lt;list&gt; &lt;queue&gt; &lt;stack&gt; &lt;vector&gt; &lt;map&gt; &lt;set&gt; &lt;bitset&gt;

    All the components in chapter 23 are implemented in the SGI STL.
    They are "mostly complete"; they include a large number of
    nonconforming extensions which must be wrapped. Some of these
    are used internally and must be renamed or duplicated.

    The SGI components are optimized for large-memory environments. For
    embedded targets, different criteria might be more appropriate. Users
    will want to be able to tune this behavior. We should provide
    ways for users to compile the library with different memory usage
    characteristics.

    A lot more work is needed on factoring out common code from different
    specializations to reduce code size here and in chapter 25. The
    easiest fix for this would be a compiler/ABI improvement that allows
    the compiler to recognize when a specialization depends only on the
    size (or other gross quality) of a template argument, and allow the
    linker to share the code with similar specializations. In its
    absence, many of the algorithms and containers can be partial-
    specialized, at least for the case of pointers, but this only solves
    a small part of the problem. Use of a type_traits-style template
    allows a few more optimization opportunities, more if the compiler
    can generate the specializations automatically.

    As an optimization, containers can specialize on the default allocator
    and bypass it, or take advantage of details of its implementation
    after it has been improved upon.

    Replacing the vector iterators, which currently are simple element
    pointers, with class objects would greatly increase the safety of the
    client interface, and also permit a "debug" mode in which range,
    ownership, and validity are rigorously checked. The current use of
    pointers for iterators is evil.

    As mentioned for chapter 24, the deque iterator is a good example of
    an opportunity to implement a "staged" iterator that would benefit
    from specializations of some algorithms.

    Chapter 24  Iterators
    ---------------------
    Headers: &lt;iterator&gt;

    Standard iterators are "mostly complete", with the exception of
    the stream iterators, which are not yet templatized on the
    stream type. Also, the base class template iterator&lt;&gt; appears
    to be wrong, so everything derived from it must also be wrong,
    currently.

    The streambuf iterators (currently located in stl/bits/std_iterator.h,
    but should be under bits/) can be rewritten to take advantage of
    friendship with the streambuf implementation.

    Matt Austern has identified opportunities where certain iterator
    types, particularly including streambuf iterators and deque
    iterators, have a "two-stage" quality, such that an intermediate
    limit can be checked much more quickly than the true limit on
    range operations. If identified with a member of iterator_traits,
    algorithms may be specialized for this case. Of course the
    iterators that have this quality can be identified by specializing
    a traits class.

    Many of the algorithms must be specialized for the streambuf
    iterators, to take advantage of block-mode operations, in order
    to allow iostream/locale operations' performance not to suffer.
    It may be that they could be treated as staged iterators and
    take advantage of those optimizations.

    Chapter 25  Algorithms
    ----------------------
    Headers: &lt;algorithm&gt;
    C headers: &lt;cstdlib&gt; (also in 18, 21, 26))

    The algorithms are "mostly complete". As mentioned above, they
    are optimized for speed at the expense of code and data size.

    Specializations of many of the algorithms for non-STL types would
    give performance improvements, but we must use great care not to
    interfere with fragile template overloading semantics for the
    standard interfaces. Conventionally the standard function template
    interface is an inline which delegates to a non-standard function
    which is then overloaded (this is already done in many places in
    the library). Particularly appealing opportunities for the sake of
    iostream performance are for copy and find applied to streambuf
    iterators or (as noted elsewhere) for staged iterators, of which
    the streambuf iterators are a good example.

    The bsearch and qsort functions cannot be overloaded properly as
    required by the standard because gcc does not yet allow overloading
    on the extern-"C"-ness of a function pointer.

    Chapter 26  Numerics
    --------------------
    Headers: &lt;complex&gt; &lt;valarray&gt; &lt;numeric&gt;
    C headers: &lt;cmath&gt;, &lt;cstdlib&gt; (also 18, 21, 25)

    Numeric components: Gabriel dos Reis's valarray, Drepper's complex,
    and the few algorithms from the STL are "mostly done".  Of course
    optimization opportunities abound for the numerically literate. It
    is not clear whether the valarray implementation really conforms
    fully, in the assumptions it makes about aliasing (and lack thereof)
    in its arguments.

    The C div() and ldiv() functions are interesting, because they are the
    only case where a C library function returns a class object by value.
    Since the C++ type div_t must be different from the underlying C type
    (which is in the wrong namespace) the underlying functions div() and
    ldiv() cannot be re-used efficiently. Fortunately they are trivial to
    re-implement.

    Chapter 27  Iostreams
    ---------------------
    Headers: &lt;iosfwd&gt; &lt;streambuf&gt; &lt;ios&gt; &lt;ostream&gt; &lt;istream&gt; &lt;iostream&gt;
    &lt;iomanip&gt; &lt;sstream&gt; &lt;fstream&gt;
    C headers: &lt;cstdio&gt; &lt;cwchar&gt; (also in 21)

    Iostream is currently in a very incomplete state. &lt;iosfwd&gt;, &lt;iomanip&gt;,
    ios_base, and basic_ios&lt;&gt; are "mostly complete". basic_streambuf&lt;&gt; and
    basic_ostream&lt;&gt; are well along, but basic_istream&lt;&gt; has had little work
    done. The standard stream objects, &lt;sstream&gt; and &lt;fstream&gt; have been
    started; basic_filebuf&lt;&gt; "write" functions have been implemented just
    enough to do "hello, world".

    Most of the istream and ostream operators &lt;&lt; and &gt;&gt; (with the exception
    of the op&lt;&lt;(integer) ones) have not been changed to use locale primitives,
    sentry objects, or char_traits members.

    All these templates should be manually instantiated for char and
    wchar_t in a way that links only used members into user programs.

    Streambuf is fertile ground for optimization extensions. An extended
    interface giving iterator access to its internal buffer would be very
    useful for other library components.

    Iostream operations (primarily operators &lt;&lt; and &gt;&gt;) can take advantage
    of the case where user code has not specified a locale, and bypass locale
    operations entirely. The current implementation of op&lt;&lt;/num_put&lt;&gt;::put,
    for the integer types, demonstrates how they can cache encoding details
    from the locale on each operation. There is lots more room for
    optimization in this area.

    The definition of the relationship between the standard streams
    cout et al. and stdout et al. requires something like a "stdiobuf".
    The SGI solution of using double-indirection to actually use a
    stdio FILE object for buffering is unsatisfactory, because it
    interferes with peephole loop optimizations.

    The &lt;sstream&gt; header work has begun. stringbuf can benefit from
    friendship with basic_string&lt;&gt; and basic_string&lt;&gt;::_Rep to use
    those objects directly as buffers, and avoid allocating and making
    copies.

    The basic_filebuf&lt;&gt; template is a complex beast. It is specified to
    use the locale facet codecvt&lt;&gt; to translate characters between native
    files and the locale character encoding. In general this involves
    two buffers, one of "char" representing the file and another of
    "char_type", for the stream, with codecvt&lt;&gt; translating. The process
    is complicated by the variable-length nature of the translation, and
    the need to seek to corresponding places in the two representations.
    For the case of basic_filebuf&lt;char&gt;, when no translation is needed,
    a single buffer suffices. A specialized filebuf can be used to reduce
    code space overhead when no locale has been imbued. Matt Austern's
    work at SGI will be useful, perhaps directly as a source of code, or
    at least as an example to draw on.

    Filebuf, almost uniquely (cf. operator new), depends heavily on
    underlying environmental facilities. In current releases iostream
    depends fairly heavily on libio constant definitions, but it should
    be made independent.  It also depends on operating system primitives
    for file operations. There is immense room for optimizations using
    (e.g.) mmap for reading. The shadow/ directory wraps, besides the
    standard C headers, the libio.h and unistd.h headers, for use mainly
    by filebuf. These wrappings have not been completed, though there
    is scaffolding in place.

    The encapsulation of certain C header &lt;cstdio&gt; names presents an
    interesting problem. It is possible to define an inline std::fprintf()
    implemented in terms of the 'extern "C"' vfprintf(), but there is no
    standard vfscanf() to use to implement std::fscanf(). It appears that
    vfscanf but be re-implemented in C++ for targets where no vfscanf
    extension has been defined. This is interesting in that it seems
    to be the only significant case in the C library where this kind of
    rewriting is necessary. (Of course Glibc provides the vfscanf()
    extension.)  (The functions related to exit() must be rewritten
    for other reasons.)


    Annex D
    -------
    Headers: &lt;strstream&gt;

    Annex D defines many non-library features, and many minor
    modifications to various headers, and a complete header.
    It is "mostly done", except that the libstdc++-2 &lt;strstream&gt;
    header has not been adopted into the library, or checked to
    verify that it matches the draft in those details that were
    clarified by the committee. Certainly it must at least be
    moved into the std namespace.

    We still need to wrap all the deprecated features in #if guards
    so that pedantic compile modes can detect their use.

    Nonstandard Extensions
    ----------------------
    Headers: &lt;iostream.h&gt; &lt;strstream.h&gt; &lt;hash&gt; &lt;rbtree&gt;
    &lt;pthread_alloc&gt; &lt;stdiobuf&gt; (etc.)

    User code has come to depend on a variety of nonstandard components
    that we must not omit. Much of this code can be adopted from
    libstdc++-v2 or from the SGI STL. This particularly includes
    &lt;iostream.h&gt;, &lt;strstream.h&gt;, and various SGI extensions such
    as &lt;hash_map.h&gt;. Many of these are already placed in the
    subdirectories ext/ and backward/. (Note that it is better to
    include them via "&lt;backward/hash_map.h&gt;" or "&lt;ext/hash_map&gt;" than
    to search the subdirectory itself via a "-I" directive.
  </literallayout></section></appendix><!-- Appendix B --><appendix version="5.0" xreflabel="Porting" xml:id="appendix.porting"><?dbhtml filename="appendix_porting.html"?><info><title>
  Porting and Maintenance
  <indexterm><primary>Appendix</primary><secondary>Porting and Maintenance</secondary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><!-- Hacking the Build System --><section version="5.0" xreflabel="Build Hacking" xml:id="appendix.porting.build_hacking"><?dbhtml filename="build_hacking.html"?><info><title>Configure and Build Hacking</title><keywordset><keyword>C++</keyword><keyword>build</keyword><keyword>configure</keyword><keyword>hacking</keyword><keyword>version</keyword><keyword>dynamic</keyword><keyword>shared</keyword></keywordset></info><section xml:id="build_hacking.prereq"><info><title>Prerequisites</title></info><para>
    As noted <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/prerequisites.html">previously</link>,
    certain other tools are necessary for hacking on files that
    control configure (<code>configure.ac</code>,
    <code>acinclude.m4</code>) and make
    (<code>Makefile.am</code>). These additional tools
    (<code>automake</code>, and <code>autoconf</code>) are further
    described in detail in their respective manuals. All the libraries
    in GCC try to stay in sync with each other in terms of versions of
    the auto-tools used, so please try to play nicely with the
    neighbors.
  </para></section><section xml:id="build_hacking.overview"><info><title>Overview</title></info><section xml:id="build_hacking.overview.basic"><info><title>General Process</title></info><para>
  The configure process begins the act of building libstdc++, and is
  started via:
</para><screen><computeroutput>
configure
</computeroutput></screen><para>
The <filename>configure</filename> file is a script generated (via
<command>autoconf</command>) from the file
<filename>configure.ac</filename>.
</para><para>
  After the configure process is complete,
</para><screen><computeroutput>
make all
</computeroutput></screen><para>
in the build directory starts the build process. The <literal>all</literal> target comes from the <filename>Makefile</filename> file, which is  generated via <command>configure</command> from the <filename>Makefile.in</filename> file, which is in turn generated (via
<command>automake</command>) from the file
<filename>Makefile.am</filename>.
</para></section><section xml:id="build_hacking.overview.map"><info><title>What Comes from Where</title></info><figure xml:id="fig.build_hacking.deps"><title>Configure and Build File Dependencies</title><mediaobject><imageobject><imagedata align="center" fileref="../images/confdeps.pdf" format="PDF" scale="75"></imagedata></imageobject><imageobject><imagedata align="center" fileref="../images/confdeps.png" format="PNG" scale="100"></imagedata></imageobject><textobject><phrase>Dependency Graph for Configure and Build Files</phrase></textobject></mediaobject></figure><para>
    Regenerate all generated files by using the command
    <command>autoreconf</command> at the top level of the libstdc++ source
    directory.
  </para></section></section><!-- overview --><section xml:id="build_hacking.configure"><info><title>Configure</title></info><section xml:id="build_hacking.configure.scripts"><info><title>Storing Information in non-AC files (like configure.host)</title></info><para>
    Until that glorious day when we can use <literal>AC_TRY_LINK</literal>
    with a cross-compiler, we have to hardcode the results of what the tests
    would have shown if they could be run.  So we have an inflexible
    mess like <filename>crossconfig.m4</filename>.
  </para><para>
    Wouldn't it be nice if we could store that information in files
    like configure.host, which can be modified without needing to
    regenerate anything, and can even be tweaked without really
    knowing how the configury all works?  Perhaps break the pieces of
    <filename>crossconfig.m4</filename> out and place them in their appropriate
    <filename class="directory">config/{cpu,os}</filename> directory.
  </para><para>
    Alas, writing macros like
    "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside
    files which are passed through autoconf.  Files which are pure
    shell script can be source'd at configure time.  Files which
    contain autoconf macros must be processed with autoconf.  We could
    still try breaking the pieces out into "config/*/cross.m4" bits,
    for instance, but then we would need arguments to aclocal/autoconf
    to properly find them all when generating configure.  I would
    discourage that.
</para></section><section xml:id="build_hacking.configure.conventions"><info><title>Coding and Commenting Conventions</title></info><para>
    Most comments should use {octothorpes, shibboleths, hash marks,
    pound signs, whatever} rather than "<literal>dnl</literal>".
    Nearly all comments in <filename>configure.ac</filename> should.
    Comments inside macros written in ancillary
    <filename class="extension">.m4</filename> files should.
    About the only comments which should <emphasis>not</emphasis>
    use <literal>#</literal>, but use <literal>dnl</literal> instead,
    are comments <emphasis>outside</emphasis> our own macros in the ancillary
    files.  The difference is that <literal>#</literal> comments show up in
    <filename>configure</filename> (which is most helpful for debugging),
    while <literal>dnl</literal>'d lines just vanish.  Since the macros
    in ancillary files generate code which appears in odd places,
    their "outside" comments tend to not be useful while reading
    <filename>configure</filename>.
  </para><para>
    Do not use any <code>$target*</code> variables, such as
    <varname>$target_alias</varname>.  The single exception is in
    <filename>configure.ac</filename>, for automake+dejagnu's sake.
  </para></section><section xml:id="build_hacking.configure.acinclude"><info><title>The acinclude.m4 layout</title></info><para>
    The nice thing about
    <filename>acinclude.m4</filename>/<filename>aclocal.m4</filename>
    is that macros aren't
    actually performed/called/expanded/whatever here, just loaded.  So
    we can arrange the contents however we like.  As of this writing,
    <filename>acinclude.m4</filename> is arranged as follows:
  </para><programlisting>
    GLIBCXX_CHECK_HOST
    GLIBCXX_TOPREL_CONFIGURE
    GLIBCXX_CONFIGURE
</programlisting><para>
    All the major variable "discovery" is done here.
    <varname>CXX</varname>, multilibs,
    etc.
  </para><programlisting>
    fragments included from elsewhere
</programlisting><para>
    Right now, "fragments" == "the math/linkage bits".
  </para><programlisting>
    GLIBCXX_CHECK_COMPILER_FEATURES
    GLIBCXX_CHECK_LINKER_FEATURES
    GLIBCXX_CHECK_WCHAR_T_SUPPORT
</programlisting><para>
  Next come extra compiler/linker feature tests.  Wide character
  support was placed here because I couldn't think of another place
  for it.  It will probably get broken apart like the math tests,
  because we're still disabling wchars on systems which could actually
  support them.
</para><programlisting>
    GLIBCXX_CHECK_SETRLIMIT_ancilliary
    GLIBCXX_CHECK_SETRLIMIT
    GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
    GLIBCXX_CHECK_POLL
    GLIBCXX_CHECK_WRITEV

    GLIBCXX_CONFIGURE_TESTSUITE
</programlisting><para>
  Feature tests which only get used in one place.  Here, things used
  only in the testsuite, plus a couple bits used in the guts of I/O.
</para><programlisting>
    GLIBCXX_EXPORT_INCLUDES
    GLIBCXX_EXPORT_FLAGS
    GLIBCXX_EXPORT_INSTALL_INFO
</programlisting><para>
  Installation variables, multilibs, working with the rest of the
  compiler.  Many of the critical variables used in the makefiles are
  set here.
</para><programlisting>
    GLIBGCC_ENABLE
    GLIBCXX_ENABLE_C99
    GLIBCXX_ENABLE_CHEADERS
    GLIBCXX_ENABLE_CLOCALE
    GLIBCXX_ENABLE_CONCEPT_CHECKS
    GLIBCXX_ENABLE_CSTDIO
    GLIBCXX_ENABLE_CXX_FLAGS
    GLIBCXX_ENABLE_C_MBCHAR
    GLIBCXX_ENABLE_DEBUG
    GLIBCXX_ENABLE_DEBUG_FLAGS
    GLIBCXX_ENABLE_LONG_LONG
    GLIBCXX_ENABLE_PCH
    GLIBCXX_ENABLE_SYMVERS
    GLIBCXX_ENABLE_THREADS
</programlisting><para>
  All the features which can be controlled with enable/disable
  configure options.  Note how they're alphabetized now?  Keep them
  like that.  :-)
</para><programlisting>
    AC_LC_MESSAGES
    libtool bits
</programlisting><para>
  Things which we don't seem to use directly, but just has to be
  present otherwise stuff magically goes wonky.
</para></section><section xml:id="build_hacking.configure.enable"><info><title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title></info><para>
    All the <literal>GLIBCXX_ENABLE_FOO</literal> macros use a common
    helper, <literal>GLIBCXX_ENABLE</literal>.  (You don't have to use
    it, but it's easy.)  The helper does two things for us:
  </para><orderedlist><listitem><para>
     Builds the call to the <literal>AC_ARG_ENABLE</literal> macro, with
     <option>--help</option> text
     properly quoted and aligned.  (Death to changequote!)
   </para></listitem><listitem><para>
     Checks the result against a list of allowed possibilities, and
     signals a fatal error if there's no match.  This means that the
     rest of the <literal>GLIBCXX_ENABLE_FOO</literal> macro doesn't need to test for
     strange arguments, nor do we need to protect against
     empty/whitespace strings with the <code>"x$foo" = "xbar"</code>
     idiom.
   </para></listitem></orderedlist><para>Doing these things correctly takes some extra autoconf/autom4te code,
   which made our macros nearly illegible.  So all the ugliness is factored
   out into this one helper macro.
</para><para>Many of the macros take an argument, passed from when they are expanded
   in configure.ac.  The argument controls the default value of the
   enable/disable switch.  Previously, the arguments themselves had defaults.
   Now they don't, because that's extra complexity with zero gain for us.
</para><para>There are three "overloaded signatures".  When reading the descriptions
   below, keep in mind that the brackets are autoconf's quotation characters,
   and that they will be stripped.  Examples of just about everything occur
   in acinclude.m4, if you want to look.
</para><programlisting>
    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
</programlisting><itemizedlist><listitem><para><literal>FEATURE</literal> is the string that follows
     <option>--enable</option>.  The results of the
     test (such as it is) will be in the variable
     <varname>$enable_FEATURE</varname>,
     where <literal>FEATURE</literal> has been squashed.  Example:
     <code>[extra-foo]</code>, controlled by the
     <option>--enable-extra-foo</option>
     option and stored in <varname>$enable_extra_foo</varname>.
   </para></listitem><listitem><para><literal>DEFAULT</literal> is the value to store in
     <varname>$enable_FEATURE</varname> if the user does
     not pass <option>--enable</option>/<option>--disable</option>.
     It should be one of the permitted values passed later.
     Examples: <code>[yes]</code>, or <code>[bar]</code>, or
     <code>[$1]</code> (which passes the argument given to the
     <literal>GLIBCXX_ENABLE_FOO</literal> macro as the default).
   </para><para>
     For cases where we need to probe for particular models of things,
     it is useful to have an undocumented "auto" value here (see
     <literal>GLIBCXX_ENABLE_CLOCALE</literal> for an example).
   </para></listitem><listitem><para><literal>HELP-ARG</literal> is any text to append to the option string
     itself in the <option>--help</option> output.  Examples:
     <code>[]</code> (i.e., an empty string, which appends nothing),
     <code>[=BAR]</code>, which produces <code>--enable-extra-foo=BAR</code>,
     and <code>[@&lt;:@=BAR@:&gt;@]</code>, which produces
     <code>--enable-extra-foo[=BAR]</code>.  See the difference?  See
     what it implies to the user?
   </para><para>
     If you're wondering what that line noise in the last example was,
     that's how you embed autoconf special characters in output text.
     They're called <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/"><emphasis>quadrigraphs</emphasis></link>
     and you should use them whenever necessary.
 </para></listitem><listitem><para><literal>HELP-STRING</literal> is what you think it is.  Do not include the
   "default" text like we used to do; it will be done for you by
   <literal>GLIBCXX_ENABLE</literal>.  By convention, these are not full English
   sentences.  Example: <literal>[turn on extra foo]</literal>
   </para></listitem></itemizedlist><para>
  With no other arguments, only the standard autoconf patterns are
  allowed: "<option>--{enable,disable}-foo[={yes,no}]</option>" The
  <varname>$enable_FEATURE</varname> variable is guaranteed to equal
  either "<literal>yes</literal>" or "<literal>no</literal>"
  after the macro.  If the user tries to pass something else, an
  explanatory error message will be given, and configure will halt.
</para><para>
  The second signature takes a fifth argument, "<code>[permit
  a | b | c | ...]</code>"
  This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> or
  ... after the equals sign in the option, and
  <varname>$enable_FEATURE</varname> is
  guaranteed to equal one of them after the macro.  Note that if you
  want to allow plain <option>--enable</option>/<option>--disable</option>
  with no "<literal>=whatever</literal>", you must
  include "<literal>yes</literal>" and "<literal>no</literal>" in the
  list of permitted values.  Also note that whatever you passed as
  <literal>DEFAULT</literal> must be in the list.  If the
  user tries to pass something not on the list, a semi-explanatory
  error message will be given, and configure will halt.  Example:
  <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
</para><para>
  The third signature takes a fifth argument.  It is arbitrary shell
  code to execute if the user actually passes the enable/disable
  option.  (If the user does not, the default is used.  Duh.)  No
  argument checking at all is done in this signature.  See
  <literal>GLIBCXX_ENABLE_CXX_FLAGS</literal> for an example of handling,
  and an error message.
</para></section><section xml:id="build_hacking.configure.version"><info><title>Shared Library Versioning</title></info><para>
The <filename class="library">libstdc++.so</filename> shared library must
be carefully managed to maintain binary compatible with older versions
of the library. This ensures a new version of the library is still usable by
programs that were linked against an older version.
</para><para>
Dependent on the target supporting it, the library uses <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.akkadia.org/drepper/symbol-versioning">ELF
symbol versioning</link> for all exported symbols. The symbol versions
are defined by a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceware.org/binutils/docs/ld/VERSION.html">linker
script</link> that assigns a version to every symbol.
The set of symbols in each version is fixed when a GCC
release is made, and must not change after that.
</para><para> When new symbols are added to the library they must be added
to a new symbol version, which must be created the first time new symbols
are added after a release. Adding a new symbol version involves the
following steps:
</para><itemizedlist><listitem><para>
Edit <filename>acinclude.m4</filename> to update the "revision" value of
<varname>libtool_VERSION</varname>, e.g. from <literal>6:22:0</literal>
to <literal>6:23:0</literal>, which will cause the shared library to be
built as <filename class="library">libstdc++.so.6.0.23</filename>.
</para></listitem><listitem><para>
Regenerate the <filename>configure</filename> script by running the
<command>autoreconf</command> tool from the correct version of the Autoconf
package (as dictated by the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/install/prerequisites.html">GCC
prerequisites</link>).
</para></listitem><listitem><para>
Edit the file <filename>config/abi/pre/gnu.ver</filename> to
add a new version node after the last new node. The node name should be
<literal>GLIBCXX_3.4.X</literal> where <literal>X</literal> is the new
revision set in <filename>acinclude.m4</filename>, and the node should
depend on the previous version e.g.
<programlisting>
    GLIBCXX_3.4.23 {

    } GLIBCXX_3.4.22;
</programlisting>
For symbols in the ABI runtime, libsupc++, the symbol version naming uses
<literal>CXXABI_1.3.Y</literal> where <literal>Y</literal> increases
monotonically with each new version. Again, the new node must depend on the
previous version node e.g.
<programlisting>
    CXXABI_1.3.11 {

    } CXXABI_1.3.10;
</programlisting>
</para></listitem><listitem><para>
In order for the <link linkend="test.run.variations">check-abi</link> test
target to pass the testsuite must be updated to know about the new symbol
version(s). Edit the file <filename>testsuite/util/testsuite_abi.cc</filename>
file to add the new versions to the <varname>known_versions</varname> list,
and update the checks for the latest versions that set the
<varname>latestp</varname> variable).
</para></listitem><listitem><para>
Add the library (<filename class="library">libstdc++.so.6.0.X</filename>)
and symbols versions
(<literal>GLIBCXX_3.4.X</literal> and <literal>CXXABI_1.3.Y</literal>)
to the <link linkend="abi.versioning.history">History</link> section in
<filename>doc/xml/manual/abi.xml</filename> at the relevant places.
</para></listitem></itemizedlist><para>
Once the new symbol version has been added you can add the names of your new
symbols in the new version node:
<programlisting>
    GLIBCXX_3.4.23 {

      # basic_string&lt;C, T, A&gt;::_Alloc_hider::_Alloc_hider(C*, A&amp;&amp;)
      _ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_;

    } GLIBCXX_3.4.22;
</programlisting>
You can either use mangled names, or demangled names inside an
<literal>extern "C++"</literal> block. You might find that the new symbol
matches an existing pattern in an old symbol version (causing the
<literal>check-abi</literal> test target to fail). If that happens then the
existing pattern must be adjusted to be more specific so that it doesn't
match the new symbol.
</para><para>
For an example of these steps, including adjusting old patterns to be less
greedy, see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html">https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html</link>
and the attached patch.
</para><para>
If it wasn't done for the last release, you might also need to regenerate
the <filename>baseline_symbols.txt</filename> file that defines the set
of expected symbols for old symbol versions. A new baseline file can be
generated by running <userinput>make new-abi-baseline</userinput> in the
<filename class="directory"><replaceable>libbuilddir</replaceable>/testsuite</filename>
directory. Be sure to generate the baseline from a clean build using
unmodified sources, or you will incorporate your local changes into the
baseline file.
</para></section></section><!-- configure --><section xml:id="build_hacking.make"><info><title>Make</title></info><para>
    The build process has to make all of object files needed for
    static or shared libraries, but first it has to generate some
    include files. The general order is as follows:
  </para><orderedlist><listitem><para>
     make include files, make pre-compiled headers
   </para></listitem><listitem><para>
     make libsupc++
   </para><para>
     Generates a libtool convenience library,
     <filename>libsupc++convenience</filename> with language-support
     routines. Also generates a freestanding static library,
     <filename>libsupc++.a</filename>.
   </para></listitem><listitem><para>
     make src
   </para><para>
     Generates several convenience libraries,
     various compatibility files for shared and static libraries,
     and then collects all the generated bits and creates
     the final libstdc++ libraries.
  </para><orderedlist><listitem><para>
     make src/c++98
   </para><para>
     Generates a libtool convenience library,
     <filename>libc++98convenience</filename> with the library components
     defined by C++98. Uses the <option>-std=gnu++98</option> dialect.
   </para></listitem><listitem><para>
     make src/c++11
   </para><para>
     Generates a libtool convenience library,
     <filename>libc++11convenience</filename> with the library components
     that were added or changed in C++11.
     Uses the <option>-std=gnu++11</option> dialect.
   </para></listitem><listitem><para>
     make src/c++17
   </para><para>
     Generates a libtool convenience library,
     <filename>libc++17convenience</filename> with the library components
     that were added or changed in C++17.
     Uses the <option>-std=gnu++17</option> dialect.
   </para></listitem><listitem><para>
     make src/c++20
   </para><para>
     Generates a libtool convenience library,
     <filename>libc++20convenience</filename> with the library components
     that were added or changed in C++20.
     Uses the <option>-std=gnu++20</option> dialect.
   </para></listitem><listitem><para>
     make src/c++23
   </para><para>
     Generates a libtool convenience library,
     <filename>libc++23convenience</filename> with the library components
     that were added or changed in C++23.
     At the time of writing (GCC 14) this convenience library is included
     in <filename>libstdc++exp.a</filename> and not in the final
     <filename>libstdc++</filename> libraries.
     Uses the <option>-std=gnu++23</option> dialect.
   </para></listitem><listitem><para>
     make src/filesystem
   </para><para>
     Generates a libtool convenience library,
     <filename>libstdc++fsconvenience</filename>,
     and a standalone static library,
     <filename>libstdc++fs.a</filename>.
     These contain definitions of the Filesystem TS extensions.
     Uses the <option>-std=gnu++17</option> dialect.
   </para></listitem><listitem><para>
     make src/libbacktrace
   </para><para>
     Generates a libtool convenience library,
     <filename>libstdc++_libbacktrace</filename>,
     containing the libbacktrace definitions used by the C++23
     <classname>std::stacktrace</classname> feature.
   </para></listitem><listitem><para>
     make src/experimental
   </para><para>
     Generates a standalone static library,
     <filename>libstdc++exp.a</filename>, containing the symbol definitions
     for experimental features and extensions. This collects the convenience
     libraries <filename>libstdc++fsconvenience</filename>,
     <filename>libstdc++_libbacktrace</filename>, and
     (at the time of writing) <filename>libc++23convenience</filename>
     and combines them into one.
     Uses the <option>-std=gnu++17</option> dialect.
   </para></listitem><listitem><para>
     make src
   </para><para>
     Generates needed compatibility objects for shared and static
     libraries. Shared-only code is seggregated at compile-time via
     the macro <literal>_GLIBCXX_SHARED</literal>.
   </para><para>
     Then, collects all the generated convenience libraries that weren't
     added to <filename>libstdc++exp.a</filename>,
     adds in any required compatibility objects,
     and creates the final shared and static libraries:
     <filename>libstdc++.so</filename> and <filename>libstdc++.a</filename>.
   </para></listitem></orderedlist></listitem></orderedlist></section><!-- make --><section xml:id="build_hacking.generated"><info><title>Generated files</title></info><para>
  Some files in the libstdc++ source tree are auto-generated from other files.
  In general, these are not regenerated automatically, so it must be done
  manually when the files they depend on are updated.
</para><itemizedlist><listitem><para>
   The header file
   <filename class="headerfile">include/bits/version.h</filename>
   is generated from <filename>version.def</filename> and
   <filename>version.tpl</filename> in the same directory.
   After editing those files, either run <command>autogen version.def</command>
   in the <filename class="directory">include</filename> directory of the
   source tree, or run <command>make update-version</command> in the
   <filename class="directory">include</filename> directory of the build tree.
   </para></listitem><listitem><para>
   The header file
   <filename class="headerfile">include/bits/unicode-data.h</filename>
   is generated by the Python script
   <filename>../contrib/unicode/gen_libstdcxx_unicode_data.py</filename>
   using data files in the same directory. The script contains information
   on which data files it uses and how to update them.
   </para></listitem><listitem><para>
   The header file
   <filename class="headerfile">include/bits/text_encoding-data.h</filename>
   is generated by the Python script
   <filename>scripts/gen_text_encoding_data.py</filename>
   using the CSV file <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iana.org/assignments/character-sets/character-sets-1.csv"></link>
   from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iana.org/time-zones">IANA Character Sets</link>
   registry.
   </para></listitem><listitem><para>
   The data file <filename>src/c++20/tzdata.zi</filename> is copied verbatim
   from the
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iana.org/time-zones">IANA Time Zone Database</link>
   (the latest version can be downloaded from
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://data.iana.org/time-zones/tzdb/tzdata.zi"></link>).
   Libstdc++ uses this data file to populate a
   <classname>std::chrono::tzdb</classname> object in case the system does not
   provide a copy of the file.
   See <xref linkend="manual.intro.setup.configure"></xref> for the
   <code>--with-libstdcxx-zoneinfo</code> option that determines whether
   this file is used.
   </para></listitem><listitem><para>
   The header file
   <filename class="headerfile">src/c++20/windows_zones-map.h</filename>
   is generated by the Python script
   <filename>scripts/gen_windows_zones_map.py</filename>
   using the XML file <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/unicode-org/cldr/blob/main/common/supplemental/windowsZones.xml"></link>
   from the Unicode CLDR Project.
   </para></listitem></itemizedlist></section><!-- Generated files --></section><!-- Hacking the Documentation Systems --><section version="5.0" xreflabel="Documentation Hacking" xml:id="appendix.porting.doc"><?dbhtml filename="documentation_hacking.html"?><info><title>Writing and Generating Documentation</title><keywordset><keyword>ISO C++</keyword><keyword>documentation</keyword><keyword>style</keyword><keyword>docbook</keyword><keyword>doxygen</keyword></keywordset></info><section xml:id="doc.intro"><info><title>Introduction</title></info><para>
      Documentation for the GNU C++ Library is created from three
      independent sources: a manual, a FAQ, and an API reference.
    </para><para>
      The sub-directory <filename class="directory">doc</filename>
      within the main source directory contains
      <filename>Makefile.am</filename> and
      <filename>Makefile.in</filename>, which provide rules for
      generating documentation, described in excruciating detail
      below. The <filename class="directory">doc</filename>
      sub-directory also contains three directories: <filename class="directory">doxygen</filename>, which contains scripts and
      fragments for <command>doxygen</command>, <filename class="directory">html</filename>, which contains an html
      version of the manual, and <filename class="directory">xml</filename>, which contains an xml version
      of the manual.
    </para><para>
      Diverging from established documentation conventions in the rest
      of the GCC project, libstdc++ does not use Texinfo as a markup
      language. Instead, Docbook is used to create the manual and the
      FAQ, and Doxygen is used to construct the API
      reference. Although divergent, this conforms to the GNU Project
      recommendations as long as the output is of sufficient quality,
      as per
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation">
      GNU Manuals</link>.
    </para></section><section xml:id="doc.generation"><info><title>Generating Documentation</title></info><para>
      Certain Makefile rules are required by the GNU Coding
      Standards. These standard rules generate HTML, PDF, XML, or man
      files. For each of the generative rules, there is an additional
      install rule that is used to install any generated documentation
      files into the prescribed installation directory. Files are
      installed into <filename class="directory">share/doc</filename>
      or <filename class="directory">share/man</filename> directories.
    </para><para>
      The standard Makefile rules are conditionally supported, based
      on the results of examining the host environment for
      prerequisites at configuration time. If requirements are not
      found, the rule is aliased to a dummy rule that does nothing,
      and produces no documentation. If the requirements are found,
      the rule forwards to a private rule that produces the requested
      documentation.
    </para><para>
      For more details on what prerequisites were found and where,
      please consult the file <filename>config.log</filename> in the
      libstdc++ build directory. Compare this log to what is expected
      for the relevant Makefile conditionals:
      <literal>BUILD_INFO</literal>, <literal>BUILD_XML</literal>,
      <literal>BUILD_HTML</literal>, <literal>BUILD_MAN</literal>,
      <literal>BUILD_PDF</literal>, and <literal>BUILD_EPUB</literal>.
    </para><para>
      Supported Makefile rules:
    </para><variablelist><varlistentry><term><emphasis>make html</emphasis></term><term><emphasis>make install-html</emphasis></term><listitem><para>
	    Generates multi-page HTML documentation, and installs it
	    in the following directories:
	  </para><para><filename>doc/libstdc++/libstdc++-api.html</filename></para><para><filename>doc/libstdc++/libstdc++-manual.html</filename></para></listitem></varlistentry><varlistentry><term><emphasis>make pdf</emphasis></term><term><emphasis>make install-pdf</emphasis></term><listitem><para>
	    Generates indexed PDF documentation, and installs it as
	    the following files:
	  </para><para><filename>doc/libstdc++/libstdc++-api.pdf</filename></para><para><filename>doc/libstdc++/libstdc++-manual.pdf</filename></para></listitem></varlistentry><varlistentry><term><emphasis>make man</emphasis></term><term><emphasis>make install-man</emphasis></term><listitem><para>
	    Generates man pages, and installs it in the following directory:
	  </para><para><filename class="directory">man/man3/</filename></para><para>
	    The generated man pages are namespace-qualified, so to look at
	    the man page for <classname>vector</classname>, one would use
	    <command>man std::vector</command>.
	  </para></listitem></varlistentry><varlistentry><term><emphasis>make epub</emphasis></term><term><emphasis>make install-epub</emphasis></term><listitem><para>
	    Generates documentation in the ebook/portable electronic
	    reader format called Epub, and installs it as the
	    following file.
	  </para><para><filename>doc/libstdc++/libstdc++-manual.epub</filename></para></listitem></varlistentry><varlistentry><term><emphasis>make xml</emphasis></term><term><emphasis>make install-xml</emphasis></term><listitem><para>
	    Generates single-file XML documentation, and installs it
	    as the following files:
	  </para><para><filename>doc/libstdc++/libstdc++-api-single.xml</filename></para><para><filename>doc/libstdc++/libstdc++-manual-single.xml</filename></para></listitem></varlistentry></variablelist><para>
      Makefile rules for several other formats are explicitly not
      supported, and are always aliased to dummy rules. These
      unsupported formats are: <emphasis>info</emphasis>,
      <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
    </para></section><section xml:id="doc.doxygen"><info><title>Doxygen</title></info><section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info><table frame="all" xml:id="table.doxygen_prereq"><title>Doxygen Prerequisites</title><tgroup align="center" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry>Tool</entry><entry>Version</entry><entry>Required By</entry></row></thead><tbody><row><entry>coreutils</entry><entry>8.5</entry><entry>all</entry></row><row><entry>bash</entry><entry>4.1</entry><entry>all</entry></row><row><entry>doxygen</entry><entry>1.9.1</entry><entry>all</entry></row><row><entry>graphviz</entry><entry>2.26</entry><entry>graphical hierarchies</entry></row><row><entry>pdflatex</entry><entry>2007-59</entry><entry>pdf output</entry></row></tbody></tgroup></table><para>
	Prerequisite tools are Bash 2.0 or later,
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.doxygen.nl">Doxygen</link>
	1.9.1 or later (for best results use at least 1.9.6), and
	the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
	coreutils</link>. (GNU versions of find, xargs, and possibly
	sed and grep are used, just because the GNU versions make
	things very easy.)
      </para><para>
	To generate the pretty pictures and hierarchy
	graphs, the
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.graphviz.org">Graphviz</link> package
	will need to be installed. For PDF
	output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tug.org/applications/pdftex/">
	pdflatex</link> is required as well as a number of TeX packages
	such as <package>texlive-xtab</package> and
	<package>texlive-tocloft</package>.
      </para><para>
	Be warned the PDF file generated via doxygen is extremely
	large. At last count, the PDF file is over three thousand
	pages. Generating this document taxes the underlying TeX
	formatting system, and will require the expansion of TeX's memory
	capacity. Specifically, the <literal>pool_size</literal>
	variable in the configuration file <filename>texmf.cnf</filename> may
	need to be increased by a minimum factor of two. Alternatively, using
	<userinput>LATEX_CMD=lualatex</userinput> might allow the docs to be
	build without running out of memory.
      </para></section><section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info><para>
	The following Makefile rules run Doxygen to generate HTML
	docs, XML docs, XML docs as a single file, PDF docs, and the
	man pages. These rules are not conditional! If the required
	tools are not found, or are the wrong versions, the rule may
	end in an error.
      </para><para><screen><userinput>make doc-html-doxygen</userinput></screen></para><para><screen><userinput>make doc-xml-doxygen</userinput></screen></para><para><screen><userinput>make doc-xml-single-doxygen</userinput></screen></para><para><screen><userinput>make doc-pdf-doxygen</userinput></screen></para><para><screen><userinput>make doc-man-doxygen</userinput></screen></para><para>
	Generated files are output into separate sub directories of
	<filename class="directory">doc/doxygen/</filename> in the
	build directory, based on the output format. For instance, the
	HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
      </para><para>
	Careful observers will see that the Makefile rules simply call
	a script from the source tree, <filename>run_doxygen</filename>, which
	does the actual work of running Doxygen and then (most
	importantly) massaging the output files. If for some reason
	you prefer to not go through the Makefile, you can call this
	script directly. (Start by passing <literal>--help</literal>.)
      </para><para>
	If you wish to tweak the Doxygen settings, do so by editing
	<filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
	library hackers are written in triple-# comments.
      </para></section><section xml:id="doxygen.debug"><info><title>Debugging Generation</title></info><para>
	  Sometimes, mis-configuration of the pre-requisite tools can
	  lead to errors when attempting to build the
	  documentation. Here are some of the obvious errors, and ways
	  to fix some common issues that may appear quite cryptic.
	</para><para>
	  First, if using a rule like <code>make pdf</code>, try to
	  narrow down the scope of the error to either docbook
	  (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
	  doc-pdf-doxygen</code>).
	</para><para>
	  Working on the doxygen path only, closely examine the
	  contents of the following build directory: <filename class="directory">build/target/libstdc++-v3/doc/doxygen/latex</filename>.
	  Pay attention to three files enclosed within, annotated as follows.
	</para><itemizedlist><listitem><para><emphasis>refman.tex</emphasis></para><para>
    The actual latex file, or partial latex file. This is generated
    via <command>doxygen</command>, and is the LaTeX version of the
    Doxygen XML file <filename>libstdc++-api.xml</filename>. Go to a specific
    line, and look at the generated LaTeX, and try to deduce what
    markup in <filename>libstdc++-api.xml</filename> is causing it.
  </para></listitem><listitem><para><emphasis>refman.log</emphasis></para><para>
    A log created by <command>latex</command> as it processes the
    <filename>refman.tex</filename> file. If generating the PDF fails
    look at the end of this file for errors such as:
    <screen>
    ! LaTeX Error: File `xtab.sty' not found.
    </screen>
    This indicates a required TeX package is missing. For the example
    above the <package>texlive-xtab</package> package needs to be
    installed.
  </para></listitem><listitem><para><emphasis>refman.out</emphasis></para><para>
    A log of the compilation of the converted LaTeX form to PDF. This
    is a linear list, from the beginning of the
    <filename>refman.tex</filename> file: the last entry of this file
    should be the end of the LaTeX file. If it is truncated, then you
    know that the last entry is the last part of the generated LaTeX
    source file that is valid. Often this file contains an error with
    a specific line number of <filename>refman.tex</filename> that is
    incorrect, or will have clues at the end of the file with the dump
    of the memory usage of LaTeX.
  </para></listitem></itemizedlist><para>
	  If the error at hand is not obvious after examination, a
	  fall-back strategy is to start commenting out the doxygen
	  input sources, which can be found in
	  <filename>doc/doxygen/user.cfg.in</filename>, look for the
	  <literal>INPUT</literal> tag. Start by commenting out whole
	  directories of header files, until the offending header is
	  identified. Then, read the latex log files to try and find
	  surround text, and look for that in the offending header.
	</para></section><section xml:id="doxygen.markup"><info><title>Markup</title></info><para>
	In general, libstdc++ files should be formatted according to
	the rules found in the
	<link linkend="contrib.coding_style">Coding Standard</link>. Before
	any doxygen-specific formatting tweaks are made, please try to
	make sure that the initial formatting is sound.
      </para><para>
	Adding Doxygen markup to a file (informally called
	<quote>doxygenating</quote>) is very simple. See the
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.doxygen.nl/download.html#latestman">Doxygen
         manual</link> for details.
	We try to use a very-recent version of Doxygen.
      </para><para>
	For classes, use
	<classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
	and <classname>std::pair</classname> as examples.  For
	functions, see their member functions, and the free functions
	in <filename class="headerfile">stl_algobase.h</filename>. Member
	functions of other container-like types should read similarly to
	these member functions.
      </para><para>
	Some commentary to accompany
	the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.doxygen.nl/manual/docblocks.html">Special
	Documentation Blocks</link> section of the Doxygen manual:
      </para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>For longer comments, use the Javadoc style...</para></listitem><listitem><para>
	    ...not the Qt style. The intermediate *'s are preferred.
	  </para></listitem><listitem><para>
	    Use the triple-slash style only for one-line comments (the
	    <quote>brief</quote> mode).
	  </para></listitem><listitem><para>
	    This is disgusting. Don't do this.
	  </para></listitem></orderedlist><para>
	Some specific guidelines:
      </para><para>
	Use the @-style of commands, not the !-style. Please be
	careful about whitespace in your markup comments. Most of the
	time it doesn't matter; doxygen absorbs most whitespace, and
	both HTML and *roff are agnostic about whitespace. However,
	in &lt;pre&gt; blocks and @code/@endcode sections, spacing can
	have <quote>interesting</quote> effects.
      </para><para>
	Use either kind of grouping, as
	appropriate. <filename>doxygroups.cc</filename> exists for this
	purpose. See <filename class="headerfile">stl_iterator.h</filename>
	for a good example of the <quote>other</quote> kind of grouping.
      </para><para>
	Markdown can be used for formatting text. Doxygen is configured to
	support this, and it is a good compromise between readable comments
	in the C++ source and nice formatting in the generated HTML.
	Please format the names of function parameters in either code font
	or italics. Use underscores or @e for emphasis when necessary.
	Use backticks or @c to refer to other standard names.
	(Examples of all these abound in the present code.)
      </para><para>
	Complicated math functions should use the multi-line format.
	An example from <filename class="headerfile">random.h</filename>:
      </para><para><literallayout class="normal">
/**
 * @brief A model of a linear congruential random number generator.
 *
 * @f[
 *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
 * @f]
 */
</literallayout></para><para>
	One area of note is the markup required for
	<literal>@file</literal> markup in header files. Two details
	are important: for filenames that have the same name in
	multiple directories, include part of the installed path to
	disambiguate. For example:
      </para><para><literallayout class="normal">
/** @file debug/vector
 *  This file is a GNU debug extension to the Standard C++ Library.
 */
</literallayout></para><para>
	The other relevant detail for header files is the use of a
	libstdc++-specific doxygen alias that helps distinguish
	between public header files (like <filename class="headerfile">random</filename>)
	from implementation or private header files (like
	<filename class="headerfile">bits/c++config.h</filename>.) This alias is spelled
	<literal>@headername</literal> and can take one or two
	arguments that detail the public header file or files that
	should be included to use the contents of the file. All header
	files that are not intended for direct inclusion must use
	<literal>headername</literal> in the <literal>file</literal>
	block. An example:
      </para><para><literallayout class="normal">
/** @file bits/basic_string.h
 *  This is an internal header file, included by other library headers.
 *  Do not attempt to use it directly. @headername{string}
 */
</literallayout></para><para>
	Be careful about using certain, special characters when
	writing Doxygen comments. Single and double quotes, and
	separators in filenames are two common trouble spots. When in
	doubt, consult the following table.
      </para><table frame="all" xml:id="table.doxygen_cmp"><title>HTML to Doxygen Markup Comparison</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><thead><row><entry>HTML</entry><entry>Doxygen</entry><entry>Markdown</entry></row></thead><tbody><row><entry>\</entry><entry>\\</entry><entry>\\</entry></row><row><entry>"</entry><entry>\"</entry><entry>\"</entry></row><row><entry>'</entry><entry>\'</entry><entry>\'</entry></row><row><entry>&lt;i&gt;</entry><entry>@a word</entry><entry>_word_ or *word*</entry></row><row><entry>&lt;b&gt;</entry><entry>@b word</entry><entry>**word** or __word__</entry></row><row><entry>&lt;code&gt;</entry><entry>@c word</entry><entry>`word`</entry></row><row><entry>&lt;em&gt;</entry><entry>@a word</entry><entry>_word_ or *word*</entry></row><row><entry>&lt;em&gt;</entry><entry>&lt;em&gt;two words or more&lt;/em&gt;</entry><entry>_two words or more_</entry></row></tbody></tgroup></table></section></section><section xml:id="doc.docbook"><info><title>Docbook</title></info><section xml:id="docbook.prereq"><info><title>Prerequisites</title></info><table frame="all" xml:id="table.docbook_prereq"><title>Docbook Prerequisites</title><tgroup align="center" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry>Tool</entry><entry>Version</entry><entry>Required By</entry></row></thead><tbody><row><entry>docbook5-style-xsl</entry><entry>1.76.1</entry><entry>all</entry></row><row><entry>xsltproc</entry><entry>1.1.26</entry><entry>all</entry></row><row><entry>xmllint</entry><entry>2.7.7</entry><entry>validation</entry></row><row><entry>dblatex</entry><entry>0.3</entry><entry>pdf output</entry></row><row><entry>pdflatex</entry><entry>2007-59</entry><entry>pdf output</entry></row><row><entry>docbook2X</entry><entry>0.8.8</entry><entry>info output</entry></row><row><entry>epub3 stylesheets</entry><entry>b3</entry><entry>epub output</entry></row></tbody></tgroup></table><para>
	An XML editor is recommended for editing the DocBook sources. Many
	exist: some notable options
	include <command>emacs</command>, <application>Kate</application>,
	or <application>Conglomerate</application>.
      </para><para>
	Some editors support special <quote>XML Validation</quote>
	modes that can validate the file as it is
	produced. Recommended is the <command>nXML Mode</command>
	for <command>emacs</command>.
      </para><para>
	Besides an editor, additional DocBook files and XML tools are
	also required.
      </para><para>
	Access to the DocBook 5.0 stylesheets and schema is required. The
	stylesheets are usually packaged by vendor, in something
	like <filename>docbook5-style-xsl</filename>. To exactly match
	generated output, please use a version of the stylesheets
	equivalent
	to <filename>docbook5-style-xsl-1.75.2-3</filename>. The
	installation directory for this package corresponds to
	the <literal>XSL_STYLE_DIR</literal>
	in <filename>doc/Makefile.am</filename> and defaults
	to <filename class="directory">/usr/share/sgml/docbook/xsl-ns-stylesheets</filename>.
      </para><para>
	For processing XML, an XSLT processor and some style
	sheets are necessary. Defaults are <command>xsltproc</command>
	provided by <filename>libxslt</filename>.
      </para><para>
	For validating the XML document, you'll need
	something like <command>xmllint</command> and access to the
	relevant DocBook schema. These are provided
	by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
      </para><para>
	For PDF output, something that transforms valid Docbook XML to PDF is
	required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://dblatex.sourceforge.net">dblatex</link>,
	<command>xmlto</command>, or <command>prince</command>. Of
	these, <command>dblatex</command> is the default.
	Please consult the <email>libstdc++@gcc.gnu.org</email> list when
	preparing printed manuals for current best practice and
	suggestions.
      </para><para>
	For Texinfo output, something that transforms valid Docbook
	XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docbook2x.sourceforge.net/">docbook2X</link>.
      </para><para>
	For epub output, the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://sourceforge.net/projects/docbook/files/epub3/">stylesheets</link> for EPUB3 are required. These stylesheets are still in development. To validate the created file, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/w3c/epubcheck">epubcheck</link> is necessary.
      </para></section><section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info><para>
	The following Makefile rules generate (in order): an HTML
	version of all the DocBook documentation, a PDF version of the
	same, and a single XML document.  These rules are not
	conditional! If the required tools are not found, or are the
	wrong versions, the rule may end in an error.
      </para><para><screen><userinput>make doc-html-docbook</userinput></screen></para><para><screen><userinput>make doc-pdf-docbook</userinput></screen></para><para><screen><userinput>make doc-xml-single-docbook</userinput></screen></para><para>
	Generated files are output into separate sub-directores of
	<filename class="directory">doc/docbook/</filename> in the
	build directory, based on the output format. For instance, the
	HTML docs will be in <filename class="directory">doc/docbook/html</filename>.
      </para><para>
	The <userinput>doc-html-docbook-regenerate</userinput> target will
	generate the HTML files and copy them back to the libstdc++ source tree.
	This can be used to update the HTML files that are checked in to
	version control.
      </para><para>
	If the Docbook stylesheets are installed in a custom location,
	one can use the variable <literal>XSL_STYLE_DIR</literal> to
	override the Makefile defaults. For example:
      </para><screen><userinput>
make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
	</userinput></screen></section><section xml:id="docbook.debug"><info><title>Debugging Generation</title></info><para>
	  Sometimes, mis-configuration of the pre-requisite tools can
	  lead to errors when attempting to build the
	  documentation. Here are some of the obvious errors, and ways
	  to fix some common issues that may appear quite cryptic.
	</para><para>
	  First, if using a rule like <code>make pdf</code>, try to
	  narrow down the scope of the error to either docbook
	  (<code>make doc-pdf-docbook</code>) or doxygen (<code>make
	  doc-pdf-doxygen</code>).
	</para><para>
	  Working on the docbook path only, closely examine the
	  contents of the following build directory:
	  <filename class="directory">build/target/libstdc++-v3/doc/docbook/latex</filename>.
	  Pay attention to three files enclosed within, annotated as follows.
	</para><itemizedlist><listitem><para><emphasis>spine.tex</emphasis></para><para>
    The actual latex file, or partial latex file. This is generated
    via <command>dblatex</command>, and is the LaTeX version of the
    DocBook XML file <filename>spine.xml</filename>. Go to a specific
    line, and look at the generated LaTeX, and try to deduce what
    markup in <filename>spine.xml</filename> is causing it.
  </para></listitem><listitem><para><emphasis>spine.out</emphasis></para><para>
    A log of the conversion from the XML form to the LaTeX form. This
    is a linear list, from the beginning of the
    <filename>spine.xml</filename> file: the last entry of this file
    should be the end of the DocBook file. If it is truncated, then
    you know that the last entry is the last part of the XML source
    file that is valid. The error is after this point.
  </para></listitem><listitem><para><emphasis>spine.log</emphasis></para><para>
    A log of the compilation of the converted LaTeX form to pdf. This
    is a linear list, from the beginning of the
    <filename>spine.tex</filename> file: the last entry of this file
    should be the end of the LaTeX file. If it is truncated, then you
    know that the last entry is the last part of the generated LaTeX
    source file that is valid. Often this file contains an error with
    a specific line number of <filename>spine.tex</filename> that is
    incorrect.
  </para></listitem></itemizedlist><para>
	  If the error at hand is not obvious after examination, or if one
	  encounters the inscruitable <quote>Incomplete
	  \ifmmode</quote> error, a fall-back strategy is to start
	  commenting out parts of the XML document (regardless of what
	  this does to over-all document validity). Start by
	  commenting out each of the largest parts of the
	  <filename>spine.xml</filename> file, section by section,
	  until the offending section is identified.
	</para></section><section xml:id="docbook.validation"><info><title>Editing and Validation</title></info><para>
	After editing the xml sources, please make sure that the XML
	documentation and markup is still valid. This can be
	done easily, with the following validation rule:
      </para><screen><userinput>make doc-xml-validate-docbook</userinput></screen><para>
	This is equivalent to doing:
      </para><screen><userinput>
	  xmllint --noout --valid <filename>xml/index.xml</filename>
	</userinput></screen><para>
	Please note that individual sections and chapters of the
	manual can be validated by substituting the file desired for
	<filename>xml/index.xml</filename> in the command
	above. Reducing scope in this manner can be helpful when
	validation on the entire manual fails.
      </para><para>
	All Docbook xml sources should always validate. No excuses!
      </para></section><section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info><literallayout class="normal"><emphasis>Which files are important</emphasis>

      All Docbook files are in the directory
      libstdc++-v3/doc/xml

      Inside this directory, the files of importance:
      spine.xml	 	- index to documentation set
      manual/spine.xml  - index to manual
      manual/*.xml  	- individual chapters and sections of the manual
      faq.xml  		- index to FAQ
      api.xml  		- index to source level / API

      All *.txml files are template xml files, i.e., otherwise empty files with
      the correct structure, suitable for filling in with new information.

      <emphasis>Canonical Writing Style</emphasis>

      class template
      function template
      member function template
      (via C++ Templates, Vandevoorde)

      class in namespace std: allocator, not std::allocator

      header file: iostream, not &lt;iostream&gt;


      <emphasis>General structure</emphasis>

      &lt;set&gt;
      &lt;book&gt;
      &lt;/book&gt;

      &lt;book&gt;
      &lt;chapter&gt;
      &lt;/chapter&gt;
      &lt;/book&gt;

      &lt;book&gt;
      &lt;part&gt;
      &lt;chapter&gt;
      &lt;section&gt;
      &lt;/section&gt;

      &lt;sect1&gt;
      &lt;/sect1&gt;

      &lt;sect1&gt;
      &lt;sect2&gt;
      &lt;/sect2&gt;
      &lt;/sect1&gt;
      &lt;/chapter&gt;

      &lt;chapter&gt;
      &lt;/chapter&gt;
      &lt;/part&gt;
      &lt;/book&gt;

      &lt;/set&gt;
    </literallayout></section><section xml:id="docbook.markup"><info><title>Markup By Example</title></info><para>
	Complete details on Docbook markup can be found in the
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tdg.docbook.org/tdg/5.0/ref-elements.html">DocBook Element Reference</link>.
	An incomplete reference for HTML to Docbook conversion is
	detailed in the table below.
      </para><table frame="all" xml:id="table.docbook_cmp"><title>HTML to Docbook XML Markup Comparison</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><thead><row><entry>HTML</entry><entry>Docbook</entry></row></thead><tbody><row><entry>&lt;p&gt;</entry><entry>&lt;para&gt;</entry></row><row><entry>&lt;pre&gt;</entry><entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
	&lt;literallayout&gt;</entry></row><row><entry>&lt;ul&gt;</entry><entry>&lt;itemizedlist&gt;</entry></row><row><entry>&lt;ol&gt;</entry><entry>&lt;orderedlist&gt;</entry></row><row><entry>&lt;il&gt;</entry><entry>&lt;listitem&gt;</entry></row><row><entry>&lt;dl&gt;</entry><entry>&lt;variablelist&gt;</entry></row><row><entry>&lt;dt&gt;</entry><entry>&lt;term&gt;</entry></row><row><entry>&lt;dd&gt;</entry><entry>&lt;listitem&gt;</entry></row><row><entry>&lt;a href=""&gt;</entry><entry>&lt;ulink url=""&gt;</entry></row><row><entry>&lt;code&gt;</entry><entry>&lt;literal&gt;, &lt;programlisting&gt;</entry></row><row><entry>&lt;strong&gt;</entry><entry>&lt;emphasis&gt;</entry></row><row><entry>&lt;em&gt;</entry><entry>&lt;emphasis&gt;</entry></row><row><entry>"</entry><entry>&lt;quote&gt;</entry></row></tbody></tgroup></table><para>
  And examples of detailed markup for which there are no real HTML
  equivalents are listed in the table below.
</para><table frame="all" xml:id="table.docbook_elem"><title>Docbook XML Element Use</title><tgroup align="left" cols="2" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><thead><row><entry>Element</entry><entry>Use</entry></row></thead><tbody><row><entry>&lt;structname&gt;</entry><entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry></row><row><entry>&lt;classname&gt;</entry><entry>&lt;classname&gt;string&lt;/classname&gt;</entry></row><row><entry>&lt;function&gt;</entry><entry><para>&lt;function&gt;clear()&lt;/function&gt;</para><para>&lt;function&gt;fs.clear()&lt;/function&gt;</para></entry></row><row><entry>&lt;type&gt;</entry><entry>&lt;type&gt;long long&lt;/type&gt;</entry></row><row><entry>&lt;varname&gt;</entry><entry>&lt;varname&gt;fs&lt;/varname&gt;</entry></row><row><entry>&lt;literal&gt;</entry><entry><para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para><para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para></entry></row><row><entry>&lt;constant&gt;</entry><entry><para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para><para>&lt;constant&gt;3.0&lt;/constant&gt;</para></entry></row><row><entry>&lt;command&gt;</entry><entry>&lt;command&gt;g++&lt;/command&gt;</entry></row><row><entry>&lt;errortext&gt;</entry><entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry></row><row><entry>&lt;filename&gt;</entry><entry><para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para><para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para><para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para></entry></row></tbody></tgroup></table></section></section></section><!-- Internals: Porting to New Hardware or Operating Systems --><section version="5.0" xreflabel="Portin Internals" xml:id="appendix.porting.internals"><?dbhtml filename="internals.html"?><info><title>Porting to New Hardware or Operating Systems</title><keywordset><keyword>ISO C++</keyword><keyword>internals</keyword></keywordset></info><para>
</para><para>This document explains how to port libstdc++ (the GNU C++ library) to
a new target.
</para><para>In order to make the GNU C++ library (libstdc++) work with a new
target, you must edit some configuration files and provide some new
header files.  Unless this is done, libstdc++ will use generic
settings which may not be correct for your target; even if they are
correct, they will likely be inefficient.
   </para><para>Before you get started, make sure that you have a working C library on
your target.  The C library need not precisely comply with any
particular standard, but should generally conform to the requirements
imposed by the ANSI/ISO standard.
   </para><para>In addition, you should try to verify that the C++ compiler generally
works.  It is difficult to test the C++ compiler without a working
library, but you should at least try some minimal test cases.
   </para><para>(Note that what we think of as a "target," the library refers to as
a "host."  The comment at the top of <code>configure.ac</code> explains why.)
   </para><section xml:id="internals.os"><info><title>Operating System</title></info><para>If you are porting to a new operating system (as opposed to a new chip
using an existing operating system), you will need to create a new
directory in the <code>config/os</code> hierarchy.  For example, the IRIX
configuration files are all in <code>config/os/irix</code>.  There is no set
way to organize the OS configuration directory.  For example,
<code>config/os/solaris/solaris-2.6</code> and
<code>config/os/solaris/solaris-2.7</code> are used as configuration
directories for these two versions of Solaris.  On the other hand, both
Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code>
directory.  The important information is that there needs to be a
directory under <code>config/os</code> to store the files for your operating
system.
</para><para>You might have to change the <code>configure.host</code> file to ensure that
your new directory is activated.  Look for the switch statement that sets
<code>os_include_dir</code>, and add a pattern to handle your operating system
if the default will not suffice.  The switch statement switches on only
the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code>
in <code>sparc-sun-solaris2.8</code>.  If the new directory is named after the
OS portion of the triplet (the default), then nothing needs to be changed.
   </para><para>The first file to create in this directory, should be called
<code>os_defines.h</code>.  This file contains basic macro definitions
that are required to allow the C++ library to work with your C library.
   </para><para>At this time, there are a few libstdc++-specific macros which may be
defined:
   </para><para><code>_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99
function declarations (which are not covered by specialization below)
found in system headers against versions found in the library headers
derived from the standard.
   </para><para><code>_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that
yields 0 if and only if the system headers are exposing proper support
for C99 functions (which are not covered by specialization below).  If
defined, it must be 0 while bootstrapping the compiler/rebuilding the
library.
   </para><para><code>_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check
the set of C99 long long function declarations found in system headers
against versions found in the library headers derived from the
standard.

   </para><para><code>_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an
expression that yields 0 if and only if the system headers are
exposing proper support for the set of C99 long long functions.  If
defined, it must be 0 while bootstrapping the compiler/rebuilding the
library.
   </para><para><code>_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an
expression that yields 0 if and only if the system headers
are exposing proper support for the related set of macros.  If defined,
it must be 0 while bootstrapping the compiler/rebuilding the library.
   </para><para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined
to 1 to check the related set of function declarations found in system
headers against versions found in the library headers derived from
the standard.
   </para><para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined
to an expression that yields 0 if and only if the system headers
are exposing proper support for the related set of functions.  If defined,
it must be 0 while bootstrapping the compiler/rebuilding the library.
   </para><para><code>_GLIBCXX_NO_OBSOLETE_ISINF_ISNAN_DYNAMIC</code> may be defined
to an expression that yields 0 if and only if the system headers
are exposing non-standard <code>isinf(double)</code> and
<code>isnan(double)</code> functions in the global namespace. Those functions
should be detected automatically by the <code>configure</code> script when
libstdc++ is built but if their presence depends on compilation flags or
other macros the static configuration can be overridden.
   </para><para>Finally, you should bracket the entire file in an include-guard, like
this:
   </para><programlisting>

#ifndef _GLIBCXX_OS_DEFINES
#define _GLIBCXX_OS_DEFINES
...
#endif
</programlisting><para>We recommend copying an existing <code>os_defines.h</code> to use as a
starting point.
   </para></section><section xml:id="internals.cpu"><info><title>CPU</title></info><para>If you are porting to a new chip (as opposed to a new operating system
running on an existing chip), you will need to create a new directory in the
<code>config/cpu</code> hierarchy.  Much like the <link linkend="internals.os">Operating system</link> setup,
there are no strict rules on how to organize the CPU configuration
directory, but careful naming choices will allow the configury to find your
setup files without explicit help.
</para><para>We recommend that for a target triplet <code>&lt;CPU&gt;-&lt;vendor&gt;-&lt;OS&gt;</code>, you
name your configuration directory <code>config/cpu/&lt;CPU&gt;</code>.  If you do this,
the configury will find the directory by itself.  Otherwise you will need to
edit the <code>configure.host</code> file and, in the switch statement that sets
<code>cpu_include_dir</code>, add a pattern to handle your chip.
   </para><para>Note that some chip families share a single configuration directory, for
example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the
<code>config/cpu/alpha</code> directory, and there is an entry in the
<code>configure.host</code> switch statement to handle this.
   </para><para>The <code>cpu_include_dir</code> sets default locations for the files controlling
<link linkend="internals.thread_safety">Thread safety</link> and <link linkend="internals.numeric_limits">Numeric limits</link>, if the defaults are not
appropriate for your chip.
   </para></section><section xml:id="internals.char_types"><info><title>Character Types</title></info><para>The library requires that you provide three header files to implement
character classification, analogous to that provided by the C libraries
<code>&lt;ctype.h&gt;</code> header.  You can model these on the files provided in
<code>config/os/generic</code>.  However, these files will almost
certainly need some modification.
</para><para>The first file to write is <code>ctype_base.h</code>.  This file provides
some very basic information about character classification.  The libstdc++
library assumes that your C library implements <code>&lt;ctype.h&gt;</code> by using
a table (indexed by character code) containing integers, where each of
these integers is a bit-mask indicating whether the character is
upper-case, lower-case, alphabetic, etc.  The <code>ctype_base.h</code>
file gives the type of the integer, and the values of the various bit
masks.  You will have to peer at your own <code>&lt;ctype.h&gt;</code> to figure out
how to define the values required by this file.
   </para><para>The <code>ctype_base.h</code> header file does not need include guards.
It should contain a single <code>struct</code> definition called
<code>ctype_base</code>.  This <code>struct</code> should contain two type
declarations, and one enumeration declaration, like this example, taken
from the IRIX configuration:
   </para><programlisting>
  struct ctype_base
     {
       typedef unsigned int 	mask;
       typedef int* 		__to_type;

       enum
       {
	 space = _ISspace,
	 print = _ISprint,
	 cntrl = _IScntrl,
	 upper = _ISupper,
	 lower = _ISlower,
	 alpha = _ISalpha,
	 digit = _ISdigit,
	 punct = _ISpunct,
	 xdigit = _ISxdigit,
	 alnum = _ISalnum,
	 graph = _ISgraph
       };
     };
</programlisting><para>The <code>mask</code> type is the type of the elements in the table.  If your
C library uses a table to map lower-case numbers to upper-case numbers,
and vice versa, you should define <code>__to_type</code> to be the type of the
elements in that table.  If you don't mind taking a minor performance
penalty, or if your library doesn't implement <code>toupper</code> and
<code>tolower</code> in this way, you can pick any pointer-to-integer type,
but you must still define the type.
</para><para>The enumeration should give definitions for all the values in the above
example, using the values from your native <code>&lt;ctype.h&gt;</code>.  They can
be given symbolically (as above), or numerically, if you prefer.  You do
not have to include <code>&lt;ctype.h&gt;</code> in this header; it will always be
included before <code>ctype_base.h</code> is included.
   </para><para>The next file to write is <code>ctype_configure_char.cc</code>.
The first function that must be written is the <code>ctype&lt;char&gt;::ctype</code> constructor.  Here is the IRIX example:
   </para><programlisting>
ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
	   size_t __refs = 0)
       : _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
	 _M_toupper(NULL),
	 _M_tolower(NULL),
	 _M_ctable(NULL),
	 _M_table(!__table
		  ? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
		  : __table)
       { }
</programlisting><para>There are two parts of this that you might choose to alter. The first,
and most important, is the line involving <code>__libc_attr</code>.  That is
IRIX system-dependent code that gets the base of the table mapping
character codes to attributes.  You need to substitute code that obtains
the address of this table on your system.  If you want to use your
operating system's tables to map upper-case letters to lower-case, and
vice versa, you should initialize <code>_M_toupper</code> and
<code>_M_tolower</code> with those tables, in similar fashion.
</para><para>Now, you have to write two functions to convert from upper-case to
lower-case, and vice versa.  Here are the IRIX versions:
   </para><programlisting>
     char
     ctype&lt;char&gt;::do_toupper(char __c) const
     { return _toupper(__c); }

     char
     ctype&lt;char&gt;::do_tolower(char __c) const
     { return _tolower(__c); }
</programlisting><para>Your C library provides equivalents to IRIX's <code>_toupper</code> and
<code>_tolower</code>.  If you initialized <code>_M_toupper</code> and
<code>_M_tolower</code> above, then you could use those tables instead.
</para><para>Finally, you have to provide two utility functions that convert strings
of characters.  The versions provided here will always work - but you
could use specialized routines for greater performance if you have
machinery to do that on your system:
   </para><programlisting>
     const char*
     ctype&lt;char&gt;::do_toupper(char* __low, const char* __high) const
     {
       while (__low &lt; __high)
	 {
	   *__low = do_toupper(*__low);
	   ++__low;
	 }
       return __high;
     }

     const char*
     ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
     {
       while (__low &lt; __high)
	 {
	   *__low = do_tolower(*__low);
	   ++__low;
	 }
       return __high;
     }
</programlisting><para>You must also provide the <code>ctype_inline.h</code> file, which
contains a few more functions.  On most systems, you can just copy
<code>config/os/generic/ctype_inline.h</code> and use it on your system.
   </para><para>In detail, the functions provided test characters for particular
properties; they are analogous to the functions like <code>isalpha</code> and
<code>islower</code> provided by the C library.
   </para><para>The first function is implemented like this on IRIX:
   </para><programlisting>
     bool
     ctype&lt;char&gt;::
     is(mask __m, char __c) const throw()
     { return (_M_table)[(unsigned char)(__c)] &amp; __m; }
</programlisting><para>The <code>_M_table</code> is the table passed in above, in the constructor.
This is the table that contains the bitmasks for each character.  The
implementation here should work on all systems.
</para><para>The next function is:
   </para><programlisting>
     const char*
     ctype&lt;char&gt;::
     is(const char* __low, const char* __high, mask* __vec) const throw()
     {
       while (__low &lt; __high)
	 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
       return __high;
     }
</programlisting><para>This function is similar; it copies the masks for all the characters
from <code>__low</code> up until <code>__high</code> into the vector given by
<code>__vec</code>.
</para><para>The last two functions again are entirely generic:
   </para><programlisting>
     const char*
     ctype&lt;char&gt;::
     scan_is(mask __m, const char* __low, const char* __high) const throw()
     {
       while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
	 ++__low;
       return __low;
     }

     const char*
     ctype&lt;char&gt;::
     scan_not(mask __m, const char* __low, const char* __high) const throw()
     {
       while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
	 ++__low;
       return __low;
     }
</programlisting></section><section xml:id="internals.thread_safety"><info><title>Thread Safety</title></info><para>The C++ library string functionality requires a couple of atomic
operations to provide thread-safety.  If you don't take any special
action, the library will use stub versions of these functions that are
not thread-safe.  They will work fine, unless your applications are
multi-threaded.
</para><para>If you want to provide custom, safe, versions of these functions, there
are two distinct approaches.  One is to provide a version for your CPU,
using assembly language constructs.  The other is to use the
thread-safety primitives in your operating system.  In either case, you
make a file called <code>atomicity.h</code>, and the variable
<code>ATOMICITYH</code> must point to this file.
   </para><para>If you are using the assembly-language approach, put this code in
<code>config/cpu/&lt;chip&gt;/atomicity.h</code>, where chip is the name of
your processor (see <link linkend="internals.cpu">CPU</link>).  No additional changes are necessary to
locate the file in this case; <code>ATOMICITYH</code> will be set by default.
   </para><para>If you are using the operating system thread-safety primitives approach,
you can also put this code in the same CPU directory, in which case no more
work is needed to locate the file.  For examples of this approach,
see the <code>atomicity.h</code> file for IRIX or IA64.
   </para><para>Alternatively, if the primitives are more closely related to the OS
than they are to the CPU, you can put the <code>atomicity.h</code> file in
the <link linkend="internals.os">Operating system</link> directory instead.  In this case, you must
edit <code>configure.host</code>, and in the switch statement that handles
operating systems, override the <code>ATOMICITYH</code> variable to point to
the appropriate <code>os_include_dir</code>.  For examples of this approach,
see the <code>atomicity.h</code> file for AIX.
   </para><para>With those bits out of the way, you have to actually write
<code>atomicity.h</code> itself.  This file should be wrapped in an
include guard named <code>_GLIBCXX_ATOMICITY_H</code>.  It should define one
type, and two functions.
   </para><para>The type is <code>_Atomic_word</code>.  Here is the version used on IRIX:
   </para><programlisting>
typedef long _Atomic_word;
</programlisting><para>This type must be a signed integral type supporting atomic operations.
If you're using the OS approach, use the same type used by your system's
primitives.  Otherwise, use the type for which your CPU provides atomic
primitives.
</para><para>Then, you must provide two functions.  The bodies of these functions
must be equivalent to those provided here, but using atomic operations:
   </para><programlisting>
     static inline _Atomic_word
     __attribute__ ((__unused__))
     __exchange_and_add (_Atomic_word* __mem, int __val)
     {
       _Atomic_word __result = *__mem;
       *__mem += __val;
       return __result;
     }

     static inline void
     __attribute__ ((__unused__))
     __atomic_add (_Atomic_word* __mem, int __val)
     {
       *__mem += __val;
     }
</programlisting></section><section xml:id="internals.numeric_limits"><info><title>Numeric Limits</title></info><para>The C++ library requires information about the fundamental data types,
such as the minimum and maximum representable values of each type.
You can define each of these values individually, but it is usually
easiest just to indicate how many bits are used in each of the data
types and let the library do the rest.  For information about the
macros to define, see the top of <code>include/bits/std_limits.h</code>.
</para><para>If you need to define any macros, you can do so in <code>os_defines.h</code>.
However, if all operating systems for your CPU are likely to use the
same values, you can provide a CPU-specific file instead so that you
do not have to provide the same definitions for each operating system.
To take that approach, create a new file called <code>cpu_limits.h</code> in
your CPU configuration directory (see <link linkend="internals.cpu">CPU</link>).
   </para></section><section xml:id="internals.libtool"><info><title>Libtool</title></info><para>The C++ library is compiled, archived and linked with libtool.
Explaining the full workings of libtool is beyond the scope of this
document, but there are a few, particular bits that are necessary for
porting.
</para><para>Some parts of the libstdc++ library are compiled with the libtool
<code>--tags CXX</code> option (the C++ definitions for libtool).  Therefore,
<code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct
logic to compile and archive objects equivalent to the C version of libtool,
<code>ltcf-c.sh</code>.  Some libtool targets have definitions for C but not
for C++, or C++ definitions which have not been kept up to date.
   </para><para>The C++ run-time library contains initialization code that needs to be
run as the library is loaded.  Often, that requires linking in special
object files when the C++ library is built as a shared library, or
taking other system-specific actions.
   </para><para>The libstdc++ library is linked with the C version of libtool, even
though it is a C++ library.  Therefore, the C version of libtool needs to
ensure that the run-time library initializers are run.  The usual way to
do this is to build the library using <code>gcc -shared</code>.
   </para><para>If you need to change how the library is linked, look at
<code>ltcf-c.sh</code> in the top-level directory.  Find the switch statement
that sets <code>archive_cmds</code>.  Here, adjust the setting for your
operating system.
   </para></section></section><!-- Test --><section version="5.0" xreflabel="Testing" xml:id="manual.intro.setup.test"><?dbhtml filename="test.html"?><info><title>Testing</title><keywordset><keyword>ISO C++</keyword><keyword>test</keyword><keyword>testsuite</keyword><keyword>performance</keyword><keyword>conformance</keyword><keyword>ABI</keyword><keyword>exception safety</keyword></keywordset></info><para>
The libstdc++ testsuite includes testing for standard conformance,
regressions, ABI, and performance.
</para><section xreflabel="Test Organization" xml:id="test.organization"><info><title>Test Organization</title></info><section xreflabel="Directory Layout" xml:id="test.organization.layout"><info><title>Directory Layout</title></info><para>
  The directory
  <filename class="directory"><replaceable>gccsrcdir</replaceable>/libstdc++-v3/testsuite</filename>
  contains the individual test cases organized in sub-directories
  corresponding to clauses of the C++ standard (detailed below),
  the DejaGnu test harness support files, and sources to various
  testsuite utilities that are packaged in a separate testing library.
</para><para>
  All test cases for functionality required by the runtime components
  of the C++ standard (ISO 14882) are files within the following
  directories:

<programlisting>
    17_intro
    18_support
    19_diagnostics
    20_util
    21_strings
    22_locale
    23_containers
    24_iterators
    25_algorithms
    26_numerics
    27_io
    28_regex
    29_atomics
    30_threads
</programlisting>
</para><para>
      In addition, the following directories include test files:

<variablelist spacing="compact"><varlistentry><term><filename class="directory">tr1</filename></term><listitem>Tests for components as described by the Technical Report
    on Standard Library Extensions (<link linked="status.iso.tr1">TR1</link>).
  </listitem></varlistentry><varlistentry><term><filename class="directory">backward</filename></term><listitem>Tests for backwards compatibility and deprecated features.
  </listitem></varlistentry><varlistentry><term><filename class="directory">demangle</filename></term><listitem>Tests for <function>__cxa_demangle</function>, the IA-64 C++ ABI
    demangler.
  </listitem></varlistentry><varlistentry><term><filename class="directory">ext</filename></term><listitem>Tests for extensions.</listitem></varlistentry><varlistentry><term><filename class="directory">performance</filename></term><listitem>Tests for performance analysis, and performance regressions.
  </listitem></varlistentry></variablelist>
   </para><para>
      Some directories don't have test files, but instead contain
      auxiliary information:

<variablelist spacing="compact"><varlistentry><term><filename class="directory">config</filename></term><listitem>Files for the DejaGnu test harness.</listitem></varlistentry><varlistentry><term><filename class="directory">lib</filename></term><listitem>Files for the DejaGnu test harness.</listitem></varlistentry><varlistentry><term><filename class="directory">libstdc++*</filename></term><listitem>Files for the DejaGnu test harness.</listitem></varlistentry><varlistentry><term><filename class="directory">data</filename></term><listitem>Sample text files for testing input and output.</listitem></varlistentry><varlistentry><term><filename class="directory">util</filename></term><listitem>Files for libtestc++, utilities and testing routines.</listitem></varlistentry></variablelist>
   </para><para>
      Within a directory that includes test files, there may be
      additional subdirectories, or files.  Originally, test cases
      were appended to one file that represented a particular section
      of the chapter under test, and was named accordingly. For
      instance, to test items related to <code> 21.3.6.1 -
      <function>basic_string::find</function> [lib.string::find]</code>
      in the standard, the following was used:
<programlisting>    21_strings/find.cc </programlisting>
      However, that practice soon became a liability as the test cases
      became huge and unwieldy, and testing new or extended
      functionality (like wide characters or named locales) became
      frustrating, leading to aggressive pruning of test cases on some
      platforms that covered up implementation errors. Now, the test
      suite has a policy of one file, one test case, which solves the
      above issues and gives finer grained results and more manageable
      error debugging. As an example, the test case quoted above
      becomes:
<programlisting>    21_strings/basic_string/find/char/1.cc
    21_strings/basic_string/find/char/2.cc
    21_strings/basic_string/find/char/3.cc
    21_strings/basic_string/find/wchar_t/1.cc
    21_strings/basic_string/find/wchar_t/2.cc
    21_strings/basic_string/find/wchar_t/3.cc</programlisting>
   </para><para>
      All new tests should be written with the policy of "one test
      case, one file" in mind.
   </para></section><section xreflabel="Naming Conventions" xml:id="test.organization.naming"><info><title>Naming Conventions</title></info><para>
      In addition, there are some special names and suffixes that are
      used within the testsuite to designate particular kinds of
      tests.
   </para><variablelist><varlistentry><term><filename class="extension">_xin.cc</filename></term><listitem>
      This test case expects some kind of interactive input in order
      to finish or pass. At the moment, the interactive tests are not
      run by default. Instead, they are run by hand, like:
<programlisting>
g++ 27_io/objects/char/3_xin.cc
cat 27_io/objects/char/3_xin.in | a.out</programlisting>
  </listitem></varlistentry><varlistentry><term><filename class="extension">.in</filename></term><listitem>
      This file contains the expected input for the corresponding <emphasis>
      _xin.cc</emphasis> test case.
  </listitem></varlistentry><varlistentry><term><filename class="extension">_neg.cc</filename></term><listitem>
      This test case is expected to fail: it's a negative test. At the
      moment, these are almost always compile time errors.
  </listitem></varlistentry><varlistentry><term><filename class="directory">char</filename></term><listitem>
      This can either be a directory name or part of a longer file
      name, and indicates that this file, or the files within this
      directory are testing the <code>char</code> instantiation of a
      template.
  </listitem></varlistentry><varlistentry><term><filename class="directory">wchar_t</filename></term><listitem>
      This can either be a directory name or part of a longer file
      name, and indicates that this file, or the files within this
      directory are testing the <code>wchar_t</code> instantiation of
      a template. Some hosts do not support <code>wchar_t</code>
      functionality, so for these targets, all of these tests will not
      be run.
  </listitem></varlistentry><varlistentry><term><filename class="directory">thread</filename></term><listitem>
      This can either be a directory name or part of a longer file
      name, and indicates that this file, or the files within this
      directory are testing situations where multiple threads are
      being used.
  </listitem></varlistentry><varlistentry><term><filename class="directory">performance</filename></term><listitem>
      This can either be an enclosing directory name or part of a
      specific file name. This indicates a test that is used to
      analyze runtime performance, for performance regression testing,
      or for other optimization related analysis. At the moment, these
      test cases are not run by default.
  </listitem></varlistentry></variablelist></section></section><section xreflabel="Running the Testsuite" xml:id="test.run"><info><title>Running the Testsuite</title></info><section xml:id="test.run.basic"><info><title>Basic</title></info><para>
      You can check the status of the build without installing it
      using the DejaGnu harness, much like the rest of the gcc
      tools, i.e.
   <userinput>make check</userinput>
      in the
      <filename class="directory"><replaceable>libbuilddir</replaceable></filename>
      directory, or
   <userinput>make check-target-libstdc++-v3</userinput>
       in the
      <filename class="directory"><replaceable>gccbuilddir</replaceable></filename>
       directory.
    </para><para>
       These commands are functionally equivalent and will create a
       '<filename class="directory">testsuite</filename>' directory underneath
       <filename class="directory"><replaceable>libbuilddir</replaceable></filename>
       containing the results of the
       tests. Two results files will be generated:
       <filename>libstdc++.sum</filename>, which is a PASS/FAIL summary
       for each test, and
       <filename>libstdc++.log</filename> which is a log of
       the exact command-line passed to the compiler, the compiler
       output, and the executable output (if any) for each test.
     </para><para>
       Archives of test results for various versions and platforms are
       archived on a daily basis on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</link>
       mailing list. Please check there for a similar
       combination of source version, operating system, and host CPU.
     </para></section><section xml:id="test.run.variations"><info><title>Variations</title></info><para>
      There are several options for running tests, including testing
      the regression tests, testing a subset of the regression tests,
      testing the performance tests, testing just compilation, testing
      installed tools, etc. In addition, there is a special rule for
      checking the exported symbols of the shared library.
    </para><para>
      To debug the DejaGnu test harness during runs, try invoking with a
      specific argument to the variable <varname>RUNTESTFLAGS</varname>,
      like so:
<programlisting>
    make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
</programlisting>
      or
<programlisting>
    make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
</programlisting>
    </para><para>
      To run a subset of the library tests, you can either generate the
      <filename>testsuite_files</filename> file (described below) by running
      <userinput>make testsuite_files</userinput> in the
      <filename class="directory"><replaceable>libbuilddir</replaceable>/testsuite</filename>
      directory, then edit the
      file to remove the tests you don't want and then run the testsuite as
      normal, or you can specify a testsuite and a subset of tests in the
      <varname>RUNTESTFLAGS</varname> variable.
    </para><para>
      For example, to run only the tests for containers you could use:

<programlisting>
    make check-target-libstdc++-v3 RUNTESTFLAGS="conformance.exp=23_containers/*"
</programlisting>
    </para><para>
      When combining this with other options in <varname>RUNTESTFLAGS</varname>
      the <option>testsuite.exp=testfiles</option> options must come first.
    </para><para>
      There are two ways to run on a simulator: set up <envar>DEJAGNU</envar>
      to point to a specially crafted <filename>site.exp</filename>,
      or pass down <option>--target_board</option> flags.
    </para><para>
    Example flags to pass down for various embedded builds are as follows:

<programlisting>
  --target=powerpc-eabisim <emphasis>(libgloss/sim)</emphasis>
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"

  --target=calmrisc32 <emphasis>(libgloss/sid)</emphasis>
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"

  --target=xscale-elf <emphasis>(newlib/sim)</emphasis>
  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
</programlisting>
    </para><para>
      Also, here is an example of how to run the libstdc++ testsuite
      for a multilibed build directory with different ABI settings:

<programlisting>
    make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
</programlisting>
    </para><para>
      If you wish to run the testsuite in a freestanding configuration, you can
      pass the <code>-ffreestanding</code> flag.  Doing so will run the tests
      that do not require hosted features, and emit a
      <literal>UNSUPPORTED</literal> for those that do.  To run tests in the
      freestanding configuration, you still need to build for a target you can
      run programs on, e.g. <code>x86_64-pc-linux-gnu</code>, as a few tests
      still execute the code they build.  Here's an example of how to run the
      testsuite with libstdc++ in freestanding mode:
<programlisting>
    make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board=unix/-ffreestanding'
</programlisting>
    </para><para>
      You can run the tests with a compiler and library that have
      already been installed.  Make sure that the compiler (e.g.,
      <command>g++</command>) is in your <envar>PATH</envar>.  If you are
      using shared libraries, then you must also ensure that the
      directory containing the shared version of libstdc++ is in your
      <envar>LD_LIBRARY_PATH</envar>, or
      <link linkend="manual.intro.using.linkage.dynamic">equivalent</link>.
      If your GCC source tree is at
      <filename class="directory">/path/to/gcc</filename>,
      then you can run the tests as follows:

<programlisting>
    runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
</programlisting>
    </para><para>
      The testsuite will create a number of files in the directory in
      which you run this command.  Some of those files might use the
      same name as files created by other testsuites (like the ones
      for GCC and G++), so you should not try to run all the
      testsuites in parallel from the same directory.
    </para><para>
      In addition, there are some testing options that are mostly of
      interest to library maintainers and system integrators. As such,
      these tests may not work on all CPU and host combinations, and
      may need to be executed in the
      <filename class="directory"><replaceable>libbuilddir</replaceable>/testsuite</filename>
      directory.  These
      options include, but are not necessarily limited to, the
      following:
    </para><variablelist><varlistentry><term><userinput>
   make testsuite_files
   </userinput></term>&gt;

  <listitem><para>
    Five files are generated that determine what test files
    are run. These files are:

    <variablelist><varlistentry><term><filename>testsuite_files</filename></term><listitem>
	 This is a list of all the test cases that will be run. Each
	 test case is on a separate line, given with an absolute path
	 from the
         <filename class="directory"><replaceable>libsrcdir</replaceable>/testsuite</filename>
         directory.
      </listitem></varlistentry><varlistentry><term><filename>testsuite_files_interactive</filename></term><listitem>
	 This is a list of all the interactive test cases, using the
	 same format as the file list above. These tests are not run
	 by default.
      </listitem></varlistentry><varlistentry><term><filename>testsuite_files_performance</filename></term><listitem>
	 This is a list of all the performance test cases, using the
	 same format as the file list above. These tests are not run
	 by default.
      </listitem></varlistentry><varlistentry><term><filename>testsuite_thread</filename></term><listitem>
	 This file indicates that the host system can run tests which
	 involved multiple threads.
      </listitem></varlistentry><varlistentry><term><filename>testsuite_wchar_t</filename></term><listitem>
	 This file indicates that the host system can run the
         <code>wchar_t</code> tests, and corresponds to the macro
         definition <literal>_GLIBCXX_USE_WCHAR_T</literal> in the
         file <filename>c++config.h</filename>.
      </listitem></varlistentry></variablelist>
  </para></listitem></varlistentry><varlistentry><term><userinput>
   make check-abi
   </userinput></term>&gt;

   <listitem><para>
     The library ABI can be tested. This involves testing the shared
     library against a baseline list of symbol exports that defines the
     previous version of the ABI. The tests require that no exported
     symbols are removed, no new symbols are added to the old symbol
     versions, and any new symbols have the latest symbol version.
     See <link linkend="abi.versioning">Versioning</link> for more details
     of the ABI version history.
   </para></listitem></varlistentry><varlistentry><term><userinput>
   make new-abi-baseline
   </userinput></term>&gt;

   <listitem><para>
     Generate a new baseline set of symbols exported from the library
     (written to a file under
     <filename class="directory"><replaceable>libsrcdir</replaceable>/config/abi/post/<replaceable>target</replaceable>/</filename>).
     A different baseline symbols file is needed for each architecture and
     is used by the <literal>check-abi</literal> target described above.
     The files are usually re-generated by target maintainers for releases.
   </para></listitem></varlistentry><varlistentry><term><userinput>
   make check-compile
  </userinput></term>&gt;

   <listitem><para>
     This rule compiles, but does not link or execute, the
     <filename>testsuite_files</filename> test cases and displays the
     output on stdout.
   </para></listitem></varlistentry><varlistentry><term><userinput>
   make check-performance
   </userinput></term>&gt;

   <listitem><para>
     This rule runs through the
     <filename>testsuite_files_performance</filename> test cases and
     collects information for performance analysis and can be used to
     spot performance regressions. Various timing information is
     collected, as well as number of hard page faults, and memory
     used. This is not run by default, and the implementation is in
     flux.
   </para></listitem></varlistentry><varlistentry><term><userinput>
   make check-debug
   </userinput></term>&gt;

   <listitem><para>
     This rule runs through the test suite under the
     <link linkend="manual.ext.debug_mode">debug mode</link>.
   </para></listitem></varlistentry><varlistentry><term><userinput>
   make check-parallel
   </userinput></term>&gt;

   <listitem><para>
     This rule runs through the test suite under the
     <link linkend="manual.ext.parallel_mode">parallel mode</link>.
   </para></listitem></varlistentry></variablelist><para>
      We are interested in any strange failures of the testsuite;
      please email the main libstdc++ mailing list if you see
      something odd or have questions.
   </para></section><section xml:id="test.run.permutations"><info><title>Permutations</title></info><para>
      The tests will be compiled with a set of default compiler flags defined
      by the
      <filename><replaceable>libbuilddir</replaceable>/scripts/testsuite_flags</filename>
      file, as well as options specified in individual tests. You can run
      the tests with different options by adding them to the output of
      the <option>--cxxflags</option> option of that script, or by setting
      the <varname>CXXFLAGS</varname> variable when running
      <command>make</command>, or via options for the DejaGnu test framework
      (described below). The latter approach uses the
      <option>--target_board</option> option that was shown earlier,
      but requires DejaGnu version 1.5.3 or newer to work reliably, so that the
      <literal>dg-options</literal> in the test aren't overridden.
      For example, to run the tests with
      <option>-O1 -D_GLIBCXX_ASSERTIONS</option>
      you could use:
<programlisting>    make check RUNTESTFLAGS=--target_board=unix/-O1/-D_GLIBCXX_ASSERTIONS</programlisting>
    </para><para>
      Since GCC 14, the libstdc++ testsuite has built-in support for running
      tests with more than one <option>-std</option>, similar to the G++ tests.
      Adding <code>set v3_std_list { 11 17 23 }</code> to
      <filename>~/.dejagnurc</filename> or to a file named by the
      <envar>DEJAGNU</envar> environment variable will cause every test to
      be run three times, using a different <option>-std</option> each time.
      Alternatively, a list of standard versions to test with can be specified
      as a comma-separated list in the <envar>GLIBCXX_TESTSUITE_STDS</envar>
      environment variable, e.g. <envar>GLIBCXX_TESTSUITE_STDS=11,17,23</envar>
      is equivalent to the <code>v3_std_list</code> value above.
      Before GCC 14, the <option>--target_board</option> option could be
      used to run the tests with different <option>-std</option> options,
      but this no longer works.
    </para><para>
      To run the libstdc++ test suite under the
      <link linkend="manual.ext.debug_mode">debug mode</link>, use
      <userinput>make check-debug</userinput>. Alternatively, edit
      <filename><replaceable>libbuilddir</replaceable>/scripts/testsuite_flags</filename>
      to add the compile-time flag <option>-D_GLIBCXX_DEBUG</option> to the
      result printed by the <option>--cxxflags</option>
      option. Additionally, add the
      <option>-D_GLIBCXX_DEBUG_PEDANTIC</option> flag to turn on
      pedantic checking. The libstdc++ test suite should produce
      the same results under debug mode that it does under release mode:
      any deviation indicates an error in either the library or the test suite.
      Note, however, that the number of tests that PASS may change, because
      some test cases are skipped in normal mode, and some are skipped in
      debug mode, as determined by the
      <literal>dg-require-<replaceable>support</replaceable></literal>
      directives described below.
    </para><para>
      The <link linkend="manual.ext.parallel_mode">parallel
      mode</link> can be tested using
      <userinput>make check-parallel</userinput>, or in much the same manner
      as the debug mode, substituting
      <option>-D_GLIBCXX_PARALLEL</option> for
      <option>-D_GLIBCXX_DEBUG</option> in the previous paragraph.
    </para><para>
      Or, just run the testsuite
      <option>-D_GLIBCXX_DEBUG</option> or <option>-D_GLIBCXX_PARALLEL</option>
      in <varname>CXXFLAGS</varname> or <varname>RUNTESTFLAGS</varname>.
    </para></section></section><section xml:id="test.new_tests"><info><title>Writing a new test case</title></info><para>
    The first step in making a new test case is to choose the correct
    directory and file name, given the organization as previously
    described.
   </para><para>
    Historically all test files were copyright the FSF, and GPL licensed.
    We no longer require that, because most tests are uninteresting
    and contain no "original authorship", and so would not be protected
    by copyright anyway.
    Adding the FSF copyright notice to new tests is incorrect unless you
    (or your employer) have a copyright assignment on file with the FSF,
    or if the test contains code copied from another test under FSF copyright.
    In particular, new tests that contain original code are not copyright FSF
    if contributed under the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/dco.html">DCO</link> terms.
    If new tests do add the FSF copyright notice and GPL licence text,
    then the first copyright year should correspond to the date
    the file was checked in to version control. If the test code is copied
    from an existing file it should retain the copyright years from the
    original file.
   </para><para>
     The DejaGnu instructions say to always return <literal>0</literal>
     from <function>main</function> to indicate success. Strictly speaking
     this is redundant in C++, since returning from <function>main</function>
     is defined to return <literal>0</literal>. Most tests still have an
     explicit return.
   </para><para>
   A bunch of utility functions and classes have already been
   abstracted out into the testsuite utility library, <code>
   libtestc++</code>. To use this functionality, just include the
   appropriate header file: the library or specific object files will
   automatically be linked in as part of the testsuite run.
   </para><para>
    Tests that need to perform runtime checks should use the
    <literal>VERIFY</literal> macro, defined in the
    <filename class="headerfile">&lt;testsuite_hooks.h&gt;</filename> header.
    This expands to a custom assertion using
    <function>__builtin_printf</function> and
    <function>__builtin_abort</function>
    (to avoid using <literal>assert</literal> and being affected by
    <literal>NDEBUG</literal>).
   </para><para>
    The testsuite uses the DejaGnu framework to compile and run the tests.
    Test cases are normal C++ files which contain special directives in
    comments.  These directives look like <literal>{ dg-* ... }</literal>
    and tell DejaGnu what to do and what kinds of behavior are to be expected
    for a test.  The core DejaGnu directives are documented in the
    <filename>dg.exp</filename> file installed by DejaGnu.
    The GCC testsuites support additional directives
    as described in the GCC internals documentation, see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Directives.html">Syntax
    and Descriptions of test directives</link>. GCC also defines many <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Effective-Target-Keywords.html">
    Keywords describing target attributes</link> (a.k.a effective targets)
    which can be used where a target <replaceable>selector</replaceable> can
    appear.
  </para><para>
  Some directives commonly used in the libstdc++ testsuite are:

<variablelist><varlistentry><term><literal>{ dg-do <replaceable>do-what-keyword</replaceable> [{ target/xfail <replaceable>selector</replaceable> }] }</literal></term><listitem>Where <replaceable>do-what-keyword</replaceable> is usually
    one of <literal>run</literal> (which is the default),
    <literal>compile</literal>, or <literal>link</literal>,
    and typical selectors are targets such as <literal>*-*-gnu*</literal>
    or an effective target such as <literal>c++11</literal>.
  </listitem></varlistentry><varlistentry><term><literal>{ dg-require-<replaceable>support</replaceable> args }</literal></term><listitem>Skip the test if the target does not provide the required support.
    See below for values of <replaceable>support</replaceable>.
  </listitem></varlistentry><varlistentry><term><literal>{ dg-options <replaceable>options</replaceable> [{ target <replaceable>selector</replaceable> }] }</literal></term></varlistentry><varlistentry><term><literal>{ dg-error <replaceable>regexp</replaceable> [ <replaceable>comment</replaceable> [{ target/xfail <replaceable>selector</replaceable> } [<replaceable>line</replaceable>] ]] }</literal></term></varlistentry><varlistentry><term><literal>{ dg-excess-errors <replaceable>comment</replaceable> [{ target/xfail <replaceable>selector</replaceable> }] }</literal></term></varlistentry></variablelist>
  For full details of these and other directives see the main GCC DejaGnu
  documentation in the internals manual.
  </para><para>
    Test cases that use features of a particular C++ standard should specify
    the minimum required standard as an effective target:
<programlisting>    // { dg-do run { target c++11 } }</programlisting>
    or
<programlisting>    // { dg-require-effective-target c++11 }</programlisting>
    Specifying the minimum required standard for a test allows it to be run
    using later standards, so that we can verify that C++11 components still
    work correctly when compiled as C++14 or later. Specifying a minimum also
    means the test will be skipped if the test is compiled using
    an older standard, e.g. using
    <option>RUNTESTFLAGS=--target_board=unix/-std=gnu++98</option>.
  </para><para>
    It is possible to indicate that a test should <emphasis>only</emphasis>
    be run for a specific standard (and not later standards) using an
    effective target like <literal>c++11_only</literal>. However, this means
    the test will be skipped by default unless <option>-std=gnu++11</option>
    or <option>-std=c++11</option> is explicitly specified, either via a
    target board, the <varname>v3_std_list</varname> dejagnu variable,
    or the <envar>GLIBCXX_TESTSUITE_STDS</envar> environment variable.
    For tests that require a specific standard it is useful to also add a
    <literal>dg-options</literal> directive:
<programlisting>    // { dg-options "-std=gnu++11" }</programlisting>
    This means the test will not get skipped by default, and will always use
    the specific standard dialect that the test requires. This isn't needed
    often, and most tests should use an effective target to specify a
    minimum standard instead, to allow them to be tested for all
    possible variations.
  </para><para>
    N.B. when a <literal>dg-options</literal> directive is used, it must come
    first so dejagnu will include those options when checking against any
    effective targets in <literal>dg-do</literal> and
    <literal>dg-require-effective-target</literal> directives.
  </para><para>
    Since GCC 14, tests which depend on a newer standard than the default
    do not need to specify that standard in a <literal>dg-options</literal>
    directive. The testsuite will detect when a test requires a newer standard
    and will automatically add a suitable <option>-std</option> flag.
  </para><para>
    If a testcase requires the use of a strict language dialect, e.g.
    <option>-std=c++11</option> rather than <option>-std=gnu++11</option>,
    the following directive will cause that to be used when the testsuite
    decides which <option>-std</option> options to use for the test:
<programlisting>    // { dg-add-options strict_std }</programlisting>
  </para><section xml:id="tests.dg.examples"><info><title>Examples of Test Directives</title></info><para>
Example 1: Testing compilation only:
<programlisting>
// { dg-do compile }
</programlisting>

Example 2: Testing for expected warnings on line 36, which all targets fail:
<programlisting>
// { dg-warning "string literals" "" { xfail *-*-* } 36 }
</programlisting>

Example 3: Testing for expected warnings on line 36:
<programlisting>
// { dg-warning "string literals" "" { target *-*-* } 36 }
</programlisting>

Example 4: Testing for compilation errors on line 41:
<programlisting>
// { dg-do compile }
// { dg-error "no match for" "" { target *-*-* } 41 }
</programlisting>

Example 5: Testing with special command line settings, or without the
use of pre-compiled headers, in particular the
<filename class="headerfile">stdc++.h.gch</filename> file. Any
options here will override the <varname>DEFAULT_CXXFLAGS</varname> and
<varname>PCH_CXXFLAGS</varname> set up in the <filename>normal.exp</filename>
file:
<programlisting>
// { dg-options "-O0" { target *-*-* } }
</programlisting>

Example 6: Compiling and linking a test only for C++14 and later, and only
if Debug Mode is active:
<programlisting>
// { dg-do link { target c++14 } }
// { dg-require-debug-mode "" }
</programlisting>

Example 7: Running a test only on x86 targets, and only for C++11 and later,
with specific options, and additional options for 32-bit x86:
<programlisting>
// { dg-options "-fstrict-enums" }
// { dg-additional-options "-march=i486" { target ia32 } }
// { dg-do run { target { ia32 || x86_64-*-* } } }
// { dg-require-effective-target "c++11" }
</programlisting>
   </para><para>
    More examples can be found in the
    <filename>libstdc++-v3/testsuite/*/*.cc</filename> files.
   </para></section><section xml:id="tests.dg.directives"><info><title>Directives Specific to Libstdc++ Tests</title></info><para>
    In addition to the usual <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Require-Support.html">Variants
    of <literal>dg-require-<replaceable>support</replaceable></literal></link>
    several more directives are available for use in libstdc++ tests,
    including the following:
   </para><variablelist><varlistentry><term><literal>dg-require-namedlocale</literal><replaceable>name</replaceable></term><listitem><para>The named locale must be available.
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-debug-mode ""</literal></term><listitem><para>Skip the test if the Debug Mode is not active
	(as determined by the <literal>_GLIBCXX_DEBUG</literal> macro).
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-parallel-mode ""</literal></term><listitem><para>Skip the test if the Parallel Mode is not active
	(as determined by the <literal>_GLIBCXX_PARALLEL</literal> macro).
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-normal-mode ""</literal></term><listitem><para>Skip the test if Debug or Parallel Mode is active.
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-atomic-builtins ""</literal></term><listitem><para>Skip the test if atomic operations on <type>bool</type>
      and <type>int</type> are not lock-free.
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-gthreads ""</literal></term><listitem><para>Skip the test if the C++11 thread library is not
      supported, as determined by the <literal>_GLIBCXX_HAS_GTHREADS</literal>
      macro.
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-gthreads-timed ""</literal></term><listitem><para>Skip the test if C++11 timed mutexes are not supported,
      as determined by the <literal>_GLIBCXX_HAS_GTHREADS</literal> and
      <literal>_GTHREAD_USE_MUTEX_TIMEDLOCK</literal> macros.
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-string-conversions ""</literal></term><listitem><para>Skip the test if the C++11 <function>to_string</function>
      and <function>stoi</function>, <function>stod</function> etc. functions
      are not fully supported (including wide character versions).
      </para></listitem></varlistentry><varlistentry><term><literal>dg-require-filesystem-ts ""</literal></term><listitem><para>Skip the test if the Filesystem TS is not supported.
      </para></listitem></varlistentry></variablelist></section></section><section xreflabel="Test Harness and Utilities" xml:id="test.harness"><info><title>Test Harness and Utilities</title></info><section xml:id="test.harness.dejagnu"><info><title>DejaGnu Harness Details</title></info><para>
    Underlying details of testing for conformance and regressions are
    abstracted via the GNU DejaGnu package. This is similar to the
    rest of GCC.
  </para><para>This is information for those looking at making changes to the testsuite
structure, and/or needing to trace DejaGnu's actions with
<option>--verbose</option>.
This will not be useful to people who are "merely" adding new tests
to the existing structure.
</para><para>The first key point when working with DejaGnu is the idea of a "tool".
Files, directories, and functions are all implicitly used when they are
named after the tool in use.  Here, the tool will always be "libstdc++".
</para><para>The <code>lib</code> subdir contains support routines.  The
<code>lib/libstdc++.exp</code> file ("support library") is loaded
automagically, and must explicitly load the others.  For example, files can
be copied from the core compiler's support directory into <code>lib</code>.
</para><para>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are
our own.  Callbacks must be prefixed with the name of the tool.  To easily
distinguish the others, by convention our own routines are named "v3-*".
</para><para>The next key point when working with DejaGnu is "test files".  Any
directory whose name starts with the tool name will be searched for test files.
(We have only one.)  In those directories, any <code>.exp</code> file is
considered a test file, and will be run in turn.  Our main test file is called
<code>normal.exp</code>; it runs all the tests in testsuite_files using the
callbacks loaded from the support library.
</para><para>The <code>config</code> directory is searched for any particular "target
board" information unique to this library.  This is currently unused and sets
only default variables.
</para></section><section xml:id="test.harness.utils"><info><title>Utilities</title></info><para>
  </para><para>
   The testsuite directory also contains some files that implement
   functionality that is intended to make writing test cases easier,
   or to avoid duplication, or to provide error checking in a way that
   is consistent across platforms and test harnesses. A stand-alone
   executable, called <emphasis>abi_check</emphasis>, and a static
   library called <emphasis>libtestc++</emphasis> are
   constructed. Both of these items are not installed, and only used
   during testing.
  </para><para>
  These files include the following functionality:
  </para><itemizedlist><listitem><para><emphasis>testsuite_abi.h</emphasis>,
       <emphasis>testsuite_abi.cc</emphasis>,
       <emphasis>testsuite_abi_check.cc</emphasis></para><para>
	Creates the executable <emphasis>abi_check</emphasis>.
	Used to check correctness of symbol versioning, visibility of
	exported symbols, and compatibility on symbols in the shared
	library, for hosts that support this feature. More information
	can be found in the ABI documentation <link linkend="appendix.porting.abi">here</link>
       </para></listitem><listitem><para><emphasis>testsuite_allocator.h</emphasis>,
       <emphasis>testsuite_allocator.cc</emphasis></para><para>
	Contains specialized allocators that keep track of construction
	and destruction. Also, support for overriding global new and
	delete operators, including verification that new and delete
	are called during execution, and that allocation over max_size
	fails.
       </para></listitem><listitem><para><emphasis>testsuite_character.h</emphasis></para><para>
	Contains <code>std::char_traits</code> and
	<code>std::codecvt</code> specializations for a user-defined
	POD.
       </para></listitem><listitem><para><emphasis>testsuite_hooks.h</emphasis>,
       <emphasis>testsuite_hooks.cc</emphasis></para><para>
       A large number of utilities, including:
       </para><itemizedlist><listitem><para>VERIFY</para></listitem><listitem><para>set_memory_limits</para></listitem><listitem><para>verify_demangle</para></listitem><listitem><para>run_tests_wrapped_locale</para></listitem><listitem><para>run_tests_wrapped_env</para></listitem><listitem><para>try_named_locale</para></listitem><listitem><para>try_mkfifo</para></listitem><listitem><para>func_callback</para></listitem><listitem><para>counter</para></listitem><listitem><para>copy_tracker</para></listitem><listitem><para>copy_constructor</para></listitem><listitem><para>assignment_operator</para></listitem><listitem><para>destructor</para></listitem><listitem><para>pod_char, pod_int and associated char_traits specializations</para></listitem></itemizedlist></listitem><listitem><para><emphasis>testsuite_io.h</emphasis></para><para>
       Error, exception, and constraint checking for
       <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>.
       </para></listitem><listitem><para><emphasis>testsuite_iterators.h</emphasis></para><para>
	 Wrappers for various iterators.
       </para></listitem><listitem><para><emphasis>testsuite_performance.h</emphasis></para><para>
       A number of class abstractions for performance counters, and
       reporting functions including:
       </para><itemizedlist><listitem><para>time_counter</para></listitem><listitem><para>resource_counter</para></listitem><listitem><para>report_performance</para></listitem></itemizedlist></listitem></itemizedlist></section></section><section xml:id="test.special"><info><title>Special Topics</title></info><section xml:id="test.exception.safety"><info><title>
  Qualifying Exception Safety Guarantees
  <indexterm><primary>Test</primary><secondary>Exception Safety</secondary></indexterm>
</title></info><section xml:id="test.exception.safety.overview"><info><title>Overview</title></info><para>
	 Testing is composed of running a particular test sequence,
	 and looking at what happens to the surrounding code when
	 exceptions are thrown. Each test is composed of measuring
	 initial state, executing a particular sequence of code under
	 some instrumented conditions, measuring a final state, and
	 then examining the differences between the two states.
       </para><para>
	 Test sequences are composed of constructed code sequences
	 that exercise a particular function or member function, and
	 either confirm no exceptions were generated, or confirm the
	 consistency/coherency of the test subject in the event of a
	 thrown exception.
       </para><para>
	 Random code paths can be constructed using the basic test
	 sequences and instrumentation as above, only combined in a
	 random or pseudo-random way.
       </para><para> To compute the code paths that throw, test instruments
	 are used that throw on allocation events
	 (<classname>__gnu_cxx::throw_allocator_random</classname>
	 and <classname>__gnu_cxx::throw_allocator_limit</classname>)
	 and copy, assignment, comparison, increment, swap, and
	 various operators
	 (<classname>__gnu_cxx::throw_type_random</classname>
	 and <classname>__gnu_cxx::throw_type_limit</classname>). Looping
	 through a given test sequence and conditionally throwing in
	 all instrumented places.  Then, when the test sequence
	 completes without an exception being thrown, assume all
	 potential error paths have been exercised in a sequential
	 manner.
       </para></section><section xml:id="test.exception.safety.status"><info><title>
    Existing tests
</title></info><itemizedlist><listitem><para>
	 Ad Hoc
       </para><para>
	 For example,
	 <filename>testsuite/23_containers/list/modifiers/3.cc</filename>.
       </para></listitem><listitem><para>
	 Policy Based Data Structures
       </para><para>
	 For example, take the test
	 functor <classname>rand_reg_test</classname> in
	 in <filename>testsuite/ext/pb_ds/regression/tree_no_data_map_rand.cc</filename>. This uses <classname>container_rand_regression_test</classname> in
<filename>testsuite/util/regression/rand/assoc/container_rand_regression_test.h</filename>.

       </para><para>
	 Which has several tests for container member functions,
Includes control and test container objects. Configuration includes
random seed, iterations, number of distinct values, and the
probability that an exception will be thrown. Assumes instantiating
container uses an extension
allocator, <classname>__gnu_cxx::throw_allocator_random</classname>,
as the allocator type.
       </para></listitem><listitem><para>
	 C++11 Container Requirements.
       </para><para>
	 Coverage is currently limited to testing container
	 requirements for exception safety,
	 although <classname>__gnu_cxx::throw_type</classname> meets
	 the additional type requirements for testing numeric data
	 structures and instantiating algorithms.
       </para><para>
	 Of particular interest is extending testing to algorithms and
	 then to parallel algorithms. Also io and locales.
       </para><para>
	 The test instrumentation should also be extended to add
	 instrumentation to <classname>iterator</classname>
	 and <classname>const_iterator</classname> types that throw
	 conditionally on iterator operations.
       </para></listitem></itemizedlist></section><section xml:id="test.exception.safety.containers"><info><title>
C++11 Requirements Test Sequence Descriptions
</title></info><itemizedlist><listitem><para>
	 Basic
       </para><para>
	 Basic consistency on exception propagation tests. For
	 each container, an object of that container is constructed,
	 a specific member function is exercised in
	 a <literal>try</literal> block, and then any thrown
	 exceptions lead to error checking in the appropriate
	 <literal>catch</literal> block. The container's use of
	 resources is compared to the container's use prior to the
	 test block. Resource monitoring is limited to allocations
	 made through the container's <type>allocator_type</type>,
	 which should be sufficient for container data
	 structures. Included in these tests are member functions
	 are <type>iterator</type> and <type>const_iterator</type>
	 operations, <function>pop_front</function>, <function>pop_back</function>, <function>push_front</function>, <function>push_back</function>, <function>insert</function>, <function>erase</function>, <function>swap</function>, <function>clear</function>,
	 and <function>rehash</function>. The container in question is
	 instantiated with two instrumented template arguments,
	 with <classname>__gnu_cxx::throw_allocator_limit</classname>
	 as the allocator type, and
	 with <classname>__gnu_cxx::throw_type_limit</classname> as
	 the value type. This allows the test to loop through
	 conditional throw points.
       </para><para>
	 The general form is demonstrated in
	 <filename>testsuite/23_containers/list/requirements/exception/basic.cc
	 </filename>. The instantiating test object is <classname>__gnu_test::basic_safety</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
       </para></listitem><listitem><para>
	 Generation Prohibited
       </para><para>
	 Exception generation tests. For each container, an object of
	 that container is constructed and all member functions
	 required to not throw exceptions are exercised. Included in
	 these tests are member functions
	 are <type>iterator</type> and <type>const_iterator</type> operations, <function>erase</function>, <function>pop_front</function>, <function>pop_back</function>, <function>swap</function>,
	 and <function>clear</function>. The container in question is
	 instantiated with two instrumented template arguments,
	 with <classname>__gnu_cxx::throw_allocator_random</classname>
	 as the allocator type, and
	 with <classname>__gnu_cxx::throw_type_random</classname> as
	 the value type. This test does not loop, an instead is sudden
	 death: first error fails.
       </para><para>
	 The general form is demonstrated in
	 <filename>testsuite/23_containers/list/requirements/exception/generation_prohibited.cc
	 </filename>. The instantiating test object is <classname>__gnu_test::generation_prohibited</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
       </para></listitem><listitem><para>
	 Propagation Consistent
       </para><para>
	 Container rollback on exception propagation tests. For
	 each container, an object of that container is constructed,
	 a specific member function that requires rollback to a previous
	 known good state is exercised in
	 a <literal>try</literal> block, and then any thrown
	 exceptions lead to error checking in the appropriate
	 <literal>catch</literal> block. The container is compared to
	 the container's last known good state using such parameters
	 as size, contents, and iterator references. Included in these
	 tests are member functions
	 are <function>push_front</function>, <function>push_back</function>, <function>insert</function>,
	 and <function>rehash</function>. The container in question is
	 instantiated with two instrumented template arguments,
	 with <classname>__gnu_cxx::throw_allocator_limit</classname>
	 as the allocator type, and
	 with <classname>__gnu_cxx::throw_type_limit</classname> as
	 the value type. This allows the test to loop through
	 conditional throw points.
       </para><para>
	 The general form demonstrated in
	 <filename>testsuite/23_containers/list/requirements/exception/propagation_coherent.cc
	 </filename>. The instantiating test object is <classname>__gnu_test::propagation_coherent</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
       </para></listitem></itemizedlist></section></section></section></section><!-- ABI Policy and Guidelines --><section version="5.0" xreflabel="abi" xml:id="appendix.porting.abi"><?dbhtml filename="abi.html"?><info><title>ABI Policy and Guidelines</title><keywordset><keyword>C++</keyword><keyword>ABI</keyword><keyword>version</keyword><keyword>dynamic</keyword><keyword>shared</keyword><keyword>compatibility</keyword></keywordset></info><para>
</para><section xml:id="abi.cxx_interface"><info><title>The C++ Interface</title></info><para>
  C++ applications often depend on specific language support
  routines, say for throwing exceptions, or catching exceptions, and
  perhaps also depend on features in the C++ Standard Library.
</para><para>
  The C++ Standard Library has many include files, types defined in
  those include files, specific named functions, and other
  behavior. The text of these behaviors, as written in source include
  files, is called the Application Programing Interface, or API.
</para><para>
  Furthermore, C++ source that is compiled into object files is
  transformed by the compiler: it arranges objects with specific
  alignment and in a particular layout, mangling names according to a
  well-defined algorithm, has specific arrangements for the support of
  virtual functions, etc. These details are defined as the compiler
  Application Binary Interface, or ABI. From GCC version 3 onwards the
  GNU C++ compiler uses an industry-standard C++ ABI, the
  <link linkend="biblio.cxxabi">Itanium C++ ABI</link>.
</para><para>
  The GNU C++ compiler, g++, has a command-line option to
  switch between various different C++ ABIs. This explicit version
  switch is the flag <code>-fabi-version</code>. In addition, some
  command-line options may change the ABI as a side-effect of
  use. Such flags include <code>-fpack-struct</code> and
  <code>-fno-exceptions</code>, but include others: see the complete
  list in the GCC manual under the heading <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
  for Code Generation Conventions</link>.
</para><para>
  The configure options used when building a specific libstdc++
  version may also impact the resulting library ABI. The available
  configure options, and their impact on the library ABI, are
  documented
<link linkend="manual.intro.setup.configure">here</link>.
</para><para> Putting all of these ideas together results in the C++ Standard
Library ABI, which is the compilation of a given library API by a
given compiler ABI. In a nutshell:
</para><para><quote>
    library API + compiler ABI = library ABI
  </quote></para><para>
 The library ABI is mostly of interest for end-users who have
 unresolved symbols and are linking dynamically to the C++ Standard
 library, and who thus must be careful to compile their application
 with a compiler that is compatible with the available C++ Standard
 library binary. In this case, compatible is defined with the equation
 above: given an application compiled with a given compiler ABI and
 library API, it will work correctly with a Standard C++ Library
 created with the same constraints.
</para><para>
  To use a specific version of the C++ ABI, one must use a
  corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
  implements the C++ ABI in question.
</para></section><section xml:id="abi.versioning"><info><title>Versioning</title></info><para> The C++ interface has evolved throughout the history of the GNU
C++ toolchain. With each release, various details have been changed so
as to give distinct versions to the C++ interface.
</para><section xml:id="abi.versioning.goals"><info><title>Goals</title></info><para>Extending existing, stable ABIs. Versioning gives subsequent
releases of library binaries the ability to add new symbols and add
functionality, all the while retaining compatibility with the previous
releases in the series. Thus, program binaries linked with the initial
release of a library binary will still run correctly if the library
binary is replaced by carefully-managed subsequent library
binaries. This is called forward compatibility.
</para><para>
The reverse (backwards compatibility) is not true. It is not possible
to take program binaries linked with the latest version of a library
binary in a release series (with additional symbols added), substitute
in the initial release of the library binary, and remain link
compatible.
</para><para>Allows multiple, incompatible ABIs to coexist at the same time.
</para></section><section xml:id="abi.versioning.history"><info><title>History</title></info><para>
 How can this complexity be managed? What does C++ versioning mean?
  Because library and compiler changes often make binaries compiled
  with one version of the GNU tools incompatible with binaries
  compiled with other (either newer or older) versions of the same GNU
  tools, specific techniques are used to make managing this complexity
  easier.
</para><para>
  The following techniques are used:
</para><orderedlist><listitem><para>Release versioning on the libgcc_s.so binary. </para><para>This is implemented via file names and the ELF
    <constant>DT_SONAME</constant> mechanism (at least on ELF
    systems). It is versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.x: libgcc_s.so.1</para></listitem><listitem><para>GCC 4.x: libgcc_s.so.1</para></listitem></itemizedlist><para>For m68k-linux the versions differ as follows: </para><itemizedlist><listitem><para>GCC 3.4, GCC 4.x: libgcc_s.so.1
    when configuring <code>--with-sjlj-exceptions</code>, or
    libgcc_s.so.2 </para></listitem></itemizedlist><para>For hppa-linux the versions differ as follows: </para><itemizedlist><listitem><para>GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1
    when configuring <code>--with-sjlj-exceptions</code>, or
    libgcc_s.so.2 </para></listitem><listitem><para>GCC 4.[2-7]: either libgcc_s.so.3 when configuring
    <code>--with-sjlj-exceptions</code>) or libgcc_s.so.4
    </para></listitem></itemizedlist></listitem><listitem><para>Symbol versioning on the libgcc_s.so binary.</para><para>It is versioned with the following labels and version
   definitions, where the version definition is the maximum for a
   particular release. Labels are cumulative. If a particular release
   is not listed, it has the same version labels as the preceding
   release.</para><para>This corresponds to the mapfile: gcc/libgcc-std.ver</para><itemizedlist><listitem><para>GCC 3.0.0: GCC_3.0</para></listitem><listitem><para>GCC 3.3.0: GCC_3.3</para></listitem><listitem><para>GCC 3.3.1: GCC_3.3.1</para></listitem><listitem><para>GCC 3.3.2: GCC_3.3.2</para></listitem><listitem><para>GCC 3.3.4: GCC_3.3.4</para></listitem><listitem><para>GCC 3.4.0: GCC_3.4</para></listitem><listitem><para>GCC 3.4.2: GCC_3.4.2</para></listitem><listitem><para>GCC 3.4.4: GCC_3.4.4</para></listitem><listitem><para>GCC 4.0.0: GCC_4.0.0</para></listitem><listitem><para>GCC 4.1.0: GCC_4.1.0</para></listitem><listitem><para>GCC 4.2.0: GCC_4.2.0</para></listitem><listitem><para>GCC 4.3.0: GCC_4.3.0</para></listitem><listitem><para>GCC 4.4.0: GCC_4.4.0</para></listitem><listitem><para>GCC 4.5.0: GCC_4.5.0</para></listitem><listitem><para>GCC 4.6.0: GCC_4.6.0</para></listitem><listitem><para>GCC 4.7.0: GCC_4.7.0</para></listitem><listitem><para>GCC 4.8.0: GCC_4.8.0</para></listitem><listitem><para>GCC 7.1.0: GCC_7.0.0</para></listitem><listitem><para>GCC 9.1.0: GCC_9.0.0</para></listitem><listitem><para>GCC 11.1.0: GCC_11.0</para></listitem><listitem><para>GCC 12.1.0: GCC_12.0.0</para></listitem><listitem><para>GCC 13.1.0: GCC_13.0.0</para></listitem></itemizedlist></listitem><listitem><para>
	Release versioning on the libstdc++.so binary, implemented in
	the same way as the libgcc_s.so binary above. Listed is the
	filename: <constant>DT_SONAME</constant> can be deduced from
	the filename by removing the last two period-delimited numbers. For
	example, filename <filename>libstdc++.so.5.0.4</filename>
	corresponds to a <constant>DT_SONAME</constant> of
	<constant>libstdc++.so.5</constant>. Binaries with equivalent
	<constant>DT_SONAME</constant>s are forward-compatibile: in
	the table below, releases incompatible with the previous
	one are explicitly noted.
	If a particular release is not listed, its libstdc++.so binary
	has the same filename and <constant>DT_SONAME</constant> as the
	preceding release.
      </para><para>It is versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.0.0: libstdc++.so.3.0.0</para></listitem><listitem><para>GCC 3.0.1: libstdc++.so.3.0.1</para></listitem><listitem><para>GCC 3.0.2: libstdc++.so.3.0.2</para></listitem><listitem><para>GCC 3.0.3: libstdc++.so.3.0.2 (See Note 1)</para></listitem><listitem><para>GCC 3.0.4: libstdc++.so.3.0.4</para></listitem><listitem><para>GCC 3.1.0: libstdc++.so.4.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem><listitem><para>GCC 3.1.1: libstdc++.so.4.0.1</para></listitem><listitem><para>GCC 3.2.0: libstdc++.so.5.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem><listitem><para>GCC 3.2.1: libstdc++.so.5.0.1</para></listitem><listitem><para>GCC 3.2.2: libstdc++.so.5.0.2</para></listitem><listitem><para>GCC 3.2.3: libstdc++.so.5.0.3 (See Note 2)</para></listitem><listitem><para>GCC 3.3.0: libstdc++.so.5.0.4</para></listitem><listitem><para>GCC 3.3.1: libstdc++.so.5.0.5</para></listitem><listitem><para>GCC 3.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem><listitem><para>GCC 3.4.1: libstdc++.so.6.0.1</para></listitem><listitem><para>GCC 3.4.2: libstdc++.so.6.0.2</para></listitem><listitem><para>GCC 3.4.3: libstdc++.so.6.0.3</para></listitem><listitem><para>GCC 4.0.0: libstdc++.so.6.0.4</para></listitem><listitem><para>GCC 4.0.1: libstdc++.so.6.0.5</para></listitem><listitem><para>GCC 4.0.2: libstdc++.so.6.0.6</para></listitem><listitem><para>GCC 4.0.3: libstdc++.so.6.0.7</para></listitem><listitem><para>GCC 4.1.0: libstdc++.so.6.0.7</para></listitem><listitem><para>GCC 4.1.1: libstdc++.so.6.0.8</para></listitem><listitem><para>GCC 4.2.0: libstdc++.so.6.0.9</para></listitem><listitem><para>GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem><listitem><para>GCC 4.2.2: libstdc++.so.6.0.9</para></listitem><listitem><para>GCC 4.3.0: libstdc++.so.6.0.10</para></listitem><listitem><para>GCC 4.4.0: libstdc++.so.6.0.11</para></listitem><listitem><para>GCC 4.4.1: libstdc++.so.6.0.12</para></listitem><listitem><para>GCC 4.4.2: libstdc++.so.6.0.13</para></listitem><listitem><para>GCC 4.5.0: libstdc++.so.6.0.14</para></listitem><listitem><para>GCC 4.6.0: libstdc++.so.6.0.15</para></listitem><listitem><para>GCC 4.6.1: libstdc++.so.6.0.16</para></listitem><listitem><para>GCC 4.7.0: libstdc++.so.6.0.17</para></listitem><listitem><para>GCC 4.8.0: libstdc++.so.6.0.18</para></listitem><listitem><para>GCC 4.8.3: libstdc++.so.6.0.19</para></listitem><listitem><para>GCC 4.9.0: libstdc++.so.6.0.20</para></listitem><listitem><para>GCC 5.1.0: libstdc++.so.6.0.21</para></listitem><listitem><para>GCC 6.1.0: libstdc++.so.6.0.22</para></listitem><listitem><para>GCC 7.1.0: libstdc++.so.6.0.23</para></listitem><listitem><para>GCC 7.2.0: libstdc++.so.6.0.24</para></listitem><listitem><para>GCC 8.1.0: libstdc++.so.6.0.25</para></listitem><listitem><para>GCC 9.1.0: libstdc++.so.6.0.26</para></listitem><listitem><para>GCC 9.2.0: libstdc++.so.6.0.27</para></listitem><listitem><para>GCC 9.3.0: libstdc++.so.6.0.28</para></listitem><listitem><para>GCC 10.1.0: libstdc++.so.6.0.28</para></listitem><listitem><para>GCC 11.1.0: libstdc++.so.6.0.29</para></listitem><listitem><para>GCC 12.1.0: libstdc++.so.6.0.30</para></listitem><listitem><para>GCC 13.1.0: libstdc++.so.6.0.31</para></listitem><listitem><para>GCC 13.2.0: libstdc++.so.6.0.32</para></listitem><listitem><para>GCC 14.1.0: libstdc++.so.6.0.33</para></listitem><listitem><para>GCC 15.1.0: libstdc++.so.6.0.34</para></listitem><listitem><para>GCC 16.1.0: libstdc++.so.6.0.34</para></listitem></itemizedlist><para>
      Note 1: Error should be libstdc++.so.3.0.3.
    </para><para>
      Note 2: Not strictly required.
    </para><para>
      Note 3: This release (but not previous or subsequent) has one
      known incompatibility, see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</link>
      in the GCC bug database.
    </para></listitem><listitem><para>Symbol versioning on the libstdc++.so binary.</para><para>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</para><para>It is versioned with the following labels and version
   definitions, where the version definition is the maximum for a
   particular release. Note, only symbols which are newly introduced
   will use the maximum version definition. Thus, for release series
   with the same label, but incremented version definitions, the later
   release has both versions. (An example of this would be the
   GCC 3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
   GLIBCPP_3.2 for symbols that were introduced in the GCC 3.2.0
   release.) If a particular release is not listed, it has the same
   version labels as the preceding release.
   </para><itemizedlist><listitem><para>GCC 3.0.0: (Error, not versioned)</para></listitem><listitem><para>GCC 3.0.1: (Error, not versioned)</para></listitem><listitem><para>GCC 3.0.2: (Error, not versioned)</para></listitem><listitem><para>GCC 3.0.3: (Error, not versioned)</para></listitem><listitem><para>GCC 3.0.4: (Error, not versioned)</para></listitem><listitem><para>GCC 3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem><listitem><para>GCC 3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem><listitem><para>GCC 3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem><listitem><para>GCC 3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem><listitem><para>GCC 3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem><listitem><para>GCC 3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem><listitem><para>GCC 3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem><listitem><para>GCC 3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem><listitem><para>GCC 3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem><listitem><para>GCC 3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem><listitem><para>GCC 3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem><listitem><para>GCC 3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem><listitem><para>GCC 3.4.2: GLIBCXX_3.4.2</para></listitem><listitem><para>GCC 3.4.3: GLIBCXX_3.4.3</para></listitem><listitem><para>GCC 4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem><listitem><para>GCC 4.0.1: GLIBCXX_3.4.5</para></listitem><listitem><para>GCC 4.0.2: GLIBCXX_3.4.6</para></listitem><listitem><para>GCC 4.0.3: GLIBCXX_3.4.7</para></listitem><listitem><para>GCC 4.1.1: GLIBCXX_3.4.8</para></listitem><listitem><para>GCC 4.2.0: GLIBCXX_3.4.9</para></listitem><listitem><para>GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem><listitem><para>GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem><listitem><para>GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</para></listitem><listitem><para>GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</para></listitem><listitem><para>GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</para></listitem><listitem><para>GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5</para></listitem><listitem><para>GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5</para></listitem><listitem><para>GCC 4.7.0: GLIBCXX_3.4.17, CXXABI_1.3.6</para></listitem><listitem><para>GCC 4.8.0: GLIBCXX_3.4.18, CXXABI_1.3.7</para></listitem><listitem><para>GCC 4.8.3: GLIBCXX_3.4.19, CXXABI_1.3.7</para></listitem><listitem><para>GCC 4.9.0: GLIBCXX_3.4.20, CXXABI_1.3.8</para></listitem><listitem><para>GCC 5.1.0: GLIBCXX_3.4.21, CXXABI_1.3.9</para></listitem><listitem><para>GCC 6.1.0: GLIBCXX_3.4.22, CXXABI_1.3.10</para></listitem><listitem><para>GCC 7.1.0: GLIBCXX_3.4.23, CXXABI_1.3.11</para></listitem><listitem><para>GCC 7.2.0: GLIBCXX_3.4.24, CXXABI_1.3.11</para></listitem><listitem><para>GCC 8.1.0: GLIBCXX_3.4.25, CXXABI_1.3.11</para></listitem><listitem><para>GCC 9.1.0: GLIBCXX_3.4.26, CXXABI_1.3.12</para></listitem><listitem><para>GCC 9.2.0: GLIBCXX_3.4.27, CXXABI_1.3.12</para></listitem><listitem><para>GCC 9.3.0: GLIBCXX_3.4.28, CXXABI_1.3.12</para></listitem><listitem><para>GCC 10.1.0: GLIBCXX_3.4.28, CXXABI_1.3.12</para></listitem><listitem><para>GCC 11.1.0: GLIBCXX_3.4.29, CXXABI_1.3.13</para></listitem><listitem><para>GCC 12.1.0: GLIBCXX_3.4.30, CXXABI_1.3.13</para></listitem><listitem><para>GCC 13.1.0: GLIBCXX_3.4.31, CXXABI_1.3.14</para></listitem><listitem><para>GCC 13.2.0: GLIBCXX_3.4.32, CXXABI_1.3.14</para></listitem><listitem><para>GCC 14.1.0: GLIBCXX_3.4.33, CXXABI_1.3.15</para></listitem><listitem><para>GCC 15.1.0: GLIBCXX_3.4.34, CXXABI_1.3.15 (CXXABI_1.3.16 for RISC-V only)</para></listitem><listitem><para>GCC 16.1.0: GLIBCXX_3.4.34, CXXABI_1.3.17</para></listitem></itemizedlist></listitem><listitem><para>Incremental bumping of a compiler pre-defined macro,
    __GXX_ABI_VERSION. This macro is defined as the version of the
    compiler v3 ABI, with g++ 3.0 being version 100. This macro will
    be automatically defined whenever g++ is used (the curious can
    test this by invoking g++ with the '-v' flag.)
    </para><para>
    This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
    Later versions defined it in "c-common.c" in the gcc directory, and from
    G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
    '-fabi-version' command-line option.
    </para><para>
    It is versioned as follows, where 'n' is given by '-fabi-version=n':
    </para><itemizedlist><listitem><para>GCC 3.0: 100</para></listitem><listitem><para>GCC 3.1: 100 (Error, should be 101)</para></listitem><listitem><para>GCC 3.2: 102</para></listitem><listitem><para>GCC 3.3: 102</para></listitem><listitem><para>GCC 3.4, GCC 4.x: 102 (when n=1)</para></listitem><listitem><para>GCC 3.4, GCC 4.x: 1000 + n (when n&gt;1) </para></listitem><listitem><para>GCC 3.4, GCC 4.x: 999999 (when n=0)</para></listitem></itemizedlist><para></para></listitem><listitem><para>Changes to the default compiler option for
    <code>-fabi-version</code>.
    </para><para>
    It is versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.0: (Error, not versioned) </para></listitem><listitem><para>GCC 3.1: (Error, not versioned) </para></listitem><listitem><para>GCC 3.2: <code>-fabi-version=1</code></para></listitem><listitem><para>GCC 3.3: <code>-fabi-version=1</code></para></listitem><listitem><para>GCC 3.4, GCC 4.x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem><listitem><para>GCC 5 and higher: <code>-fabi-version=0</code> <emphasis>(See GCC manual for meaning)</emphasis></para></listitem></itemizedlist><para></para></listitem><listitem xml:id="abi.versioning.__GLIBCXX__"><para>Incremental bumping of a library pre-defined macro. For releases
    before 3.4.0, the macro is <symbol>__GLIBCPP__</symbol>. For later
    releases, it's <symbol>__GLIBCXX__</symbol>. (The libstdc++ project
    generously changed from CPP to CXX throughout its source to allow the
    "C" pre-processor the CPP macro namespace.) These macros are defined
    as the date the library was released, in compressed ISO date format,
    as an integer constant.
    </para><para>
    This macro is defined in the file
    <filename class="headerfile">c++config</filename> in the
    <filename class="directory">libstdc++-v3/include/bits</filename>
    directory.  Up to GCC 4.1.0, it was
    changed every night by an automated script. Since GCC 4.1.0 it is set
    during configuration to the same value as
    <filename>gcc/DATESTAMP</filename>, so for an official release its value
    is the same as the date of the release, which is given in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC Release
    Timeline</link>.
    </para><para>
    This macro can be used in code to detect whether the C++ Standard Library
    implementation in use is libstdc++, but is not useful for detecting the
    libstdc++ version, nor whether particular features are supported.
    The macro value might be a date after a feature was added to the
    development trunk, but the release could be from an older branch without
    the feature. For example, in the 5.4.0 release the macro has the value
    <literal>20160603</literal> which is greater than the
    <literal>20160427</literal> value of the macro in the 6.1.0 release,
    but there are features supported in the 6.1.0 release that are not
    supported in the 5.4.0 release.
    You also can't test for the exact values listed below to try and
    identify a release, because a snapshot taken from the gcc-5-branch on
    2016-04-27 would have the same value for the macro as the 6.1.0 release
    despite being a different version.
    Many GNU/Linux distributions build their GCC packages from snapshots, so
    the macro can have dates that don't correspond to official releases.
    </para><para>
    It is versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.0.0: <literal>20010615</literal></para></listitem><listitem><para>GCC 3.0.1: <literal>20010819</literal></para></listitem><listitem><para>GCC 3.0.2: <literal>20011023</literal></para></listitem><listitem><para>GCC 3.0.3: <literal>20011220</literal></para></listitem><listitem><para>GCC 3.0.4: <literal>20020220</literal></para></listitem><listitem><para>GCC 3.1.0: <literal>20020514</literal></para></listitem><listitem><para>GCC 3.1.1: <literal>20020725</literal></para></listitem><listitem><para>GCC 3.2.0: <literal>20020814</literal></para></listitem><listitem><para>GCC 3.2.1: <literal>20021119</literal></para></listitem><listitem><para>GCC 3.2.2: <literal>20030205</literal></para></listitem><listitem><para>GCC 3.2.3: <literal>20030422</literal></para></listitem><listitem><para>GCC 3.3.0: <literal>20030513</literal></para></listitem><listitem><para>GCC 3.3.1: <literal>20030804</literal></para></listitem><listitem><para>GCC 3.3.2: <literal>20031016</literal></para></listitem><listitem><para>GCC 3.3.3: <literal>20040214</literal></para></listitem><listitem><para>GCC 3.4.0: <literal>20040419</literal></para></listitem><listitem><para>GCC 3.4.1: <literal>20040701</literal></para></listitem><listitem><para>GCC 3.4.2: <literal>20040906</literal></para></listitem><listitem><para>GCC 3.4.3: <literal>20041105</literal></para></listitem><listitem><para>GCC 3.4.4: <literal>20050519</literal></para></listitem><listitem><para>GCC 3.4.5: <literal>20051201</literal></para></listitem><listitem><para>GCC 3.4.6: <literal>20060306</literal></para></listitem><listitem><para>GCC 4.0.0: <literal>20050421</literal></para></listitem><listitem><para>GCC 4.0.1: <literal>20050707</literal></para></listitem><listitem><para>GCC 4.0.2: <literal>20050921</literal></para></listitem><listitem><para>GCC 4.0.3: <literal>20060309</literal></para></listitem><listitem><para>
      GCC 4.1.0 and later: the GCC release date, as shown in the
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC
      Release Timeline</link>
    </para></listitem></itemizedlist><para></para></listitem><listitem><para>
    Since GCC 7, incremental bumping of a library pre-defined macro,
    <symbol>_GLIBCXX_RELEASE</symbol>. This macro is defined to the GCC
    major version that the libstdc++ headers belong to, as an integer constant.
    When compiling with GCC it has the same value as GCC's pre-defined
    macro <symbol>__GNUC__</symbol>.
    This macro can be used when libstdc++ is used with a non-GNU
    compiler where <symbol>__GNUC__</symbol> is not defined, or has a
    different value that doesn't correspond to the libstdc++ version.
    </para><para>
    This macro is defined in the file
    <filename class="headerfile">c++config</filename> in the
    <filename class="directory">libstdc++-v3/include/bits</filename>
    directory and is generated automatically by autoconf as part of the
    configure-time generation of
    <filename class="headerfile">config.h</filename> and subsequently
    <filename class="headerfile">&lt;bits/c++config.h&gt;</filename>.
    </para></listitem><listitem><para>
    Historically, incremental bumping of a library pre-defined macro,
    <symbol>_GLIBCPP_VERSION</symbol>. This macro was defined as the
    released version of the library, as a string literal. This was only
    implemented in GCC 3.1.0 releases and higher, and was deprecated in
    3.4.x (where it was called <symbol>_GLIBCXX_VERSION</symbol>),
    and is not defined in 4.0.0 and higher.
    </para><para>
    This macro is defined in the same file as
    <symbol>_GLIBCXX_RELEASE</symbol>, described above.
    </para><para>
    It is versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.0.0: <literal>"3.0.0"</literal></para></listitem><listitem><para>GCC 3.0.1: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.1"</literal>)</para></listitem><listitem><para>GCC 3.0.2: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.2"</literal>)</para></listitem><listitem><para>GCC 3.0.3: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.3"</literal>)</para></listitem><listitem><para>GCC 3.0.4: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.4"</literal>)</para></listitem><listitem><para>GCC 3.1.0: <literal>"3.1.0"</literal></para></listitem><listitem><para>GCC 3.1.1: <literal>"3.1.1"</literal></para></listitem><listitem><para>GCC 3.2.0: <literal>"3.2"</literal></para></listitem><listitem><para>GCC 3.2.1: <literal>"3.2.1"</literal></para></listitem><listitem><para>GCC 3.2.2: <literal>"3.2.2"</literal></para></listitem><listitem><para>GCC 3.2.3: <literal>"3.2.3"</literal></para></listitem><listitem><para>GCC 3.3.0: <literal>"3.3"</literal></para></listitem><listitem><para>GCC 3.3.1: <literal>"3.3.1"</literal></para></listitem><listitem><para>GCC 3.3.2: <literal>"3.3.2"</literal></para></listitem><listitem><para>GCC 3.3.3: <literal>"3.3.3"</literal></para></listitem><listitem><para>GCC 3.4: <literal>"version-unused"</literal></para></listitem><listitem><para>GCC 4 and later: not defined</para></listitem></itemizedlist><para></para></listitem><listitem><para>
    Matching each specific C++ compiler release to a specific set of
    C++ include files. This is only implemented in GCC 3.1.1 releases
    and higher.
    </para><para>
    All C++ includes are installed in
    <filename class="directory">include/c++</filename>, then nested in a
    directory hierarchy corresponding to the C++ compiler's released
    version. This version corresponds to the variable "gcc_version" in
    "libstdc++-v3/acinclude.m4," and more details can be found in that
    file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0).
    </para><para>
    C++ includes are versioned as follows:
    </para><itemizedlist><listitem><para>GCC 3.0.0: include/g++-v3</para></listitem><listitem><para>GCC 3.0.1: include/g++-v3</para></listitem><listitem><para>GCC 3.0.2: include/g++-v3</para></listitem><listitem><para>GCC 3.0.3: include/g++-v3</para></listitem><listitem><para>GCC 3.0.4: include/g++-v3</para></listitem><listitem><para>GCC 3.1.0: include/g++-v3</para></listitem><listitem><para>GCC 3.1.1: include/c++/3.1.1</para></listitem><listitem><para>GCC 3.2.0: include/c++/3.2</para></listitem><listitem><para>GCC 3.2.1: include/c++/3.2.1</para></listitem><listitem><para>GCC 3.2.2: include/c++/3.2.2</para></listitem><listitem><para>GCC 3.2.3: include/c++/3.2.3</para></listitem><listitem><para>GCC 3.3.0: include/c++/3.3</para></listitem><listitem><para>GCC 3.3.1: include/c++/3.3.1</para></listitem><listitem><para>GCC 3.3.2: include/c++/3.3.2</para></listitem><listitem><para>GCC 3.3.3: include/c++/3.3.3</para></listitem><listitem><para>GCC 3.4.x: include/c++/3.4.x</para></listitem><listitem><para>GCC 4.x.y: include/c++/4.x.y</para></listitem><listitem><para>GCC 5.1.0: include/c++/5.1.0</para></listitem><listitem><para>GCC x.y.0: include/c++/x.y.0 (for releases after GCC 5.1.0)</para></listitem></itemizedlist><para></para></listitem></orderedlist><para>
  Taken together, these techniques can accurately specify interface
  and implementation changes in the GNU C++ tools themselves. Used
  properly, they allow both the GNU C++ tools implementation, and
  programs using them, an evolving yet controlled development that
  maintains backward compatibility.
</para></section><section xml:id="abi.versioning.prereq"><info><title>Prerequisites</title></info><para>
      Minimum environment that supports a versioned ABI: A supported
      dynamic linker, a GNU linker of sufficient vintage to understand
      demangled C++ name globbing (ld) or the Sun linker, a shared
      executable compiled
      with g++, and shared libraries (libgcc_s, libstdc++) compiled by
      a compiler (g++) with a compatible ABI. Phew.
    </para><para>
      On top of all that, an additional constraint: libstdc++ did not
      attempt to version symbols (or age gracefully, really) until
      version 3.1.0.
    </para><para>
      Most modern GNU/Linux and BSD versions, particularly ones using
      GCC 3.1 and later, will meet the
      requirements above, as does Solaris 2.5 and up.
    </para></section><section xml:id="abi.versioning.config"><info><title>Configuring</title></info><para>
      It turns out that most of the configure options that change
      default behavior will impact the mangled names of exported
      symbols, and thus impact versioning and compatibility.
    </para><para>
      For more information on configure options, including ABI
      impacts, see:
      <link linkend="manual.intro.setup.configure">here</link>
    </para><para>
      There is one flag that explicitly deals with symbol versioning:
      --enable-symvers.
    </para><para>
      In particular, libstdc++-v3/acinclude.m4 has a macro called
      GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
      passed in via --enable-symvers=foo). At that point, the macro
      attempts to make sure that all the requirement for symbol
      versioning are in place. For more information, please consult
      acinclude.m4.
    </para></section><section xml:id="abi.versioning.active"><info><title>Checking Active</title></info><para>
      When the GNU C++ library is being built with symbol versioning
      on, you should see the following at configure time for
      libstdc++ (showing either 'gnu' or another of the supported styles):
    </para><screen><computeroutput>
  checking versioning on shared library symbols... gnu
</computeroutput></screen><para>
  If you don't see this line in the configure output, or if this line
  appears but the last word is 'no', then you are out of luck.
</para><para>
  If the compiler is pre-installed, a quick way to test is to compile
  the following (or any) simple C++ file and link it to the shared
  libstdc++ library:
</para><programlisting>
#include &lt;iostream&gt;

int main()
{ std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }

%g++ hello.cc -o hello.out

%ldd hello.out
	libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
	libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
	libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
	libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
	/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)

%nm hello.out
</programlisting><para>
If you see symbols in the resulting output with "GLIBCXX_3" as part
of the name, then the executable is versioned. Here's an example:
</para><para><code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code></para><para>
On Solaris 2, you can use <code>pvs -r</code> instead:
</para><programlisting>
%g++ hello.cc -o hello.out

%pvs -r hello.out
        libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12);
        libgcc_s.so.1 (GCC_3.0);
        libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3);
</programlisting><para><code>ldd -v</code> works too, but is very verbose.
</para></section></section><section xml:id="abi.changes_allowed"><info><title>Allowed Changes</title></info><para>
The following will cause the library minor version number to
increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
</para><orderedlist><listitem><para>Adding an exported global or static data member</para></listitem><listitem><para>Adding an exported function, static or non-virtual member function</para></listitem><listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem></orderedlist><para>
Other allowed changes are possible.
</para></section><section xml:id="abi.changes_no"><info><title>Prohibited Changes</title></info><para>
The following non-exhaustive list will cause the library major version
number to increase, say from "libstdc++.so.3.0.4" to
"libstdc++.so.4.0.0".
</para><orderedlist><listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem><listitem><para>Changing size of an exported symbol</para></listitem><listitem><para>Changing alignment of an exported symbol</para></listitem><listitem><para>Changing the layout of an exported symbol</para></listitem><listitem><para>Changing mangling on an exported symbol</para></listitem><listitem><para>Deleting an exported symbol</para></listitem><listitem><para>Changing the inheritance properties of a type by adding or removing
    base classes</para></listitem><listitem><para>
  Changing the size, alignment, or layout of types
  specified in the C++ standard. These may not necessarily be
  instantiated or otherwise exported in the library binary, and
  include all the required locale facets, as well as things like
  std::basic_streambuf, et al.
</para></listitem><listitem><para> Adding an explicit copy constructor or destructor to a
class that would otherwise have implicit versions. This will change
the way the compiler deals with this class in by-value return
statements or parameters: instead of passing instances of this
class in registers, the compiler will be forced to use memory. See the
section on <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#calls">Function
Calling Conventions and APIs</link>
 of the C++ ABI documentation for further details.
</para></listitem></orderedlist></section><section xml:id="abi.impl"><info><title>Implementation</title></info><orderedlist><listitem><para>
     Separation of interface and implementation
   </para><para>
     This is accomplished by two techniques that separate the API from
     the ABI: forcing undefined references to link against a library
     binary for definitions.
   </para><variablelist><varlistentry><term>Include files have declarations, source files have defines</term><listitem><para>
	For non-templatized types, such as much of <code>class
	locale</code>, the appropriate standard C++ include, say
	<code>locale</code>, can contain full declarations, while
	various source files (say <code> locale.cc, locale_init.cc,
	localename.cc</code>) contain definitions.
      </para></listitem></varlistentry><varlistentry><term>Extern template on required types</term><listitem><para>
       For parts of the standard that have an explicit list of
       required instantiations, the GNU extension syntax <code> extern
       template </code> can be used to control where template
       definitions reside. By marking required instantiations as
       <code> extern template </code> in include files, and providing
       explicit instantiations in the appropriate instantiation files,
       non-inlined template functions can be versioned. This technique
       is mostly used on parts of the standard that require <code>
       char</code> and <code> wchar_t</code> instantiations, and
       includes <code> basic_string</code>, the locale facets, and the
       types in <code> iostreams</code>.
     </para></listitem></varlistentry></variablelist><para>
   In addition, these techniques have the additional benefit that they
   reduce binary size, which can increase runtime performance.
 </para></listitem><listitem><para>
     Namespaces linking symbol definitions to export mapfiles
   </para><para>
     All symbols in the shared library binary are processed by a
     linker script at build time that either allows or disallows
     external linkage. Because of this, some symbols, regardless of
     normal C/C++ linkage, are not visible. Symbols that are internal
     have several appealing characteristics: by not exporting the
     symbols, there are no relocations when the shared library is
     started and thus this makes for faster runtime loading
     performance by the underlying dynamic loading mechanism. In
     addition, they have the possibility of changing without impacting
     ABI compatibility.
   </para><para>The following namespaces are transformed by the mapfile:</para><variablelist><varlistentry><term><code>namespace std</code></term><listitem><para> Defaults to exporting all symbols in label
<code>GLIBCXX</code> that do not begin with an underscore, i.e.,
<code>__test_func</code> would not be exported by default. Select
exceptional symbols are allowed to be visible.</para></listitem></varlistentry><varlistentry><term><code>namespace __gnu_cxx</code></term><listitem><para> Defaults to not exporting any symbols in label
<code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem></varlistentry><varlistentry><term><code>namespace __gnu_internal</code></term><listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem></varlistentry><varlistentry><term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term><listitem><para> Defaults to not exporting any symbols in label
<code>CXXABI</code>, select items are allowed to be visible.</para></listitem></varlistentry></variablelist><para>
</para></listitem><listitem><para>Freezing the API</para><para>Disallowed changes, as above, are not made on a stable release
branch. Enforcement tends to be less strict with GNU extensions that
standard includes.</para></listitem></orderedlist></section><section xml:id="abi.testing"><info><title>Testing</title></info><section xml:id="abi.testing.single"><info><title>Single ABI Testing</title></info><para>
      Testing for GNU C++ ABI changes is composed of two distinct
      areas: testing the C++ compiler (g++) for compiler changes, and
      testing the C++ library (libstdc++) for library changes.
    </para><para>
      Testing the C++ compiler ABI can be done various ways.
    </para><para>
      One.  Intel ABI checker.
    </para><para>
Two.
The second is yet unreleased, but has been announced on the gcc
mailing list. It is yet unspecified if these tools will be freely
available, and able to be included in a GNU project. Please contact
Mark Mitchell (mark@codesourcery.com) for more details, and current
status.
</para><para>
Three.
Involves using the vlad.consistency test framework. This has also been
discussed on the gcc mailing lists.
</para><para>
Testing the C++ library ABI can also be done various ways.
</para><para>
One.
(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
one with a new compiler and an old library, and the other with an old
compiler and a new library, and look for testsuite regressions)
</para><para>
Details on how to set this kind of test up can be found here:
http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
</para><para>
Two.
Use the 'make check-abi' rule in the libstdc++ Makefile.
</para><para>
This is a proactive check of the library ABI. Currently, exported symbol
names that are either weak or defined are checked against a last known
good baseline. Currently, this baseline is keyed off of 3.4.0
binaries, as this was the last time the .so number was incremented. In
addition, all exported names are demangled, and the exported objects
are checked to make sure they are the same size as the same object in
the baseline.

Notice that each baseline is relative to a <emphasis>default</emphasis>
configured library and compiler: in particular, if options such as
--enable-clocale, or --with-cpu, in case of multilibs, are used at
configure time, the check may fail, either because of substantive
differences or because of limitations of the current checking
machinery.
</para><para>
This dataset is insufficient, yet a start. Also needed is a
comprehensive check for all user-visible types part of the standard
library for sizeof() and alignof() changes.
</para><para>
Verifying compatible layouts of objects is not even attempted.  It
should be possible to use sizeof, alignof, and offsetof to compute
offsets for each structure and type in the standard library, saving to
another datafile. Then, compute this in a similar way for new
binaries, and look for differences.
</para><para>
Another approach might be to use the -fdump-class-hierarchy flag to
get information. However, currently this approach gives insufficient
data for use in library testing, as class data members, their offsets,
and other detailed data is not displayed with this flag.
(See PR g++/7470 on how this was used to find bugs.)
</para><para>
Perhaps there are other C++ ABI checkers. If so, please notify
us. We'd like to know about them!
</para></section><section xml:id="abi.testing.multi"><info><title>Multiple ABI Testing</title></info><para>
A "C" application, dynamically linked to two shared libraries, liba,
libb. The dependent library liba is a C++ shared library compiled with
GCC 3.3, and uses io, exceptions, locale, etc. The dependent library
libb is a C++ shared library compiled with GCC 3.4, and also uses io,
exceptions, locale, etc.
</para><para> As above, libone is constructed as follows: </para><programlisting>
%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc

%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0

%ln -s libone.so.1.0.0 libone.so

%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc

%ar cru libone.a a.o
</programlisting><para> And, libtwo is constructed as follows: </para><programlisting>
%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc

%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0

%ln -s libtwo.so.1.0.0 libtwo.so

%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc

%ar cru libtwo.a b.o
</programlisting><para> ...with the resulting libraries looking like </para><screen><computeroutput>
%ldd libone.so.1.0.0
	libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
	libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
	libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
	libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
	/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)

%ldd libtwo.so.1.0.0
	libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
	libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
	libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
	libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
	/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</computeroutput></screen><para>
  Then, the "C" compiler is used to compile a source file that uses
  functions from each library.
</para><programlisting>
gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
</programlisting><para>
  Which gives the expected:
</para><screen><computeroutput>
%ldd a.out
	libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
	libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
	libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
	libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
	libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
	/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</computeroutput></screen><para>
  This resulting binary, when executed, will be able to safely use
  code from both liba, and the dependent libstdc++.so.6, and libb,
  with the dependent libstdc++.so.5.
</para></section></section><section xml:id="abi.issues"><info><title>Outstanding Issues</title></info><para>
  Some features in the C++ language make versioning especially
  difficult. In particular, compiler generated constructs such as
  implicit instantiations for templates, typeinfo information, and
  virtual tables all may cause ABI leakage across shared library
  boundaries. Because of this, mixing C++ ABIs is not recommended at
  this time.
</para><para>
  For more background on this issue, see these bugzilla entries:
</para><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</link></para><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</link></para></section><bibliography xml:id="abi.biblio"><info><title>Bibliography</title></info><biblioentry xml:id="biblio.abicheck"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://abicheck.sourceforge.net">
	  ABIcheck
	</link></title></biblioentry><biblioentry xml:id="biblio.cxxabi"><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://itanium-cxx-abi.github.io/cxx-abi/">
	  Itanium C++ ABI
	</link></title></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oracle.com/cd/E23824_01/html/819-0690/index.html">
	Linker and Libraries Guide (document 819-0690)
	</link></title></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://docs.oracle.com/cd/E19422-01/819-3689/">
      Sun Studio 11: C++ Migration Guide (document 819-3689)
	</link></title></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.akkadia.org/drepper/dsohowto.pdf">
      How to Write Shared Libraries
	</link></title><author><personname><firstname>Ulrich</firstname><surname>Drepper</surname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://developer.arm.com/documentation/ihi0036/latest/">
      C++ ABI for the ARM Architecture
	</link></title></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html">
      Dynamic Shared Objects: Survey and Issues
	</link></title><subtitle>
      ISO C++ J16/06-0046
    </subtitle><author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html">
	Versioning With Namespaces
	</link></title><subtitle>
      ISO C++ J16/06-0083
    </subtitle><author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author></biblioentry><biblioentry><title><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://syrcose.ispras.ru/2009/files/02_paper.pdf">
      Binary Compatibility of Shared Libraries Implemented in C++
      on GNU/Linux Systems
	</link></title><subtitle>
      SYRCoSE 2009
    </subtitle><author><personname><firstname>Pavel</firstname><surname>Shved</surname></personname></author><author><personname><firstname>Denis</firstname><surname>Silakov</surname></personname></author></biblioentry></bibliography></section><!-- API Evolution and Deprecation History --><section version="5.0" xreflabel="api" xml:id="appendix.porting.api"><?dbhtml filename="api.html"?><info><title>API Evolution and Deprecation History</title><keywordset><keyword>ISO C++</keyword><keyword>api</keyword><keyword>evolution</keyword><keyword>deprecation</keyword><keyword>history</keyword></keywordset></info><para>
A list of user-visible changes, in chronological order
</para><section xml:id="api.rel_300"><info><title><constant>3.0</constant></title></info><para>
Extensions moved to <filename class="directory">include/ext</filename>.
  </para><para>
Include files from the SGI/HP sources that pre-date the ISO standard
are added. These files are placed into
the <filename class="directory">include/backward</filename> directory and a deprecated warning
is added that notifies on inclusion (<literal>-Wno-deprecated</literal>
deactivates the warning.)
</para><para>Deprecated include <filename class="headerfile">&lt;backward/strstream&gt;</filename> added.</para><para>Removal of include <filename class="headerfile">&lt;builtinbuf.h&gt;</filename>, <filename class="headerfile">&lt;indstream.h&gt;</filename>, <filename class="headerfile">&lt;parsestream.h&gt;</filename>, <filename class="headerfile">&lt;PlotFile.h&gt;</filename>, <filename class="headerfile">&lt;SFile.h&gt;</filename>, <filename class="headerfile">&lt;stdiostream.h&gt;</filename>, and <filename class="headerfile">&lt;stream.h&gt;</filename>.
</para></section><section xml:id="api.rel_310"><info><title><constant>3.1</constant></title></info><para>
  </para><para>
Extensions from SGI/HP moved from <code>namespace std</code>
to <code>namespace __gnu_cxx</code>. As part of this, the following
new includes are
added: <filename class="headerfile">&lt;ext/algorithm&gt;</filename>, <filename class="headerfile">&lt;ext/functional&gt;</filename>, <filename class="headerfile">&lt;ext/iterator&gt;</filename>, <filename class="headerfile">&lt;ext/memory&gt;</filename>, and <filename class="headerfile">&lt;ext/numeric&gt;</filename>.
</para><para>
Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
</para><para>
Extensions to tree data structures added in <filename class="headerfile">&lt;ext/rb_tree&gt;</filename>.
</para><para>
Removal of <filename class="headerfile">&lt;ext/tree&gt;</filename>, moved to <filename class="headerfile">&lt;backward/tree.h&gt;</filename>.
</para></section><section xml:id="api.rel_320"><info><title><constant>3.2</constant></title></info><para>
  </para><para>Symbol versioning introduced for shared library.</para><para>Removal of include <filename class="headerfile">&lt;backward/strstream.h&gt;</filename>.</para><para>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </para><para> For GCC releases from 2.95 through the 3.1 series, defining
   <literal>__USE_MALLOC</literal> on the gcc command line would change the
   default allocation strategy to instead use <code>malloc</code> and
   <code>free</code>. For the 3.2 and 3.3 release series the same
   functionality was spelled <literal>_GLIBCXX_FORCE_NEW</literal>. From
   GCC 3.4 onwards the default allocator uses <code>new</code> anyway,
   but for the optional pooling allocators the functionality is enabled by
   setting <literal>GLIBCXX_FORCE_NEW</literal> in the environment, see
   <link linkend="manual.ext.allocator.mt">the mt allocator chapter</link>
   for details.
   </para><para>Error handling in iostreams cleaned up, made consistent. </para></section><section xml:id="api.rel_330"><info><title><constant>3.3</constant></title></info><para>
  </para></section><section xml:id="api.rel_340"><info><title><constant>3.4</constant></title></info><para>
  </para><para>
Large file support.
</para><para> Extensions for generic characters and <code>char_traits</code> added in <filename class="headerfile">&lt;ext/pod_char_traits.h&gt;</filename>.
</para><para>
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.
</para><para>
Support for <code>char_traits</code> beyond builtin types.
</para><para>
Conformant <code>allocator</code> class and usage in containers. As
part of this, the following extensions are
added: <filename class="headerfile">&lt;ext/bitmap_allocator.h&gt;</filename>, <filename class="headerfile">&lt;ext/debug_allocator.h&gt;</filename>, <filename class="headerfile">&lt;ext/mt_allocator.h&gt;</filename>, <filename class="headerfile">&lt;ext/malloc_allocator.h&gt;</filename>,<filename class="headerfile">&lt;ext/new_allocator.h&gt;</filename>, <filename class="headerfile">&lt;ext/pool_allocator.h&gt;</filename>.
</para><para>
This is a change from all previous versions, and may require
source-level changes due to allocator-related changes to structures
names and template parameters, filenames, and file locations. Some,
like <code>__simple_alloc, __allocator, __alloc, </code> and <code>
_Alloc_traits</code> have been removed.
</para><para>Default behavior of <code>std::allocator</code> has changed.</para><para>
   Previous versions prior to 3.4 cache allocations in a memory
   pool, instead of passing through to call the global allocation
   operators (i.e., <classname>__gnu_cxx::pool_allocator</classname>).  More
   recent versions default to the
   simpler <classname>__gnu_cxx::new_allocator</classname>.
</para><para> Previously, all allocators were written to the SGI
   style, and all STL containers expected this interface. This
   interface had a traits class called <code>_Alloc_traits</code> that
   attempted to provide more information for compile-time allocation
   selection and optimization. This traits class had another allocator
   wrapper, <code>__simple_alloc&lt;T,A&gt;</code>, which was a
   wrapper around another allocator, A, which itself is an allocator
   for instances of T. But wait, there's more:
   <code>__allocator&lt;T,A&gt;</code> is another adapter.  Many of
   the provided allocator classes were SGI style: such classes can be
   changed to a conforming interface with this wrapper:
   <code>__allocator&lt;T, __alloc&gt;</code> is thus the same as
   <code>allocator&lt;T&gt;</code>.
   </para><para> The class <classname>allocator</classname> used the typedef
   <type>__alloc</type> to select an underlying allocator that
   satisfied memory allocation requests. The selection of this
   underlying allocator was not user-configurable.
   </para><table frame="all" xml:id="table.extension_allocators"><title>Extension Allocators</title><tgroup align="left" cols="4" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><colspec colname="c4"></colspec><thead><row><entry>Allocator (3.4)</entry><entry>Header (3.4)</entry><entry>Allocator (3.[0-3])</entry><entry>Header (3.[0-3])</entry></row></thead><tbody><row><entry><classname>__gnu_cxx::new_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/new_allocator.h&gt;</filename></entry><entry><classname>std::__new_alloc</classname></entry><entry><filename class="headerfile">&lt;memory&gt;</filename></entry></row><row><entry><classname>__gnu_cxx::malloc_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/malloc_allocator.h&gt;</filename></entry><entry><classname>std::__malloc_alloc_template&lt;int&gt;</classname></entry><entry><filename class="headerfile">&lt;memory&gt;</filename></entry></row><row><entry><classname>__gnu_cxx::debug_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/debug_allocator.h&gt;</filename></entry><entry><classname>std::debug_alloc&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;memory&gt;</filename></entry></row><row><entry><classname>__gnu_cxx::__pool_alloc&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/pool_allocator.h&gt;</filename></entry><entry><classname>std::__default_alloc_template&lt;bool,int&gt;</classname></entry><entry><filename class="headerfile">&lt;memory&gt;</filename></entry></row><row><entry><classname>__gnu_cxx::__mt_alloc&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/mt_allocator.h&gt;</filename></entry><entry> </entry><entry> </entry></row><row><entry><classname>__gnu_cxx::bitmap_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/bitmap_allocator.h&gt;</filename></entry><entry> </entry><entry> </entry></row></tbody></tgroup></table><para> Releases after gcc-3.4 have continued to add to the collection
   of available allocators. All of these new allocators are
   standard-style. The following table includes details, along with
   the first released version of GCC that included the extension allocator.
   </para><table frame="all" xml:id="table.extension_allocators2"><title>Extension Allocators Continued</title><tgroup align="left" cols="3" colsep="1" rowsep="1"><colspec colname="c1"></colspec><colspec colname="c2"></colspec><colspec colname="c3"></colspec><thead><row><entry>Allocator</entry><entry>Include</entry><entry>Version</entry></row></thead><tbody><row><entry><classname>__gnu_cxx::array_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/array_allocator.h&gt;</filename></entry><entry>4.0.0</entry></row><row><entry><classname>__gnu_cxx::throw_allocator&lt;T&gt;</classname></entry><entry><filename class="headerfile">&lt;ext/throw_allocator.h&gt;</filename></entry><entry>4.2.0</entry></row></tbody></tgroup></table><para>
Debug mode first appears.
</para><para>
Precompiled header support <acronym>PCH</acronym> support.
</para><para>
Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>.
</para><para>
Extension <filename class="headerfile">&lt;ext/stdio_sync_filebuf.h&gt;</filename> added.
</para><para>
Extension <filename class="headerfile">&lt;ext/demangle.h&gt;</filename> added.
</para></section><section xml:id="api.rel_400"><info><title><constant>4.0</constant></title></info><para>
  </para><para>
TR1 features first appear.
</para><para>
Extension allocator <filename class="headerfile">&lt;ext/array_allocator.h&gt;</filename> added.
</para><para>
Extension <code>codecvt</code> specializations moved to <filename class="headerfile">&lt;ext/codecvt_specializations.h&gt;</filename>.
</para><para>
Removal of <filename class="headerfile">&lt;ext/demangle.h&gt;</filename>.
</para></section><section xml:id="api.rel_410"><info><title><constant>4.1</constant></title></info><para>
  </para><para>
Removal of <filename class="headerfile">&lt;cassert&gt;</filename> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls.
</para><para> Extensions for policy-based data structures first added. New includes,
types, namespace <code>pb_assoc</code>.
</para><para> Extensions for typelists added in <filename class="headerfile">&lt;ext/typelist.h&gt;</filename>.
</para><para> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <filename class="headerfile">&lt;ext/vstring.h&gt;</filename>.
</para></section><section xml:id="api.rel_420"><info><title><constant>4.2</constant></title></info><para>
  </para><para> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>.
</para><para>TR1 <filename class="headerfile">&lt;random&gt;</filename>, <filename class="headerfile">&lt;complex&gt;</filename>, and C compatibility headers added.</para><para> Extensions for concurrent programming consolidated
into <filename class="headerfile">&lt;ext/concurrence.h&gt;</filename> and <filename class="headerfile">&lt;ext/atomicity.h&gt;</filename>,
including change of namespace to <code>__gnu_cxx</code> in some
cases. Added types
include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</para><para> Extensions for type traits consolidated
into <filename class="headerfile">&lt;ext/type_traits.h&gt;</filename>. Additional traits are added
(<code>__conditional_type</code>, <code>__enable_if</code>, others.)
</para><para> Extensions for policy-based data structures revised. New includes,
types, namespace moved to <code>__pb_ds</code>.
</para><para> Extensions for debug mode modified: now nested in <code>namespace
std::__debug</code> and extensions in <code>namespace
__gnu_cxx::__debug</code>.</para><para> Extensions added: <filename class="headerfile">&lt;ext/typelist.h&gt;</filename>
and <filename class="headerfile">&lt;ext/throw_allocator.h&gt;</filename>.
</para></section><section xml:id="api.rel_430"><info><title><constant>4.3</constant></title></info><para>
  </para><para>
C++0X features first appear.
</para><para>TR1 <filename class="headerfile">&lt;regex&gt;</filename> and <filename class="headerfile">&lt;cmath&gt;</filename>'s mathematical special function added.
</para><para>
Backward include edit.
</para><itemizedlist><listitem><para>Removed</para><para><filename class="headerfile">&lt;algobase.h&gt;</filename><filename class="headerfile">&lt;algo.h&gt;</filename><filename class="headerfile">&lt;alloc.h&gt;</filename><filename class="headerfile">&lt;bvector.h&gt;</filename><filename class="headerfile">&lt;complex.h&gt;</filename><filename class="headerfile">&lt;defalloc.h&gt;</filename><filename class="headerfile">&lt;deque.h&gt;</filename><filename class="headerfile">&lt;fstream.h&gt;</filename><filename class="headerfile">&lt;function.h&gt;</filename><filename class="headerfile">&lt;hash_map.h&gt;</filename><filename class="headerfile">&lt;hash_set.h&gt;</filename><filename class="headerfile">&lt;hashtable.h&gt;</filename><filename class="headerfile">&lt;heap.h&gt;</filename><filename class="headerfile">&lt;iomanip.h&gt;</filename><filename class="headerfile">&lt;iostream.h&gt;</filename><filename class="headerfile">&lt;istream.h&gt;</filename><filename class="headerfile">&lt;iterator.h&gt;</filename><filename class="headerfile">&lt;list.h&gt;</filename><filename class="headerfile">&lt;map.h&gt;</filename><filename class="headerfile">&lt;multimap.h&gt;</filename><filename class="headerfile">&lt;multiset.h&gt;</filename><filename class="headerfile">&lt;new.h&gt;</filename><filename class="headerfile">&lt;ostream.h&gt;</filename><filename class="headerfile">&lt;pair.h&gt;</filename><filename class="headerfile">&lt;queue.h&gt;</filename><filename class="headerfile">&lt;rope.h&gt;</filename><filename class="headerfile">&lt;set.h&gt;</filename><filename class="headerfile">&lt;slist.h&gt;</filename><filename class="headerfile">&lt;stack.h&gt;</filename><filename class="headerfile">&lt;streambuf.h&gt;</filename><filename class="headerfile">&lt;stream.h&gt;</filename><filename class="headerfile">&lt;tempbuf.h&gt;</filename><filename class="headerfile">&lt;tree.h&gt;</filename><filename class="headerfile">&lt;vector.h&gt;</filename></para></listitem><listitem><para>Added</para><para><filename class="headerfile">&lt;hash_map&gt;</filename> and <filename class="headerfile">&lt;hash_set&gt;</filename>
  </para></listitem><listitem><para>Added in C++11</para><para><filename class="headerfile">&lt;auto_ptr.h&gt;</filename> and <filename class="headerfile">&lt;binders.h&gt;</filename>
  </para></listitem></itemizedlist><para>
Header dependency streamlining.
</para><itemizedlist><listitem><para><filename class="headerfile">&lt;algorithm&gt;</filename> no longer includes <filename class="headerfile">&lt;climits&gt;</filename>, <filename class="headerfile">&lt;cstring&gt;</filename>, or <filename class="headerfile">&lt;iosfwd&gt;</filename> </para></listitem><listitem><para><filename class="headerfile">&lt;bitset&gt;</filename> no longer includes <filename class="headerfile">&lt;istream&gt;</filename> or <filename class="headerfile">&lt;ostream&gt;</filename>, adds <filename class="headerfile">&lt;iosfwd&gt;</filename> </para></listitem><listitem><para><filename class="headerfile">&lt;functional&gt;</filename> no longer includes <filename class="headerfile">&lt;cstddef&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;iomanip&gt;</filename> no longer includes <filename class="headerfile">&lt;istream&gt;</filename>, <filename class="headerfile">&lt;istream&gt;</filename>, or <filename class="headerfile">&lt;functional&gt;</filename>, adds <filename class="headerfile">&lt;ioswd&gt;</filename> </para></listitem><listitem><para><filename class="headerfile">&lt;numeric&gt;</filename> no longer includes <filename class="headerfile">&lt;iterator&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;string&gt;</filename> no longer includes <filename class="headerfile">&lt;algorithm&gt;</filename> or <filename class="headerfile">&lt;memory&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;valarray&gt;</filename> no longer includes <filename class="headerfile">&lt;numeric&gt;</filename> or <filename class="headerfile">&lt;cstdlib&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;tr1/hashtable&gt;</filename> no longer includes <filename class="headerfile">&lt;memory&gt;</filename> or <filename class="headerfile">&lt;functional&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;tr1/memory&gt;</filename> no longer includes <filename class="headerfile">&lt;algorithm&gt;</filename></para></listitem><listitem><para><filename class="headerfile">&lt;tr1/random&gt;</filename> no longer includes <filename class="headerfile">&lt;algorithm&gt;</filename> or <filename class="headerfile">&lt;fstream&gt;</filename></para></listitem></itemizedlist><para>
Debug mode for <filename class="headerfile">&lt;unordered_map&gt;</filename> and <filename class="headerfile">&lt;unordered_set&gt;</filename>.
</para><para>
Parallel mode first appears.
</para><para>Variadic template implementations of items in <filename class="headerfile">&lt;tuple&gt;</filename> and
    <filename class="headerfile">&lt;functional&gt;</filename>.
</para><para>Default <code>what</code> implementations give more elaborate
    exception strings for <code>bad_cast</code>,
    <code>bad_typeid</code>, <code>bad_exception</code>, and
    <code>bad_alloc</code>.
</para><para>
PCH binary files no longer installed. Instead, the source files are installed.
</para><para>
Namespace pb_ds moved to __gnu_pb_ds.
</para></section><section xml:id="api.rel_440"><info><title><constant>4.4</constant></title></info><para>
  </para><para>
C++0X features.
</para><itemizedlist><listitem><para>
    Added.
  </para><para><filename class="headerfile">&lt;atomic&gt;</filename>,
    <filename class="headerfile">&lt;chrono&gt;</filename>,
    <filename class="headerfile">&lt;condition_variable&gt;</filename>,
    <filename class="headerfile">&lt;forward_list&gt;</filename>,
    <filename class="headerfile">&lt;initializer_list&gt;</filename>,
    <filename class="headerfile">&lt;mutex&gt;</filename>,
    <filename class="headerfile">&lt;ratio&gt;</filename>,
    <filename class="headerfile">&lt;thread&gt;</filename></para></listitem><listitem><para>
    Updated and improved.
  </para><para><filename class="headerfile">&lt;algorithm&gt;</filename>,
    <filename class="headerfile">&lt;system_error&gt;</filename>,
    <filename class="headerfile">&lt;type_traits&gt;</filename></para></listitem><listitem><para>
    Use of the GNU extension namespace association converted to inline namespaces.
  </para></listitem><listitem><para>
    Preliminary support for <classname>initializer_list</classname>
    and defaulted and deleted constructors in container classes.
  </para></listitem><listitem><para><classname>unique_ptr</classname>.
  </para></listitem><listitem><para>
    Support for new character types <type>char16_t</type>
    and <type>char32_t</type> added
    to <classname>char_traits</classname>, <classname>basic_string</classname>, <classname>numeric_limits</classname>,
    and assorted compile-time type traits.
  </para></listitem><listitem><para>
    Support for string conversions <function>to_string</function>
    and <function>to_wstring</function>.
  </para></listitem><listitem><para>
    Member functions taking string arguments were added to iostreams
    including <classname>basic_filebuf</classname>, <classname>basic_ofstream</classname>,
    and <classname>basic_ifstream</classname>.
  </para></listitem><listitem><para>
    Exception propagation support,
    including <classname>exception_ptr</classname>, <function>current_exception</function>, <function>copy_exception</function>,
    and <function>rethrow_exception</function>.
  </para></listitem></itemizedlist><para>
Uglification of <literal>try</literal> to <literal>__try</literal>
and <literal>catch</literal> to <literal>__catch</literal>.
  </para><para>
Audit of internal mutex usage, conversion to functions returning static
local mutex.
  </para><para> Extensions
added: <filename class="headerfile">&lt;ext/pointer.h&gt;</filename>
and <filename class="headerfile">&lt;ext/extptr_allocator.h&gt;</filename>. Support
for non-standard pointer types has been added
to <classname>vector</classname>
and <classname>forward_list</classname>.
</para></section><section xml:id="api.rel_450"><info><title><constant>4.5</constant></title></info><para>
  </para><para>
C++0X features.
</para><itemizedlist><listitem><para>
    Added.
  </para><para><filename class="headerfile">&lt;functional&gt;</filename>,
    <filename class="headerfile">&lt;future&gt;</filename>,
    <filename class="headerfile">&lt;random&gt;</filename></para></listitem><listitem><para>
    Updated and improved.
  </para><para><filename class="headerfile">&lt;atomic&gt;</filename>,
    <filename class="headerfile">&lt;system_error&gt;</filename>,
    <filename class="headerfile">&lt;type_traits&gt;</filename></para></listitem><listitem><para>
    Add support for explicit operators and standard layout types.
  </para></listitem></itemizedlist><para>
Profile mode first appears.
</para><para>
Support for decimal floating-point arithmetic, including <classname>decimal32</classname>, <classname>decimal64</classname>, and <classname>decimal128</classname>.
</para><para>
Python pretty-printers are added for use with appropriately-advanced versions of <command>gdb</command>.
</para><para>
Audit for application of function attributes nothrow, const, pure, and noreturn.
</para><para>
The default behavior for comparing typeinfo names changed, so
in <filename class="headerfile">&lt;typeinfo&gt;</filename>, <literal>__GXX_MERGED_TYPEINFO_NAMES</literal>
now defaults to zero.
</para><para> Extensions modified: <filename class="headerfile">&lt;ext/throw_allocator.h&gt;</filename>.
</para></section><section xml:id="api.rel_460"><info><title><constant>4.6</constant></title></info><para>
  Use constexpr and nullptr where appropriate throughout the library.
</para><para>
  The library was updated to avoid including
  <filename class="headerfile">&lt;stddef.h&gt;</filename> in order
  to reduce namespace pollution.
</para><para>Reference-count annotations to assist data race detectors.
</para><para>
  Added <function>make_exception_ptr</function> as an alias of
  <function>copy_exception</function>.
</para></section><section xml:id="api.rel_470"><info><title><constant>4.7</constant></title></info><para>Use of noexcept throughout library.</para><para>Partial support for C++11 allocators first appears.</para><para><classname>monotonic_clock</classname> renamed to
  <classname>steady_clock</classname> as required by the final C++11
  standard.
</para><para>A new clocale model for newlib is available.</para><para>
  The library was updated to avoid including
  <filename class="headerfile">&lt;unistd.h&gt;</filename> in order
  to reduce namespace pollution.
</para><para>Debug Mode was improved for unordered containers. </para></section><section xml:id="api.rel_480"><info><title><constant>4.8</constant></title></info><para>
  New random number engines and distributions.
  Optimisations for random.
</para><para>New --enable-libstdcxx-verbose configure option</para><para>
  The --enable-libstdcxx-time configure option becomes unnecessary given a
  sufficiently recent glibc.
</para></section><section xml:id="api.rel_490"><info><title><constant>4.9</constant></title></info><para> Implementation of <classname>regex</classname> completed. </para><para> C++14 library and TS implementations are added. </para><para><function>copy_exception</function> deprecated. </para><para><classname>__gnu_cxx::array_allocator</classname> deprecated. </para></section><section xml:id="api.rel_51"><info><title><constant>5</constant></title></info><para>
  ABI transition adds new implementations of several components, using the
  <code>abi_tag</code> attribute and the <code>__cxx11</code> inline
  namespace to distinguish the new entities from the old ones.
</para><itemizedlist><listitem><para>
    Use of the new or old ABI can be selected per-translation unit with the
    <xref linkend="manual.intro.using.macros"><symbol>_GLIBCXX_USE_CXX11_ABI</symbol>
    macro</xref>.
  </para></listitem><listitem><para>
    New non-reference-counted <classname>string</classname> implementation.
  </para></listitem><listitem><para>
    New <classname>list</classname> implementation containing a new
    data member in order to provide O(1) <function>size()</function>.
  </para></listitem><listitem><para>
    New <classname>ios_base::failure</classname> implementation inheriting
    from <classname>system_error</classname>.
  </para></listitem></itemizedlist><para>
  C++11 support completed (movable iostreams, new I/O manipulators,
  Unicode conversion utilities, atomic operations for
  <classname>shared_ptr</classname>, functions for notifying condition
  variables and making futures ready at thread exit).
</para><para>
   Changed formatting of floating point types when
   <code>ios_base::fixed|ios_base::scientific</code> is set in a stream's
   format flags.
</para><para> Improved C++14 support and TS implementations. </para><para> New random number engines and distributions. </para><para>
  GDB Xmethods for containers and <classname>unique_ptr</classname> added.
</para><para><classname>has_trivial_default_constructor</classname>,
  <classname>has_trivial_copy_constructor</classname> and
  <classname>has_trivial_copy_assign</classname> deprecated.
</para><section xml:id="api.rel_53"><info><title><constant>5.3</constant></title></info><para> Experimental implementation of the C++ Filesystem TS added. </para></section></section><section xml:id="api.rel_61"><info><title><constant>6</constant></title></info><para> C++14 support completed. </para><para>
  Support for mathematical special functions (ISO/IEC 29124:2010) added.
</para><para>
  Assertions to check function preconditions can be enabled by defining the
  <link linkend="manual.intro.using.macros"><symbol>_GLIBCXX_ASSERTIONS</symbol>
  macro</link>.
  The initial set of assertions are a subset of the checks enabled by
  the Debug Mode, but without the ABI changes and changes to algorithmic
  complexity that are caused by enabling the full Debug Mode.
</para></section><section xml:id="api.rel_71"><info><title><constant>7</constant></title></info><para>
  The type of exception thrown by iostreams changed to the <code>cxx11</code>
  ABI version of <classname>std::ios_base::failure</classname>.
</para><para>
  Experimental C++17 support added, including most new library features.
  The meaning of <classname>shared_ptr&lt;T[]&gt;</classname> changed to
  match the C++17 semantics.
</para><para><xref linkend="manual.intro.using.macros"><symbol>_GLIBCXX_RELEASE</symbol>
  macro</xref> added.
</para><para><classname>has_trivial_default_constructor</classname>,
  <classname>has_trivial_copy_constructor</classname> and
  <classname>has_trivial_copy_assign</classname> removed.
</para><para>
Calling a <code>std::bind</code> result as volatile was deprecated for C++17.
</para><para> Profile Mode was deprecated. </para><section xml:id="api.rel_72"><info><title><constant>7.2</constant></title></info><para>
  Library Fundamentals TS header
  <filename class="headerfile">&lt;experimental/source_location&gt;</filename>
  added.
</para></section><section xml:id="api.rel_73"><info><title><constant>7.3</constant></title></info><para>
  Including new C++14 or C++17 headers without a suitable <option>-std</option>
  no longer causes compilation to fail via <literal>#error</literal>.
  Instead the header is simply empty and doesn't define anything.
</para></section></section><section xml:id="api.rel_81"><info><title><constant>8</constant></title></info><para>
  The exceptions thrown by iostreams can now be caught by handlers for either
  version of <classname>std::ios_base::failure</classname>.
</para><para>
  Improved experimental C++17 support. Headers
  <filename class="headerfile">&lt;charconv&gt;</filename> and
  <filename class="headerfile">&lt;filesystem&gt;</filename>.
  Experimental implementation of the C++17 Filesystem library added.
</para><para>
  Experimental C++2a support
  (<function>to_address</function> and <classname>endian</classname>).
</para><para>
  AddressSanitizer annotations added to <classname>std::vector</classname>
  to detect out-of-range accesses to the unused capacity of a vector.
</para><para><function>std::char_traits&lt;char16_t&gt;::to_int_type(u'\uFFFF')</function>
  now returns <literal>0xFFFD</literal>, as <literal>0xFFFF</literal> is
  used for <function>std::char_traits&lt;char16_t&gt;::eof()</function>.
</para><para>
  The extension allowing arithmetic on
  <classname>std::atomic&lt;void*&gt;</classname> and types like
  <classname>std::atomic&lt;R(*)()&gt;</classname> was deprecated.
</para><para>
  The <function>std::uncaught_exception</function> function was deprecated
  for C++17 mode.
</para><para>
  The nested typedefs <type>std::hash::result_type</type> and
  <type>std::hash::argument_type</type> were deprecated for C++17 mode.
</para><para>
  The deprecated iostream members <type>ios_base::io_state</type>,
  <type>ios_base::open_mode</type>, <type>ios_base::seek_dir</type>, and
  <function>basic_streambuf::stossc</function> were removed for C++17 mode.
</para><para>
  The non-standard C++0x <function>std::copy_exception</function> function
  was removed.
</para><para>
  For <option>-std=c++11</option>, <option>-std=c++14</option>, and
  <option>-std=c++17</option> modes the <filename>&lt;complex.h&gt;</filename>
  header no longer includes the C99 <filename>&lt;complex.h&gt;</filename>
  header.
</para><para>
  For the non-default <option>--enable-symvers=gnu-versioned-namespace</option>
  configuration, the shared library SONAME has been changed to
  <filename>libstdc++.so.8</filename>.
</para><para>
  The extension allowing containers to be instantiated with an allocator
  that doesn't match the container's value type is no longer allowed in
  strict (<option>-std=c++NN</option>) modes, only in
  <option>-std=gnu++NN</option> modes.
</para></section><section xml:id="api.rel_91"><info><title><constant>9</constant></title></info><para>
  C++17 header
  <filename class="headerfile">&lt;memory_resource&gt;</filename>
  added.
</para><para>
  Experimental C++2a support improved, with new headers
  <filename class="headerfile">&lt;bit&gt;</filename> and
  <filename class="headerfile">&lt;version&gt;</filename> added.
  Support for new character type <type>char8_t</type> added
  to <classname>char_traits</classname>, <classname>basic_string</classname>,
  <classname>numeric_limits</classname>,
  and relevant locale facets and type traits.
</para><para>
  Experimental implementation of the Networking TS library added,
  with new headers
  <filename class="headerfile">&lt;experimental/buffer&gt;</filename>,
  <filename class="headerfile">&lt;experimental/executor&gt;</filename>,
  <filename class="headerfile">&lt;experimental/internet&gt;</filename>,
  <filename class="headerfile">&lt;experimental/io_context&gt;</filename>,
  <filename class="headerfile">&lt;experimental/net&gt;</filename>,
  <filename class="headerfile">&lt;experimental/netfwd&gt;</filename>,
  <filename class="headerfile">&lt;experimental/socket&gt;</filename>,
  and
  <filename class="headerfile">&lt;experimental/timer&gt;</filename>.
</para></section><section xml:id="api.rel_101"><info><title><constant>10</constant></title></info><para> Deprecated features removed:
<itemizedlist><listitem> Profile Mode </listitem><listitem><classname>__gnu_cxx::array_allocator</classname></listitem></itemizedlist>
</para><para>
  The non-standard <function>std::__is_nullptr_t</function> type trait
  was deprecated.
</para><para>
  The <classname>std::packaged_task</classname> constructors taking
  an allocator argument are only defined for C++11 and C++14.
</para><para>
  Several members of <classname>std::allocator</classname> were removed
  for C++20 mode. The removed functionality has been provided by
  <classname>std::allocator_traits</classname> since C++11 and that should
  be used instead.
</para><para>
  The type of the <classname>std::iterator</classname> base class of
  <classname>std::istreambuf_iterator</classname> was changed to be
  consistent for all <option>-std</option> modes.
  Before GCC 10.1 the base class had one type in C++98 mode and a
  different type in C++11 and later modes. The type in C++98 mode
  was changed to be the same as for C++11 and later.
</para><para>
  Experimental C++2a support improved, with new headers
  <filename class="headerfile">&lt;concepts&gt;</filename>,
  <filename class="headerfile">&lt;ranges&gt;</filename>,
  <filename class="headerfile">&lt;compare&gt;</filename>,
  <filename class="headerfile">&lt;coroutine&gt;</filename>,
  <filename class="headerfile">&lt;numbers&gt;</filename>,
  <filename class="headerfile">&lt;span&gt;</filename>,
  and
  <filename class="headerfile">&lt;stop_token&gt;</filename>
  added.
</para><para>
  The extension allowing containers to be instantiated with an allocator
  that doesn't match the container's value type is no longer allowed in
  C++20 mode, even in non-strict <option>-std=gnu++20</option> mode.
</para></section><section xml:id="api.rel_111"><info><title><constant>11</constant></title></info><para>
  The <option>--enable-cheaders=c_std</option> configuration
  was deprecated.
</para><para>
  When compiling as C++20, the <function>operator&gt;&gt;</function> overloads
  for extracting strings into character buffers only work with arrays,
  not raw pointers.
</para><para><code>std::string::reserve(n)</code> will no longer reduce
  the string's capacity.
  Calling <function>reserve()</function> with no arguments is equivalent
  to <function>shrink_to_fit()</function>, but is deprecated.
  <function>shrink_to_fit()</function> should be used instead.
</para></section><section xml:id="api.rel_121"><info><title><constant>12</constant></title></info><para>
The <function>std::random_shuffle</function> algorithms are deprecated
for C++14 and later. The C++11 <function>std::shuffle</function> algorithm
can be used instead.
</para><para>
The <function>std::unexpected</function> function and related typedef and
accessors for the unexpected handler are deprecated for C++11 and later.
Dynamic exception specifications should be replaced with <code>noexcept</code>.
</para><para>
C++98 adaptable function utilities
(<code>std::bind1st</code>, <code>std::unary_function</code>,
<code>std::ptr_fun</code>, <code>std::mem_fun_ref</code> etc.)
were deprecated for C++11.
<code>std::iterator</code>, <code>std::raw_storage_iterator</code>,
<code>get_temporary_buffer</code>, and <code>std::not_fun</code>
were deprecated for C++17.
</para><para>
Non-standard <code>std::pair</code> constructors were deprecated.
A non-standard default argument for
<code>vector&lt;bool&gt;::insert(const_iterator, const bool&amp;)</code>
was deprecated.
</para><para>
The <literal>bitmap</literal>, <literal>mt</literal>, and <literal>pool</literal>
options for <option>--enable-libstdcxx-allocator</option> were removed.
For the <literal>new</literal> option, <classname>std::allocator</classname>
no longer derives from <classname>__gnu_cxx::new_allocator</classname>;
they both derive from <classname>std::__new_allocator</classname> instead.
</para><para><function>std::condition_variable::wait</function> changed to be
<code>noexcept(false)</code> to allow thread cancellation exceptions to
be thrown from <function>pthread_cond_wait</function> without aborting
the process.
</para></section><section xml:id="api.rel_123"><info><title><constant>12.3</constant></title></info><para>
Calling a <code>std::bind</code> result as volatile is ill-formed for C++20
and later.
</para></section><section xml:id="api.rel_131"><info><title><constant>13</constant></title></info><para>
Tunables <varname>glibcxx.eh_pool.obj_count</varname> and
<varname>glibcxx.eh_pool.obj_size</varname> were added.
</para><para>Static library <filename>libstdc++exp.a</filename> was added
to provide the symbols for the experimental C++ Contracts support.</para></section><section xml:id="api.rel_133"><info><title><constant>13.3</constant></title></info><para>
Symbols for the Filesystem TS and C++23 <filename>&lt;stacktrace&gt;</filename>
header were added to the static library <filename>libstdc++exp.a</filename>.
</para></section><section xml:id="api.rel_141"><info><title><constant>14</constant></title></info><para>
Deprecated the non-standard overload that allows <code>std::setfill</code>
to be used with <code>std::basic_istream</code>.
</para><para>
  The extension allowing <code>std::basic_string</code> to be instantiated
  with an allocator that doesn't match the string's character type is no
  longer allowed in C++20 mode.
</para></section><section xml:id="api.rel_151"><info><title><constant>15</constant></title></info><para>
Enabled debug assertions by default for unoptimized builds.
</para><para>
Added warnings when including the headers that were deprecated in C++17
and removed in C++20:
<filename class="headerfile">&lt;ccomplex&gt;</filename>,
<filename class="headerfile">&lt;ciso646&gt;</filename>,
<filename class="headerfile">&lt;cstdalign&gt;</filename>,
<filename class="headerfile">&lt;cstdbool&gt;</filename>, and
<filename class="headerfile">&lt;ctgmath&gt;</filename>.
</para><para>
Nested <code>result_type</code> and <code>argument_type</code> removed from
<classname>std::hash</classname> specializations for C++20.
</para></section><section xml:id="api.rel_16"><info><title><constant>16</constant></title></info><para>
Deprecated the non-standard overload of <code>std::fabs</code> for
<code>std::complex</code> arguments.
</para><para>
Made <code>std::is_integral_v&lt;__int128&gt;</code> true for strict
<code>-std</code> dialects.
</para></section><section xml:id="api.rel_17"><info><title><constant>17</constant></title></info><para>
Removed allocator-extended constructors and support for uses-allocator
construction from <classname>std::promise</classname> and
<classname>std::packaged_task</classname>.
</para><para><code>std::numeric_limits::has_denorm</code>,
<code>std::numeric_limits::has_denorm_loss</code>,
and <code>enum std::float_denorm_style</code> and its enumerators
were deprecated for C++23.
</para></section></section><!-- Backwards Compatibility --><section version="5.0" xreflabel="backwards" xml:id="manual.appendix.porting.backwards"><?dbhtml filename="backwards.html"?><info><title>Backwards Compatibility</title><keywordset><keyword>ISO C++</keyword><keyword>backwards</keyword></keywordset></info><section xml:id="backwards.first"><info><title>First</title></info><para>The first generation GNU C++ library was called libg++.  It was a
separate GNU project, although reliably paired with GCC. Rumors imply
that it had a working relationship with at least two kinds of
dinosaur.
</para><para>Some background: libg++ was designed and created when there was no
ISO standard to provide guidance.  Classes like linked lists are now
provided for by <classname>std::list&lt;T&gt;</classname> and do not need to be
created by <function>genclass</function>.  (For that matter, templates exist
now and are well-supported, whereas genclass (mostly) predates them.)
</para><para>There are other classes in libg++ that are not specified in the
ISO Standard (e.g., statistical analysis).  While there are a lot of
really useful things that are used by a lot of people, the Standards
Committee couldn't include everything, and so a lot of those
<quote>obvious</quote> classes didn't get included.
</para><para>That project is no longer maintained or supported, and the sources
archived. For the desperate, the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://ftp.gnu.org/old-gnu/libg++/">ftp.gnu.org</link>
server still has the libg++ source.
</para></section><section xml:id="backwards.second"><info><title>Second</title></info><para>
  The second generation GNU C++ library was called libstdc++, or
  libstdc++-v2. It spans the time between libg++ and pre-ISO C++
  standardization and is usually associated with the following GCC
  releases: egcs 1.x, gcc 2.95, and gcc 2.96.
</para><para>
  The STL portions of that library are based on SGI/HP STL release 3.11.
</para><para>
  That project is no longer maintained or supported, and the sources
  archived.  The code was replaced and rewritten for libstdc++-v3.
</para></section><section xml:id="backwards.third"><info><title>Third</title></info><para> The third generation GNU C++ library is called libstdc++, or
libstdc++-v3.
</para><para>The subset commonly known as the Standard Template Library
	 (clauses 23 through 25 in C++98, mostly) is adapted from the final release
	 of the SGI STL (version 3.3), with extensive changes.
      </para><para>A more formal description of the V3 goals can be found in the
	 official <link linkend="contrib.design_notes">design document</link>.
      </para><para>Portability notes and known implementation limitations are as follows.</para><section xml:id="backwards.third.headers"><info><title>Pre-ISO headers removed</title></info><para> The pre-ISO C++ headers
      (<filename class="headerfile">&lt;iostream.h&gt;</filename>,
      <filename class="headerfile">&lt;defalloc.h&gt;</filename> etc.) are
      not supported.
</para><para>For those of you new to ISO C++ (welcome, time travelers!), the
      ancient pre-ISO headers have new names.
      The C++ FAQ has a good explanation in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://isocpp.org/wiki/faq/coding-standards#std-headers">What's
      the difference between &lt;xxx&gt; and &lt;xxx.h&gt; headers?</link>.
   </para><para>Porting between pre-ISO headers and ISO headers is simple: headers
like <filename class="headerfile">&lt;vector.h&gt;</filename> can be replaced with <filename class="headerfile">&lt;vector&gt;</filename> and a using
directive <code>using namespace std;</code> can be put at the global
scope. This should be enough to get this code compiling, assuming the
other usage is correct.
</para></section><section xml:id="backwards.third.hash"><info><title>Extension headers hash_map, hash_set moved to ext or backwards</title></info><para>At this time most of the features of the SGI STL extension have been
	 replaced by standardized libraries.
	 In particular, the <classname>unordered_map</classname> and
	 <classname>unordered_set</classname> containers of TR1 and C++ 2011
	 are suitable replacements for the non-standard
	 <classname>hash_map</classname> and <classname>hash_set</classname>
	 containers in the SGI STL.
      </para><para> Header files <filename class="headerfile">&lt;hash_map&gt;</filename> and <filename class="headerfile">&lt;hash_set&gt;</filename> moved
to <filename class="headerfile">&lt;ext/hash_map&gt;</filename> and  <filename class="headerfile">&lt;ext/hash_set&gt;</filename>,
respectively. At the same time, all types in these files are enclosed
in <code>namespace __gnu_cxx</code>. Later versions deprecate
these files, and suggest using TR1's  <filename class="headerfile">&lt;unordered_map&gt;</filename>
and  <filename class="headerfile">&lt;unordered_set&gt;</filename> instead.
</para><para>The extensions are no longer in the global or <code>std</code>
	 namespaces, instead they are declared in the <code>__gnu_cxx</code>
	 namespace. For maximum portability, consider defining a namespace
	 alias to use to talk about extensions, e.g.:
      </para><programlisting>
      #ifdef __GNUC__
      #if __GNUC__ &lt; 3
	#include &lt;hash_map.h&gt;
	namespace extension { using ::hash_map; }; // inherit globals
      #else
	#include &lt;backward/hash_map&gt;
	#if __GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ == 0
	  namespace extension = std;               // GCC 3.0
	#else
	  namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
	#endif
      #endif
      #else      // ...  there are other compilers, right?
	namespace extension = std;
      #endif

      extension::hash_map&lt;int,int&gt; my_map;
</programlisting><para>This is a bit cleaner than defining typedefs for all the
	 instantiations you might need.
      </para><para>The following autoconf tests check for working HP/SGI hash containers.
</para><programlisting>
# AC_HEADER_EXT_HASH_MAP
AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [
  AC_CACHE_CHECK(for ext/hash_map,
  ac_cv_cxx_ext_hash_map,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -Werror"
  AC_TRY_COMPILE([#include &lt;ext/hash_map&gt;], [using __gnu_cxx::hash_map;],
  ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_ext_hash_map" = yes; then
    AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ])
  fi
])
</programlisting><programlisting>
# AC_HEADER_EXT_HASH_SET
AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
  AC_CACHE_CHECK(for ext/hash_set,
  ac_cv_cxx_ext_hash_set,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -Werror"
  AC_TRY_COMPILE([#include &lt;ext/hash_set&gt;], [using __gnu_cxx::hash_set;],
  ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_ext_hash_set" = yes; then
    AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ])
  fi
])
</programlisting></section><section xml:id="backwards.third.nocreate_noreplace"><info><title>No <code>ios::nocreate/ios::noreplace</code>.
</title></info><para>Historically these flags were used with iostreams to control whether
new files are created or not when opening a file stream, similar to the
<code>O_CREAT</code> and <code>O_EXCL</code> flags for the
<function>open(2)</function> system call. Because iostream modes correspond
to <function>fopen(3)</function> modes these flags are not supported.
For input streams a new file will not be created anyway, so
<code>ios::nocreate</code> is not needed.
For output streams, a new file will be created if it does not exist, which is
consistent with the behaviour of <function>fopen</function>.
</para><para>When one of these flags is needed a possible alternative is to attempt
to open the file using <type>std::ifstream</type> first to determine whether
the file already exists or not. This may not be reliable however, because
whether the file exists or not could change between opening the
<type>std::istream</type> and re-opening with an output stream. If you need
to check for existence and open a file as a single operation then you will
need to use OS-specific facilities outside the C++ standard library, such
as <function>open(2)</function>.
</para></section><section xml:id="backwards.third.streamattach"><info><title>
No <code>stream::attach(int fd)</code>
</title></info><para>
      Phil Edwards writes: It was considered and rejected for the ISO
      standard.  Not all environments use file descriptors.  Of those
      that do, not all of them use integers to represent them.
    </para><para>
      For a portable solution (among systems which use
      file descriptors), you need to implement a subclass of
      <code>std::streambuf</code> (or
      <code>std::basic_streambuf&lt;..&gt;</code>) which opens a file
      given a descriptor, and then pass an instance of this to the
      stream-constructor.
    </para><para>
      An extension is available that implements this.
      <filename class="headerfile">&lt;ext/stdio_filebuf.h&gt;</filename>
      contains a derived class called
      <classname>__gnu_cxx::stdio_filebuf</classname>.
      This class can be constructed from a C <code>FILE*</code> or a file
      descriptor, and provides the <code>fd()</code> function.
    </para><para>
 For another example of this, refer to
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</link>
      by Nicolai Josuttis.
</para></section><section xml:id="backwards.third.support_cxx98"><info><title>
Support for C++98 dialect.
</title></info><para>Check for complete library coverage of the C++1998/2003 standard.
</para><programlisting>
# AC_HEADER_STDCXX_98
AC_DEFUN([AC_HEADER_STDCXX_98], [
  AC_CACHE_CHECK(for ISO C++ 98 include files,
  ac_cv_cxx_stdcxx_98,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  AC_TRY_COMPILE([
    #include &lt;cassert&gt;
    #include &lt;cctype&gt;
    #include &lt;cerrno&gt;
    #include &lt;cfloat&gt;
    #include &lt;ciso646&gt;
    #include &lt;climits&gt;
    #include &lt;clocale&gt;
    #include &lt;cmath&gt;
    #include &lt;csetjmp&gt;
    #include &lt;csignal&gt;
    #include &lt;cstdarg&gt;
    #include &lt;cstddef&gt;
    #include &lt;cstdio&gt;
    #include &lt;cstdlib&gt;
    #include &lt;cstring&gt;
    #include &lt;ctime&gt;

    #include &lt;algorithm&gt;
    #include &lt;bitset&gt;
    #include &lt;complex&gt;
    #include &lt;deque&gt;
    #include &lt;exception&gt;
    #include &lt;fstream&gt;
    #include &lt;functional&gt;
    #include &lt;iomanip&gt;
    #include &lt;ios&gt;
    #include &lt;iosfwd&gt;
    #include &lt;iostream&gt;
    #include &lt;istream&gt;
    #include &lt;iterator&gt;
    #include &lt;limits&gt;
    #include &lt;list&gt;
    #include &lt;locale&gt;
    #include &lt;map&gt;
    #include &lt;memory&gt;
    #include &lt;new&gt;
    #include &lt;numeric&gt;
    #include &lt;ostream&gt;
    #include &lt;queue&gt;
    #include &lt;set&gt;
    #include &lt;sstream&gt;
    #include &lt;stack&gt;
    #include &lt;stdexcept&gt;
    #include &lt;streambuf&gt;
    #include &lt;string&gt;
    #include &lt;typeinfo&gt;
    #include &lt;utility&gt;
    #include &lt;valarray&gt;
    #include &lt;vector&gt;
  ],,
  ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no)
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_stdcxx_98" = yes; then
    AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
  fi
])
</programlisting></section><section xml:id="backwards.third.support_tr1"><info><title>
Support for C++TR1 dialect.
</title></info><para>Check for library coverage of the TR1 standard.
</para><programlisting>
# AC_HEADER_STDCXX_TR1
AC_DEFUN([AC_HEADER_STDCXX_TR1], [
  AC_CACHE_CHECK(for ISO C++ TR1 include files,
  ac_cv_cxx_stdcxx_tr1,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  AC_TRY_COMPILE([
  #include &lt;tr1/array&gt;
  #include &lt;tr1/ccomplex&gt;
  #include &lt;tr1/cctype&gt;
  #include &lt;tr1/cfenv&gt;
  #include &lt;tr1/cfloat&gt;
  #include &lt;tr1/cinttypes&gt;
  #include &lt;tr1/climits&gt;
  #include &lt;tr1/cmath&gt;
  #include &lt;tr1/complex&gt;
  #include &lt;tr1/cstdarg&gt;
  #include &lt;tr1/cstdbool&gt;
  #include &lt;tr1/cstdint&gt;
  #include &lt;tr1/cstdio&gt;
  #include &lt;tr1/cstdlib&gt;
  #include &lt;tr1/ctgmath&gt;
  #include &lt;tr1/ctime&gt;
  #include &lt;tr1/cwchar&gt;
  #include &lt;tr1/cwctype&gt;
  #include &lt;tr1/functional&gt;
  #include &lt;tr1/memory&gt;
  #include &lt;tr1/random&gt;
  #include &lt;tr1/regex&gt;
  #include &lt;tr1/tuple&gt;
  #include &lt;tr1/type_traits&gt;
  #include &lt;tr1/unordered_set&gt;
  #include &lt;tr1/unordered_map&gt;
  #include &lt;tr1/utility&gt;
  ],,
  ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no)
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_stdcxx_tr1" = yes; then
    AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ])
  fi
])
</programlisting><para>An alternative is to check just for specific TR1 includes, such as &lt;unordered_map&gt; and &lt;unordered_set&gt;.
</para><programlisting>
# AC_HEADER_TR1_UNORDERED_MAP
AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [
  AC_CACHE_CHECK(for tr1/unordered_map,
  ac_cv_cxx_tr1_unordered_map,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  AC_TRY_COMPILE([#include &lt;tr1/unordered_map&gt;], [using std::tr1::unordered_map;],
  ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no)
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_tr1_unordered_map" = yes; then
    AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ])
  fi
])
</programlisting><programlisting>
# AC_HEADER_TR1_UNORDERED_SET
AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
  AC_CACHE_CHECK(for tr1/unordered_set,
  ac_cv_cxx_tr1_unordered_set,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  AC_TRY_COMPILE([#include &lt;tr1/unordered_set&gt;], [using std::tr1::unordered_set;],
  ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no)
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_tr1_unordered_set" = yes; then
    AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
  fi
])
</programlisting></section><section xml:id="backwards.third.support_cxx11"><info><title>
Support for C++11 dialect.
</title></info><para>Check for baseline language coverage in the compiler for the C++11 standard.
</para><programlisting>
# AC_COMPILE_STDCXX_11
AC_DEFUN([AC_COMPILE_STDCXX_11], [
  AC_CACHE_CHECK(if g++ supports C++11 features without additional flags,
  ac_cv_cxx_compile_cxx11_native,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  AC_TRY_COMPILE([
  template &lt;typename T&gt;
    struct check final
    {
      static constexpr T value{ __cplusplus };
    };

    typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;

    int a;
    decltype(a) b;

    typedef check&lt;int&gt; check_type;
    check_type c{};
    check_type&amp;&amp; cr = static_cast&lt;check_type&amp;&amp;&gt;(c);

    static_assert(check_type::value == 201103L, "C++11 compiler");],,
  ac_cv_cxx_compile_cxx11_native=yes, ac_cv_cxx_compile_cxx11_native=no)
  AC_LANG_RESTORE
  ])

  AC_CACHE_CHECK(if g++ supports C++11 features with -std=c++11,
  ac_cv_cxx_compile_cxx11_cxx,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -std=c++11"
  AC_TRY_COMPILE([
  template &lt;typename T&gt;
    struct check final
    {
      static constexpr T value{ __cplusplus };
    };

    typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;

    int a;
    decltype(a) b;

    typedef check&lt;int&gt; check_type;
    check_type c{};
    check_type&amp;&amp; cr = static_cast&lt;check_type&amp;&amp;&gt;(c);

    static_assert(check_type::value == 201103L, "C++11 compiler");],,
  ac_cv_cxx_compile_cxx11_cxx=yes, ac_cv_cxx_compile_cxx11_cxx=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])

  AC_CACHE_CHECK(if g++ supports C++11 features with -std=gnu++11,
  ac_cv_cxx_compile_cxx11_gxx,
  [AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -std=gnu++11"
  AC_TRY_COMPILE([
  template &lt;typename T&gt;
    struct check final
    {
      static constexpr T value{ __cplusplus };
    };

    typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;

    int a;
    decltype(a) b;

    typedef check&lt;int&gt; check_type;
    check_type c{};
    check_type&amp;&amp; cr = static_cast&lt;check_type&amp;&amp;&gt;(c);

    static_assert(check_type::value == 201103L, "C++11 compiler");],,
  ac_cv_cxx_compile_cxx11_gxx=yes, ac_cv_cxx_compile_cxx11_gxx=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])

  if test "$ac_cv_cxx_compile_cxx11_native" = yes ||
     test "$ac_cv_cxx_compile_cxx11_cxx" = yes ||
     test "$ac_cv_cxx_compile_cxx11_gxx" = yes; then
    AC_DEFINE(HAVE_STDCXX_11,,[Define if g++ supports C++11 features. ])
  fi
])
</programlisting><para>Check for library coverage of the C++2011 standard.
  (Some library headers are commented out in this check, they are
  not currently provided by libstdc++).
</para><programlisting>
# AC_HEADER_STDCXX_11
AC_DEFUN([AC_HEADER_STDCXX_11], [
  AC_CACHE_CHECK(for ISO C++11 include files,
  ac_cv_cxx_stdcxx_11,
  [AC_REQUIRE([AC_COMPILE_STDCXX_11])
  AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -std=gnu++11"

  AC_TRY_COMPILE([
    #include &lt;cassert&gt;
    #include &lt;ccomplex&gt;
    #include &lt;cctype&gt;
    #include &lt;cerrno&gt;
    #include &lt;cfenv&gt;
    #include &lt;cfloat&gt;
    #include &lt;cinttypes&gt;
    #include &lt;ciso646&gt;
    #include &lt;climits&gt;
    #include &lt;clocale&gt;
    #include &lt;cmath&gt;
    #include &lt;csetjmp&gt;
    #include &lt;csignal&gt;
    #include &lt;cstdalign&gt;
    #include &lt;cstdarg&gt;
    #include &lt;cstdbool&gt;
    #include &lt;cstddef&gt;
    #include &lt;cstdint&gt;
    #include &lt;cstdio&gt;
    #include &lt;cstdlib&gt;
    #include &lt;cstring&gt;
    #include &lt;ctgmath&gt;
    #include &lt;ctime&gt;
    // #include &lt;cuchar&gt;
    #include &lt;cwchar&gt;
    #include &lt;cwctype&gt;

    #include &lt;algorithm&gt;
    #include &lt;array&gt;
    #include &lt;atomic&gt;
    #include &lt;bitset&gt;
    #include &lt;chrono&gt;
    // #include &lt;codecvt&gt;
    #include &lt;complex&gt;
    #include &lt;condition_variable&gt;
    #include &lt;deque&gt;
    #include &lt;exception&gt;
    #include &lt;forward_list&gt;
    #include &lt;fstream&gt;
    #include &lt;functional&gt;
    #include &lt;future&gt;
    #include &lt;initializer_list&gt;
    #include &lt;iomanip&gt;
    #include &lt;ios&gt;
    #include &lt;iosfwd&gt;
    #include &lt;iostream&gt;
    #include &lt;istream&gt;
    #include &lt;iterator&gt;
    #include &lt;limits&gt;
    #include &lt;list&gt;
    #include &lt;locale&gt;
    #include &lt;map&gt;
    #include &lt;memory&gt;
    #include &lt;mutex&gt;
    #include &lt;new&gt;
    #include &lt;numeric&gt;
    #include &lt;ostream&gt;
    #include &lt;queue&gt;
    #include &lt;random&gt;
    #include &lt;ratio&gt;
    #include &lt;regex&gt;
    #include &lt;scoped_allocator&gt;
    #include &lt;set&gt;
    #include &lt;sstream&gt;
    #include &lt;stack&gt;
    #include &lt;stdexcept&gt;
    #include &lt;streambuf&gt;
    #include &lt;string&gt;
    #include &lt;system_error&gt;
    #include &lt;thread&gt;
    #include &lt;tuple&gt;
    #include &lt;typeindex&gt;
    #include &lt;typeinfo&gt;
    #include &lt;type_traits&gt;
    #include &lt;unordered_map&gt;
    #include &lt;unordered_set&gt;
    #include &lt;utility&gt;
    #include &lt;valarray&gt;
    #include &lt;vector&gt;
  ],,
  ac_cv_cxx_stdcxx_11=yes, ac_cv_cxx_stdcxx_11=no)
  AC_LANG_RESTORE
  CXXFLAGS="$ac_save_CXXFLAGS"
  ])
  if test "$ac_cv_cxx_stdcxx_11" = yes; then
    AC_DEFINE(STDCXX_11_HEADERS,,[Define if ISO C++11 header files are present. ])
  fi
])
</programlisting><para>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For
<filename class="headerfile">&lt;unordered_map&gt;</filename>
</para><programlisting>
# AC_HEADER_UNORDERED_MAP
AC_DEFUN([AC_HEADER_UNORDERED_MAP], [
  AC_CACHE_CHECK(for unordered_map,
  ac_cv_cxx_unordered_map,
  [AC_REQUIRE([AC_COMPILE_STDCXX_11])
  AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -std=gnu++11"
  AC_TRY_COMPILE([#include &lt;unordered_map&gt;], [using std::unordered_map;],
  ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_unordered_map" = yes; then
    AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ])
  fi
])
</programlisting><programlisting>
# AC_HEADER_UNORDERED_SET
AC_DEFUN([AC_HEADER_UNORDERED_SET], [
  AC_CACHE_CHECK(for unordered_set,
  ac_cv_cxx_unordered_set,
  [AC_REQUIRE([AC_COMPILE_STDCXX_11])
  AC_LANG_SAVE
  AC_LANG_CPLUSPLUS
  ac_save_CXXFLAGS="$CXXFLAGS"
  CXXFLAGS="$CXXFLAGS -std=gnu++11"
  AC_TRY_COMPILE([#include &lt;unordered_set&gt;], [using std::unordered_set;],
  ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no)
  CXXFLAGS="$ac_save_CXXFLAGS"
  AC_LANG_RESTORE
  ])
  if test "$ac_cv_cxx_unordered_set" = yes; then
    AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
  fi
])
</programlisting><para>
  Some C++11 features first appeared in GCC 4.3 and could be enabled by
  <option>-std=c++0x</option> and <option>-std=gnu++0x</option> for GCC
  releases which pre-date the 2011 standard. Those C++11 features and GCC's
  support for them were still changing until the 2011 standard was finished,
  but the autoconf checks above could be extended to test for incomplete
  C++11 support with <option>-std=c++0x</option> and
  <option>-std=gnu++0x</option>.
</para></section><section xml:id="backwards.third.iterator_type"><info><title><code>Container::iterator_type</code> is not necessarily <code>Container::value_type*</code>
</title></info><para>
  This is a change in behavior from older versions. Now, most
  <type>iterator_type</type> typedefs in container classes are POD
  objects, not <type>value_type</type> pointers.
</para></section></section></section></appendix><!-- Appendix C --><appendix version="5.0" xreflabel="Free" xml:id="appendix.free"><?dbhtml filename="appendix_free.html"?><info><title>
  Free Software Needs Free Documentation
  <indexterm><primary>Appendix</primary><secondary>Free Documentation</secondary></indexterm>
</title><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></info><para>
The biggest deficiency in free operating systems is not in the
software--it is the lack of good free manuals that we can include in
these systems.  Many of our most important programs do not come with
full manuals.  Documentation is an essential part of any software
package; when an important free software package does not come with a
free manual, that is a major gap.  We have many such gaps today.
</para><para>
Once upon a time, many years ago, I thought I would learn Perl.  I got
a copy of a free manual, but I found it hard to read.  When I asked
Perl users about alternatives, they told me that there were better
introductory manuals--but those were not free.
</para><para>
Why was this?  The authors of the good manuals had written them for
O'Reilly Associates, which published them with restrictive terms--no
copying, no modification, source files not available--which exclude
them from the free software community.
</para><para>
That wasn't the first time this sort of thing has happened, and (to
our community's great loss) it was far from the last.  Proprietary
manual publishers have enticed a great many authors to restrict their
manuals since then.  Many times I have heard a GNU user eagerly tell
me about a manual that he is writing, with which he expects to help
the GNU project--and then had my hopes dashed, as he proceeded to
explain that he had signed a contract with a publisher that would
restrict it so that we cannot use it.
</para><para>
Given that writing good English is a rare skill among programmers, we
can ill afford to lose manuals this way.
</para><para>
  Free documentation, like free software, is a matter of freedom,
not price.  The problem with these manuals was not that O'Reilly
Associates charged a price for printed copies--that in itself is fine.
(The Free Software Foundation <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/doc/doc.html">sells printed copies</link> of
free GNU manuals, too.)  But GNU manuals are available in source code
form, while these manuals are available only on paper.  GNU manuals
come with permission to copy and modify; the Perl manuals do not.
These restrictions are the problems.
</para><para>
The criterion for a free manual is pretty much the same as for free
software: it is a matter of giving all users certain freedoms.
Redistribution (including commercial redistribution) must be
permitted, so that the manual can accompany every copy of the program,
on-line or on paper.  Permission for modification is crucial too.
</para><para>
As a general rule, I don't believe that it is essential for people to
have permission to modify all sorts of articles and books.  The issues
for writings are not necessarily the same as those for software.  For
example, I don't think you or I are obliged to give permission to
modify articles like this one, which describe our actions and our
views.
</para><para>
But there is a particular reason why the freedom to modify is crucial
for documentation for free software.  When people exercise their right
to modify the software, and add or change its features, if they are
conscientious they will change the manual too--so they can provide
accurate and usable documentation with the modified program.  A manual
which forbids programmers to be conscientious and finish the job, or
more precisely requires them to write a new manual from scratch if
they change the program, does not fill our community's needs.
</para><para>
While a blanket prohibition on modification is unacceptable, some
kinds of limits on the method of modification pose no problem.  For
example, requirements to preserve the original author's copyright
notice, the distribution terms, or the list of authors, are ok.  It is
also no problem to require modified versions to include notice that
they were modified, even to have entire sections that may not be
deleted or changed, as long as these sections deal with nontechnical
topics.  (Some GNU manuals have them.)
</para><para>
These kinds of restrictions are not a problem because, as a practical
matter, they don't stop the conscientious programmer from adapting the
manual to fit the modified program.  In other words, they don't block
the free software community from making full use of the manual.
</para><para>
However, it must be possible to modify all the <emphasis>technical</emphasis>
content of the manual, and then distribute the result in all the usual
media, through all the usual channels; otherwise, the restrictions do
block the community, the manual is not free, and so we need another
manual.
</para><para>
Unfortunately, it is often hard to find someone to write another
manual when a proprietary manual exists.  The obstacle is that many
users think that a proprietary manual is good enough--so they don't
see the need to write a free manual.  They do not see that the free
operating system has a gap that needs filling.
</para><para>
Why do users think that proprietary manuals are good enough?  Some
have not considered the issue.  I hope this article will do something
to change that.
</para><para>
Other users consider proprietary manuals acceptable for the same
reason so many people consider proprietary software acceptable: they
judge in purely practical terms, not using freedom as a criterion.
These people are entitled to their opinions, but since those opinions
spring from values which do not include freedom, they are no guide for
those of us who do value freedom.
</para><para>
Please spread the word about this issue.  We continue to lose manuals
to proprietary publishing.  If we spread the word that proprietary
manuals are not sufficient, perhaps the next person who wants to help
GNU by writing documentation will realize, before it is too late, that
he must above all make it free.
</para><para>
We can also encourage commercial publishers to sell free, copylefted
manuals instead of proprietary ones.  One way you can help this is to
check the distribution terms of a manual before you buy it, and
prefer copylefted manuals to non-copylefted ones.
</para><para>
[Note: We now maintain a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/doc/other-free-books.html">web page
that lists free books available from other publishers</link>].
</para><para>Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA</para><para>Verbatim copying and distribution of this entire article are
permitted worldwide, without royalty, in any medium, provided this
notice is preserved.</para><para>Report any problems or suggestions to <email>webmaster@fsf.org</email>.</para></appendix><!-- Appendix D --><appendix version="5.0" xml:base="../gnu/gpl-3.0.xml" xml:id="appendix.gpl-3.0"><info><title><acronym>GNU</acronym> General Public License version 3
  </title></info><?dbhtml filename="appendix_gpl.html"?><para>
    Version 3, 29 June 2007
  </para><para>
    Copyright © 2007 Free Software Foundation, Inc.
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.fsf.org">https://www.fsf.org</link>
  </para><para>
    Everyone is permitted to copy and distribute verbatim copies of this license
    document, but changing it is not allowed.
  </para><bridgehead renderas="sect1" xml:id="gpl-3-preamble">
    Preamble
  </bridgehead><para>
    The <acronym>GNU</acronym> General Public License is a free, copyleft
    license for software and other kinds of works.
  </para><para>
    The licenses for most software and other practical works are designed to
    take away your freedom to share and change the works.  By contrast, the
    <acronym>GNU</acronym> General Public License is intended to guarantee your
    freedom to share and change all versions of a program—to make sure it
    remains free software for all its users.  We, the Free Software Foundation,
    use the <acronym>GNU</acronym> General Public License for most of our
    software; it applies also to any other work released this way by its
    authors.  You can apply it to your programs, too.
  </para><para>
    When we speak of free software, we are referring to freedom, not price.  Our
    General Public Licenses are designed to make sure that you have the freedom
    to distribute copies of free software (and charge for them if you wish),
    that you receive source code or can get it if you want it, that you can
    change the software or use pieces of it in new free programs, and that you
    know you can do these things.
  </para><para>
    To protect your rights, we need to prevent others from denying you these
    rights or asking you to surrender the rights.  Therefore, you have certain
    responsibilities if you distribute copies of the software, or if you modify
    it: responsibilities to respect the freedom of others.
  </para><para>
    For example, if you distribute copies of such a program, whether gratis or
    for a fee, you must pass on to the recipients the same freedoms that you
    received.  You must make sure that they, too, receive or can get the source
    code.  And you must show them these terms so they know their rights.
  </para><para>
    Developers that use the <acronym>GNU</acronym> <acronym>GPL</acronym>
    protect your rights with two steps: (1) assert copyright on the software,
    and (2) offer you this License giving you legal permission to copy,
    distribute and/or modify it.
  </para><para>
    For the developers’ and authors’ protection, the
    <acronym>GPL</acronym> clearly explains that there is no warranty for this
    free software.  For both users’ and authors’ sake, the
    <acronym>GPL</acronym> requires that modified versions be marked as changed,
    so that their problems will not be attributed erroneously to authors of
    previous versions.
  </para><para>
    Some devices are designed to deny users access to install or run modified
    versions of the software inside them, although the manufacturer can do so.
    This is fundamentally incompatible with the aim of protecting users’
    freedom to change the software.  The systematic pattern of such abuse occurs
    in the area of products for individuals to use, which is precisely where it
    is most unacceptable.  Therefore, we have designed this version of the
    <acronym>GPL</acronym> to prohibit the practice for those products.  If such
    problems arise substantially in other domains, we stand ready to extend this
    provision to those domains in future versions of the <acronym>GPL</acronym>,
    as needed to protect the freedom of users.
  </para><para>
    Finally, every program is threatened constantly by software patents.  States
    should not allow patents to restrict development and use of software on
    general-purpose computers, but in those that do, we wish to avoid the
    special danger that patents applied to a free program could make it
    effectively proprietary.  To prevent this, the <acronym>GPL</acronym>
    assures that patents cannot be used to render the program non-free.
  </para><para>
    The precise terms and conditions for copying, distribution and modification
    follow.
  </para><bridgehead>
    TERMS AND CONDITIONS
  </bridgehead><bridgehead renderas="sect1" xml:id="gpl-3-definitions">
    0. Definitions.
  </bridgehead><para>
    “This License” refers to version 3 of the <acronym>GNU</acronym>
    General Public License.
  </para><para>
    “Copyright” also means copyright-like laws that apply to other
    kinds of works, such as semiconductor masks.
  </para><para>
    “The Program” refers to any copyrightable work licensed under
    this License.  Each licensee is addressed as “you”.
    “Licensees” and “recipients” may be individuals or
    organizations.
  </para><para>
    To “modify” a work means to copy from or adapt all or part of
    the work in a fashion requiring copyright permission, other than the making
    of an exact copy.  The resulting work is called a “modified
    version” of the earlier work or a work “based on” the
    earlier work.
  </para><para>
    A “covered work” means either the unmodified Program or a work
    based on the Program.
  </para><para>
    To “propagate” a work means to do anything with it that, without
    permission, would make you directly or secondarily liable for infringement
    under applicable copyright law, except executing it on a computer or
    modifying a private copy.  Propagation includes copying, distribution (with
    or without modification), making available to the public, and in some
    countries other activities as well.
  </para><para>
    To “convey” a work means any kind of propagation that enables
    other parties to make or receive copies.  Mere interaction with a user
    through a computer network, with no transfer of a copy, is not conveying.
  </para><para>
    An interactive user interface displays “Appropriate Legal
    Notices” to the extent that it includes a convenient and prominently
    visible feature that (1) displays an appropriate copyright notice, and (2)
    tells the user that there is no warranty for the work (except to the extent
    that warranties are provided), that licensees may convey the work under this
    License, and how to view a copy of this License.  If the interface presents
    a list of user commands or options, such as a menu, a prominent item in the
    list meets this criterion.
  </para><bridgehead renderas="sect1" xml:id="SourceCode">
    1. Source Code.
  </bridgehead><para>
    The “source code” for a work means the preferred form of the
    work for making modifications to it.  “Object code” means any
    non-source form of a work.
  </para><para>
    A “Standard Interface” means an interface that either is an
    official standard defined by a recognized standards body, or, in the case of
    interfaces specified for a particular programming language, one that is
    widely used among developers working in that language.
  </para><para>
    The “System Libraries” of an executable work include anything,
    other than the work as a whole, that (a) is included in the normal form of
    packaging a Major Component, but which is not part of that Major Component,
    and (b) serves only to enable use of the work with that Major Component, or
    to implement a Standard Interface for which an implementation is available
    to the public in source code form.  A “Major Component”, in this
    context, means a major essential component (kernel, window system, and so
    on) of the specific operating system (if any) on which the executable work
    runs, or a compiler used to produce the work, or an object code interpreter
    used to run it.
  </para><para>
    The “Corresponding Source” for a work in object code form means
    all the source code needed to generate, install, and (for an executable
    work) run the object code and to modify the work, including scripts to
    control those activities.  However, it does not include the work’s
    System Libraries, or general-purpose tools or generally available free
    programs which are used unmodified in performing those activities but which
    are not part of the work.  For example, Corresponding Source includes
    interface definition files associated with source files for the work, and
    the source code for shared libraries and dynamically linked subprograms that
    the work is specifically designed to require, such as by intimate data
    communication or control flow between those subprograms and other parts of
    the work.
  </para><para>
    The Corresponding Source need not include anything that users can regenerate
    automatically from other parts of the Corresponding Source.
  </para><para>
    The Corresponding Source for a work in source code form is that same work.
  </para><bridgehead renderas="sect1" xml:id="BasicPermissions">
    2. Basic Permissions.
  </bridgehead><para>
    All rights granted under this License are granted for the term of copyright
    on the Program, and are irrevocable provided the stated conditions are met.
    This License explicitly affirms your unlimited permission to run the
    unmodified Program.  The output from running a covered work is covered by
    this License only if the output, given its content, constitutes a covered
    work.  This License acknowledges your rights of fair use or other
    equivalent, as provided by copyright law.
  </para><para>
    You may make, run and propagate covered works that you do not convey,
    without conditions so long as your license otherwise remains in force.  You
    may convey covered works to others for the sole purpose of having them make
    modifications exclusively for you, or provide you with facilities for
    running those works, provided that you comply with the terms of this License
    in conveying all material for which you do not control copyright.  Those
    thus making or running the covered works for you must do so exclusively on
    your behalf, under your direction and control, on terms that prohibit them
    from making any copies of your copyrighted material outside their
    relationship with you.
  </para><para>
    Conveying under any other circumstances is permitted solely under the
    conditions stated below.  Sublicensing is not allowed; section 10 makes it
    unnecessary.
  </para><bridgehead renderas="sect1" xml:id="Protecting">
    3. Protecting Users’ Legal Rights From Anti-Circumvention Law.
  </bridgehead><para>
    No covered work shall be deemed part of an effective technological measure
    under any applicable law fulfilling obligations under article 11 of the WIPO
    copyright treaty adopted on 20 December 1996, or similar laws prohibiting or
    restricting circumvention of such measures.
  </para><para>
    When you convey a covered work, you waive any legal power to forbid
    circumvention of technological measures to the extent such circumvention is
    effected by exercising rights under this License with respect to the covered
    work, and you disclaim any intention to limit operation or modification of
    the work as a means of enforcing, against the work’s users, your or
    third parties’ legal rights to forbid circumvention of technological
    measures.
  </para><bridgehead renderas="sect1" xml:id="ConveyingVerbatim">
    4. Conveying Verbatim Copies.
  </bridgehead><para>
    You may convey verbatim copies of the Program’s source code as you
    receive it, in any medium, provided that you conspicuously and appropriately
    publish on each copy an appropriate copyright notice; keep intact all
    notices stating that this License and any non-permissive terms added in
    accord with section 7 apply to the code; keep intact all notices of the
    absence of any warranty; and give all recipients a copy of this License
    along with the Program.
  </para><para>
    You may charge any price or no price for each copy that you convey, and you
    may offer support or warranty protection for a fee.
  </para><bridgehead renderas="sect1" xml:id="ConveyingModified">
    5. Conveying Modified Source Versions.
  </bridgehead><para>
    You may convey a work based on the Program, or the modifications to produce
    it from the Program, in the form of source code under the terms of section
    4, provided that you also meet all of these conditions:
  </para><orderedlist continuation="restarts" inheritnum="ignore" numeration="loweralpha"><listitem><para>
        The work must carry prominent notices stating that you modified it, and
        giving a relevant date.
      </para></listitem><listitem><para>
        The work must carry prominent notices stating that it is released under
        this License and any conditions added under section 7.  This requirement
        modifies the requirement in section 4 to “keep intact all
        notices”.
      </para></listitem><listitem><para>
        You must license the entire work, as a whole, under this License to
        anyone who comes into possession of a copy.  This License will therefore
        apply, along with any applicable section 7 additional terms, to the
        whole of the work, and all its parts, regardless of how they are
        packaged.  This License gives no permission to license the work in any
        other way, but it does not invalidate such permission if you have
        separately received it.
      </para></listitem><listitem><para>
        If the work has interactive user interfaces, each must display
        Appropriate Legal Notices; however, if the Program has interactive
        interfaces that do not display Appropriate Legal Notices, your work need
        not make them do so.
      </para></listitem></orderedlist><para>
    A compilation of a covered work with other separate and independent works,
    which are not by their nature extensions of the covered work, and which are
    not combined with it such as to form a larger program, in or on a volume of
    a storage or distribution medium, is called an “aggregate” if
    the compilation and its resulting copyright are not used to limit the access
    or legal rights of the compilation’s users beyond what the individual works
    permit.  Inclusion of a covered work in an aggregate does not cause
    this License to apply to the other parts of the aggregate.
  </para><bridgehead renderas="sect1" xml:id="ConveyingNonSource">
    6. Conveying Non-Source Forms.
  </bridgehead><para>
    You may convey a covered work in object code form under the terms of
    sections 4 and 5, provided that you also convey the machine-readable
    Corresponding Source under the terms of this License, in one of these ways:
  </para><orderedlist continuation="restarts" inheritnum="ignore" numeration="loweralpha"><listitem><para>
        Convey the object code in, or embodied in, a physical product (including
        a physical distribution medium), accompanied by the Corresponding Source
        fixed on a durable physical medium customarily used for software
        interchange.
      </para></listitem><listitem><para>
        Convey the object code in, or embodied in, a physical product (including
        a physical distribution medium), accompanied by a written offer, valid
        for at least three years and valid for as long as you offer spare parts
        or customer support for that product model, to give anyone who possesses
        the object code either (1) a copy of the Corresponding Source for all
        the software in the product that is covered by this License, on a
        durable physical medium customarily used for software interchange, for a
        price no more than your reasonable cost of physically performing this
        conveying of source, or (2) access to copy the Corresponding Source from
        a network server at no charge.
      </para></listitem><listitem><para>
        Convey individual copies of the object code with a copy of the written
        offer to provide the Corresponding Source.  This alternative is allowed
        only occasionally and noncommercially, and only if you received the
        object code with such an offer, in accord with subsection 6b.
      </para></listitem><listitem><para>
        Convey the object code by offering access from a designated place
        (gratis or for a charge), and offer equivalent access to the
        Corresponding Source in the same way through the same place at no
        further charge.  You need not require recipients to copy the
        Corresponding Source along with the object code.  If the place to copy
        the object code is a network server, the Corresponding Source may be on
        a different server (operated by you or a third party) that supports
        equivalent copying facilities, provided you maintain clear directions
        next to the object code saying where to find the Corresponding Source.
        Regardless of what server hosts the Corresponding Source, you remain
        obligated to ensure that it is available for as long as needed to
        satisfy these requirements.
      </para></listitem><listitem><para>
        Convey the object code using peer-to-peer transmission, provided you
        inform other peers where the object code and Corresponding Source of the
        work are being offered to the general public at no charge under
        subsection 6d.
      </para></listitem></orderedlist><para>
    A separable portion of the object code, whose source code is excluded from
    the Corresponding Source as a System Library, need not be included in
    conveying the object code work.
  </para><para>
    A “User Product” is either (1) a “consumer product”,
    which means any tangible personal property which is normally used for
    personal, family, or household purposes, or (2) anything designed or sold
    for incorporation into a dwelling.  In determining whether a product is a
    consumer product, doubtful cases shall be resolved in favor of coverage.
    For a particular product received by a particular user, “normally
    used” refers to a typical or common use of that class of product,
    regardless of the status of the particular user or of the way in which the
    particular user actually uses, or expects or is expected to use, the
    product.  A product is a consumer product regardless of whether the product
    has substantial commercial, industrial or non-consumer uses, unless such
    uses represent the only significant mode of use of the product.
  </para><para>
    “Installation Information” for a User Product means any methods,
    procedures, authorization keys, or other information required to install and
    execute modified versions of a covered work in that User Product from a
    modified version of its Corresponding Source.  The information must suffice
    to ensure that the continued functioning of the modified object code is in
    no case prevented or interfered with solely because modification has been
    made.
  </para><para>
    If you convey an object code work under this section in, or with, or
    specifically for use in, a User Product, and the conveying occurs as part of
    a transaction in which the right of possession and use of the User Product
    is transferred to the recipient in perpetuity or for a fixed term
    (regardless of how the transaction is characterized), the Corresponding
    Source conveyed under this section must be accompanied by the Installation
    Information.  But this requirement does not apply if neither you nor any
    third party retains the ability to install modified object code on the User
    Product (for example, the work has been installed in
    <acronym>ROM</acronym>).
  </para><para>
    The requirement to provide Installation Information does not include a
    requirement to continue to provide support service, warranty, or updates for
    a work that has been modified or installed by the recipient, or for the User
    Product in which it has been modified or installed.  Access to a network may
    be denied when the modification itself materially and adversely affects the
    operation of the network or violates the rules and protocols for
    communication across the network.
  </para><para>
    Corresponding Source conveyed, and Installation Information provided, in
    accord with this section must be in a format that is publicly documented
    (and with an implementation available to the public in source code form),
    and must require no special password or key for unpacking, reading or
    copying.
  </para><bridgehead renderas="sect1" xml:id="AdditionalTerms">
     7. Additional Terms.
   </bridgehead><para>
     “Additional permissions” are terms that supplement the terms of
     this License by making exceptions from one or more of its conditions.
     Additional permissions that are applicable to the entire Program shall be
     treated as though they were included in this License, to the extent that
     they are valid under applicable law.  If additional permissions apply only
     to part of the Program, that part may be used separately under those
     permissions, but the entire Program remains governed by this License
     without regard to the additional permissions.
   </para><para>
     When you convey a copy of a covered work, you may at your option remove any
     additional permissions from that copy, or from any part of it.  (Additional
     permissions may be written to require their own removal in certain cases
     when you modify the work.)  You may place additional permissions on
     material, added by you to a covered work, for which you have or can give
     appropriate copyright permission.
   </para><para>
     Notwithstanding any other provision of this License, for material you add
     to a covered work, you may (if authorized by the copyright holders of that
     material) supplement the terms of this License with terms:
   </para><orderedlist continuation="restarts" inheritnum="ignore" numeration="loweralpha"><listitem><para>
         Disclaiming warranty or limiting liability differently from the terms
         of sections 15 and 16 of this License; or
       </para></listitem><listitem><para>
         Requiring preservation of specified reasonable legal notices or author
         attributions in that material or in the Appropriate Legal Notices
         displayed by works containing it; or
       </para></listitem><listitem><para>
         Prohibiting misrepresentation of the origin of that material, or
         requiring that modified versions of such material be marked in
         reasonable ways as different from the original version; or
       </para></listitem><listitem><para>
         Limiting the use for publicity purposes of names of licensors or
         authors of the material; or
       </para></listitem><listitem><para>
         Declining to grant rights under trademark law for use of some trade
         names, trademarks, or service marks; or
       </para></listitem><listitem><para>
         Requiring indemnification of licensors and authors of that material by
         anyone who conveys the material (or modified versions of it) with
         contractual assumptions of liability to the recipient, for any
         liability that these contractual assumptions directly impose on those
         licensors and authors.
       </para></listitem></orderedlist><para>
     All other non-permissive additional terms are considered “further
     restrictions” within the meaning of section 10.  If the Program as
     you received it, or any part of it, contains a notice stating that it is
     governed by this License along with a term that is a further restriction,
     you may remove that term.  If a license document contains a further
     restriction but permits relicensing or conveying under this License, you
     may add to a covered work material governed by the terms of that license
     document, provided that the further restriction does not survive such
     relicensing or conveying.
   </para><para>
     If you add terms to a covered work in accord with this section, you must
     place, in the relevant source files, a statement of the additional terms
     that apply to those files, or a notice indicating where to find the
     applicable terms.
   </para><para>
     Additional terms, permissive or non-permissive, may be stated in the form
     of a separately written license, or stated as exceptions; the above
     requirements apply either way.
   </para><bridgehead renderas="sect1" xml:id="gpl-3-termination">
     8. Termination.
   </bridgehead><para>
     You may not propagate or modify a covered work except as expressly provided
     under this License.  Any attempt otherwise to propagate or modify it is
     void, and will automatically terminate your rights under this License
     (including any patent licenses granted under the third paragraph of section
     11).
   </para><para>
     However, if you cease all violation of this License, then your license from
     a particular copyright holder is reinstated (a) provisionally, unless and
     until the copyright holder explicitly and finally terminates your license,
     and (b) permanently, if the copyright holder fails to notify you of the
     violation by some reasonable means prior to 60 days after the cessation.
   </para><para>
     Moreover, your license from a particular copyright holder is reinstated
     permanently if the copyright holder notifies you of the violation by some
     reasonable means, this is the first time you have received notice of
     violation of this License (for any work) from that copyright holder, and
     you cure the violation prior to 30 days after your receipt of the notice.
   </para><para>
     Termination of your rights under this section does not terminate the
     licenses of parties who have received copies or rights from you under this
     License.  If your rights have been terminated and not permanently
     reinstated, you do not qualify to receive new licenses for the same
     material under section 10.
   </para><bridgehead renderas="sect1" xml:id="AcceptanceNotRequired">
     9. Acceptance Not Required for Having Copies.
   </bridgehead><para>
     You are not required to accept this License in order to receive or run a
     copy of the Program.  Ancillary propagation of a covered work occurring
     solely as a consequence of using peer-to-peer transmission to receive a
     copy likewise does not require acceptance.  However, nothing other than
     this License grants you permission to propagate or modify any covered work.
     These actions infringe copyright if you do not accept this License.
     Therefore, by modifying or propagating a covered work, you indicate your
     acceptance of this License to do so.
   </para><bridgehead renderas="sect1" xml:id="AutomaticDownstream">
     10. Automatic Licensing of Downstream Recipients.
   </bridgehead><para>
     Each time you convey a covered work, the recipient automatically receives a
     license from the original licensors, to run, modify and propagate that
     work, subject to this License.  You are not responsible for enforcing
     compliance by third parties with this License.
   </para><para>
     An “entity transaction” is a transaction transferring control
     of an organization, or substantially all assets of one, or subdividing an
     organization, or merging organizations.  If propagation of a covered work
     results from an entity transaction, each party to that transaction who
     receives a copy of the work also receives whatever licenses to the work the
     party’s predecessor in interest had or could give under the previous
     paragraph, plus a right to possession of the Corresponding Source of the
     work from the predecessor in interest, if the predecessor has it or can get
     it with reasonable efforts.
   </para><para>
     You may not impose any further restrictions on the exercise of the rights
     granted or affirmed under this License.  For example, you may not impose a
     license fee, royalty, or other charge for exercise of rights granted under
     this License, and you may not initiate litigation (including a cross-claim
     or counterclaim in a lawsuit) alleging that any patent claim is infringed
     by making, using, selling, offering for sale, or importing the Program or
     any portion of it.
   </para><bridgehead renderas="sect1" xml:id="Patents">
    11. Patents.
  </bridgehead><para>
    A “contributor” is a copyright holder who authorizes use under
    this License of the Program or a work on which the Program is based.  The
    work thus licensed is called the contributor’s “contributor
    version”.
  </para><para>
    A contributor’s “essential patent claims” are all patent
    claims owned or controlled by the contributor, whether already acquired or
    hereafter acquired, that would be infringed by some manner, permitted by
    this License, of making, using, or selling its contributor version, but do
    not include claims that would be infringed only as a consequence of further
    modification of the contributor version.  For purposes of this definition,
    “control” includes the right to grant patent sublicenses in a
    manner consistent with the requirements of this License.
  </para><para>
    Each contributor grants you a non-exclusive, worldwide, royalty-free patent
    license under the contributor’s essential patent claims, to make, use,
    sell, offer for sale, import and otherwise run, modify and propagate the
    contents of its contributor version.
  </para><para>
    In the following three paragraphs, a “patent license” is any
    express agreement or commitment, however denominated, not to enforce a
    patent (such as an express permission to practice a patent or covenant not
    to sue for patent infringement).  To “grant” such a patent
    license to a party means to make such an agreement or commitment not to
    enforce a patent against the party.
  </para><para>
    If you convey a covered work, knowingly relying on a patent license, and the
    Corresponding Source of the work is not available for anyone to copy, free
    of charge and under the terms of this License, through a publicly available
    network server or other readily accessible means, then you must either (1)
    cause the Corresponding Source to be so available, or (2) arrange to deprive
    yourself of the benefit of the patent license for this particular work, or
    (3) arrange, in a manner consistent with the requirements of this License,
    to extend the patent license to downstream recipients.  “Knowingly
    relying” means you have actual knowledge that, but for the patent
    license, your conveying the covered work in a country, or your
    recipient’s use of the covered work in a country, would infringe one
    or more identifiable patents in that country that you have reason to believe
    are valid.
  </para><para>
    If, pursuant to or in connection with a single transaction or arrangement,
    you convey, or propagate by procuring conveyance of, a covered work, and
    grant a patent license to some of the parties receiving the covered work
    authorizing them to use, propagate, modify or convey a specific copy of the
    covered work, then the patent license you grant is automatically extended to
    all recipients of the covered work and works based on it.
  </para><para>
    A patent license is “discriminatory” if it does not include
    within the scope of its coverage, prohibits the exercise of, or is
    conditioned on the non-exercise of one or more of the rights that are
    specifically granted under this License.  You may not convey a covered work
    if you are a party to an arrangement with a third party that is in the
    business of distributing software, under which you make payment to the third
    party based on the extent of your activity of conveying the work, and under
    which the third party grants, to any of the parties who would receive the
    covered work from you, a discriminatory patent license (a) in connection
    with copies of the covered work conveyed by you (or copies made from those
    copies), or (b) primarily for and in connection with specific products or
    compilations that contain the covered work, unless you entered into that
    arrangement, or that patent license was granted, prior to 28 March 2007.
  </para><para>
    Nothing in this License shall be construed as excluding or limiting any
    implied license or other defenses to infringement that may otherwise be
    available to you under applicable patent law.
  </para><bridgehead renderas="sect1" xml:id="NoSurrender">
    12. No Surrender of Others’ Freedom.
  </bridgehead><para>
    If conditions are imposed on you (whether by court order, agreement or
    otherwise) that contradict the conditions of this License, they do not
    excuse you from the conditions of this License.  If you cannot convey a
    covered work so as to satisfy simultaneously your obligations under this
    License and any other pertinent obligations, then as a consequence you may
    not convey it at all.  For example, if you agree to terms that obligate you
    to collect a royalty for further conveying from those to whom you convey the
    Program, the only way you could satisfy both those terms and this License
    would be to refrain entirely from conveying the Program.
  </para><bridgehead renderas="sect1" xml:id="UsedWithAGPL">
    13. Use with the <acronym>GNU</acronym> Affero General Public License.
  </bridgehead><para>
    Notwithstanding any other provision of this License, you have permission to
    link or combine any covered work with a work licensed under version 3 of the
    <acronym>GNU</acronym> Affero General Public License into a single combined
    work, and to convey the resulting work.  The terms of this License will
    continue to apply to the part which is the covered work, but the special
    requirements of the <acronym>GNU</acronym> Affero General Public License,
    section 13, concerning interaction through a network will apply to the
    combination as such.
  </para><bridgehead renderas="sect1" xml:id="RevisedVersions">
    14. Revised Versions of this License.
  </bridgehead><para>
    The Free Software Foundation may publish revised and/or new versions of the
    <acronym>GNU</acronym> General Public License from time to time.  Such new
    versions will be similar in spirit to the present version, but may differ in
    detail to address new problems or concerns.
  </para><para>
    Each version is given a distinguishing version number.  If the Program
    specifies that a certain numbered version of the <acronym>GNU</acronym>
    General Public License “or any later version” applies to it, you
    have the option of following the terms and conditions either of that
    numbered version or of any later version published by the Free Software
    Foundation.  If the Program does not specify a version number of the
    <acronym>GNU</acronym> General Public License, you may choose any version
    ever published by the Free Software Foundation.
  </para><para>
    If the Program specifies that a proxy can decide which future versions of
    the <acronym>GNU</acronym> General Public License can be used, that
    proxy’s public statement of acceptance of a version permanently
    authorizes you to choose that version for the Program.
  </para><para>
    Later license versions may give you additional or different permissions.
    However, no additional obligations are imposed on any author or copyright
    holder as a result of your choosing to follow a later version.
  </para><bridgehead renderas="sect1" xml:id="WarrantyDisclaimer">
    15. Disclaimer of Warranty.
  </bridgehead><para>
    THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
    LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
    OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF
    ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
    THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
    YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR OR CORRECTION.
  </para><bridgehead renderas="sect1" xml:id="LiabilityLimitation">
    16. Limitation of Liability.
  </bridgehead><para>
    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
    ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE
    PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
    GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
    OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA
    OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
    PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
    EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGES.
  </para><bridgehead renderas="sect1" xml:id="InterpretationSecs1516">
    17. Interpretation of Sections 15 and 16.
  </bridgehead><para>
    If the disclaimer of warranty and limitation of liability provided above
    cannot be given local legal effect according to their terms, reviewing
    courts shall apply local law that most closely approximates an absolute
    waiver of all civil liability in connection with the Program, unless a
    warranty or assumption of liability accompanies a copy of the Program in
    return for a fee.
  </para><bridgehead>
    END OF TERMS AND CONDITIONS
  </bridgehead><bridgehead renderas="sect1" xml:id="HowToApply">
    How to Apply These Terms to Your New Programs
  </bridgehead><para>
    If you develop a new program, and you want it to be of the greatest possible
    use to the public, the best way to achieve this is to make it free software
    which everyone can redistribute and change under these terms.
  </para><para>
    To do so, attach the following notices to the program.  It is safest to
    attach them to the start of each source file to most effectively state the
    exclusion of warranty; and each file should have at least the
    “copyright” line and a pointer to where the full notice is
    found.
  </para><screen><replaceable>one line to give the program’s name and a brief idea of what it does.</replaceable>
Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable>

This program is free software: you can redistribute it and/or modify
it under the terms of the <acronym>GNU</acronym> General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
<acronym>GNU</acronym> General Public License for more details.

You should have received a copy of the <acronym>GNU</acronym> General Public License
along with this program.  If not, see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</link>.
  </screen><para>
    Also add information on how to contact you by electronic and paper mail.
  </para><para>
    If the program does terminal interaction, make it output a short notice like
    this when it starts in an interactive mode:
  </para><screen><replaceable>program</replaceable> Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable>
This program comes with ABSOLUTELY NO WARRANTY; for details type ‘<literal>show w</literal>’.
This is free software, and you are welcome to redistribute it
under certain conditions; type ‘<literal>show c</literal>’ for details.
  </screen><para>
    The hypothetical commands ‘<literal>show w</literal>’ and
    ‘<literal>show c</literal>’ should show the appropriate parts of
    the General Public License.  Of course, your program’s commands might be
    different; for a GUI interface, you would use an “about box”.
  </para><para>
    You should also get your employer (if you work as a programmer) or school,
    if any, to sign a “copyright disclaimer” for the program, if
    necessary.  For more information on this, and how to apply and follow the
    <acronym>GNU</acronym> <acronym>GPL</acronym>, see
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</link>.
  </para><para>
    The <acronym>GNU</acronym> General Public License does not permit
    incorporating your program into proprietary programs.  If your program is a
    subroutine library, you may consider it more useful to permit linking
    proprietary applications with the library.  If this is what you want to do,
    use the <acronym>GNU</acronym> Lesser General Public License instead of this
    License.  But first, please read <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/licenses/why-not-lgpl.html">https://www.gnu.org/licenses/why-not-lgpl.html</link>.
  </para></appendix><!-- Appendix E --><appendix version="5.0" xml:base="../gnu/fdl-1.3.xml" xml:id="appendix.gfdl-1.3"><info><title>GNU Free Documentation License</title></info><?dbhtml filename="appendix_gfdl.html"?><simpara>Version 1.3, 3 November 2008</simpara><simpara>
    Copyright © 2000, 2001, 2002, 2007, 2008
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.fsf.org">Free Software Foundation, Inc.</link>
  </simpara><simpara>
    Everyone is permitted to copy and distribute verbatim copies of this
    license document, but changing it is not allowed.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section0">
    0. PREAMBLE
  </bridgehead><simpara>
    The purpose of this License is to make a manual, textbook, or other
    functional and useful document “free” in the sense of freedom:
    to assure everyone the effective freedom to copy and redistribute it, with
    or without modifying it, either commercially or
    noncommercially. Secondarily, this License preserves for the author and
    publisher a way to get credit for their work, while not being considered
    responsible for modifications made by others.
  </simpara><simpara>
    This License is a kind of “copyleft”, which means that
    derivative works of the document must themselves be free in the same
    sense. It complements the GNU General Public License, which is a copyleft
    license designed for free software.
  </simpara><simpara>
    We have designed this License in order to use it for manuals for free
    software, because free software needs free documentation: a free program
    should come with manuals providing the same freedoms that the software
    does. But this License is not limited to software manuals; it can be used
    for any textual work, regardless of subject matter or whether it is
    published as a printed book. We recommend this License principally for
    works whose purpose is instruction or reference.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section1">
    1. APPLICABILITY AND DEFINITIONS
  </bridgehead><simpara>
    This License applies to any manual or other work, in any medium, that
    contains a notice placed by the copyright holder saying it can be
    distributed under the terms of this License. Such a notice grants a
    world-wide, royalty-free license, unlimited in duration, to use that work
    under the conditions stated herein. The “Document”, below,
    refers to any such manual or work. Any member of the public is a licensee,
    and is addressed as “you”. You accept the license if you copy,
    modify or distribute the work in a way requiring permission under
    copyright law.
  </simpara><simpara>
    A “Modified Version” of the Document means any work containing
    the Document or a portion of it, either copied verbatim, or with
    modifications and/or translated into another language.
  </simpara><simpara>
    A “Secondary Section” is a named appendix or a front-matter
    section of the Document that deals exclusively with the relationship of
    the publishers or authors of the Document to the Document’s overall
    subject (or to related matters) and contains nothing that could fall
    directly within that overall subject. (Thus, if the Document is in part a
    textbook of mathematics, a Secondary Section may not explain any
    mathematics.) The relationship could be a matter of historical connection
    with the subject or with related matters, or of legal, commercial,
    philosophical, ethical or political position regarding them.
  </simpara><simpara>
    The “Invariant Sections” are certain Secondary Sections whose
    titles are designated, as being those of Invariant Sections, in the notice
    that says that the Document is released under this License. If a section
    does not fit the above definition of Secondary then it is not allowed to
    be designated as Invariant. The Document may contain zero Invariant
    Sections. If the Document does not identify any Invariant Sections then
    there are none.
  </simpara><simpara>
    The “Cover Texts” are certain short passages of text that are
    listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
    that the Document is released under this License. A Front-Cover Text may
    be at most 5 words, and a Back-Cover Text may be at most 25 words.
  </simpara><simpara>
    A “Transparent” copy of the Document means a machine-readable
    copy, represented in a format whose specification is available to the
    general public, that is suitable for revising the document
    straightforwardly with generic text editors or (for images composed of
    pixels) generic paint programs or (for drawings) some widely available
    drawing editor, and that is suitable for input to text formatters or for
    automatic translation to a variety of formats suitable for input to text
    formatters. A copy made in an otherwise Transparent file format whose
    markup, or absence of markup, has been arranged to thwart or discourage
    subsequent modification by readers is not Transparent. An image format is
    not Transparent if used for any substantial amount of text. A copy that is
    not “Transparent” is called “Opaque”.
  </simpara><simpara>
    Examples of suitable formats for Transparent copies include plain ASCII
    without markup, Texinfo input format, LaTeX input format, SGML or XML
    using a publicly available DTD, and standard-conforming simple HTML,
    PostScript or PDF designed for human modification. Examples of transparent
    image formats include PNG, XCF and JPG. Opaque formats include proprietary
    formats that can be read and edited only by proprietary word processors,
    SGML or XML for which the DTD and/or processing tools are not generally
    available, and the machine-generated HTML, PostScript or PDF produced by
    some word processors for output purposes only.
  </simpara><simpara>
    The “Title Page” means, for a printed book, the title page
    itself, plus such following pages as are needed to hold, legibly, the
    material this License requires to appear in the title page. For works in
    formats which do not have any title page as such, “Title Page”
    means the text near the most prominent appearance of the work’s
    title, preceding the beginning of the body of the text.
  </simpara><simpara>
    The “publisher” means any person or entity that distributes
    copies of the Document to the public.
  </simpara><simpara>
    A section “Entitled XYZ” means a named subunit of the Document
    whose title either is precisely XYZ or contains XYZ in parentheses
    following text that translates XYZ in another language. (Here XYZ stands
    for a specific section name mentioned below, such as
    “Acknowledgements”, “Dedications”,
    “Endorsements”, or “History”.) To “Preserve
    the Title” of such a section when you modify the Document means that
    it remains a section “Entitled XYZ” according to this
    definition.
  </simpara><simpara>
    The Document may include Warranty Disclaimers next to the notice which
    states that this License applies to the Document. These Warranty
    Disclaimers are considered to be included by reference in this License,
    but only as regards disclaiming warranties: any other implication that
    these Warranty Disclaimers may have is void and has no effect on the
    meaning of this License.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section2">
    2. VERBATIM COPYING
  </bridgehead><simpara>
    You may copy and distribute the Document in any medium, either
    commercially or noncommercially, provided that this License, the copyright
    notices, and the license notice saying this License applies to the
    Document are reproduced in all copies, and that you add no other
    conditions whatsoever to those of this License. You may not use technical
    measures to obstruct or control the reading or further copying of the
    copies you make or distribute. However, you may accept compensation in
    exchange for copies. If you distribute a large enough number of copies you
    must also follow the conditions in section 3.
  </simpara><simpara>
    You may also lend copies, under the same conditions stated above, and you
    may publicly display copies.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section3">
    3. COPYING IN QUANTITY
  </bridgehead><simpara>
    If you publish printed copies (or copies in media that commonly have
    printed covers) of the Document, numbering more than 100, and the
    Document’s license notice requires Cover Texts, you must enclose
    the copies in covers that carry, clearly and legibly, all these Cover
    Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the
    back cover. Both covers must also clearly and legibly identify you as the
    publisher of these copies. The front cover must present the full title
    with all words of the title equally prominent and visible. You may add
    other material on the covers in addition. Copying with changes limited to
    the covers, as long as they preserve the title of the Document and satisfy
    these conditions, can be treated as verbatim copying in other respects.
  </simpara><simpara>
    If the required texts for either cover are too voluminous to fit legibly,
    you should put the first ones listed (as many as fit reasonably) on the
    actual cover, and continue the rest onto adjacent pages.
  </simpara><simpara>
    If you publish or distribute Opaque copies of the Document numbering more
    than 100, you must either include a machine-readable Transparent copy
    along with each Opaque copy, or state in or with each Opaque copy a
    computer-network location from which the general network-using public has
    access to download using public-standard network protocols a complete
    Transparent copy of the Document, free of added material. If you use the
    latter option, you must take reasonably prudent steps, when you begin
    distribution of Opaque copies in quantity, to ensure that this Transparent
    copy will remain thus accessible at the stated location until at least one
    year after the last time you distribute an Opaque copy (directly or
    through your agents or retailers) of that edition to the public.
  </simpara><simpara>
    It is requested, but not required, that you contact the authors of the
    Document well before redistributing any large number of copies, to give
    them a chance to provide you with an updated version of the Document.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section4">
    4. MODIFICATIONS
  </bridgehead><simpara>
    You may copy and distribute a Modified Version of the Document under the
    conditions of sections 2 and 3 above, provided that you release the
    Modified Version under precisely this License, with the Modified Version
    filling the role of the Document, thus licensing distribution and
    modification of the Modified Version to whoever possesses a copy of it. In
    addition, you must do these things in the Modified Version:
  </simpara><orderedlist numeration="upperalpha"><listitem><simpara>
        Use in the Title Page (and on the covers, if any) a title distinct
        from that of the Document, and from those of previous versions (which
        should, if there were any, be listed in the History section of the
        Document). You may use the same title as a previous version if the
        original publisher of that version gives permission.
      </simpara></listitem><listitem><simpara>
        List on the Title Page, as authors, one or more persons or entities
        responsible for authorship of the modifications in the Modified
        Version, together with at least five of the principal authors of the
        Document (all of its principal authors, if it has fewer than five),
        unless they release you from this requirement.
      </simpara></listitem><listitem><simpara>
        State on the Title page the name of the publisher of the Modified
        Version, as the publisher.
      </simpara></listitem><listitem><simpara>
        Preserve all the copyright notices of the Document.
      </simpara></listitem><listitem><simpara>
        Add an appropriate copyright notice for your modifications adjacent to
        the other copyright notices.
      </simpara></listitem><listitem><simpara>
        Include, immediately after the copyright notices, a license notice
        giving the public permission to use the Modified Version under the
        terms of this License, in the form shown in the Addendum below.
      </simpara></listitem><listitem><simpara>
        Preserve in that license notice the full lists of Invariant Sections
        and required Cover Texts given in the Document’s license
        notice.
      </simpara></listitem><listitem><simpara>
        Include an unaltered copy of this License.
      </simpara></listitem><listitem><simpara>
        Preserve the section Entitled “History”, Preserve its
        Title, and add to it an item stating at least the title, year, new
        authors, and publisher of the Modified Version as given on the Title
        Page. If there is no section Entitled “History” in the
        Document, create one stating the title, year, authors, and publisher
        of the Document as given on its Title Page, then add an item
        describing the Modified Version as stated in the previous sentence.
      </simpara></listitem><listitem><simpara>
        Preserve the network location, if any, given in the Document for
        public access to a Transparent copy of the Document, and likewise the
        network locations given in the Document for previous versions it was
        based on.  These may be placed in the “History”
        section. You may omit a network location for a work that was published
        at least four years before the Document itself, or if the original
        publisher of the version it refers to gives permission.
      </simpara></listitem><listitem><simpara>
        For any section Entitled “Acknowledgements” or
        “Dedications”, Preserve the Title of the section, and
        preserve in the section all the substance and tone of each of the
        contributor acknowledgements and/or dedications given therein.
      </simpara></listitem><listitem><simpara>
        Preserve all the Invariant Sections of the Document, unaltered in
        their text and in their titles. Section numbers or the equivalent are
        not considered part of the section titles.
      </simpara></listitem><listitem><simpara>
        Delete any section Entitled “Endorsements”. Such a section
        may not be included in the Modified Version.
      </simpara></listitem><listitem><simpara>
        Do not retitle any existing section to be Entitled
        “Endorsements” or to conflict in title with any Invariant
        Section.
      </simpara></listitem><listitem><simpara>
        Preserve any Warranty Disclaimers.
      </simpara></listitem></orderedlist><simpara>
    If the Modified Version includes new front-matter sections or appendices
    that qualify as Secondary Sections and contain no material copied from the
    Document, you may at your option designate some or all of these sections
    as invariant. To do this, add their titles to the list of Invariant
    Sections in the Modified Version’s license notice. These titles
    must be distinct from any other section titles.
  </simpara><simpara>
    You may add a section Entitled “Endorsements”, provided it
    contains nothing but endorsements of your Modified Version by various
    parties — for example, statements of peer review or that the text
    has been approved by an organization as the authoritative definition of a
    standard.
  </simpara><simpara>
    You may add a passage of up to five words as a Front-Cover Text, and a
    passage of up to 25 words as a Back-Cover Text, to the end of the list of
    Cover Texts in the Modified Version. Only one passage of Front-Cover Text
    and one of Back-Cover Text may be added by (or through arrangements made
    by) any one entity. If the Document already includes a cover text for the
    same cover, previously added by you or by arrangement made by the same
    entity you are acting on behalf of, you may not add another; but you may
    replace the old one, on explicit permission from the previous publisher
    that added the old one.
  </simpara><simpara>
    The author(s) and publisher(s) of the Document do not by this License give
    permission to use their names for publicity for or to assert or imply
    endorsement of any Modified Version.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section5">
    5. COMBINING DOCUMENTS
  </bridgehead><simpara>
    You may combine the Document with other documents released under this
    License, under the terms defined in section 4 above for modified versions,
    provided that you include in the combination all of the Invariant Sections
    of all of the original documents, unmodified, and list them all as
    Invariant Sections of your combined work in its license notice, and that
    you preserve all their Warranty Disclaimers.
  </simpara><simpara>
    The combined work need only contain one copy of this License, and multiple
    identical Invariant Sections may be replaced with a single copy. If there
    are multiple Invariant Sections with the same name but different contents,
    make the title of each such section unique by adding at the end of it, in
    parentheses, the name of the original author or publisher of that section
    if known, or else a unique number. Make the same adjustment to the section
    titles in the list of Invariant Sections in the license notice of the
    combined work.
  </simpara><simpara>
    In the combination, you must combine any sections Entitled
    “History” in the various original documents, forming one
    section Entitled “History”; likewise combine any sections
    Entitled “Acknowledgements”, and any sections Entitled
    “Dedications”. You must delete all sections Entitled
    “Endorsements”.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section6">
    6. COLLECTIONS OF DOCUMENTS
  </bridgehead><simpara>
    You may make a collection consisting of the Document and other documents
    released under this License, and replace the individual copies of this
    License in the various documents with a single copy that is included in
    the collection, provided that you follow the rules of this License for
    verbatim copying of each of the documents in all other respects.
  </simpara><simpara>
    You may extract a single document from such a collection, and distribute
    it individually under this License, provided you insert a copy of this
    License into the extracted document, and follow this License in all other
    respects regarding verbatim copying of that document.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section7">
    7. AGGREGATION WITH INDEPENDENT WORKS
  </bridgehead><simpara>
    A compilation of the Document or its derivatives with other separate and
    independent documents or works, in or on a volume of a storage or
    distribution medium, is called an “aggregate” if the copyright
    resulting from the compilation is not used to limit the legal rights of
    the compilation’s users beyond what the individual works
    permit. When the Document is included in an aggregate, this License does
    not apply to the other works in the aggregate which are not themselves
    derivative works of the Document.
  </simpara><simpara>
    If the Cover Text requirement of section 3 is applicable to these copies
    of the Document, then if the Document is less than one half of the entire
    aggregate, the Document’s Cover Texts may be placed on covers that
    bracket the Document within the aggregate, or the electronic equivalent of
    covers if the Document is in electronic form. Otherwise they must appear
    on printed covers that bracket the whole aggregate.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section8">
    8. TRANSLATION
  </bridgehead><simpara>
    Translation is considered a kind of modification, so you may distribute
    translations of the Document under the terms of section 4. Replacing
    Invariant Sections with translations requires special permission from
    their copyright holders, but you may include translations of some or all
    Invariant Sections in addition to the original versions of these Invariant
    Sections. You may include a translation of this License, and all the
    license notices in the Document, and any Warranty Disclaimers, provided
    that you also include the original English version of this License and the
    original versions of those notices and disclaimers. In case of a
    disagreement between the translation and the original version of this
    License or a notice or disclaimer, the original version will prevail.
  </simpara><simpara>
    If a section in the Document is Entitled “Acknowledgements”,
    “Dedications”, or “History”, the requirement
    (section 4) to Preserve its Title (section 1) will typically require
    changing the actual title.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section9">
    9. TERMINATION
  </bridgehead><simpara>
    You may not copy, modify, sublicense, or distribute the Document except as
    expressly provided under this License. Any attempt otherwise to copy,
    modify, sublicense, or distribute it is void, and will automatically
    terminate your rights under this License.
  </simpara><simpara>
    However, if you cease all violation of this License, then your license
    from a particular copyright holder is reinstated (a) provisionally, unless
    and until the copyright holder explicitly and finally terminates your
    license, and (b) permanently, if the copyright holder fails to notify you
    of the violation by some reasonable means prior to 60 days after the
    cessation.
  </simpara><simpara>
    Moreover, your license from a particular copyright holder is reinstated
    permanently if the copyright holder notifies you of the violation by some
    reasonable means, this is the first time you have received notice of
    violation of this License (for any work) from that copyright holder, and
    you cure the violation prior to 30 days after your receipt of the notice.
  </simpara><simpara>
    Termination of your rights under this section does not terminate the
    licenses of parties who have received copies or rights from you under this
    License. If your rights have been terminated and not permanently
    reinstated, receipt of a copy of some or all of the same material does not
    give you any rights to use it.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section10">
    10. FUTURE REVISIONS OF THIS LICENSE
  </bridgehead><simpara>
    The Free Software Foundation may publish new, revised versions of the GNU
    Free Documentation License from time to time. Such new versions will be
    similar in spirit to the present version, but may differ in detail to
    address new problems or concerns. See
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/copyleft/">Copyleft</link>.
  </simpara><simpara>
    Each version of the License is given a distinguishing version number. If
    the Document specifies that a particular numbered version of this License
    “or any later version” applies to it, you have the option of
    following the terms and conditions either of that specified version or of
    any later version that has been published (not as a draft) by the Free
    Software Foundation. If the Document does not specify a version number of
    this License, you may choose any version ever published (not as a draft)
    by the Free Software Foundation. If the Document specifies that a proxy
    can decide which future versions of this License can be used, that
    proxy’s public statement of acceptance of a version permanently
    authorizes you to choose that version for the Document.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-section11">
    11. RELICENSING
  </bridgehead><simpara>
    “Massive Multiauthor Collaboration Site” (or “MMC
    Site”) means any World Wide Web server that publishes copyrightable
    works and also provides prominent facilities for anybody to edit those
    works. A public wiki that anybody can edit is an example of such a
    server. A “Massive Multiauthor Collaboration” (or
    “MMC”) contained in the site means any set of copyrightable
    works thus published on the MMC site.
  </simpara><simpara>
    “CC-BY-SA” means the Creative Commons Attribution-Share Alike
    3.0 license published by Creative Commons Corporation, a not-for-profit
    corporation with a principal place of business in San Francisco,
    California, as well as future copyleft versions of that license published
    by that same organization.
  </simpara><simpara>
    “Incorporate” means to publish or republish a Document, in
    whole or in part, as part of another Document.
  </simpara><simpara>
    An MMC is “eligible for relicensing” if it is licensed under
    this License, and if all works that were first published under this
    License somewhere other than this MMC, and subsequently incorporated in
    whole or in part into the MMC, (1) had no cover texts or invariant
    sections, and (2) were thus incorporated prior to November 1, 2008.
  </simpara><simpara>
    The operator of an MMC Site may republish an MMC contained in the site
    under CC-BY-SA on the same site at any time before August 1, 2009,
    provided the MMC is eligible for relicensing.
  </simpara><bridgehead renderas="sect2" xml:id="fdl-1-addendum">
    ADDENDUM: How to use this License for your documents
  </bridgehead><simpara>
    To use this License in a document you have written, include a copy of the
    License in the document and put the following copyright and license
    notices just after the title page:
  </simpara><screen>Copyright © YEAR YOUR NAME

Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.3 or any later version
published by the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in
the section entitled “GNU Free Documentation License”.</screen><simpara>
    If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
    replace the “with… Texts.” line with this:
  </simpara><screen>with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts
being LIST, and with the Back-Cover Texts being LIST.</screen><simpara>
    If you have Invariant Sections without Cover Texts, or some other
    combination of the three, merge those two alternatives to suit the
    situation.
  </simpara><simpara>
    If your document contains nontrivial examples of program code, we
    recommend releasing these examples in parallel under your choice of free
    software license, such as the GNU General Public License, to permit their
    use in free software.
  </simpara></appendix></part></book>