[libstdc++] automate documentation.html changes, basic_string doxygen hooks

Phil Edwards phil@jaj.com
Sat Aug 31 18:25:00 GMT 2002


string, wstring, and basic_string hav never been doxygenated.  This adds
the initial hooks to make them at least show up the output.

The "how to get basic_string<some_random_type> to work" question needs an
answer in the string howto.  This adds a placeholder for that.  I'll come
back to that later.

Benjmain recently copied out all of the "Contents" blocks from our
various HOWTOs into an expanded form in the parent documentation.html.
To avoid repetitious editing, this makes documentation.html a target in
docs/html/Makefile.  So, for example, after editing 21_strings/howto.html
to add a new entry, it automatically showed up in the expanded list.
(The initial regen changed indentation on all those lines, and added </li>
also, so the diff is large.)

Some comment and whitespace fixups.


2002-08-31  Phil Edwards  <pme@gcc.gnu.org>

	* acinclude.m4:  Minor comment tweaks.

	* docs/html/makedoc.awk:  New file...
	* docs/html/Makefile:  ...called from here...
	* docs/html/documentation.html:  ...to help generate this.

	* docs/html/21_strings/howto.html:  Prepare for new entry.
	* include/bits/basic_string.h:  Initial basic_stirng hook for
	doxygen.  Remove trailing whitespace.
	* include/bits/char_traits.h:  Point to onlinedocs for new entry.
	* include/bits/stringfwd.h:  Add doxygen hooks for string and
	wstring typedefs.


Index: acinclude.m4
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/acinclude.m4,v
retrieving revision 1.216
diff -u -3 -p -r1.216 acinclude.m4
--- acinclude.m4	23 Aug 2002 19:33:37 -0000	1.216
+++ acinclude.m4	1 Sep 2002 00:21:57 -0000
@@ -1,5 +1,5 @@
 dnl
