libstdc++-v3/doc/html/manual/strings.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7.  Strings</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="traits.html" title="Traits" /><link rel="next" href="localization.html" title="Chapter 8.  Localization" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7.
   4   Strings
   5
   6 </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="traits.html">Prev</a> </td><th width="60%" align="center">Part II.
   7   Standard Contents
   8 </th><td width="20%" align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 7.  Strings"><div class="titlepage"><div><div><h2 class="title"><a id="std.strings"></a>Chapter 7.
   9   Strings
  10   <a id="id479157" class="indexterm"></a>
  11 </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="strings.html#std.strings.string">String Classes</a></span></dt><dd><dl><dt><span class="sect2"><a href="strings.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.case">Case Sensitivity</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.character_types">Arbitrary Character Types</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.token">Tokenizing</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.shrink">Shrink to Fit</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.Cstring">CString (MFC)</a></span></dt></dl></dd></dl></div><div class="sect1" title="String Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.strings.string"></a>String Classes</h2></div></div></div><div class="sect2" title="Simple Transformations"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.simple"></a>Simple Transformations</h3></div></div></div><p>
  12       Here are Standard, simple, and portable ways to perform common
  13       transformations on a <code class="code">string</code> instance, such as
  14       "convert to all upper case." The word transformations
  15       is especially apt, because the standard template function
  16       <code class="code">transform&lt;&gt;</code> is used.
  17    </p><p>
  18      This code will go through some iterations.  Here's a simple
  19      version:
  20    </p><pre class="programlisting">
  21    #include &lt;string&gt;
  22    #include &lt;algorithm&gt;
  23    #include &lt;cctype&gt;      // old &lt;ctype.h&gt;
  24
  25    struct ToLower
  26    {
  27      char operator() (char c) const  { return std::tolower(c); }
  28    };
  29
  30    struct ToUpper
  31    {
  32      char operator() (char c) const  { return std::toupper(c); }
  33    };
  34
  35    int main()
  36    {
  37      std::string  s ("Some Kind Of Initial Input Goes Here");
  38
  39      // Change everything into upper case
  40      std::transform (s.begin(), s.end(), s.begin(), ToUpper());
  41
  42      // Change everything into lower case
  43      std::transform (s.begin(), s.end(), s.begin(), ToLower());
  44
  45      // Change everything back into upper case, but store the
  46      // result in a different string
  47      std::string  capital_s;
  48      capital_s.resize(s.size());
  49      std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
  50    }
  51    </pre><p>
  52      <span class="emphasis"><em>Note</em></span> that these calls all
  53       involve the global C locale through the use of the C functions
  54       <code class="code">toupper/tolower</code>.  This is absolutely guaranteed to work --
  55       but <span class="emphasis"><em>only</em></span> if the string contains <span class="emphasis"><em>only</em></span> characters
  56       from the basic source character set, and there are <span class="emphasis"><em>only</em></span>
  57       96 of those.  Which means that not even all English text can be
  58       represented (certain British spellings, proper names, and so forth).
  59       So, if all your input forevermore consists of only those 96
  60       characters (hahahahahaha), then you're done.
  61    </p><p><span class="emphasis"><em>Note</em></span> that the
  62       <code class="code">ToUpper</code> and <code class="code">ToLower</code> function objects
  63       are needed because <code class="code">toupper</code> and <code class="code">tolower</code>
  64       are overloaded names (declared in <code class="code">&lt;cctype&gt;</code> and
  65       <code class="code">&lt;locale&gt;</code>) so the template-arguments for
  66       <code class="code">transform&lt;&gt;</code> cannot be deduced, as explained in
  67       <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html" target="_top">this
  68       message</a>.
  69
  70       At minimum, you can write short wrappers like
  71    </p><pre class="programlisting">
  72    char toLower (char c)
  73    {
  74       return std::tolower(c);
  75    } </pre><p>(Thanks to James Kanze for assistance and suggestions on all of this.)
  76    </p><p>Another common operation is trimming off excess whitespace.  Much
  77       like transformations, this task is trivial with the use of string's
  78       <code class="code">find</code> family.  These examples are broken into multiple
  79       statements for readability:
  80    </p><pre class="programlisting">
  81    std::string  str (" \t blah blah blah    \n ");
  82
  83    // trim leading whitespace
  84    string::size_type  notwhite = str.find_first_not_of(" \t\n");
  85    str.erase(0,notwhite);
  86
  87    // trim trailing whitespace
  88    notwhite = str.find_last_not_of(" \t\n");
  89    str.erase(notwhite+1); </pre><p>Obviously, the calls to <code class="code">find</code> could be inserted directly
  90       into the calls to <code class="code">erase</code>, in case your compiler does not
  91       optimize named temporaries out of existence.
  92    </p></div><div class="sect2" title="Case Sensitivity"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.case"></a>Case Sensitivity</h3></div></div></div><p>
  93     </p><p>The well-known-and-if-it-isn't-well-known-it-ought-to-be
  94       <a class="ulink" href="http://www.gotw.ca/gotw/" target="_top">Guru of the Week</a>
  95       discussions held on Usenet covered this topic in January of 1998.
  96       Briefly, the challenge was, <span class="quote">“<span class="quote">write a 'ci_string' class which
  97       is identical to the standard 'string' class, but is
  98       case-insensitive in the same way as the (common but nonstandard)
  99       C function stricmp()</span>”</span>.
 100    </p><pre class="programlisting">
 101    ci_string s( "AbCdE" );
 102
 103    // case insensitive
 104    assert( s == "abcde" );
 105    assert( s == "ABCDE" );
 106
 107    // still case-preserving, of course
 108    assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
 109    assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre><p>The solution is surprisingly easy.  The original answer was
 110    posted on Usenet, and a revised version appears in Herb Sutter's
 111    book <span class="emphasis"><em>Exceptional C++</em></span> and on his website as <a class="ulink" href="http://www.gotw.ca/gotw/029.htm" target="_top">GotW 29</a>.
 112    </p><p>See?  Told you it was easy!</p><p>
 113      <span class="emphasis"><em>Added June 2000:</em></span> The May 2000 issue of C++
 114      Report contains a fascinating <a class="ulink" href="http://lafstern.org/matt/col2_new.pdf" target="_top"> article</a> by
 115      Matt Austern (yes, <span class="emphasis"><em>the</em></span> Matt Austern) on why
 116      case-insensitive comparisons are not as easy as they seem, and
 117      why creating a class is the <span class="emphasis"><em>wrong</em></span> way to go
 118      about it in production code.  (The GotW answer mentions one of
 119      the principle difficulties; his article mentions more.)
 120    </p><p>Basically, this is "easy" only if you ignore some things,
 121       things which may be too important to your program to ignore.  (I chose
 122       to ignore them when originally writing this entry, and am surprised
 123       that nobody ever called me on it...)  The GotW question and answer
 124       remain useful instructional tools, however.
 125    </p><p><span class="emphasis"><em>Added September 2000:</em></span>  James Kanze provided a link to a
 126       <a class="ulink" href="http://www.unicode.org/reports/tr21/tr21-5.html" target="_top">Unicode
 127       Technical Report discussing case handling</a>, which provides some
 128       very good information.
 129    </p></div><div class="sect2" title="Arbitrary Character Types"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.character_types"></a>Arbitrary Character Types</h3></div></div></div><p>
 130     </p><p>The <code class="code">std::basic_string</code> is tantalizingly general, in that
 131       it is parameterized on the type of the characters which it holds.
 132       In theory, you could whip up a Unicode character class and instantiate
 133       <code class="code">std::basic_string&lt;my_unicode_char&gt;</code>, or assuming
 134       that integers are wider than characters on your platform, maybe just
 135       declare variables of type <code class="code">std::basic_string&lt;int&gt;</code>.
 136    </p><p>That's the theory.  Remember however that basic_string has additional
 137       type parameters, which take default arguments based on the character
 138       type (called <code class="code">CharT</code> here):
 139    </p><pre class="programlisting">
 140       template &lt;typename CharT,
 141                 typename Traits = char_traits&lt;CharT&gt;,
 142                 typename Alloc = allocator&lt;CharT&gt; &gt;
 143       class basic_string { .... };</pre><p>Now, <code class="code">allocator&lt;CharT&gt;</code> will probably Do The Right
 144       Thing by default, unless you need to implement your own allocator
 145       for your characters.
 146    </p><p>But <code class="code">char_traits</code> takes more work.  The char_traits
 147       template is <span class="emphasis"><em>declared</em></span> but not <span class="emphasis"><em>defined</em></span>.
 148       That means there is only
 149    </p><pre class="programlisting">
 150       template &lt;typename CharT&gt;
 151         struct char_traits
 152         {
 153             static void foo (type1 x, type2 y);
 154             ...
 155         };</pre><p>and functions such as char_traits&lt;CharT&gt;::foo() are not
 156       actually defined anywhere for the general case.  The C++ standard
 157       permits this, because writing such a definition to fit all possible
 158       CharT's cannot be done.
 159    </p><p>The C++ standard also requires that char_traits be specialized for
 160       instantiations of <code class="code">char</code> and <code class="code">wchar_t</code>, and it
 161       is these template specializations that permit entities like
 162       <code class="code">basic_string&lt;char,char_traits&lt;char&gt;&gt;</code> to work.
 163    </p><p>If you want to use character types other than char and wchar_t,
 164       such as <code class="code">unsigned char</code> and <code class="code">int</code>, you will
 165       need suitable specializations for them.  For a time, in earlier
 166       versions of GCC, there was a mostly-correct implementation that
 167       let programmers be lazy but it broke under many situations, so it
 168       was removed.  GCC 3.4 introduced a new implementation that mostly
 169       works and can be specialized even for <code class="code">int</code> and other
 170       built-in types.
 171    </p><p>If you want to use your own special character class, then you have
 172       <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html" target="_top">a lot
 173       of work to do</a>, especially if you with to use i18n features
 174       (facets require traits information but don't have a traits argument).
 175    </p><p>Another example of how to specialize char_traits was given <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html" target="_top">on the
 176       mailing list</a> and at a later date was put into the file <code class="code">
 177       include/ext/pod_char_traits.h</code>.  We agree
 178       that the way it's used with basic_string (scroll down to main())
 179       doesn't look nice, but that's because <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html" target="_top">the
 180       nice-looking first attempt</a> turned out to <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html" target="_top">not
 181       be conforming C++</a>, due to the rule that CharT must be a POD.
 182       (See how tricky this is?)
 183    </p></div><div class="sect2" title="Tokenizing"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.token"></a>Tokenizing</h3></div></div></div><p>
 184     </p><p>The Standard C (and C++) function <code class="code">strtok()</code> leaves a lot to
 185       be desired in terms of user-friendliness.  It's unintuitive, it
 186       destroys the character string on which it operates, and it requires
 187       you to handle all the memory problems.  But it does let the client
 188       code decide what to use to break the string into pieces; it allows
 189       you to choose the "whitespace," so to speak.
 190    </p><p>A C++ implementation lets us keep the good things and fix those
 191       annoyances.  The implementation here is more intuitive (you only
 192       call it once, not in a loop with varying argument), it does not
 193       affect the original string at all, and all the memory allocation
 194       is handled for you.
 195    </p><p>It's called stringtok, and it's a template function. Sources are
 196    as below, in a less-portable form than it could be, to keep this
 197    example simple (for example, see the comments on what kind of
 198    string it will accept).
 199    </p><pre class="programlisting">
 200 #include &lt;string&gt;
 201 template &lt;typename Container&gt;
 202 void
 203 stringtok(Container &amp;container, string const &amp;in,
 204           const char * const delimiters = " \t\n")
 205 {
 206     const string::size_type len = in.length();
 207           string::size_type i = 0;
 208
 209     while (i &lt; len)
 210     {
 211         // Eat leading whitespace
 212         i = in.find_first_not_of(delimiters, i);
 213         if (i == string::npos)
 214           return;   // Nothing left but white space
 215
 216         // Find the end of the token
 217         string::size_type j = in.find_first_of(delimiters, i);
 218
 219         // Push token
 220         if (j == string::npos)
 221         {
 222           container.push_back(in.substr(i));
 223           return;
 224         }
 225         else
 226           container.push_back(in.substr(i, j-i));
 227
 228         // Set up for next loop
 229         i = j + 1;
 230     }
 231 }
 232 </pre><p>
 233      The author uses a more general (but less readable) form of it for
 234      parsing command strings and the like.  If you compiled and ran this
 235      code using it:
 236    </p><pre class="programlisting">
 237    std::list&lt;string&gt;  ls;
 238    stringtok (ls, " this  \t is\t\n  a test  ");
 239    for (std::list&lt;string&gt;const_iterator i = ls.begin();
 240         i != ls.end(); ++i)
 241    {
 242        std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n";
 243    } </pre><p>You would see this as output:
 244    </p><pre class="programlisting">
 245    :this:
 246    :is:
 247    :a:
 248    :test: </pre><p>with all the whitespace removed.  The original <code class="code">s</code> is still
 249       available for use, <code class="code">ls</code> will clean up after itself, and
 250       <code class="code">ls.size()</code> will return how many tokens there were.
 251    </p><p>As always, there is a price paid here, in that stringtok is not
 252       as fast as strtok.  The other benefits usually outweigh that, however.
 253    </p><p><span class="emphasis"><em>Added February 2001:</em></span>  Mark Wilden pointed out that the
 254       standard <code class="code">std::getline()</code> function can be used with standard
 255       <code class="code">istringstreams</code> to perform
 256       tokenizing as well.  Build an istringstream from the input text,
 257       and then use std::getline with varying delimiters (the three-argument
 258       signature) to extract tokens into a string.
 259    </p></div><div class="sect2" title="Shrink to Fit"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.shrink"></a>Shrink to Fit</h3></div></div></div><p>
 260     </p><p>From GCC 3.4 calling <code class="code">s.reserve(res)</code> on a
 261       <code class="code">string s</code> with <code class="code">res &lt; s.capacity()</code> will
 262       reduce the string's capacity to <code class="code">std::max(s.size(), res)</code>.
 263    </p><p>This behaviour is suggested, but not required by the standard. Prior
 264       to GCC 3.4 the following alternative can be used instead
 265    </p><pre class="programlisting">
 266       std::string(str.data(), str.size()).swap(str);
 267    </pre><p>This is similar to the idiom for reducing
 268       a <code class="code">vector</code>'s memory usage
 269       (see <a class="link" href="../faq.html#faq.size_equals_capacity" title="7.8.">this FAQ
 270       entry</a>) but the regular copy constructor cannot be used
 271       because libstdc++'s <code class="code">string</code> is Copy-On-Write.
 272    </p><p>In <a class="link" href="status.html#status.iso.200x" title="C++ 200x">C++0x</a> mode you can call
 273       <code class="code">s.shrink_to_fit()</code> to achieve the same effect as
 274       <code class="code">s.reserve(s.size())</code>.
 275    </p></div><div class="sect2" title="CString (MFC)"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.Cstring"></a>CString (MFC)</h3></div></div></div><p>
 276     </p><p>A common lament seen in various newsgroups deals with the Standard
 277       string class as opposed to the Microsoft Foundation Class called
 278       CString.  Often programmers realize that a standard portable
 279       answer is better than a proprietary nonportable one, but in porting
 280       their application from a Win32 platform, they discover that they
 281       are relying on special functions offered by the CString class.
 282    </p><p>Things are not as bad as they seem.  In
 283       <a class="ulink" href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html" target="_top">this
 284       message</a>, Joe Buck points out a few very important things:
 285    </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Standard <code class="code">string</code> supports all the operations
 286              that CString does, with three exceptions.
 287          </p></li><li class="listitem"><p>Two of those exceptions (whitespace trimming and case
 288              conversion) are trivial to implement.  In fact, we do so
 289              on this page.
 290          </p></li><li class="listitem"><p>The third is <code class="code">CString::Format</code>, which allows formatting
 291              in the style of <code class="code">sprintf</code>.  This deserves some mention:
 292          </p></li></ul></div><p>
 293       The old libg++ library had a function called form(), which did much
 294       the same thing.  But for a Standard solution, you should use the
 295       stringstream classes.  These are the bridge between the iostream
 296       hierarchy and the string class, and they operate with regular
 297       streams seamlessly because they inherit from the iostream
 298       hierarchy.  An quick example:
 299    </p><pre class="programlisting">
 300    #include &lt;iostream&gt;
 301    #include &lt;string&gt;
 302    #include &lt;sstream&gt;
 303
 304    string f (string&amp; incoming)     // incoming is "foo  N"
 305    {
 306        istringstream   incoming_stream(incoming);
 307        string          the_word;
 308        int             the_number;
 309
 310        incoming_stream &gt;&gt; the_word        // extract "foo"
 311                        &gt;&gt; the_number;     // extract N
 312
 313        ostringstream   output_stream;
 314        output_stream &lt;&lt; "The word was " &lt;&lt; the_word
 315                      &lt;&lt; " and 3*N was " &lt;&lt; (3*the_number);
 316
 317        return output_stream.str();
 318    } </pre><p>A serious problem with CString is a design bug in its memory
 319       allocation.  Specifically, quoting from that same message:
 320    </p><pre class="programlisting">
 321    CString suffers from a common programming error that results in
 322    poor performance.  Consider the following code:
 323
 324    CString n_copies_of (const CString&amp; foo, unsigned n)
 325    {
 326            CString tmp;
 327            for (unsigned i = 0; i &lt; n; i++)
 328                    tmp += foo;
 329            return tmp;
 330    }
 331
 332    This function is O(n^2), not O(n).  The reason is that each +=
 333    causes a reallocation and copy of the existing string.  Microsoft
 334    applications are full of this kind of thing (quadratic performance
 335    on tasks that can be done in linear time) -- on the other hand,
 336    we should be thankful, as it's created such a big market for high-end
 337    ix86 hardware. :-)
 338
 339    If you replace CString with string in the above function, the
 340    performance is O(n).
 341    </pre><p>Joe Buck also pointed out some other things to keep in mind when
 342       comparing CString and the Standard string class:
 343    </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>CString permits access to its internal representation; coders
 344              who exploited that may have problems moving to <code class="code">string</code>.
 345          </p></li><li class="listitem"><p>Microsoft ships the source to CString (in the files
 346              MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation
 347              bug and rebuild your MFC libraries.
 348              <span class="emphasis"><em><span class="emphasis"><em>Note:</em></span> It looks like the CString shipped
 349              with VC++6.0 has fixed this, although it may in fact have been
 350              one of the VC++ SPs that did it.</em></span>
 351          </p></li><li class="listitem"><p><code class="code">string</code> operations like this have O(n) complexity
 352              <span class="emphasis"><em>if the implementors do it correctly</em></span>.  The libstdc++
 353              implementors did it correctly.  Other vendors might not.
 354          </p></li><li class="listitem"><p>While chapters of the SGI STL are used in libstdc++, their
 355              string class is not.  The SGI <code class="code">string</code> is essentially
 356              <code class="code">vector&lt;char&gt;</code> and does not do any reference
 357              counting like libstdc++'s does.  (It is O(n), though.)
 358              So if you're thinking about SGI's string or rope classes,
 359              you're now looking at four possibilities:  CString, the
 360              libstdc++ string, the SGI string, and the SGI rope, and this
 361              is all before any allocator or traits customizations!  (More
 362              choices than you can shake a stick at -- want fries with that?)
 363          </p></li></ul></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="traits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Traits </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8.
 364   Localization
 365
 366 </td></tr></table></div></body></html>