[libstdc++] Notes on specializing char_traits for basic_string<arbitrary-stuff>

[Phil Edwards <phil at jaj dot com>]

Been meaning to do this for a while now.


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

	* docs/html/21_strings/howto.html:  Write #5, char_traits.
	* docs/html/17_intro/porting.texi:  Expand on os_include_dir.
	* docs/html/17_intro/porting.html:  Regenerate.


Index: docs/html/17_intro/porting.texi
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/porting.texi,v
retrieving revision 1.6
diff -u -3 -p -r1.6 porting.texi
--- docs/html/17_intro/porting.texi	24 Jun 2002 05:50:58 -0000	1.6
+++ docs/html/17_intro/porting.texi	10 Oct 2002 21:58:48 -0000
@@ -102,12 +102,13 @@ directory.  The important information is
 directory under @file{config/os} to store the files for your operating
 system.
 
-You'll have to change the @file{configure.target} file to ensure that
-your new directory is activated.  Look for the switch statement that
-sets @code{os_include_dir}, and add a pattern to handle your operating
-system.  The switch statement switches on only the OS portion of the
-standard target triplet; e.g., the @code{solaris2.8} in
-@code{sparc-sun-solaris2.8}.
+You might have to change the @file{configure.target} file to ensure that
+your new directory is activated.  Look for the switch statement that sets
+@code{os_include_dir}, and add a pattern to handle your operating system
+if the default will not suffice.  The switch statement switches on only
+the OS portion of the standard target triplet; e.g., the @code{solaris2.8}
+in @code{sparc-sun-solaris2.8}.  If the new directory is named after the
+OS portion of the triplet (the default), then nothing needs to be changed.
 
 The first file to create in this directory, should be called
 @file{os_defines.h}.  This file contains basic macro definitions
Index: docs/html/21_strings/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/21_strings/howto.html,v
retrieving revision 1.13
diff -u -3 -p -r1.13 howto.html
--- docs/html/21_strings/howto.html	7 Oct 2002 18:11:19 -0000	1.13
+++ docs/html/21_strings/howto.html	10 Oct 2002 21:58:48 -0000
@@ -340,13 +340,74 @@
 
 <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>The <code>std::basic_string</code> is tantalizingly general, in that
+      it is parameterized on the type of the characters which it holds.
+      In theory, you could whip up a Unicode character class and instantiate
+      <code>std::basic_string&lt;my_unicode_char&gt;</code>, or assuming
+      that integers are wider than characters on your platform, maybe just
+      declare variables of type <code>std::basic_string&lt;int&gt;</code>.
+   </p>
+   <p>That's the theory.  Remember however that basic_string has additional
+      type parameters, which take default arguments based on the character
+      type (called CharT here):
+      <pre>
+      template &lt;typename CharT,
+                typename Traits = char_traits&lt;CharT&gt;,
+                typename Alloc = allocator&lt;CharT&gt; &gt;
+      class basic_string { .... };</pre>
+      Now, <code>allocator&lt;CharT&gt;</code> will probably Do The Right
+      Thing by default, unless you need to do something very strange with
+      memory allocation in your characters.
+   </p>
+   <p>But <code>char_traits</code> takes more work.  The char_traits
+      template is <em>declared</em> but not <em>defined</em>.
+      That means there is only
+      <pre>
+      template &lt;typename CharT&gt;
+        struct char_traits
+        {
+            static void foo (type1 x, type2 y);
+            ...
+        };</pre>
+      and functions such as char_traits&lt;CharT&gt;::foo() are not
+      actually defined anywhere for the general case.  The C++ standard
+      permits this, because writing such a definition to fit all possible
+      CharT's cannot be done.  (For a time, in earlier versions of GCC,
+      there was a mostly-correct implementation that let programmers be
+      lazy.  :-)  But it broke under many situations, so it was removed.
+      You are no longer allowed to be lazy and non-portable.)
+   </p>
+   <p>The C++ standard also requires that char_traits be specialized for
+      instantiations of <code>char</code> and <code>wchar_t</code>, and it
+      is these template specializations that permit entities like
+      <code>basic_string&lt;char,char_traits&lt;char&gt;&gt;</code> to work.
+   </p>
+   <p>If you want to use character types other than char and wchar_t,
+      such as <code>unsigned char</code> and <code>int</code>, you will
+      need to write specializations for them at the present time.  If you
+      want to use your own special character class, then you have
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html";>a lot
+      of work to do</a>, especially if you with to use i18n features
+      (facets require traits information but don't have a traits argument).
+   </p>
+   <p>One example of how to specialize char_traits is given
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html";>in
+      this message</a>.  We agree that the way it's used with basic_string
+      (scroll down to main()) doesn't look nice, but that's because
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html";>the
+      nice-looking first attempt</a> turned out to
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html";>not
+      be conforming C++</a>, due to the rule that CharT must be a POD.
+      (See how tricky this is?)
+   </p>
+   <p>Other approaches were suggested in that same thread, such as providing
+      more specializations and/or some helper types in the library to assist
+      users writing such code.  So far nobody has had the time...
+      <a href="../17_intro/contribute.html">do you?</a>
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
-
 
 
 <!-- ####################################################### -->