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.

4 files changed, 77 insertions, 12 deletions

diff --git a/libstdc++-v3/doc/html/manual/debug_mode_semantics.html b/libstdc++-v3/doc/html/manual/debug_mode_semantics.html
index fb84276..35d8aa3 100644
--- a/libstdc++-v3/doc/html/manual/debug_mode_semantics.html
+++ b/libstdc++-v3/doc/html/manual/debug_mode_semantics.html
@@ -35,10 +35,10 @@
   (N.B. In GCC 3.4.x and 4.0.0, due to a bug,
   <code class="code">-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has
   been fixed in GCC 4.0.1 and later versions.) </p><p>The following library components provide extra debugging
-  capabilities in debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li class="listitem"><p><code class="code">std::bitset</code></p></li><li class="listitem"><p><code class="code">std::deque</code></p></li><li class="listitem"><p><code class="code">std::list</code></p></li><li class="listitem"><p><code class="code">std::map</code></p></li><li class="listitem"><p><code class="code">std::multimap</code></p></li><li class="listitem"><p><code class="code">std::multiset</code></p></li><li class="listitem"><p><code class="code">std::set</code></p></li><li class="listitem"><p><code class="code">std::vector</code></p></li><li class="listitem"><p><code class="code">std::unordered_map</code></p></li><li class="listitem"><p><code class="code">std::unordered_multimap</code></p></li><li class="listitem"><p><code class="code">std::unordered_set</code></p></li><li class="listitem"><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations,
+  capabilities in debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="code">std::array</code> (no safe iterators)</p></li><li class="listitem"><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li class="listitem"><p><code class="code">std::bitset</code></p></li><li class="listitem"><p><code class="code">std::deque</code></p></li><li class="listitem"><p><code class="code">std::list</code></p></li><li class="listitem"><p><code class="code">std::map</code></p></li><li class="listitem"><p><code class="code">std::multimap</code></p></li><li class="listitem"><p><code class="code">std::multiset</code></p></li><li class="listitem"><p><code class="code">std::set</code></p></li><li class="listitem"><p><code class="code">std::vector</code></p></li><li class="listitem"><p><code class="code">std::unordered_map</code></p></li><li class="listitem"><p><code class="code">std::unordered_multimap</code></p></li><li class="listitem"><p><code class="code">std::unordered_set</code></p></li><li class="listitem"><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations,
 e.g.  <code class="code">operator[]</code>,
 they will not always be run when using the <code class="code">char</code> and
