We're required to document anything the standard says is
implementation-defined. This adds a few missing things to the C++98
and C++11 docs, and adds the new stuff for C++17.
I'll regenerate the HTML soon, as I'll be making some more doc changes
next week.
* doc/xml/manual/status_cxx1998.xml: Improve documentation of
implementation-defined properties.
* doc/xml/manual/status_cxx2011.xml: Likewise.
* doc/xml/manual/status_cxx2017.xml: Likewise.
Committed to trunk. I'll backport the relevant parts to the branches
too.
commit f31956238e6e47f44a333e48fc903c6b6b6f8835
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Fri Oct 7 16:17:28 2016 +0100
Improve implementation-defined docs for libstdc++
* doc/xml/manual/status_cxx1998.xml: Improve documentation of
implementation-defined properties.
* doc/xml/manual/status_cxx2011.xml: Likewise.
* doc/xml/manual/status_cxx2017.xml: Likewise.
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
index 1679ee0..6afb016 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
@@ -1087,19 +1087,14 @@ particular release.
<emphasis>[18.6.1]/8</emphasis> (exception),
<emphasis>[18.6.2.1]/5</emphasis> (bad_exception): The
<code>what()</code>
member function of class <code>std::exception</code>, and these other
- classes publicly derived from it, simply returns the name of the
- class. But they are the <emphasis>mangled</emphasis> names; 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>.
- (The classes in <code><stdexcept></code> have constructors which
- require an argument to use later for <code>what()</code> calls, so the
- problem of <code>what()</code>'s value does not arise in most
- user-defined exceptions.)
+ classes publicly derived from it, returns the name of the
+ class, e.g. <literal>"std::bad_alloc"</literal>.
</para>
<para><emphasis>[18.5.1]/7</emphasis> The return value of
- <code>std::type_info::name()</code> is the mangled type name (see the
- previous entry for more).
+ <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]/5</emphasis> <emphasis>"Implementors are
encouraged to
supply libraries that can accept allocators that encapsulate more
@@ -1114,6 +1109,7 @@ particular release.
</para>
<para><emphasis>[21.1.3.1]/3,4</emphasis>,
<emphasis>[21.1.3.2]/2</emphasis>,
+ <emphasis>[21.3]/6 basic_string::iterator,
basic_string::const_iterator</emphasis>,
<emphasis>[23.*]'s foo::iterator</emphasis>,
<emphasis>[27.*]'s foo::*_type</emphasis>,
<emphasis>others...</emphasis>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
index e1b372d..83a266f 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -2572,9 +2572,41 @@ particular release.
</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>
- Only <classname>bad_alloc</classname> (or types derived from it) will
- be thrown.
+ 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>
@@ -2584,6 +2616,18 @@ particular release.
</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
@@ -2593,6 +2637,11 @@ particular release.
</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.
@@ -2604,6 +2653,13 @@ particular release.
</para>
<para>
+ <emphasis>23.3.2.1 [array.overview]</emphasis>
+ <classname>array<T, N>::iterator</classname> is <code>T*</code> and
+ <classname>array<T, N>::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>,
@@ -2652,6 +2708,20 @@ particular release.
</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>
@@ -2666,6 +2736,12 @@ particular release.
</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
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
index f1d709e..c03978e 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
@@ -876,4 +876,112 @@ Feature-testing recommendations for C++</link>.
</tgroup>
</table>
+<section xml:id="iso.2017.specific" xreflabel="Implementation
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.6.5 [optional.bad_optional_access]</emphasis>
+ <code>what()</code> returns <literal>"bad optional access"</literal>.
+ </para>
+
+ <para>
+ <emphasis>20.7.2 [variant.variant]</emphasis>
+ Whether <classname>variant</classname> supports over-aligned types
+ should be documented here.
+ </para>
+
+ <para>
+ <emphasis>20.7.10 [variant.bad.access]</emphasis>
+ <code>what()</code> returns <literal>"Unexpected index"</literal>.
+ </para>
+
+ <para>
+ <emphasis>20.12.5.2 [memory.resource.pool.options]</emphasis>
+ The limits for maximum number of blocks and largest allocation size
+ supported by <classname>pool_options</classname> should be documented
+ here.
+ </para>
+
+ <para>
+ <emphasis>20.12.6.1 [memory.resource.monotonic.buffer.ctor]</emphasis>
+ The default <code>next_buffer_size</code> and growth factor should
+ be documented here.
+ </para>
+
+ <para>
+ <emphasis>20.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>20.19.3 [execpol.type],
+ 25.2.3 [algorithms.parallel.exec]</emphasis>
+ There are no implementation-defined execution policies.
+ </para>
+
+ <para>
+ <emphasis>22.4.2 [string.view.template]</emphasis>
+ <classname>basic_string_view<C, T>::iterator</classname> is
+ <code>C*</code> and
+ <classname>basic_string_view<C, T>::const_iterator</classname> is
+ <code>const C*</code>.
+ </para>
+
+
+ <para>
+ <emphasis>25.2.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>26.4.1 [cfenv.syn]</emphasis>
+ The effects of the <filename><cfenv></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>26.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>26.9.5 [sf.cmath]</emphasis>
+ The effect of calling the mathematical special functions with large
+ inputs should be documented here.
+ </para>
+
+ <para>
+ <emphasis>27.10.2.1 [fs.conform.9945]</emphasis>
+ The behavior of the filesystem library implementation will depend on
+ the target operating system. Some features will not be not supported
+ on some targets.
+ </para>
+
+ <para>
+ <emphasis>27.10.6 [fs.filesystem.syn]</emphasis>
+ The clock used for file times is
+ <classname>std::chrono::system_clock</classname>.
+ </para>
+
+ <para>
+ <emphasis>27.10.8 [path.generic]</emphasis>
+ dot-dot in the root-directory refers to the root-directory itself.
+ </para>
+
+
+</section>
+
</section>
