howto.html: Fix example code...

2002-11-20  Jonathan Wakely  <redi@gcc.gnu.org>

	* docs/html/21_strings/howto.html: Fix example code, cite Gaby's
	explanation of "<unknown type>" error with toupper/tolower.
	* docs/html/22_locale/howto.html: Be more consistent with
	example in 21_strings.

From-SVN: r59284

libstdc++-v3/ChangeLog

@@ -1,3 +1,10 @@
+2002-11-20  Jonathan Wakely  <redi@gcc.gnu.org>
+
+	* docs/html/21_strings/howto.html: Fix example code, cite Gaby's
+	explanation of "<unknown type>" error with toupper/tolower.
+	* docs/html/22_locale/howto.html: Be more consistent with
+	example in 21_strings.
+
 2002-11-19  John Gustafsson  <forgoil@rsn.bth.se>
 
 	* docs/html/20_util/howto.html: Fix typo.

libstdc++-v3/docs/html/21_strings/howto.html

@@ -278,19 +278,32 @@
    #include <algorithm>
    #include <cctype>      // old <ctype.h>
 
+   struct ToLower
+   {
+     char operator() (char c) const  { return std::tolower(c); }
+   };
+
+   struct ToUpper
+   {
+     char operator() (char c) const  { return std::toupper(c); }
+   };
+
+   int main()
+   {
      std::string  s ("Some Kind Of Initial Input Goes Here");
 
      // Change everything into upper case
-   std::transform (s.begin(), s.end(), s.begin(), toupper);
+     std::transform (s.begin(), s.end(), s.begin(), ToUpper());
 
      // Change everything into lower case
-   std::transform (s.begin(), s.end(), s.begin(), tolower);
+     std::transform (s.begin(), s.end(), s.begin(), ToLower());
 
      // Change everything back into upper case, but store the
      // result in a different string
      std::string  capital_s;
-   capital_s.reserve(s.size());
+     capital_s.resize(s.size());
-   std::transform (s.begin(), s.end(), capital_s.begin(), tolower); </pre>
+     std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
+   } </pre>
    <p><span class="larger"><strong>Note</strong></span> that these calls all
       involve the global C locale through the use of the C functions
       <code>toupper/tolower</code>.  This is absolutely guaranteed to work --
@@ -301,19 +314,28 @@
       So, if all your input forevermore consists of only those 96
       characters (hahahahahaha), then you're done.
    </p>
-   <p>At minimum, you can write short wrappers like
+   <p><span class="larger"><strong>Note</strong></span> that the
+      <code>ToUpper</code> and <code>ToLower</code> function objects
+      are needed because <code>toupper</code> and <code>tolower</code>
+      are overloaded names (declared in <code>&lt;cctype&gt;</code> and
+      <code>&lt;locale&gt;</code>) so the template-arguments for
+      <code>transform&lt;&gt;</code> cannot be deduced, as explained in
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this
+      message</a>.  <!-- section 14.8.2.4 clause 16 in ISO 14882:1998
+      if you're into that sort of thing -->
+      At minimum, you can write short wrappers like
    </p>
    <pre>
    char toLower (char c)
    {
-      return tolower(static_cast&lt;unsigned char&gt;(c));
+      return std::tolower(c);
    } </pre>
    <p>The correct method is to use a facet for a particular locale
       and call its conversion functions.  These are discussed more in
       Chapter 22; the specific part is
-      <a href="../22_locale/howto.html#5">here</a>, which shows the
+      <a href="../22_locale/howto.html#7">Correct Transformations</a>,
-      final version of this code.  (Thanks to James Kanze for assistance
+      which shows the final version of this code.  (Thanks to James Kanze
-      and suggestions on all of this.)
+      for assistance and suggestions on all of this.)
    </p>
    <p>Another common operation is trimming off excess whitespace.  Much
       like transformations, this task is trivial with the use of string's

libstdc++-v3/docs/html/22_locale/howto.html

@@ -168,18 +168,18 @@
    #include <algorithm>
    #include <cctype>      // old <ctype.h>
 
-   struct Toupper
+   struct ToUpper
    {
-       Toupper(std::locale const& l) : loc(l) {;}
+       ToUpper(std::locale const& l) : loc(l) {;}
-       char operator() (char c)  { return std::toupper(c,loc); }
+       char operator() (char c) const  { return std::toupper(c,loc); }
    private:
        std::locale const& loc;
    };
    
-   struct Tolower
+   struct ToLower
    {
-       Tolower(std::locale const& l) : loc(l) {;}
+       ToLower(std::locale const& l) : loc(l) {;}
-       char operator() (char c)  { return std::tolower(c,loc); }
+       char operator() (char c) const  { return std::tolower(c,loc); }
    private:
        std::locale const& loc;
    };
@@ -188,8 +188,8 @@
    {
       std::string  s("Some Kind Of Initial Input Goes Here");
       std::locale  loc_c("C");
-      Toupper      up(loc_c);
+      ToUpper      up(loc_c);
-      Tolower      down(loc_c);
+      ToLower      down(loc_c);
    
       // Change everything into upper case.
       std::transform(s.begin(), s.end(), s.begin(), up);
@@ -202,6 +202,10 @@
       std::string  capital_s;
       std::transform(s.begin(), s.end(), std::back_inserter(capital_s), up);
    }</pre>
+   <p>The <code>ToUpper</code> and <code>ToLower</code> structs can be
+      generalized for other character types by making <code>operator()</code>
+      a member function template.
+   </p>
    <p>The final version of the code uses <code>bind2nd</code> to eliminate
       the wrapper structs, but the resulting code is tricky.  I have not
       shown it here because no compilers currently available to me will