From: Jonathan Wakely <jwakely@redhat.com>
Date: Fri, 20 Sep 2024 16:35:48 +0000 (+0100)
Subject: libstdc++: Document missing features for old std:string ABI [PR116777]
X-Git-Tag: basepoints/gcc-16~5807
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=82309222300acf68e345b32155df21e1b876144e;p=thirdparty%2Fgcc.git

libstdc++: Document missing features for old std:string ABI [PR116777]

There are several features that are not supported when using the old
std::string ABI. It's possible that PR 81967 will get fixed, but the
missing C++20 features almost certainly won't be. Document this in the
manual.

libstdc++-v3/ChangeLog:

	PR libstdc++/116777
	* doc/xml/manual/using.xml: Document features that are not
	supported for the gcc4-compatible ABI.
	* doc/html/manual/using_dual_abi.html: Regenerate.
---

diff --git a/libstdc++-v3/doc/html/manual/using_dual_abi.html b/libstdc++-v3/doc/html/manual/using_dual_abi.html
index 916ac575f64..939eedae362 100644
--- a/libstdc++-v3/doc/html/manual/using_dual_abi.html
+++ b/libstdc++-v3/doc/html/manual/using_dual_abi.html
@@ -22,7 +22,7 @@
   of the macro is <code class="literal">1</code> which causes the new ABI to be active,
   so to use the old ABI you must explicitly define the macro to
   <code class="literal">0</code> before including any library headers.
-  (Be aware that some GNU/Linux distributions configure GCC 5 differently so
+  (Be aware that some GNU/Linux distributions configured GCC 5 differently so
   that the default value of the macro is <code class="literal">0</code> and users must
   define it to <code class="literal">1</code> to enable the new ABI.)
 </p><p> Although the changes were made for C++11 conformance, the choice of ABI
@@ -72,6 +72,22 @@
   Handlers for <code class="classname">std::exception</code> will always catch
   iostreams exceptions, because the old and new type both inherit from
   <code class="classname">std::exception</code>.
+</p><p>
+  Some features are not supported when using the old ABI, including:
+  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+    Using <code class="classname">std::string::const_iterator</code> for
+    positional arguments to member functions such as
+    <code class="function">std::string::erase</code>.
+  </li><li class="listitem">
+    Allocator propagation in <code class="classname">std::string</code>.
+  </li><li class="listitem">
+    Using <code class="classname">std::string</code> at compile-time in
+    <code class="code">constexpr</code> functions.
+  </li><li class="listitem">
+    Class <code class="classname">std::chrono::time_zone</code> and all related APIs.
+  </li><li class="listitem">
+    The <code class="filename">&lt;syncstream&gt;</code> header.
+  </li></ul></div><p>
 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.abi.trouble"></a>Troubleshooting</h3></div></div></div><p> If you get linker errors about undefined references to symbols
   that involve types in the <code class="code">std::__cxx11</code> namespace or the tag
   <code class="code">[abi:cxx11]</code> then it probably indicates that you are trying to
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index 4e1c70040b5..89119f6fb2d 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -1368,7 +1368,7 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
   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 configure GCC 5 differently so
+  (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>
@@ -1428,6 +1428,30 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
   <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 xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>
 
 <para> If you get linker errors about undefined references to symbols