Improve libstdc++ docs w.r.t newer C++ standards

Instead of repeating all the old headers for every new standard I've
changed the docs to only list the new headers for each standard.

	* doc/xml/manual/test.xml: Improve documentation on writing tests for
	newer standards.
	* doc/xml/manual/using.xml: Document all headers for C++11 and later.
	* doc/html/*: Regenerate.

From-SVN: r263163
This commit is contained in:
Jonathan Wakely 2018-07-31 16:02:32 +01:00 committed by Jonathan Wakely
parent 77a6c969e9
commit 3e64a626d7
8 changed files with 378 additions and 99 deletions

View File

@ -1,5 +1,10 @@
2018-07-31 Jonathan Wakely <jwakely@redhat.com>
* doc/xml/manual/test.xml: Improve documentation on writing tests for
newer standards.
* doc/xml/manual/using.xml: Document all headers for C++11 and later.
* doc/html/*: Regenerate.
* include/ext/pointer.h [__cplusplus >= 201103L]
(_Pointer_adapter::operator bool): Add explicit conversion operator
to replace safe bool idiom.

View File

@ -526,4 +526,18 @@
<code class="code">weak_ptr::owner_before</code>
</em></span>
</span></dt><dd><p>Add noexcept.
</p></dd><dt><a id="manual.bugs.dr2993"></a><span class="term"><a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2993" target="_top">2993</a>:
<span class="emphasis"><em><code class="code">reference_wrapper&lt;T&gt;</code> conversion from <code class="code">T&amp;&amp;</code>
</em></span>
</span></dt><dd><p>Replaced the constructors with a constrained template,
to prevent participation in overload resolution when not valid.
</p></dd><dt><a id="manual.bugs.dr3074"></a><span class="term"><a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3074" target="_top">3074</a>:
<span class="emphasis"><em>Non-member functions for <code class="code">valarray</code> should only deduce from the <code class="code">valarray</code>
</em></span>
</span></dt><dd><p>Change scalar operands to be non-deduced context, so that
they will allow conversions from other types to the value_type.
</p></dd><dt><a id="manual.bugs.dr3076"></a><span class="term"><a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#3076" target="_top">3076</a>:
<span class="emphasis"><em><code class="code">basic_string</code> CTAD ambiguity
</em></span>
</span></dt><dd><p>Change constructors to constrained templates.
</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="license.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="status.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="setup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">License </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Setup</td></tr></table></div></body></html>

File diff suppressed because one or more lines are too long

View File

@ -875,7 +875,11 @@ and test for <code class="code">__STDCPP_MATH_SPEC_FUNCS__ &gt;= 201003L</code>.
<a class="link" href="http://open-std.org/JTC1/SC22/WG21/docs/papers/2015/p0013r1.html" target="_top">
P0013R1
</a>
</td><td align="left">Logical Operator Type Traits (revision 1)</td><td align="left">Y</td><td align="left">Library Fundamentals 2 TS</td></tr></tbody></table></div></div><br class="table-break" /><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="iso.2017.specific"></a>Implementation Specific Behavior</h4></div></div></div><p>For behaviour which is also specified by previous standards,
</td><td align="left">Logical Operator Type Traits (revision 1)</td><td align="left">Y</td><td align="left">Library Fundamentals 2 TS</td></tr><tr><td align="left">
<a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4531.html" target="_top">
N4531
</a>
</td><td align="left">std::rand replacement, revision 3</td><td align="left">Y</td><td align="left">Library Fundamentals 2 TS</td></tr></tbody></table></div></div><br class="table-break" /><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="iso.2017.specific"></a>Implementation Specific Behavior</h4></div></div></div><p>For behaviour which is also specified by previous standards,
see <a class="link" href="status.html#iso.1998.specific" title="Implementation Specific Behavior">C++ 1998/2003 Implementation
Specific Behavior</a> and <a class="link" href="status.html#iso.2011.specific" title="Implementation Specific Behavior">C++
2011 Implementation Specific Behavior</a>. This section only

View File

@ -464,12 +464,15 @@ cat 27_io/objects/char/3_xin.in | a.out</pre></dd><dt><span class="term"><code c
possible variations.
</p><p>
Similarly, tests which depend on a newer standard than the default
should use <code class="literal">dg-options</code> instead of an effective target,
so that they are not skipped by default.
must use <code class="literal">dg-options</code> instead of (or in addition to)
an effective target, so that they are not skipped by default.
For example, tests for C++17 features should use
</p><pre class="programlisting"> // { dg-options "-std=gnu++17" }</pre><p>
and not
</p><pre class="programlisting"> // { dg-do run "c++1z" }</pre><p>
before any <code class="literal">dg-do</code> such as:
</p><pre class="programlisting"> // { dg-do run "c++17" }</pre><p>
The <code class="literal">dg-options</code> directive must come first, so that
the <code class="literal">-std</code> flag has already been added to the options
before checking the <code class="literal">c++17</code> target.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="tests.dg.examples"></a>Examples of Test Directives</h4></div></div></div><p>
Example 1: Testing compilation only:
</p><pre class="programlisting">

File diff suppressed because one or more lines are too long

View File

@ -763,12 +763,15 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
<para>
Similarly, tests which depend on a newer standard than the default
should use <literal>dg-options</literal> instead of an effective target,
so that they are not skipped by default.
must use <literal>dg-options</literal> instead of (or in addition to)
an effective target, so that they are not skipped by default.
For example, tests for C++17 features should use
<programlisting> // { dg-options "-std=gnu++17" }</programlisting>
and not
<programlisting> // { dg-do run "c++1z" }</programlisting>
before any <literal>dg-do</literal> such as:
<programlisting> // { dg-do run "c++17" }</programlisting>
The <literal>dg-options</literal> directive must come first, so that
the <literal>-std</literal> flag has already been added to the options
before checking the <literal>c++17</literal> target.
</para>
<section xml:id="tests.dg.examples"><info><title>Examples of Test Directives</title></info>

View File

@ -128,7 +128,7 @@
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
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>
@ -140,16 +140,24 @@
<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 (TR1, C++ ABI, and Extensions).
Headers), and all others (TS, TR1, C++ ABI, and Extensions).
</para>
<para>
Two dialects of standard headers are supported, corresponding to
the 1998 standard as updated for 2003, and the current 2011 standard.
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>
C++98/03 include files. These are available in the default compilation mode, i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
<xref linkend="table.cxx98_headers"/> and
<xref linkend="table.cxx98_cheaders"/> and
<xref linkend="table.cxx98_deprheaders"/>
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">
@ -207,6 +215,7 @@
<row>
<entry><filename class="headerfile">valarray</filename></entry>
<entry><filename class="headerfile">vector</filename></entry>
<entry namest="c3" nameend="c5"/>
</row>
</tbody>
</tgroup>
@ -248,14 +257,38 @@
<entry><filename class="headerfile">ctime</filename></entry>
<entry><filename class="headerfile">cwchar</filename></entry>
<entry><filename class="headerfile">cwctype</filename></entry>
<entry namest="c4" nameend="c5"/>
</row>
</tbody>
</tgroup>
</table>
<para>
C++11 include files. These are only available in C++11 compilation
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 cols="1" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<tbody>
<row>
<entry><filename class="headerfile">strstream</filename></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.cxx11_headers"/> and
<xref linkend="table.cxx11_cheaders"/> 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/>
@ -271,73 +304,33 @@ mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
<tbody>
<row>
<entry><filename class="headerfile">algorithm</filename></entry>
<entry><filename class="headerfile">array</filename></entry>
<entry><filename class="headerfile">bitset</filename></entry>
<entry><filename class="headerfile">atomic</filename></entry>
<entry><filename class="headerfile">chrono</filename></entry>
<entry><filename class="headerfile">complex</filename></entry>
</row>
<row>
<entry><filename class="headerfile">codecvt</filename></entry>
<entry><filename class="headerfile">condition_variable</filename></entry>
<entry><filename class="headerfile">deque</filename></entry>
<entry><filename class="headerfile">exception</filename></entry>
<entry><filename class="headerfile">forward_list</filename></entry>
<entry><filename class="headerfile">fstream</filename></entry>
</row>
<row>
<entry><filename class="headerfile">functional</filename></entry>
<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">iomanip</filename></entry>
<entry><filename class="headerfile">ios</filename></entry>
</row>
<row>
<entry><filename class="headerfile">iosfwd</filename></entry>
<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>
</row>
<row>
<entry><filename class="headerfile">list</filename></entry>
<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">mutex</filename></entry>
</row>
<row>
<entry><filename class="headerfile">new</filename></entry>
<entry><filename class="headerfile">numeric</filename></entry>
<entry><filename class="headerfile">ostream</filename></entry>
<entry><filename class="headerfile">queue</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">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">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">typeinfo</filename></entry>
<entry><filename class="headerfile">unordered_map</filename></entry>
<entry><filename class="headerfile">unordered_set</filename></entry>
</row>
<row>
<entry><filename class="headerfile">utility</filename></entry>
<entry><filename class="headerfile">valarray</filename></entry>
<entry><filename class="headerfile">vector</filename></entry>
</row>
</tbody>
</tgroup>
@ -356,39 +349,231 @@ mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
<colspec colname="c5"/>
<tbody>
<row>
<entry><filename class="headerfile">cassert</filename></entry>
<entry><filename class="headerfile">ccomplex</filename></entry>
<entry><filename class="headerfile">cctype</filename></entry>
<entry><filename class="headerfile">cerrno</filename></entry>
<entry><filename class="headerfile">cfenv</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cfloat</filename></entry>
<entry><filename class="headerfile">cinttypes</filename></entry>
<entry><filename class="headerfile">ciso646</filename></entry>
<entry><filename class="headerfile">climits</filename></entry>
<entry><filename class="headerfile">clocale</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cmath</filename></entry>
<entry><filename class="headerfile">csetjmp</filename></entry>
<entry><filename class="headerfile">csignal</filename></entry>
<entry><filename class="headerfile">cstdarg</filename></entry>
<entry><filename class="headerfile">cstdalign</filename></entry>
<entry><filename class="headerfile">cstdbool</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cstddef</filename></entry>
<entry><filename class="headerfile">cstdint</filename></entry>
<entry><filename class="headerfile">cstdlib</filename></entry>
<entry><filename class="headerfile">cstdio</filename></entry>
<entry><filename class="headerfile">cstring</filename></entry>
<entry><filename class="headerfile">ctgmath</filename></entry>
<entry><filename class="headerfile">cuchar</filename></entry>
<entry namest="c4" nameend="c5"/>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.cxx14_headers"/> 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/>
<table frame="all" xml:id="table.cxx14_headers">
<title>C++ 2014 Library Header</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<tbody>
<row>
<entry><filename class="headerfile">shared_mutex</filename></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.cxx17_headers"/> 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/>
<table frame="all" xml:id="table.cxx17_headers">
<title>C++ 2017 Library Headers</title>
<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<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 namest="c4" nameend="c5"/>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.cxx20_headers"/>
shows the C++2a include files.
These are available in C++2a compilation
mode, i.e. <literal>-std=c++2a</literal> or <literal>-std=gnu++2a</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/>
<table frame="all" xml:id="table.cxx20_headers">
<title>C++ 2020 Library Headers</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<!--
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
-->
<tbody>
<row>
<entry><filename class="headerfile">bit</filename></entry>
<entry><filename class="headerfile">version</filename></entry>
</row>
<!-- TODO compare, concepts, contract, span, syncstream -->
</tbody>
</tgroup>
</table>
<para>
The following headers have been removed in the C++2a working draft.
They are still available when using this implementation, but in future
they might start to produce warnings or errors when included in C++2a 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 cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<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>
<entry><filename class="headerfile">ctime</filename></entry>
<entry><filename class="headerfile">cuchar</filename></entry>
<entry><filename class="headerfile">cwchar</filename></entry>
<entry><filename class="headerfile">cwctype</filename></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.filesystemts_headers"/>,
shows the additional include file define by the
File System Technical Specification, ISO/IEC TS 18822.
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/>
<table frame="all" xml:id="table.filesystemts_headers">
<title>File System TS Header</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<tbody>
<row>
<entry><filename class="headerfile">experimental/filesystem</filename></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="table.libfundts_headers"/>,
shows the additional include files define by the C++ Extensions for
Library Fundamentals Technical Specification, ISO/IEC TS 19568.
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/>
<table frame="all" xml:id="table.libfundts_headers">
<title>Library Fundamentals TS Headers</title>
<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<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/optional</filename></entry>
<entry><filename class="headerfile">experimental/propagate_const</filename></entry>
<entry><filename class="headerfile">experimental/random</filename></entry>
</row>
<row>
<entry><filename class="headerfile">experimental/ratio</filename></entry>
<entry><filename class="headerfile">experimental/regex</filename></entry>
<entry><filename class="headerfile">experimental/set</filename></entry>
<entry><filename class="headerfile">experimental/source_location</filename></entry>
<entry><filename class="headerfile">experimental/string</filename></entry>
</row>
<row>
<entry><filename class="headerfile">experimental/string_view</filename></entry>
<entry><filename class="headerfile">experimental/ssytem_error</filename></entry>
<entry><filename class="headerfile">experimental/tuple</filename></entry>
<entry><filename class="headerfile">experimental/type_traits</filename></entry>
<entry><filename class="headerfile">experimental/unordered_map</filename></entry>
</row>
<row>
<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>
<entry namest="c4" nameend="c5"/>
</row>
</tbody>
</tgroup>
@ -426,6 +611,7 @@ mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
</row>
<row>
<entry><filename class="headerfile">tr1/utility</filename></entry>
<entry namest="c2" nameend="c5"/>
</row>
</tbody>
@ -566,6 +752,7 @@ compiler supports scalar decimal floating-point types defined via
</row>
<row>
<entry><filename class="headerfile">ext/vstring.h</filename></entry>
<entry namest="c2" nameend="c5"/>
</row>
</tbody>
@ -586,18 +773,22 @@ compiler supports scalar decimal floating-point types defined via
<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>
</row>
<row>
<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 namest="c2" nameend="c5"/>
</row>
</tbody>