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