[committed] libstdc++: Restore __gnu_debug::array [PR100682]

[committed] libstdc++: Restore __gnu_debug::array [PR100682]

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 876 bytes --]

As the PR points out, we removed the debug version of std::array without
any period of deprecation. Although std::array contains all the actual
debug checks now, removing the <debug/arrray> header breaks any code
that was using that explicitly. The manual still lists doing that as
supported.

This restores the <debug/array> header, but simply defines
__gnu_debug::array as an alias for std::array, and declares the alias
with the deprecated attribute. The docs are updated to match.

Signed-off-by: Jonathan Wakely <jwakely@redhat.com>

libstdc++-v3/ChangeLog:

	PR libstdc++/100682
	* doc/xml/manual/debug_mode.xml: Update documentation about
	debug capability of std::array.
	* doc/html/*: Regenerate.
	* include/debug/array: New file.

Tested powerpc64le-linux. Committed to trunk.

This should be backported to gcc-11 branch too, but I'll do it after
the 11.2 release.


[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 5655 bytes --]

commit 254e5d19a177af23a77b67fd51d0d1a25eaabfc7
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Jul 22 11:45:32 2021

    libstdc++: Restore __gnu_debug::array [PR100682]
    
    As the PR points out, we removed the debug version of std::array without
    any period of deprecation. Although std::array contains all the actual
    debug checks now, removing the <debug/arrray> header breaks any code
    that was using that explicitly. The manual still lists doing that as
    supported.
    
    This restores the <debug/array> header, but simply defines
    __gnu_debug::array as an alias for std::array, and declares the alias
    with the deprecated attribute. The docs are updated to match.
    
    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
    
    libstdc++-v3/ChangeLog:
    
            PR libstdc++/100682
            * doc/xml/manual/debug_mode.xml: Update documentation about
            debug capability of std::array.
            * doc/html/*: Regenerate.
            * include/debug/array: New file.

diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml
index 883e8cb4f03..dbd5c2b7775 100644
--- a/libstdc++-v3/doc/xml/manual/debug_mode.xml
+++ b/libstdc++-v3/doc/xml/manual/debug_mode.xml
@@ -104,6 +104,7 @@
 <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>
@@ -122,7 +123,7 @@
 <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> specialisations (<code>std::string</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
@@ -263,7 +264,7 @@ which always works correctly.
 </tgroup>
 </table>
 
-<para>In addition, when compiling in C++11 mode, these additional
+<para>When compiling in C++11 mode (or newer), these
 containers have additional debug capability.
 </para>
 
@@ -285,12 +286,6 @@ containers have additional debug capability.
   </row>
 </thead>
 <tbody>
-  <row>
-    <entry><classname>std::array</classname></entry>
-    <entry><filename class="headerfile">array</filename></entry>
-    <entry><classname>__gnu_debug::array</classname></entry>
-    <entry><filename class="headerfile">&lt;debug/array&gt;</filename></entry>
-  </row>
   <row>
     <entry><classname>std::forward_list</classname></entry>
     <entry><filename class="headerfile">forward_list</filename></entry>
@@ -324,6 +319,20 @@ containers have additional debug capability.
 </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>
 
diff --git a/libstdc++-v3/include/debug/array b/libstdc++-v3/include/debug/array
new file mode 100644
index 00000000000..5cb51dfe8b5
--- /dev/null
+++ b/libstdc++-v3/include/debug/array
@@ -0,0 +1,45 @@
+// Redeclaration of std::array in debug namespace -*- C++ -*-
+
+// Copyright (C) 2021 Free Software Foundation, Inc.
+//
+// This file is part of the GNU ISO C++ Library.  This library is free
+// software; you can redistribute it and/or modify it under the
+// terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 3, or (at your option)
+// any later version.
+
+// This library 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
+// GNU General Public License for more details.
+
+// Under Section 7 of GPL version 3, you are granted additional
+// permissions described in the GCC Runtime Library Exception, version
+// 3.1, as published by the Free Software Foundation.
+
+// You should have received a copy of the GNU General Public License and
+// a copy of the GCC Runtime Library Exception along with this program;
+// see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
+// <http://www.gnu.org/licenses/>.
+
+/** @file debug/array
+ *  This file is a GNU debug extension to the Standard C++ Library.
+ */
+
+#ifndef _GLIBCXX_DEBUG_ARRAY
+#define _GLIBCXX_DEBUG_ARRAY 1
+
+#pragma GCC system_header
+
+#include <array>
+
+namespace __gnu_debug
+{
+  template<typename _Tp, std::size_t _Nm>
+    using array _GLIBCXX_DEPRECATED_SUGGEST("std::array")
+      = std::array<_Tp, _Nm>;
+
+  using std::get;
+  using std::swap;
+}
+#endif // _GLIBCXX_DEBUG_ARRAY