Improve implementation-defined docs for libstdc++
authorJonathan Wakely <jwakely@redhat.com>
Fri, 7 Oct 2016 18:02:53 +0000 (19:02 +0100)
committerJonathan Wakely <redi@gcc.gnu.org>
Fri, 7 Oct 2016 18:02:53 +0000 (19:02 +0100)
* 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.

From-SVN: r240869

libstdc++-v3/ChangeLog
libstdc++-v3/doc/xml/manual/status_cxx1998.xml
libstdc++-v3/doc/xml/manual/status_cxx2011.xml
libstdc++-v3/doc/xml/manual/status_cxx2017.xml

index 68f1b516647eedbbc80ff02579020c70a123a604..187c59e99b4840b571d9600a6c02d8a988405ac3 100644 (file)
@@ -1,5 +1,10 @@
 2016-10-07  Jonathan Wakely  <jwakely@redhat.com>
 
+       * 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.
+
        * doc/xml/manual/status_cxx2017.xml: Update status.
        * include/std/type_traits (has_unique_object_representations): Define.
        * testsuite/20_util/has_unique_object_representations/value.cc: New.
index 1679ee0c80877372bfa16f5dedece77299ae82aa..6afb016a45fe09595de19045141f53616d7b84a2 100644 (file)
@@ -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>&lt;stdexcept&gt;</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>
index e1b372d643fb2abe7416b044501596c045f06df2..83a266f4760abfb78fcbcbe1dffe959c6bc85827 100644 (file)
@@ -2571,10 +2571,42 @@ particular release.
       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>
-      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>
@@ -2583,6 +2615,18 @@ particular release.
       <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>
@@ -2592,6 +2636,11 @@ particular release.
       The function <function>eof</function> returns <code>int_type(-1)</code>.
    </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>
@@ -2603,6 +2652,13 @@ particular release.
       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>,
@@ -2651,6 +2707,20 @@ particular release.
       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>,
@@ -2665,6 +2735,12 @@ particular release.
       <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
index f1d709ee07142cb262bc410d9215ca82fbe354c3..c03978e5e1fcfbb89e7f983fcceafdef761ba795 100644 (file)
@@ -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&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>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>&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>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>