-dnl Initialize configure bits.
+dnl Initialize basic configure bits, set toplevel_srcdir for Makefiles.
 dnl
 dnl GLIBCPP_TOPREL_CONFIGURE
 AC_DEFUN(GLIBCPP_TOPREL_CONFIGURE, [
@@ -37,13 +37,10 @@ AC_DEFUN(GLIBCPP_TOPREL_CONFIGURE, [
 ])
 
 dnl
-dnl Initialize configure bits.
+dnl Initialize the rest of the library configury.
 dnl
 dnl GLIBCPP_CONFIGURE
 AC_DEFUN(GLIBCPP_CONFIGURE, [
-
-#possibly test for the presence of the compiler sources here?
-
   # Export build and source directories.
   # These need to be absolute paths, yet at the same time need to
   # canonicalize only relative paths, because then amd will not unmount
Index: docs/html/Makefile
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/Makefile,v
retrieving revision 1.4
diff -u -3 -p -r1.4 Makefile
--- docs/html/Makefile	16 May 2002 17:43:19 -0000	1.4
+++ docs/html/Makefile	1 Sep 2002 00:21:58 -0000
@@ -1,10 +1,28 @@
-PWD=$${PWDCMD-pwd}
 
+PWD=$${PWDCMD-pwd}
 MAKEINFO=makeinfo
 INC=../../../gcc/doc/include
 
-all: faq/index.txt 17_intro/porting.html 17_intro/porting-howto.html
-
+all: documentation.html                  \
+     faq/index.txt                       \
+     17_intro/porting.html               \
+     17_intro/porting-howto.html
+
+# chock full of GNUism, probably
+documentation.html: $(wildcard */howto.html)
+	sed -n '1,/beginlist/p' $@ > tmp.top
+	sed -n '/endlist/,$$p' $@ > tmp.bottom
+	echo '  <ul>' > tmp.middle
+	for i in [[:digit:]]*/howto.html; do \
+	  title=`grep 'h1 ' $$i |\
+	  sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\
+	  awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\
+	done
+	awk -v file=ext/howto.html -v "title=Extensions to the Standard Library"\
+	  -f makedoc.awk ext/howto.html >> tmp.middle ;\
+	echo '  </ul>' >> tmp.middle
+	cat tmp.top tmp.middle tmp.bottom > $@
+	rm tmp.top tmp.middle tmp.bottom
 
 faq/index.txt: faq/index.html
 	lynx -dump $< | sed "s%file://localhost`${PWD}`%..%" > $@
@@ -16,3 +34,4 @@ faq/index.txt: faq/index.html
 17_intro/porting-howto.html: 17_intro/porting-howto.xml
 	xltproc -o $@ /usr/share/xml/docbook/xsl-stylesheets-1.48-2/html/docbook.xsl $<
 
+# vim:noet ts=4
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.20
diff -u -3 -p -r1.20 documentation.html
--- docs/html/documentation.html	20 Aug 2002 00:44:19 -0000	1.20
+++ docs/html/documentation.html	1 Sep 2002 00:21:58 -0000
@@ -24,7 +24,7 @@
       <ul>
          <li><a href="17_intro/COPYING">License</a>
          - GPL v2 license terms
-	 <li><a href="abi.txt">ABI Policy and Guidelines</a> 
+         <li><a href="abi.txt">ABI Policy and Guidelines</a> 
          <li><a href="17_intro/BUGS">BUGS</a>
          <li><a href="17_intro/PROBLEMS">PROBLEMS</a>
          - target-specific known issues
@@ -84,121 +84,127 @@
 <br>
 <h2><a name="3">Chapter-Specific Documentation</a></h2>
 <p>Information, extensions, notes and advice on specific implementation 
-   capabilites and or liabilities broken down into chapter names based on the 
+   capabilites and/or liabilities broken down into chapter names based on the 
    C++ standard.
 </p>
-      <ul>
-         <li>Intro (Chapter 17)
-	 <ul>
-         <li><a href="17_intro/howto.html#1">Header files</a>
-         <li><a href="17_intro/howto.html#3">Using <foo> vs <foo.h></a>
-         <li><a href="17_intro/howto.html#2">Multithreading</a>
-         <li><a href="17_intro/howto.html#4">Porting</a>
-         <li><a href="17_intro/howto.html#5">Implementation-specific behavior</a>
-         <li><a href="17_intro/howto.html#6">Using preprocessor macros to change behavior of the library</a>
-	 </ul>
-
-         <li>Library Support (Chapter 18)
-	 <ul>
-         <li><a href="18_support/howto.html#1">Types</a>
-         <li><a href="18_support/howto.html#2">Implementation properties</a>
-         <li><a href="18_support/howto.html#3">Start and Termination</a>
-         <li><a href="18_support/howto.html#4">Dynamic memory management</a>
-         <li><a href="18_support/howto.html#5">RTTI, the ABI, and demangling</a>
-	 </ul>
-
-
-         <li>Diagnostics (Chapter 19)
-	 <ul>
-         <li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a>
-         <li><a href="19_diagnostics/howto.html#2">Exception class hierarchy diagram</a>
-         <li><a href="19_diagnostics/howto.html#3">Concept checkers -- new and improved!</a>
-         <li><a href="19_diagnostics/howto.html#4">Verbose terminate</a>
-	 </ul>
-
-         <li>Utilities (Chapter 20)
-	 <ul>
-         <li><a href="20_util/howto.html#1">auto_ptr is not omnipotent</a>
-         <li><a href="20_util/howto.html#1">auto_ptr inside container classes</a>
-         <li><a href="20_util/howto.html#1">Functors</a>
-         <li><a href="20_util/howto.html#1">Pairs</a>
-	 </ul>
-
-
-         <li>Strings (Chapter 21)
-	 <ul>
-         <li><a href="21_strings/howto.html#1">MFC's CString</a>
-         <li><a href="21_strings/howto.html#2">A case-insensitive string class</a>
-         <li><a href="21_strings/howto.html#3">Breaking a C++ string into tokens</a>
-         <li><a href="21_strings/howto.html#4">Simple transformations</a>
-	 </ul>
-
-         <li>Localization (Chapter 22)
-	 <ul>
-         <li><a href="22_locale/howto.html#1">Class locale</a>
-         <li><a href="22_locale/howto.html#2">Class codecvt</a>
-         <li><a href="22_locale/howto.html#3">Class ctype</a>
-         <li><a href="22_locale/howto.html#4">Class messages</a>
-         <li><a href="22_locale/howto.html#5">Bjarne Stroustrup on Locales</a>
-         <li><a href="22_locale/howto.html#6">Nathan Myers on Locales</a>
-         <li><a href="22_locale/howto.html#7">Correct Transformations </a>
-	 </ul>
-
-         <li>Containers (Chapter 23)
-	 <ul>
-         <li><a href="23_containers/howto.html#1">Making code unaware of the container/array difference</a>
-         <li><a href="23_containers/howto.html#2">Variable-sized bitmasks</a>
-         <li><a href="23_containers/howto.html#3">Containers and multithreading</a>
-         <li><a href="23_containers/howto.html#4">"Hinting" during insertion</a>
-         <li><a href="23_containers/howto.html#5">Bitmasks and string arguments</a>
-         <li><a href="23_containers/howto.html#6"><code>std::list::size()</code> is O(n)!</a>
-         <li><a href="23_containers/howto.html#7">Space overhead management for vectors </a>
-	 </ul>
-
-         <li>Iterators (Chapter24)
-	 <ul>
-         <li><a href="24_iterators/howto.html#1">They aren't pointers!</a>
-         <li><a href="24_iterators/howto.html#1">It ends where?</a>
-	 </ul>
-
-         <li>Algorithms (Chapter 25)
-	 <ul>
-         <li><a href="25_algorithms/howto.html#1">Prerequisites</a>
-         <li><a href="25_algorithms/howto.html#2">Special swaps</a>
-	 </ul>
-
-         <li>Numerics (Chapter 26)
-	 <ul>
-         <li><a href="26_numerics/howto.html#1">Complex Number Processing</a>
-         <li><a href="26_numerics/howto.html#2">Array Processing</a>
-         <li><a href="26_numerics/howto.html#3">Numerical Functions</a>
-         <li><a href="26_numerics/howto.html#4">C99</a>
-	 </ul>
-
-         <li>I/O (Chapter 27)
-	 <ul>
-         <li><a href="27_io/howto.html#1">Copying a file</a>
-         <li><a href="27_io/howto.html#2">The buffering is screwing up my program!</a>
-	 </ul>
-	 <ul>
-         <li><a href="27_io/howto.html#3">Binary I/O</a>
-         <li><a href="27_io/howto.html#6">More on binary I/O</a>
-         <li><a href="27_io/howto.html#5">Deriving a stream buffer</a>
-         <li><a href="27_io/howto.html#4">What is this <sstream>/stringstreams thing?</a>
-         <li><a href="27_io/howto.html#7">Pathetic performance? Ditch C.</a>
-         <li><a href="27_io/howto.html#8">Threads and I/O</a>
-	 </ul>
-
-         <li>Extensions to the Standard Library
-	 <ul>
-         <li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a>
-         <li><a href="ext/howto.html#2">Added members and types</a>
-         <li><a href="ext/howto.html#3">Allocators (versions 3.0, 3.1, 3.2)</a>
-         <li><a href="ext/howto.html#4">Allocators (version 3.3)</a>
-         <li><a href="ext/howto.html#5">Compile-time checks</a>
-         <li><a href="ext/howto.html#6">LWG Issues</a>
-	 </ul>
-      </ul>
+<!--
+  The list below is automatically generated.  To make changes in the text,
+  edit the appropriate HOWTO file and run "make" in this directory.  In
+  those files, you may reorder entries as you like, but DO NOT change the
+  "#number"s in anchors, for they are used elsewhere and in bookmarks.
+-->
+<!-- beginlist -->
+  <ul>
+   <li>Library Introduction (Chapter 17)</li>
+   <ul>
+     <li><a href="17_intro/howto.html#2">The Standard C++ header files</a></li>
+     <li><a href="17_intro/howto.html#3">The Standard C++ library and multithreading</a></li>
+     <li><a href="17_intro/howto.html#4"><code><foo></code> vs <code><foo.h></code></a></li>
+     <li><a href="17_intro/porting-howto.html">Porting HOWTO</a></li>
+     <li><a href="17_intro/howto.html#5">Behavior specific to libstdc++-v3</a></li>
+     <li><a href="17_intro/howto.html#6">Preprocessor macros controlling the library</a></li>
+   </ul>
+
+   <li>Library Support (Chapter 18)</li>
+   <ul>
+     <li><a href="18_support/howto.html#1">Types</a></li>
+     <li><a href="18_support/howto.html#2">Implementation properties</a></li>
+     <li><a href="18_support/howto.html#3">Start and Termination</a></li>
+     <li><a href="18_support/howto.html#4">Dynamic memory management</a></li>
+     <li><a href="18_support/howto.html#5">RTTI, the ABI, and demangling</a></li>
+   </ul>
+
+   <li>Diagnostics (Chapter 19)</li>
+   <ul>
+     <li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li>
+     <li><a href="19_diagnostics/howto.html#2">Exception class hierarchy diagram</a></li>
+     <li><a href="19_diagnostics/howto.html#3">Concept checkers -- <strong>new and improved!</strong></a></li>
+     <li><a href="19_diagnostics/howto.html#4">Verbose <code>terminate</code></a></li>
+   </ul>
+
+   <li>General Utilities (Chapter 20)</li>
+   <ul>
+     <li><a href="20_util/howto.html#1"><code>auto_ptr</code> is not omnipotent</a></li>
+     <li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li>
+     <li><a href="20_util/howto.html#3">Functors</a></li>
+     <li><a href="20_util/howto.html#4">Pairs</a></li>
+   </ul>
+
+   <li>Strings (Chapter 21)</li>
+   <ul>
+     <li><a href="21_strings/howto.html#1">MFC's CString</a></li>
+     <li><a href="21_strings/howto.html#2">A case-insensitive string class</a></li>
+     <li><a href="21_strings/howto.html#3">Breaking a C++ string into tokens</a></li>
+     <li><a href="21_strings/howto.html#4">Simple transformations</a></li>
+     <li><a href="21_strings/howto.html#5">Making strings of arbitrary character types</a></li>
+   </ul>
+
+   <li>Localization (Chapter 22)</li>
+   <ul>
+     <li><a href="22_locale/howto.html#1">class locale</a></li>
+     <li><a href="22_locale/howto.html#2">class codecvt</a></li>
+     <li><a href="22_locale/howto.html#3">class ctype</a></li>
+     <li><a href="22_locale/howto.html#4">class messages</a></li>
+     <li><a href="22_locale/howto.html#5">Bjarne Stroustrup on Locales</a></li>
+     <li><a href="22_locale/howto.html#6">Nathan Myers on Locales   </a></li>
+     <li><a href="22_locale/howto.html#7">Correct Transformations</a></li>
+   </ul>
+
+   <li>Containers (Chapter 23)</li>
+   <ul>
+     <li><a href="23_containers/howto.html#1">Making code unaware of the container/array difference</a></li>
+     <li><a href="23_containers/howto.html#2">Variable-sized bitmasks</a></li>
+     <li><a href="23_containers/howto.html#3">Containers and multithreading</a></li>
+     <li><a href="23_containers/howto.html#4">"Hinting" during insertion</a></li>
+     <li><a href="23_containers/howto.html#5">Bitmasks and string arguments</a></li>
+     <li><a href="23_containers/howto.html#6"><code>std::list::size()</code> is O(n)!</a></li>
+     <li><a href="23_containers/howto.html#7">Space overhead management for vectors</a></li>
+   </ul>
+
+   <li>Iterators (Chapter 24)</li>
+   <ul>
+     <li><a href="24_iterators/howto.html#1">They ain't pointers!</a></li>
+     <li><a href="24_iterators/howto.html#2">It ends <em>where?</em></a></li>
+   </ul>
+
+   <li>Algorithms (Chapter 25)</li>
+   <ul>
+     <li><a href="25_algorithms/howto.html#1">Prerequisites</a></li>
+     <li><a href="25_algorithms/howto.html#2">Special <code>swap</code>s</a></li>
+   </ul>
+
+   <li>Numerics (Chapter 26)</li>
+   <ul>
+     <li><a href="26_numerics/howto.html#1">Complex Number Processing</a></li>
+     <li><a href="26_numerics/howto.html#2">Array Processing</a></li>
+     <li><a href="26_numerics/howto.html#3">Numerical Functions</a></li>
+     <li><a href="26_numerics/howto.html#4">C99</a></li>
+   </ul>
+
+   <li>Input/Output (Chapter 27)</li>
+   <ul>
+     <li><a href="27_io/howto.html#1">Copying a file</a></li>
+     <li><a href="27_io/howto.html#2">The buffering is screwing up my program!</a></li>
+     <li><a href="27_io/howto.html#3">Binary I/O</a></li>
+     <li><a href="27_io/howto.html#5">What is this <sstream>/stringstreams thing?</a></li>
+     <li><a href="27_io/howto.html#6">Deriving a stream buffer</a></li>
+     <li><a href="27_io/howto.html#7">More on binary I/O</a></li>
+     <li><a href="27_io/howto.html#8">Pathetic performance?  Ditch C.</a></li>
+     <li><a href="27_io/howto.html#9">Threads and I/O</a></li>
+   </ul>
+
+   <li>Extensions to the Standard Library</li>
+   <ul>
+     <li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a></li>
+     <li><a href="ext/howto.html#2">Added members and types</a></li>
+     <li><a href="ext/howto.html#3">Allocators (versions 3.0, 3.1, 3.2)</a></li>
+     <li><a href="ext/howto.html#6">Allocators (version 3.3)</a></li>
+     <li><a href="ext/howto.html#4">Compile-time checks</a></li>
+     <li><a href="ext/howto.html#5">LWG Issues</a></li>
+   </ul>
+
+  </ul>
+<!-- endlist -->
 
 <hr />
 <br>
Index: docs/html/makedoc.awk
===================================================================
RCS file: docs/html/makedoc.awk
diff -N docs/html/makedoc.awk
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ docs/html/makedoc.awk	1 Sep 2002 00:21:58 -0000
@@ -0,0 +1,69 @@
+# Take apart bits of HTML and puts them back together again in new and
+# fascinating ways.  Copyright (C) 2002 Free Software Foundation, Inc.
+# Contributed by Phil Edwards <pme@gcc.gnu.org>.  Simple two-state automaton
+# inspired by Richard Henderson's gcc/mkmap-symver.awk.
+
+# 'file' is the name of the file on stdin
+# 'title' is the text to print at the start of the list
+
+BEGIN {
+  state = "looking";
+  entries = 0;
+  printf ("   <li>%s</li>\n", title);
+  printf ("   <ul>\n");
+}
+
+# Searching for the little table of contents at the top.
+state == "looking" && /^<h1>Contents/ {
+  state = "entries";
+  next;
+}
+
+# Ignore everything else up to that point.
+state == "looking" {
+  next;
+}
+
+# An entry in the table of contents.  Pull that line apart.
+state == "entries" && /<li>/ {
+  extract_info($0);
+  next;
+}
+
+# End of the list.  Don't bother reading the rest of the file.  (It could
+# also contain more <li>'s, so that would be incorrect as well as wasteful.)
+state == "entries" && /^<\/ul>/ {
+  exit;
+}
+
+END {
+  for (i = 0; i < entries; i++)
+    printf ("     %s\n", entry[i]);
+  printf ("   </ul>\n\n");
+}
+
+function extract_info(line) {
+  # thistarget will be things like "#5" or "elsewhere.html"
+  match(line,"href=\".*\"");
+  thistarget = substr(line,RSTART+6,RLENGTH-7);
+
+  # take apart the filename
+  split(file,X,"/");
+  if (thistarget ~ /^#/) {
+    # local name, use directory and filename
+    target = file thistarget
+  } else {
+    # different file, only use directory
+    target = X[1] "/" thistarget
+  }
+
+  # visible text
+  gsub("</a>","",line);
+  start = index(line,"\">") + 2;
+  thistext = substr(line,start);
+
+  # Assemble and store the HTML for later output.
+  entry[entries++] = "<li><a href=\"" target "\">" thistext "</a></li>"
+}
+
+# vim:sw=2
Index: docs/html/21_strings/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/21_strings/howto.html,v
retrieving revision 1.10
diff -u -3 -p -r1.10 howto.html
--- docs/html/21_strings/howto.html	23 Nov 2001 16:29:00 -0000	1.10
+++ docs/html/21_strings/howto.html	1 Sep 2002 00:21:58 -0000
@@ -25,6 +25,7 @@
    <li><a href="#2">A case-insensitive string class</a>
    <li><a href="#3">Breaking a C++ string into tokens</a>
    <li><a href="#4">Simple transformations</a>
+   <li><a href="#5">Making strings of arbitrary character types</a>
 </ul>
 
 <hr>
@@ -316,6 +317,15 @@
       Obviously, the calls to <code>find</code> could be inserted directly
       into the calls to <code>erase</code>, in case your compiler does not
       optimize named temporaries out of existence.
+   </p>
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
+   </p>
+
+<hr>
+<h2><a name="5">Making strings of arbitrary character types</a></h2>
+   <p>how to work with char_traits -- in the archives, just need to
+      go through and pull the examples together
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
Index: include/bits/basic_string.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/basic_string.h,v
retrieving revision 1.24
diff -u -3 -p -r1.24 basic_string.h
--- include/bits/basic_string.h	26 Apr 2002 18:21:30 -0000	1.24
+++ include/bits/basic_string.h	1 Sep 2002 00:21:58 -0000
@@ -46,44 +46,64 @@
 
 namespace std
 {
-  // Documentation?  What's that? 
-  // Nathan Myers <ncm@cantrip.org>.
-  //
-  // A string looks like this:
-  //
-  //                               	[_Rep]
-  //                               	_M_length
-  //  [basic_string<char_type>]		_M_capacity
-  //  _M_dataplus                	_M_state
-  //  _M_p ---------------->   		unnamed array of char_type
-  
-  // Where the _M_p points to the first character in the string, and
-  // you cast it to a pointer-to-_Rep and subtract 1 to get a
-  // pointer to the header.
-  
-  // This approach has the enormous advantage that a string object
-  // requires only one allocation.  All the ugliness is confined
-  // within a single pair of inline functions, which each compile to
-  // a single "add" instruction: _Rep::_M_data(), and
-  // string::_M_rep(); and the allocation function which gets a
-  // block of raw bytes and with room enough and constructs a _Rep
-  // object at the front.
-  
-  // The reason you want _M_data pointing to the character array and
-  // not the _Rep is so that the debugger can see the string
-  // contents. (Probably we should add a non-inline member to get
-  // the _Rep for the debugger to use, so users can check the actual
-  // string length.)
-  
-  // Note that the _Rep object is a POD so that you can have a
-  // static "empty string" _Rep object already "constructed" before
-  // static constructors have run.  The reference-count encoding is
-  // chosen so that a 0 indicates one reference, so you never try to
-  // destroy the empty-string _Rep object.
-  
-  // All but the last paragraph is considered pretty conventional
-  // for a C++ string implementation.
-  
+  /**
+   *  @class basic_string basic_string.h <string>
+   *  @brief  Managing sequences of characters and character-like objects.
+   *
+   *  @ingroup Containers
+   *  @ingroup Sequences
+   *
+   *  Meets the requirements of a <a href="tables.html#65">container</a>, a
+   *  <a href="tables.html#66">reversible container</a>, and a
+   *  <a href="tables.html#67">sequence</a>.  Of the
+   *  <a href="tables.html#68">optional sequence requirements</a>, only
+   *  @c push_back, @c at, and array access are supported.
+   *
+   *  @doctodo
+   *
+   *
+   *  @if maint
+   *  Documentation?  What's that?
+   *  Nathan Myers <ncm@cantrip.org>.
+   *
+   *  A string looks like this:
+   *
+   *  @code
+   *                                        [_Rep]
+   *                                        _M_length
+   *   [basic_string<char_type>]            _M_capacity
+   *   _M_dataplus                          _M_state
+   *   _M_p ---------------->               unnamed array of char_type
+   *  @endcode
+   *
+   *  Where the _M_p points to the first character in the string, and
+   *  you cast it to a pointer-to-_Rep and subtract 1 to get a
+   *  pointer to the header.
+   *
+   *  This approach has the enormous advantage that a string object
+   *  requires only one allocation.  All the ugliness is confined
+   *  within a single pair of inline functions, which each compile to
+   *  a single "add" instruction: _Rep::_M_data(), and
+   *  string::_M_rep(); and the allocation function which gets a
+   *  block of raw bytes and with room enough and constructs a _Rep
+   *  object at the front.
+   *
+   *  The reason you want _M_data pointing to the character array and
+   *  not the _Rep is so that the debugger can see the string
+   *  contents. (Probably we should add a non-inline member to get
+   *  the _Rep for the debugger to use, so users can check the actual
+   *  string length.)
+   *
+   *  Note that the _Rep object is a POD so that you can have a
+   *  static "empty string" _Rep object already "constructed" before
+   *  static constructors have run.  The reference-count encoding is
+   *  chosen so that a 0 indicates one reference, so you never try to
+   *  destroy the empty-string _Rep object.
+   *
+   *  All but the last paragraph is considered pretty conventional
+   *  for a C++ string implementation.
+   *  @endif
+  */
   // 21.3  Template class basic_string
   template<typename _CharT, typename _Traits, typename _Alloc>
     class basic_string
@@ -104,7 +124,7 @@ namespace std
                                                             const_iterator;
       typedef reverse_iterator<const_iterator> 	const_reverse_iterator;
       typedef reverse_iterator<iterator> 		    reverse_iterator;
-    
+
     private:
       // _Rep: string representation
       //   Invariants:
@@ -125,7 +145,7 @@ namespace std
 	// Types:
 	typedef typename _Alloc::template rebind<char>::other _Raw_bytes_alloc;
 
-	// (Public) Data members: 
+	// (Public) Data members:
 
 	// The maximum number of individual char_type elements of an
 	// individual string is determined by _S_max_size. This is the
@@ -133,10 +153,10 @@ namespace std
 	// is the maximum number of bytes the allocator can allocate.)
 	// If one was to divvy up the theoretical largest size string,
 	// with a terminating character and m _CharT elements, it'd
-	// look like this: 
+	// look like this:
 	// npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
 	// Solving for m:
-	// m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1 
+	// m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
 	// In addition, this implementation quarters this ammount.
 	static const size_type 	_S_max_size;
 	static const _CharT 	_S_terminal;
@@ -144,7 +164,7 @@ namespace std
 	size_type 		_M_length;
 	size_type 		_M_capacity;
 	_Atomic_word		_M_references;
-	
+
         bool
 	_M_is_leaked() const
         { return _M_references < 0; }
@@ -154,50 +174,50 @@ namespace std
         { return _M_references > 0; }
 
         void
-	_M_set_leaked() 
+	_M_set_leaked()
         { _M_references = -1; }
 
         void
-	_M_set_sharable() 
+	_M_set_sharable()
         { _M_references = 0; }
 
-	_CharT* 
+	_CharT*
 	_M_refdata() throw()
 	{ return reinterpret_cast<_CharT*>(this + 1); }
 
-	_CharT& 
+	_CharT&
 	operator[](size_t __s) throw()
 	{ return _M_refdata() [__s]; }
 
-	_CharT* 
+	_CharT*
 	_M_grab(const _Alloc& __alloc1, const _Alloc& __alloc2)
-	{ 
-	  return (!_M_is_leaked() && __alloc1 == __alloc2) 
-	          ? _M_refcopy() : _M_clone(__alloc1);  
+	{
+	  return (!_M_is_leaked() && __alloc1 == __alloc2)
+	          ? _M_refcopy() : _M_clone(__alloc1);
 	}
 
 	// Create & Destroy
-	static _Rep* 
+	static _Rep*
 	_S_create(size_t, const _Alloc&);
 
-	void 
+	void
 	_M_dispose(const _Alloc& __a)
-	{ 
-	  if (__exchange_and_add(&_M_references, -1) <= 0)  
-	    _M_destroy(__a); 
+	{
+	  if (__exchange_and_add(&_M_references, -1) <= 0)
+	    _M_destroy(__a);
 	}  // XXX MT
 
-	void 
+	void
 	_M_destroy(const _Alloc&) throw();
 
-	_CharT* 
+	_CharT*
 	_M_refcopy() throw()
-	{ 
-	  __atomic_add(&_M_references, 1); 
-	  return _M_refdata(); 
+	{
+	  __atomic_add(&_M_references, 1);
+	  return _M_refdata();
 	}  // XXX MT
 
-	_CharT* 
+	_CharT*
 	_M_clone(const _Alloc&, size_type __res = 0);
       };
 
@@ -224,45 +244,45 @@ namespace std
       // (carefully) in an empty string with one reference.
       static size_type _S_empty_rep_storage[(sizeof(_Rep) + sizeof(_CharT) + sizeof(size_type) - 1)/sizeof(size_type)];
 
-      _CharT* 
-      _M_data() const 
+      _CharT*
+      _M_data() const
       { return  _M_dataplus._M_p; }
 
-      _CharT* 
-      _M_data(_CharT* __p) 
+      _CharT*
+      _M_data(_CharT* __p)
       { return (_M_dataplus._M_p = __p); }
 
-      _Rep* 
+      _Rep*
       _M_rep() const
       { return &((reinterpret_cast<_Rep*> (_M_data()))[-1]); }
 
       // For the internal use we have functions similar to `begin'/`end'
       // but they do not call _M_leak.
-      iterator 
+      iterator
       _M_ibegin() const { return iterator(_M_data()); }
 
-      iterator 
+      iterator
       _M_iend() const { return iterator(_M_data() + this->size()); }
 
-      void 
+      void
       _M_leak()    // for use in begin() & non-const op[]
-      { 
-	if (!_M_rep()->_M_is_leaked()) 
-	  _M_leak_hard(); 
+      {
+	if (!_M_rep()->_M_is_leaked())
+	  _M_leak_hard();
       }
 
-      iterator 
+      iterator
       _M_check(size_type __pos) const
-      { 
+      {
 	if (__pos > this->size())
-	  __throw_out_of_range("basic_string::_M_check"); 
-	return _M_ibegin() + __pos; 
+	  __throw_out_of_range("basic_string::_M_check");
+	return _M_ibegin() + __pos;
       }
 
       // NB: _M_fold doesn't check for a bad __pos1 value.
-      iterator 
+      iterator
       _M_fold(size_type __pos, size_type __off) const
-      { 
+      {
 	bool __testoff =  __off < this->size() - __pos;
 	size_type __newoff = __testoff ? __off : this->size() - __pos;
 	return (_M_ibegin() + __pos + __newoff);
@@ -273,8 +293,8 @@ namespace std
       template<class _Iterator>
         static void
         _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
-        { 
-	  for (; __k1 != __k2; ++__k1, ++__p) 
+        {
+	  for (; __k1 != __k2; ++__k1, ++__p)
 	    traits_type::assign(*__p, *__k1); // These types are off.
 	}
 
@@ -285,7 +305,7 @@ namespace std
       static void
       _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
- 
+
       static void
       _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2)
       { traits_type::copy(__p, __k1, __k2 - __k1); }
@@ -294,13 +314,13 @@ namespace std
       _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
       { traits_type::copy(__p, __k1, __k2 - __k1); }
 
-      void 
+      void
       _M_mutate(size_type __pos, size_type __len1, size_type __len2);
 
-      void 
+      void
       _M_leak_hard();
 
-      static _Rep& 
+      static _Rep&
       _S_empty_rep()
       { return *reinterpret_cast<_Rep*>(&_S_empty_rep_storage); }
 
@@ -309,10 +329,10 @@ namespace std
       // NB: We overload ctors in some cases instead of using default
       // arguments, per 17.4.4.4 para. 2 item 2.
 
-      inline 
+      inline
       basic_string();
 
-      explicit 
+      explicit
       basic_string(const _Alloc& __a);
 
       // NB: per LWG issue 42, semantics different from IS:
@@ -331,154 +351,154 @@ namespace std
         basic_string(_InputIterator __beg, _InputIterator __end,
 		     const _Alloc& __a = _Alloc());
 
-      ~basic_string() 
+      ~basic_string()
       { _M_rep()->_M_dispose(this->get_allocator()); }
 
-      basic_string& 
+      basic_string&
       operator=(const basic_string& __str) { return this->assign(__str); }
 
-      basic_string& 
+      basic_string&
       operator=(const _CharT* __s) { return this->assign(__s); }
 
-      basic_string& 
+      basic_string&
       operator=(_CharT __c) { return this->assign(1, __c); }
 
       // Iterators:
-      iterator 
-      begin() 
-      { 
-	_M_leak(); 
+      iterator
+      begin()
+      {
+	_M_leak();
 	return iterator(_M_data());
       }
 
-      const_iterator 
-      begin() const 
+      const_iterator
+      begin() const
       { return const_iterator(_M_data()); }
 
-      iterator 
+      iterator
       end()
       {
          _M_leak();
 	 return iterator(_M_data() + this->size());
       }
 
-      const_iterator 
+      const_iterator
       end() const
       { return const_iterator(_M_data() + this->size()); }
 
-      reverse_iterator 
-      rbegin() 
+      reverse_iterator
+      rbegin()
       { return reverse_iterator(this->end()); }
 
-      const_reverse_iterator 
-      rbegin() const 
+      const_reverse_iterator
+      rbegin() const
       { return const_reverse_iterator(this->end()); }
 
-      reverse_iterator 
-      rend() 
+      reverse_iterator
+      rend()
       { return reverse_iterator(this->begin()); }
 
-      const_reverse_iterator 
-      rend() const 
+      const_reverse_iterator
+      rend() const
       { return const_reverse_iterator(this->begin()); }
 
     public:
       // Capacity:
-      size_type 
+      size_type
       size() const { return _M_rep()->_M_length; }
 
-      size_type 
+      size_type
       length() const { return _M_rep()->_M_length; }
 
-      size_type 
+      size_type
       max_size() const { return _Rep::_S_max_size; }
 
-      void 
+      void
       resize(size_type __n, _CharT __c);
 
-      void 
+      void
       resize(size_type __n) { this->resize(__n, _CharT()); }
 
-      size_type 
+      size_type
       capacity() const { return _M_rep()->_M_capacity; }
 
-      void 
+      void
       reserve(size_type __res_arg = 0);
 
-      void 
+      void
       clear() { _M_mutate(0, this->size(), 0); }
 
-      bool 
+      bool
       empty() const { return this->size() == 0; }
 
       // Element access:
-      const_reference 
-      operator[] (size_type __pos) const 
+      const_reference
+      operator[] (size_type __pos) const
       { return _M_data()[__pos]; }
 
-      reference 
-      operator[](size_type __pos) 
-      { 
-	_M_leak(); 
-	return _M_data()[__pos]; 
+      reference
+      operator[](size_type __pos)
+      {
+	_M_leak();
+	return _M_data()[__pos];
       }
 
-      const_reference 
+      const_reference
       at(size_type __n) const
       {
 	if (__n >= this->size())
 	  __throw_out_of_range("basic_string::at");
-	return _M_data()[__n]; 
+	return _M_data()[__n];
       }
 
-      reference 
+      reference
       at(size_type __n)
       {
 	if (__n >= size())
 	  __throw_out_of_range("basic_string::at");
-	_M_leak(); 
-	return _M_data()[__n]; 
+	_M_leak();
+	return _M_data()[__n];
       }
 
       // Modifiers:
-      basic_string& 
+      basic_string&
       operator+=(const basic_string& __str) { return this->append(__str); }
 
-      basic_string& 
+      basic_string&
       operator+=(const _CharT* __s) { return this->append(__s); }
 
-      basic_string& 
+      basic_string&
       operator+=(_CharT __c) { return this->append(size_type(1), __c); }
 
-      basic_string& 
+      basic_string&
       append(const basic_string& __str);
 
-      basic_string& 
+      basic_string&
       append(const basic_string& __str, size_type __pos, size_type __n);
 
-      basic_string& 
+      basic_string&
       append(const _CharT* __s, size_type __n);
 
-      basic_string& 
+      basic_string&
       append(const _CharT* __s)
       { return this->append(__s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       append(size_type __n, _CharT __c);
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         append(_InputIterator __first, _InputIterator __last)
         { return this->replace(_M_iend(), _M_iend(), __first, __last); }
 
-      void 
+      void
       push_back(_CharT __c)
       { this->replace(_M_iend(), _M_iend(), 1, __c); }
 
-      basic_string& 
+      basic_string&
       assign(const basic_string& __str);
 
-      basic_string& 
+      basic_string&
       assign(const basic_string& __str, size_type __pos, size_type __n)
       {
 	const size_type __strsize = __str.size();
@@ -489,7 +509,7 @@ namespace std
 	return this->assign(__str._M_data() + __pos, __newsize);
       }
 
-      basic_string& 
+      basic_string&
       assign(const _CharT* __s, size_type __n)
       {
 	if (__n > this->max_size())
@@ -511,20 +531,20 @@ namespace std
 	  }
       }
 
-      basic_string& 
+      basic_string&
       assign(const _CharT* __s)
       { return this->assign(__s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       assign(size_type __n, _CharT __c)
       { return this->replace(_M_ibegin(), _M_iend(), __n, __c); }
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         assign(_InputIterator __first, _InputIterator __last)
         { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
 
-      void 
+      void
       insert(iterator __p, size_type __n, _CharT __c)
       {	this->replace(__p, __p, __n, __c);  }
 
@@ -532,11 +552,11 @@ namespace std
         void insert(iterator __p, _InputIterator __beg, _InputIterator __end)
         { this->replace(__p, __p, __beg, __end); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos1, const basic_string& __str)
       { return this->insert(__pos1, __str, 0, __str.size()); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos1, const basic_string& __str,
 	     size_type __pos2, size_type __n)
       {
@@ -545,10 +565,10 @@ namespace std
 	  __throw_out_of_range("basic_string::insert");
 	const bool __testn = __n < __strsize - __pos2;
 	const size_type __newsize = __testn ? __n : __strsize - __pos2;
-	return this->insert(__pos1, __str._M_data() + __pos2, __newsize); 
+	return this->insert(__pos1, __str._M_data() + __pos2, __newsize);
       }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos, const _CharT* __s, size_type __n)
       {
 	const size_type __size = this->size();
@@ -582,43 +602,43 @@ namespace std
 	  }
        }
 
-      basic_string&  
+      basic_string&
       insert(size_type __pos, const _CharT* __s)
       { return this->insert(__pos, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos, size_type __n, _CharT __c)
-      { 
-	this->insert(_M_check(__pos), __n, __c); 
-	return *this; 
+      {
+	this->insert(_M_check(__pos), __n, __c);
+	return *this;
       }
 
-      iterator 
+      iterator
       insert(iterator __p, _CharT __c = _CharT())
       {
 	size_type __pos = __p - _M_ibegin();
 	this->insert(_M_check(__pos), size_type(1), __c);
-	_M_rep()->_M_set_leaked(); 
- 	return this->_M_ibegin() + __pos; 
+	_M_rep()->_M_set_leaked();
+ 	return this->_M_ibegin() + __pos;
       }
 
-      basic_string& 
+      basic_string&
       erase(size_type __pos = 0, size_type __n = npos)
-      { 
+      {
 	return this->replace(_M_check(__pos), _M_fold(__pos, __n),
-			     _M_data(), _M_data()); 
+			     _M_data(), _M_data());
       }
 
-      iterator 
+      iterator
       erase(iterator __position)
       {
 	size_type __i = __position - _M_ibegin();
         this->replace(__position, __position + 1, _M_data(), _M_data());
-	_M_rep()->_M_set_leaked(); 
+	_M_rep()->_M_set_leaked();
 	return _M_ibegin() + __i;
       }
 
-      iterator 
+      iterator
       erase(iterator __first, iterator __last)
       {
         size_type __i = __first - _M_ibegin();
@@ -627,18 +647,18 @@ namespace std
        return _M_ibegin() + __i;
       }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n, const basic_string& __str)
       { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos1, size_type __n1, const basic_string& __str,
 	      size_type __pos2, size_type __n2);
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, const _CharT* __s,
 	      size_type __n2)
-      { 
+      {
 	const size_type __size = this->size();
  	if (__pos > __size)
 	  __throw_out_of_range("basic_string::replace");
@@ -657,32 +677,32 @@ namespace std
 			  typename iterator_traits<const _CharT*>::iterator_category());
       }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, const _CharT* __s)
       { return this->replace(__pos, __n1, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
       { return this->replace(_M_check(__pos), _M_fold(__pos, __n1), __n2, __c); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const basic_string& __str)
       { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2,
                            const _CharT* __s, size_type __n)
       { return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const _CharT* __s)
       { return this->replace(__i1, __i2, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, size_type __n, _CharT __c);
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         replace(iterator __i1, iterator __i2,
 		_InputIterator __k1, _InputIterator __k2)
         { return _M_replace(__i1, __i2, __k1, __k2,
@@ -690,23 +710,23 @@ namespace std
 
       // Specializations for the common case of pointer and iterator:
       // useful to avoid the overhead of temporary buffering in _M_replace.
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1, __k2 - __k1); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const _CharT* __k1, const _CharT* __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1, __k2 - __k1); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1.base(), __k2 - __k1);
 	}
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const_iterator __k1, const_iterator __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1.base(), __k2 - __k1);
@@ -714,13 +734,13 @@ namespace std
 
     private:
       template<class _InputIterator>
-        basic_string& 
-        _M_replace(iterator __i1, iterator __i2, _InputIterator __k1, 
+        basic_string&
+        _M_replace(iterator __i1, iterator __i2, _InputIterator __k1,
 		   _InputIterator __k2, input_iterator_tag);
 
       template<class _ForwardIterator>
-        basic_string& 
-        _M_replace_safe(iterator __i1, iterator __i2, _ForwardIterator __k1, 
+        basic_string&
+        _M_replace_safe(iterator __i1, iterator __i2, _ForwardIterator __k1,
 		   _ForwardIterator __k2);
 
       // _S_construct_aux is used to implement the 21.3.1 para 15 which
@@ -733,7 +753,7 @@ namespace std
           typedef typename iterator_traits<_InIter>::iterator_category _Tag;
           return _S_construct(__beg, __end, __a, _Tag());
 	}
- 
+
       template<class _InIter>
         static _CharT*
         _S_construct_aux(_InIter __beg, _InIter __end, const _Alloc& __a,
@@ -742,7 +762,7 @@ namespace std
 	  return _S_construct(static_cast<size_type>(__beg),
 			      static_cast<value_type>(__end), __a);
 	}
- 
+
       template<class _InIter>
         static _CharT*
         _S_construct(_InIter __beg, _InIter __end, const _Alloc& __a)
@@ -756,7 +776,7 @@ namespace std
         static _CharT*
          _S_construct(_InIter __beg, _InIter __end, const _Alloc& __a,
 		      input_iterator_tag);
-      
+
       // For forward_iterators up to random_access_iterators, used for
       // string::iterator, _CharT*, etc.
       template<class _FwdIter>
@@ -764,19 +784,19 @@ namespace std
         _S_construct(_FwdIter __beg, _FwdIter __end, const _Alloc& __a,
 		     forward_iterator_tag);
 
-      static _CharT* 
+      static _CharT*
       _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
 
     public:
 
-      size_type 
+      size_type
       copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
 
-      void 
+      void
       swap(basic_string<_CharT, _Traits, _Alloc>& __s);
 
       // String operations:
-      const _CharT* 
+      const _CharT*
       c_str() const
       {
 	// MT: This assumes concurrent writes are OK.
@@ -785,137 +805,137 @@ namespace std
         return _M_data();
       }
 
-      const _CharT* 
+      const _CharT*
       data() const { return _M_data(); }
 
-      allocator_type 
+      allocator_type
       get_allocator() const { return _M_dataplus; }
 
-      size_type 
+      size_type
       find(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find(const basic_string& __str, size_type __pos = 0) const
       { return this->find(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find(const _CharT* __s, size_type __pos = 0) const
       { return this->find(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find(_CharT __c, size_type __pos = 0) const;
 
-      size_type 
+      size_type
       rfind(const basic_string& __str, size_type __pos = npos) const
       { return this->rfind(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       rfind(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       rfind(const _CharT* __s, size_type __pos = npos) const
       { return this->rfind(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       rfind(_CharT __c, size_type __pos = npos) const;
 
-      size_type 
+      size_type
       find_first_of(const basic_string& __str, size_type __pos = 0) const
       { return this->find_first_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find_first_of(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find_first_of(const _CharT* __s, size_type __pos = 0) const
       { return this->find_first_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_first_of(_CharT __c, size_type __pos = 0) const
       { return this->find(__c, __pos); }
 
-      size_type 
+      size_type
       find_last_of(const basic_string& __str, size_type __pos = npos) const
       { return this->find_last_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find_last_of(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find_last_of(const _CharT* __s, size_type __pos = npos) const
       { return this->find_last_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_last_of(_CharT __c, size_type __pos = npos) const
       { return this->rfind(__c, __pos); }
 
-      size_type 
+      size_type
       find_first_not_of(const basic_string& __str, size_type __pos = 0) const
       { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
-      find_first_not_of(const _CharT* __s, size_type __pos, 
+      size_type
+      find_first_not_of(const _CharT* __s, size_type __pos,
 			size_type __n) const;
 
-      size_type 
+      size_type
       find_first_not_of(const _CharT* __s, size_type __pos = 0) const
       { return this->find_first_not_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_first_not_of(_CharT __c, size_type __pos = 0) const;
 
-      size_type 
+      size_type
       find_last_not_of(const basic_string& __str, size_type __pos = npos) const
       { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
-      find_last_not_of(const _CharT* __s, size_type __pos, 
+      size_type
+      find_last_not_of(const _CharT* __s, size_type __pos,
 		       size_type __n) const;
-      size_type 
+      size_type
       find_last_not_of(const _CharT* __s, size_type __pos = npos) const
       { return this->find_last_not_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_last_not_of(_CharT __c, size_type __pos = npos) const;
 
-      basic_string 
+      basic_string
       substr(size_type __pos = 0, size_type __n = npos) const
-      { 
+      {
 	if (__pos > this->size())
 	  __throw_out_of_range("basic_string::substr");
-	return basic_string(*this, __pos, __n); 
+	return basic_string(*this, __pos, __n);
       }
 
-      int 
+      int
       compare(const basic_string& __str) const
       {
 	size_type __size = this->size();
 	size_type __osize = __str.size();
 	size_type __len = min(__size, __osize);
-      
+
 	int __r = traits_type::compare(_M_data(), __str.data(), __len);
 	if (!__r)
 	  __r =  __size - __osize;
 	return __r;
       }
 
-      int 
+      int
       compare(size_type __pos, size_type __n, const basic_string& __str) const;
 
-      int 
+      int
       compare(size_type __pos1, size_type __n1, const basic_string& __str,
 	      size_type __pos2, size_type __n2) const;
 
-      int 
+      int
       compare(const _CharT* __s) const;
 
       // _GLIBCPP_RESOLVE_LIB_DEFECTS
       // 5. String::compare specification questionable
-      int 
+      int
       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
 
-      int 
-      compare(size_type __pos, size_type __n1, const _CharT* __s, 
+      int
+      compare(size_type __pos, size_type __n1, const _CharT* __s,
 	      size_type __n2) const;
   };
 
Index: include/bits/char_traits.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/char_traits.h,v
retrieving revision 1.14
diff -u -3 -p -r1.14 char_traits.h
--- include/bits/char_traits.h	31 Jul 2002 02:47:33 -0000	1.14
+++ include/bits/char_traits.h	1 Sep 2002 00:21:58 -0000
@@ -42,17 +42,21 @@
 
 #pragma GCC system_header
 
-#include <cstring> 	// For memmove, memset, memchr
-#include <bits/fpos.h> 		// For streampos
+#include <cstring>            // For memmove, memset, memchr
+#include <bits/fpos.h>        // For streampos
 
 namespace std 
 {
-  // 21.1.2
+  // 21.1
   /**
    *  @brief  Basis for explicit traits specializations.
    *
    *  @note  For any given actual character type, this definition is
    *  probably wrong.
+   *
+   *  See http://gcc.gnu.org/onlinedocs/libstdc++/21_strings/howto.html#5
+   *  for advice on how to make use of this class for "unusual" character
+   *  types.
   */
   template<class _CharT>
     struct char_traits
@@ -108,7 +112,7 @@ namespace std 
     };
 
 
-  /// 21.1.4  char_traits specializations
+  /// 21.1.3.1  char_traits specializations
   template<>
     struct char_traits<char>
     {
@@ -178,6 +182,7 @@ namespace std 
 
 
 #ifdef _GLIBCPP_USE_WCHAR_T
+  /// 21.1.3.2  char_traits specializations
   template<>
     struct char_traits<wchar_t>
     {
Index: include/bits/stringfwd.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stringfwd.h,v
retrieving revision 1.6
diff -u -3 -p -r1.6 stringfwd.h
--- include/bits/stringfwd.h	16 Feb 2002 02:41:09 -0000	1.6
+++ include/bits/stringfwd.h	1 Sep 2002 00:21:58 -0000
@@ -60,7 +60,9 @@ namespace std
            typename _Alloc = allocator<_CharT> >
     class basic_string;
 
+  /// 99%% of %string users only ever [need to] see the typedef.
   typedef basic_string<char>    string;
+  /// 99%% of %wstring users only ever [need to] see the typedef.
   typedef basic_string<wchar_t> wstring;
 } // namespace std
 



More information about the Gcc-patches mailing list