[libc++] <sstream>: update references to standard paragraphs

[rupe]

Summary

The paragraph numbers used previously did not match the C++20 nor
C++17 standards. I have updated them to the textual dotted names to
avoid this problem in future.

libcxx/include/sstream

 // -*- C++ -*-
 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP_SSTREAM
 #define _LIBCPP_SSTREAM
 
 /*
-    sstream synopsis
+    sstream synopsis [sstream.syn]
 
+// Class template basic_stringbuf [stringbuf]
 template <class charT, class traits = char_traits<charT>, class Allocator = allocator<charT> >
 class basic_stringbuf
     : public basic_streambuf<charT, traits>
 {
 public:
     typedef charT                          char_type;
     typedef traits                         traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef Allocator                      allocator_type;
 
-    // 27.8.1.1 [stringbuf.cons], constructors:
+    // [stringbuf.cons] constructors:
     explicit basic_stringbuf(ios_base::openmode which = ios_base::in | ios_base::out); // before C++20
     basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}               // C++20
     explicit basic_stringbuf(ios_base::openmode which);                                // C++20
     explicit basic_stringbuf(const basic_string<char_type, traits_type, allocator_type>& str,
                              ios_base::openmode which = ios_base::in | ios_base::out);
     basic_stringbuf(basic_stringbuf&& rhs);
 
-    // 27.8.1.2 Assign and swap:
+    // [stringbuf.assign] Assign and swap:
     basic_stringbuf& operator=(basic_stringbuf&& rhs);
     void swap(basic_stringbuf& rhs);
 
-    // 27.8.1.3 Get and set:
+    // [stringbuf.members] Member functions:
     basic_string<char_type, traits_type, allocator_type> str() const;
     void str(const basic_string<char_type, traits_type, allocator_type>& s);
 
 protected:
-    // 27.8.1.4 Overridden virtual functions:
+    // [stringbuf.virtuals] Overridden virtual functions:
     virtual int_type underflow();
     virtual int_type pbackfail(int_type c = traits_type::eof());
     virtual int_type overflow (int_type c = traits_type::eof());
     virtual basic_streambuf<char_type, traits_type>* setbuf(char_type*, streamsize);
     virtual pos_type seekoff(off_type off, ios_base::seekdir way,
                              ios_base::openmode which = ios_base::in | ios_base::out);
     virtual pos_type seekpos(pos_type sp,
                              ios_base::openmode which = ios_base::in | ios_base::out);
 };
 
+// [stringbuf.assign] non member swap
 template <class charT, class traits, class Allocator>
   void swap(basic_stringbuf<charT, traits, Allocator>& x,
             basic_stringbuf<charT, traits, Allocator>& y);
 
 typedef basic_stringbuf<char>    stringbuf;
 typedef basic_stringbuf<wchar_t> wstringbuf;
 
+// Class template basic_istringstream [istringstream]
 template <class charT, class traits = char_traits<charT>, class Allocator = allocator<charT> >
 class basic_istringstream
     : public basic_istream<charT, traits>
 {
 public:
     typedef charT                          char_type;
     typedef traits                         traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef Allocator                      allocator_type;
 
-    // 27.8.2.1 Constructors:
+    // [istringstream.cons] Constructors:
     explicit basic_istringstream(ios_base::openmode which = ios_base::in); // before C++20
     basic_istringstream() : basic_istringstream(ios_base::in) {}           // C++20
     explicit basic_istringstream(ios_base::openmode which);                // C++20
 
     explicit basic_istringstream(const basic_string<char_type, traits_type,allocator_type>& str,
                                  ios_base::openmode which = ios_base::in);
     basic_istringstream(basic_istringstream&& rhs);
 
-    // 27.8.2.2 Assign and swap:
+    // [istringstream.assign] Assign and swap:
     basic_istringstream& operator=(basic_istringstream&& rhs);
     void swap(basic_istringstream& rhs);
 
-    // 27.8.2.3 Members:
+    // [istringstream.members] Member functions:
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const;
     basic_string<char_type, traits_type, allocator_type> str() const;
     void str(const basic_string<char_type, traits_type, allocator_type>& s);
 };
 
 template <class charT, class traits, class Allocator>
   void swap(basic_istringstream<charT, traits, Allocator>& x,
             basic_istringstream<charT, traits, Allocator>& y);
 
 typedef basic_istringstream<char>    istringstream;
 typedef basic_istringstream<wchar_t> wistringstream;
 
+// Class template basic_ostringstream [ostringstream]
 template <class charT, class traits = char_traits<charT>, class Allocator = allocator<charT> >
 class basic_ostringstream
     : public basic_ostream<charT, traits>
 {
 public:
     // types:
     typedef charT                          char_type;
     typedef traits                         traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef Allocator                      allocator_type;
 
-    // 27.8.3.1 Constructors/destructor:
+    // [ostringstream.cons] Constructors:
     explicit basic_ostringstream(ios_base::openmode which = ios_base::out); // before C++20
     basic_ostringstream() : basic_ostringstream(ios_base::out) {}           // C++20
     explicit basic_ostringstream(ios_base::openmode which);                 // C++20
 
     explicit basic_ostringstream(const basic_string<char_type, traits_type, allocator_type>& str,
                                  ios_base::openmode which = ios_base::out);
     basic_ostringstream(basic_ostringstream&& rhs);
 
-    // 27.8.3.2 Assign/swap:
+    // [ostringstream.assign] Assign and swap:
     basic_ostringstream& operator=(basic_ostringstream&& rhs);
     void swap(basic_ostringstream& rhs);
 
-    // 27.8.3.3 Members:
+    // [ostringstream.members] Member functions:
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const;
     basic_string<char_type, traits_type, allocator_type> str() const;
     void str(const basic_string<char_type, traits_type, allocator_type>& s);
 };
 
 template <class charT, class traits, class Allocator>
   void swap(basic_ostringstream<charT, traits, Allocator>& x,
             basic_ostringstream<charT, traits, Allocator>& y);
 
 typedef basic_ostringstream<char>    ostringstream;
 typedef basic_ostringstream<wchar_t> wostringstream;
 
+// Class template basic_stringstream [stringstream]
 template <class charT, class traits = char_traits<charT>, class Allocator = allocator<charT> >
 class basic_stringstream
     : public basic_iostream<charT, traits>
 {
 public:
     // types:
     typedef charT                          char_type;
     typedef traits                         traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef Allocator                      allocator_type;
 
-    // constructors/destructor
+    // [stringstream.cons] constructors
     explicit basic_stringstream(ios_base::openmode which = ios_base::out | ios_base::in); // before C++20
     basic_stringstream() : basic_stringstream(ios_base::out | ios_base::in) {}            // C++20
     explicit basic_stringstream(ios_base::openmode which);                                // C++20
 
     explicit basic_stringstream(const basic_string<char_type, traits_type, allocator_type>& str,
                                 ios_base::openmode which = ios_base::out|ios_base::in);
     basic_stringstream(basic_stringstream&& rhs);
 
-    // 27.8.5.1 Assign/swap:
+    // [stringstream.assign] Assign and swap:
     basic_stringstream& operator=(basic_stringstream&& rhs);
     void swap(basic_stringstream& rhs);
 
-    // Members:
+    // [stringstream.members] Member functions:
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const;
     basic_string<char_type, traits_type, allocator_type> str() const;
     void str(const basic_string<char_type, traits_type, allocator_type>& str);
 };
 
 template <class charT, class traits, class Allocator>
   void swap(basic_stringstream<charT, traits, Allocator>& x,
             basic_stringstream<charT, traits, Allocator>& y);

 #endif
 
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 
-// basic_stringbuf
+// Class template basic_stringbuf [stringbuf]
 
 template <class _CharT, class _Traits, class _Allocator>
 class _LIBCPP_TEMPLATE_VIS basic_stringbuf
     : public basic_streambuf<_CharT, _Traits>
 {
 public:
     typedef _CharT                         char_type;
     typedef _Traits                        traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef _Allocator                     allocator_type;
 
     typedef basic_string<char_type, traits_type, allocator_type> string_type;
 
 private:
 
     string_type __str_;
     mutable char_type* __hm_;
     ios_base::openmode __mode_;
 
 public:
-    // 30.8.2.1 [stringbuf.cons], constructors
+    // [stringbuf.cons] constructors:
     _LIBCPP_INLINE_VISIBILITY
     basic_stringbuf()
         : __hm_(nullptr), __mode_(ios_base::in | ios_base::out) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_stringbuf(ios_base::openmode __wch)
         : __hm_(nullptr), __mode_(__wch) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_stringbuf(const string_type& __s,
                              ios_base::openmode __wch = ios_base::in | ios_base::out)
         : __str_(__s.get_allocator()), __hm_(nullptr), __mode_(__wch)
     {
         str(__s);
     }
 
     basic_stringbuf(basic_stringbuf&& __rhs);
 
-    // 27.8.1.2 Assign and swap:
+    // [stringbuf.assign] Assign and swap:
     basic_stringbuf& operator=(basic_stringbuf&& __rhs);
     void swap(basic_stringbuf& __rhs);
 
-    // 27.8.1.3 Get and set:
+    // [stringbuf.members] Member functions:
     string_type str() const;
     void str(const string_type& __s);
 
 protected:
-    // 27.8.1.4 Overridden virtual functions:
+    // [stringbuf.virtuals] Overridden virtual functions:
     int_type underflow() override;
     int_type pbackfail(int_type __c = traits_type::eof()) override;
     int_type overflow (int_type __c = traits_type::eof()) override;
     pos_type seekoff(off_type __off, ios_base::seekdir __way,
                      ios_base::openmode __wch = ios_base::in | ios_base::out) override;
     _LIBCPP_INLINE_VISIBILITY
     pos_type seekpos(pos_type __sp,
                      ios_base::openmode __wch = ios_base::in | ios_base::out) override {
basic_stringbuf<_CharT, _Traits, _Allocator>::seekoff(off_type __off,
     if (__wch & ios_base::out)
     {
         this->setp(this->pbase(), this->epptr());
         this->pbump(__noff);
     }
     return pos_type(__noff);
 }
 
-// basic_istringstream
+// Class template basic_istringstream [istringstream]
 
 template <class _CharT, class _Traits, class _Allocator>
 class _LIBCPP_TEMPLATE_VIS basic_istringstream
     : public basic_istream<_CharT, _Traits>
 {
 public:
     typedef _CharT                         char_type;
     typedef _Traits                        traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef _Allocator                     allocator_type;
 
     typedef basic_string<char_type, traits_type, allocator_type> string_type;
 
 private:
     basic_stringbuf<char_type, traits_type, allocator_type> __sb_;
 
 public:
-    // 30.8.3.1 [istringstream.cons], constructors
+    // [istringstream.cons] Constructors:
     _LIBCPP_INLINE_VISIBILITY
     basic_istringstream()
         : basic_istream<_CharT, _Traits>(&__sb_), __sb_(ios_base::in) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_istringstream(ios_base::openmode __wch)
         : basic_istream<_CharT, _Traits>(&__sb_), __sb_(__wch | ios_base::in) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_istringstream(const string_type& __s,
                                  ios_base::openmode __wch = ios_base::in)
         : basic_istream<_CharT, _Traits>(&__sb_)
         , __sb_(__s, __wch | ios_base::in)
     { }
 
     _LIBCPP_INLINE_VISIBILITY
     basic_istringstream(basic_istringstream&& __rhs)
         : basic_istream<_CharT, _Traits>(_VSTD::move(__rhs))
         , __sb_(_VSTD::move(__rhs.__sb_))
     {
         basic_istream<_CharT, _Traits>::set_rdbuf(&__sb_);
     }
 
-    // 27.8.2.2 Assign and swap:
+    // [istringstream.assign] Assign and swap:
     basic_istringstream& operator=(basic_istringstream&& __rhs) {
         basic_istream<char_type, traits_type>::operator=(_VSTD::move(__rhs));
         __sb_ = _VSTD::move(__rhs.__sb_);
         return *this;
     }
     _LIBCPP_INLINE_VISIBILITY
     void swap(basic_istringstream& __rhs) {
         basic_istream<char_type, traits_type>::swap(__rhs);
         __sb_.swap(__rhs.__sb_);
     }
 
-    // 27.8.2.3 Members:
+    // [istringstream.members] Member functions:
     _LIBCPP_INLINE_VISIBILITY
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const {
         return const_cast<basic_stringbuf<char_type, traits_type, allocator_type>*>(&__sb_);
     }
     _LIBCPP_INLINE_VISIBILITY
     string_type str() const {
         return __sb_.str();
     }
     _LIBCPP_INLINE_VISIBILITY
     void str(const string_type& __s) {
         __sb_.str(__s);
     }
 };
 
 template <class _CharT, class _Traits, class _Allocator>
 inline _LIBCPP_INLINE_VISIBILITY
 void
 swap(basic_istringstream<_CharT, _Traits, _Allocator>& __x,
      basic_istringstream<_CharT, _Traits, _Allocator>& __y)
 {
     __x.swap(__y);
 }
 
-// basic_ostringstream
+// Class template basic_ostringstream [ostringstream]
 
 template <class _CharT, class _Traits, class _Allocator>
 class _LIBCPP_TEMPLATE_VIS basic_ostringstream
     : public basic_ostream<_CharT, _Traits>
 {
 public:
     typedef _CharT                         char_type;
     typedef _Traits                        traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef _Allocator                     allocator_type;
 
     typedef basic_string<char_type, traits_type, allocator_type> string_type;
 
 private:
     basic_stringbuf<char_type, traits_type, allocator_type> __sb_;
 
 public:
-    // 30.8.4.1 [ostringstream.cons], constructors
+    // [ostringstream.cons] Constructors:
     _LIBCPP_INLINE_VISIBILITY
     basic_ostringstream()
         : basic_ostream<_CharT, _Traits>(&__sb_), __sb_(ios_base::out) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_ostringstream(ios_base::openmode __wch)
         : basic_ostream<_CharT, _Traits>(&__sb_), __sb_(__wch | ios_base::out) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_ostringstream(const string_type& __s,
                                  ios_base::openmode __wch = ios_base::out)
         : basic_ostream<_CharT, _Traits>(&__sb_)
         , __sb_(__s, __wch | ios_base::out)
     { }
 
     _LIBCPP_INLINE_VISIBILITY
     basic_ostringstream(basic_ostringstream&& __rhs)
         : basic_ostream<_CharT, _Traits>(_VSTD::move(__rhs))
         , __sb_(_VSTD::move(__rhs.__sb_))
     {
         basic_ostream<_CharT, _Traits>::set_rdbuf(&__sb_);
     }
 
-    // 27.8.2.2 Assign and swap:
+    // [ostringstream.assign] Assign and swap:
     basic_ostringstream& operator=(basic_ostringstream&& __rhs) {
         basic_ostream<char_type, traits_type>::operator=(_VSTD::move(__rhs));
         __sb_ = _VSTD::move(__rhs.__sb_);
         return *this;
     }
 
     _LIBCPP_INLINE_VISIBILITY
     void swap(basic_ostringstream& __rhs) {
         basic_ostream<char_type, traits_type>::swap(__rhs);
         __sb_.swap(__rhs.__sb_);
     }
 
-    // 27.8.2.3 Members:
+    // [ostringstream.members] Member functions:
     _LIBCPP_INLINE_VISIBILITY
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const {
         return const_cast<basic_stringbuf<char_type, traits_type, allocator_type>*>(&__sb_);
     }
     _LIBCPP_INLINE_VISIBILITY
     string_type str() const {
         return __sb_.str();
     }
     _LIBCPP_INLINE_VISIBILITY
     void str(const string_type& __s) {
         __sb_.str(__s);
     }
 };
 
 template <class _CharT, class _Traits, class _Allocator>
 inline _LIBCPP_INLINE_VISIBILITY
 void
 swap(basic_ostringstream<_CharT, _Traits, _Allocator>& __x,
      basic_ostringstream<_CharT, _Traits, _Allocator>& __y)
 {
     __x.swap(__y);
 }
 
-// basic_stringstream
+// Class template basic_stringstream [stringstream]
 
 template <class _CharT, class _Traits, class _Allocator>
 class _LIBCPP_TEMPLATE_VIS basic_stringstream
     : public basic_iostream<_CharT, _Traits>
 {
 public:
     typedef _CharT                         char_type;
     typedef _Traits                        traits_type;
     typedef typename traits_type::int_type int_type;
     typedef typename traits_type::pos_type pos_type;
     typedef typename traits_type::off_type off_type;
     typedef _Allocator                     allocator_type;
 
     typedef basic_string<char_type, traits_type, allocator_type> string_type;
 
 private:
     basic_stringbuf<char_type, traits_type, allocator_type> __sb_;
 
 public:
-    // 30.8.5.1 [stringstream.cons], constructors
+    // [stringstream.cons] constructors
     _LIBCPP_INLINE_VISIBILITY
     basic_stringstream()
         : basic_iostream<_CharT, _Traits>(&__sb_), __sb_(ios_base::in | ios_base::out) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_stringstream(ios_base::openmode __wch)
         : basic_iostream<_CharT, _Traits>(&__sb_), __sb_(__wch) {}
 
     _LIBCPP_INLINE_VISIBILITY
     explicit basic_stringstream(const string_type& __s,
                                 ios_base::openmode __wch = ios_base::in | ios_base::out)
         : basic_iostream<_CharT, _Traits>(&__sb_)
         , __sb_(__s, __wch)
     { }
 
     _LIBCPP_INLINE_VISIBILITY
     basic_stringstream(basic_stringstream&& __rhs)
         : basic_iostream<_CharT, _Traits>(_VSTD::move(__rhs))
         , __sb_(_VSTD::move(__rhs.__sb_))
     {
         basic_istream<_CharT, _Traits>::set_rdbuf(&__sb_);
     }
 
-    // 27.8.2.2 Assign and swap:
+    // [stringstream.assign] Assign and swap:
     basic_stringstream& operator=(basic_stringstream&& __rhs) {
         basic_iostream<char_type, traits_type>::operator=(_VSTD::move(__rhs));
         __sb_ = _VSTD::move(__rhs.__sb_);
         return *this;
     }
     _LIBCPP_INLINE_VISIBILITY
     void swap(basic_stringstream& __rhs) {
         basic_iostream<char_type, traits_type>::swap(__rhs);
         __sb_.swap(__rhs.__sb_);
     }
 
-    // 27.8.2.3 Members:
+    // [stringstream.members] Member functions:
     _LIBCPP_INLINE_VISIBILITY
     basic_stringbuf<char_type, traits_type, allocator_type>* rdbuf() const {
         return const_cast<basic_stringbuf<char_type, traits_type, allocator_type>*>(&__sb_);
     }
     _LIBCPP_INLINE_VISIBILITY
     string_type str() const {
         return __sb_.str();
     }