-<code class="code">wchar_t</code> specialisations (<code class="code">std::string</code> and
+<code class="code">wchar_t</code> specializations (<code class="code">std::string</code> and
 <code class="code">std::wstring</code>).  This is because libstdc++ uses GCC's
 <code class="code">extern template</code> extension to provide explicit instantiations
 of <code class="code">std::string</code> and <code class="code">std::wstring</code>, and those
diff --git a/libstdc++-v3/doc/html/manual/debug_mode_using.html b/libstdc++-v3/doc/html/manual/debug_mode_using.html
index e4f7ea5..4deb498 100644
--- a/libstdc++-v3/doc/html/manual/debug_mode_using.html
+++ b/libstdc++-v3/doc/html/manual/debug_mode_using.html
@@ -18,6 +18,17 @@
   mode or with debug mode. The
   following table provides the names and headers of the debugging
   containers:
-</p><div class="table"><a id="table.debug_mode_containers"></a><p class="title"><strong>Table 17.1. Debugging Containers</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::bitset</code></td><td align="left"><code class="filename">bitset</code></td><td align="left"><code class="classname">__gnu_debug::bitset</code></td><td align="left"><code class="filename">&lt;debug/bitset&gt;</code></td></tr><tr><td align="left"><code class="classname">std::deque</code></td><td align="left"><code class="filename">deque</code></td><td align="left"><code class="classname">__gnu_debug::deque</code></td><td align="left"><code class="filename">&lt;debug/deque&gt;</code></td></tr><tr><td align="left"><code class="classname">std::list</code></td><td align="left"><code class="filename">list</code></td><td align="left"><code class="classname">__gnu_debug::list</code></td><td align="left"><code class="filename">&lt;debug/list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::map</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::map</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multimap</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::multimap</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multiset</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::multiset</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::set</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::set</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::wstring</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::wstring</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::basic_string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::basic_string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::vector</code></td><td align="left"><code class="filename">vector</code></td><td align="left"><code class="classname">__gnu_debug::vector</code></td><td align="left"><code class="filename">&lt;debug/vector&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /><p>In addition, when compiling in C++11 mode, these additional
+</p><div class="table"><a id="table.debug_mode_containers"></a><p class="title"><strong>Table 17.1. Debugging Containers</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::bitset</code></td><td align="left"><code class="filename">bitset</code></td><td align="left"><code class="classname">__gnu_debug::bitset</code></td><td align="left"><code class="filename">&lt;debug/bitset&gt;</code></td></tr><tr><td align="left"><code class="classname">std::deque</code></td><td align="left"><code class="filename">deque</code></td><td align="left"><code class="classname">__gnu_debug::deque</code></td><td align="left"><code class="filename">&lt;debug/deque&gt;</code></td></tr><tr><td align="left"><code class="classname">std::list</code></td><td align="left"><code class="filename">list</code></td><td align="left"><code class="classname">__gnu_debug::list</code></td><td align="left"><code class="filename">&lt;debug/list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::map</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::map</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multimap</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::multimap</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multiset</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::multiset</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::set</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::set</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::wstring</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::wstring</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::basic_string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::basic_string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::vector</code></td><td align="left"><code class="filename">vector</code></td><td align="left"><code class="classname">__gnu_debug::vector</code></td><td align="left"><code class="filename">&lt;debug/vector&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /><p>When compiling in C++11 mode (or newer), these
 containers have additional debug capability.
-</p><div class="table"><a id="table.debug_mode_containers_cxx11"></a><p class="title"><strong>Table 17.2. Debugging Containers C++11</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers C++11" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::array</code></td><td align="left"><code class="filename">array</code></td><td align="left"><code class="classname">__gnu_debug::array</code></td><td align="left"><code class="filename">&lt;debug/array&gt;</code></td></tr><tr><td align="left"><code class="classname">std::forward_list</code></td><td align="left"><code class="filename">forward_list</code></td><td align="left"><code class="classname">__gnu_debug::forward_list</code></td><td align="left"><code class="filename">&lt;debug/forward_list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_map</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_set</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode_semantics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
\ No newline at end of file
+</p><div class="table"><a id="table.debug_mode_containers_cxx11"></a><p class="title"><strong>Table 17.2. Debugging Containers C++11</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers C++11" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::forward_list</code></td><td align="left"><code class="filename">forward_list</code></td><td align="left"><code class="classname">__gnu_debug::forward_list</code></td><td align="left"><code class="filename">&lt;debug/forward_list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_map</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_set</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /><p>Prior to GCC 11 a debug version of <code class="classname">std::array</code>
+was available as <code class="classname">__gnu_debug::array</code> in the
+header <code class="filename">&lt;debug/array&gt;</code>.
+Because <code class="classname">array::iterator</code> is just a pointer,
+the debug <code class="classname">array</code> 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
+<code class="classname">std::array</code>, without needing a separate type,
+so <code class="classname">__gnu_debug::array</code> is just an alias for
+<code class="classname">std::array</code>.
+That alias is deprecated and may be removed in a future release.
+</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode_semantics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
\ No newline at end of file
diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml
index 883e8cb..dbd5c2b 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>
 
@@ -286,12 +287,6 @@ containers have additional debug capability.
 </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>
     <entry><classname>__gnu_debug::forward_list</classname></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 0000000..5cb51df
--- /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