string.htm

自编的一个String类

</div>

<h3><a name="compare"></a>The <em>compare</em> functions</h3>
<div align="left">

<table border="1" width="100%" cellpadding="2">
  <tr>
    <td width="50%" valign="top"><tt>int compare(const String&amp; str) const</tt></td>
    <td width="50%" valign="top">a.compare(b) compares a and b in normal sort order. Return
    -1, 0 or 1</td>
  </tr>
  <tr>
    <td width="50%" valign="top"><tt>int compare(uint pos, uint n, const String&amp; str)
    const</tt></td>
    <td width="50%" valign="top">a.compare(pos,n,b) compares String(a,pos,n) and b in normal
    sort order. Return -1, 0 or 1</td>
  </tr>
  <tr>
    <td width="50%" valign="top"><tt>int compare(uint pos1, uint n1, const String&amp; str,
    uint pos2, uint n2) const</tt></td>
    <td width="50%" valign="top">a.compare(pos1,n1,b,pos2,n2) compares String(a,pos1,n1) and
    String(b,pos2,n2) in normal sort order. Return -1, 0 or 1</td>
  </tr>
  <tr>
    <td width="50%" valign="top"><tt>int compare(const char* s) const</tt></td>
    <td width="50%" valign="top">return compare(String(s))</td>
  </tr>
  <tr>
    <td width="50%" valign="top"><tt>int compare(uint pos1, uint n1, const char* s, uint n2 =
    npos) const</tt></td>
    <td width="50%" valign="top">return compare(pos1, n1, String(s,n2))</td>
  </tr>
</table>
</div>

<h2><a name="binary"></a>The binary String functions</h2>

<p>+ means concatenate, otherwise the meanings are obvious.</p>

<pre>String operator+(const String&amp; lhs, const String&amp; rhs)
String operator+(const char* lhs, const String&amp; rhs)
String operator+(char lhs, const String&amp; rhs)
String operator+(const String&amp; lhs, const char* rhs)
String operator+(const String&amp; lhs, char rhs)</pre>

<pre>bool operator==(const String&amp; lhs, const String&amp; rhs)
bool operator==(const char* lhs, const String&amp; rhs)
bool operator==(const String&amp; lhs, const char* rhs)</pre>

<pre>bool operator!=(const String&amp; lhs, const String&amp; rhs)
bool operator!=(const char* lhs, const String&amp; rhs)
bool operator!=(const String&amp; lhs, const char* rhs)</pre>

<pre>bool operator&lt;(const String&amp; lhs, const String&amp; rhs)
bool operator&lt;(const char* lhs, const String&amp; rhs)
bool operator&lt;(const String&amp; lhs, const char* rhs)</pre>

<pre>bool operator&gt;(const String&amp; lhs, const String&amp; rhs)
bool operator&gt;(const char* lhs, const String&amp; rhs)
bool operator&gt;(const String&amp; lhs, const char* rhs)</pre>

<pre>bool operator&lt;=(const String&amp; lhs, const String&amp; rhs)
bool operator&lt;=(const char* lhs, const String&amp; rhs)
bool operator&lt;=(const String&amp; lhs, const char* rhs)</pre>

<pre>bool operator&gt;=(const String&amp; lhs, const String&amp; rhs)
bool operator&gt;=(const char* lhs, const String&amp; rhs)
bool operator&gt;=(const String&amp; lhs, const char* rhs)</pre>

<pre>void swap(const String&amp; A, const String&amp; B)
</pre>

<p>The stream functions - slightly rough implementation as yet:</p>

<pre>istream&amp; operator&gt;&gt;(istream&amp; is, String&amp; str)</pre>

<p>&nbsp;&nbsp; ... read token from istream</p>

<pre>ostream&amp; operator&lt;&lt;(ostream&amp; os, const String&amp; str)</pre>

<p>&nbsp;&nbsp; ... output a String</p>

<pre>istream&amp; getline(istream is, String&amp; str, char delim = '\n')</pre>

<p>&nbsp;&nbsp; ... read a line<br>
</p>

<h2><a name="policies"></a>The policies</h2>

<h3><a name="realloc"></a>Reallocation policy</h3>

<p>This section discusses under what circumstances the String data in a String object will
be moved. It is unclear to me what the standard allows. Moving the String data invalidates
the const char* returned by .data() and .c_str() and any reference returned by the
non-const versions of .at() or operator[] (and any iterators referring to the string).</p>

<p>I describe here what my program does. Another standard String package may (and probably
does) follow different rules.</p>

<p>The value returned by .c_str will most likely become invalid under almost any operation
of the String which changes the value of the String. Also a call to .c_str will invalidate
a const char* returned by .data() and any reference returned by .at() or operator[].</p>

<p>If A is a String that has been assigned a capacity with the reserve function then the
following functions will not cause a reallocation (so the value returned by .data() etc.
will remain valid)</p>

<pre>   A += ...
   A.assign(...)
   A.append(...)
   A.insert(...)
   A.erase(...)
   A.replace(...)</pre>

<p>where ... denotes a legitimate argument, providing the resulting String will fit in the
assigned capacity (as set by a call to reserve).</p>

<p>If the resulting String will not fit into the assigned capacity the String data will be
moved (so the value returned by .data() etc. will not remain valid). Also the String will
no longer be regarded as having an assigned capacity.</p>

<p>The concept of having an assigned capacity is important in considering the behaviour of
assign, erase and replace when the parameters are such that length of the String is
reduced. For example</p>

<pre>   String A = &quot;0123456789&quot;;
   A.reserve(1); // will set capacity to A.size() = 10
   const char* d = A.data();
   A.erase(1,9);</pre>

<p>will leave a valid value in <em>d</em> whereas</p>

<pre>   String A = &quot;0123456789&quot;;
   const char* d = A.data();
   A.erase(1,9);
</pre>

<p>will not leave a valid value in d since the storage of the String data will have been
moved.</p>

<p>The operator= does not conform to these rules. A = <em>something</em> will always
remove any assigned capacity for A (and will not pick up any capacity from the <em>something</em>).</p>

<p>In this package A.reserve() or A.reserve(0) will remove any assigned capacity. ie it
will be as though no capacity had ever been assigned. So an erase or a replace that
changes a length will cause a reallocation.</p>

<p>But don't expect anyone else's package to follow these rules. <br>
</p>

<h3><a name="plus"></a>Policy on operator+, operator+= and append</h3>

<p>The evaluation of the concatenation expression A+B is delayed until the expression is
used or until the value is referred to twice. This means the expressions such as A+B+C are
evaluated in one sweep rather than having A+B formed as a temporary before evaluating
A+B+C.</p>

<p>Unfortunately, this means that in expressions such as A + <em>c_string</em> the
c-string <em>c_string</em> will be converted to a String object, before the overall String
is formed. Since c-strings will usually be small I don't see this as a serious problem.</p>

<p>Likewise A+=X or A.append(X) will not be evaluated until the result is used (unless A
has been assigned a capacity that is large enough to accommodate X). This means that
sequences like</p>

<pre>   A += X1;
   A += X2;
   ...</pre>

<p>will not cause repeated reallocations of the space used by the String data.</p>

<h2><a name="functions"></a>String functions</h2>

<p>These are a set of simple functions for manipulating strings. You need the 
header file <i>str_fns.h</i> and body file <i>str_fns.cpp</i>.</p>

<table border="1" width="100%" cellpadding="2">
  <tr>
    <td width="50%"><tt>String ToString(int i)</tt></td>
    <td width="50%">Convert int to string</td>
  </tr>
  <tr>
    <td width="50%"><tt>String ToString(long i)</tt></td>
    <td width="50%">Convert long to string</td>
  </tr>
  <tr>
    <td width="50%"><tt>String ToString(double f, int ndec = 4)</tt></td>
    <td width="50%">Convert double to string; ndec determines the number of 
    decimal places</td>
  </tr>
  <tr>
    <td width="50%"><tt>void UpperCase(String&amp; S)</tt></td>
    <td width="50%">Convert string to upper case</td>
  </tr>
  <tr>
    <td width="50%"><tt>void LowerCase(String&amp; S)</tt></td>
    <td width="50%">Convert string to lower case</td>
  </tr>
  <tr>
    <td width="50%"><tt>bool IsInt(const String&amp; S)</tt></td>
    <td width="50%">Does a string represent an integer</td>
  </tr>
  <tr>
    <td width="50%"><tt>bool IsFloat(const String&amp; S)</tt></td>
    <td width="50%">Does a string represent a floating point number (includes 
    integer, does not allow for E format)</td>
  </tr>
  </table>

<h2><a name="command"></a>Command line class</h2>

<p>This is a simple class for extracting the information from the command line 
(when you call a program from a text window). See the <a href="genemake.htm">
genemake</a> program as an example. I assume you call your program with a 
command like</p>

<pre>   program -options A B C</pre>
<p>where <i>program</i> is the name of the program, <i>options</i> is a sequence 
of single letter options with no spaces and <i>A B C</i> is a sequence of names separated by 
spaces.</p>

<p>Start your main program with</p>

<pre>   #include &quot;str.h&quot;
   #include &quot;commline.h&quot;
   
   int main(int argc, char** argv)
   {
      CommandLine CL(argc, argv);
      ...
</pre>

<p>Here are the member functions for the <i>CommandLine</i> class.</p>


<table border="1" width="100%" cellpadding="2">
  <tr>
    <td width="50%"><tt>CommandLine(int argc, char** argv)</tt></td>
    <td width="50%">Constructor: <i>argc</i>, <i>argv</i> from <i>main(int argc, char** argv)</i></td>
  </tr>
  <tr>
    <td width="50%"><tt>int argc()</tt></td>
    <td width="50%">Return argc</td>
  </tr>
  <tr>
    <td width="50%"><tt>char** argv()</tt></td>
    <td width="50%">Return argv</td>
  </tr>
  <tr>
    <td width="50%"><tt>String GetArg(int i)</tt></td>
    <td width="50%">Get the <i>i</i>-th name; <i>i</i>=1 for first name after 
    options</td>
  </tr>
  <tr>
    <td width="50%"><tt>String GetOptions()</tt></td>
    <td width="50%">Get option sequence</td>
  </tr>
  <tr>
    <td width="50%"><tt>int NumberOfArgs()</tt></td>
    <td width="50%">Return number of arguments excluding options</td>
  </tr>
  <tr>
    <td width="50%"><tt>bool Options()</tt></td>
    <td width="50%">True if there are options</td>
  </tr>
  <tr>
    <td width="50%"><tt>bool HasOption(const String&amp; s)</tt></td>
    <td width="50%">True if <i>options</i> has any character in <i>s</i></td>
  </tr>
  </table>


<h2><a name="todo"></a>To do list</h2>

<ul>
  <li>Can there be memory leaks following an exception?</li>
  <li>Tests for failure to allocate memory (?)</li>
  <li>Avoid virtual call by operator[] and at</li>
  <li>Inline functions where appropriate</li>
  <li>Try to reduce the number of virtual function calls</li>
  <li>Try to remove repeated pieces of code</li>
  <li>Check all code is exercised by test program</li>
  <li>Redo IO routines</li>
  <li>Implement iterators</li>
  <li>Better comments</li>
  <li>Document policy on operator[] and at.</li>
</ul>

<p>&nbsp;</p>

<h2><a name="history"></a>History</h2>

<ul>
  <li>April, 1996: First version</li>
  <li>November, 1996: Fix problems with <em>find</em> and <em>rfind</em>, change <em>string</em>
    to <em>String</em>, update simulated exceptions.</li>
  <li>August, 1998: Minor fixes, align with January '96 working paper.</li>
  <li>September, 1998: Align with official standard, minor improvements.</li>
  <li>July, 2001: Fix IO, minor changes, include format and gstring programs and 
  string functions.</li>
</ul>

<h3><a name="Aug98"></a>August, 1998 changes</h3>

<ul>
  <li>remove replaced by <a href="#editing">erase</a></li>
  <li>order of arguments changed in <a href="#compare">compare</a></li>
  <li>replace(str, pos, n, c) changed to <a href="#editing">replace(str, pos, n1, n2, c)</a>
    [make sure you update your program if you are using this, since the old version will still
    compile and will give wrong answers]</li>
  <li>update behaviour of <a href="#storage">reserve</a> (see <a href="#realloc">notes</a>).</li>
  <li><a href="#storage">clear()</a></li>
  <li><a href="#binary">swap(A,B)</a></li>
  <li>some defaults for arguments deleted</li>
  <li>updated exception library</li>
  <li>fixed global variable problem (?)</li>
  <li>html version of documentation</li>
</ul>

<h3><a name="Sep98"></a>September, 1998 changes</h3>

<ul>
  <li>align with C++ standard - delete a number of default values for parameters</li>
  <li>minor improvements - particularly remove some unnecessary copies</li>
</ul>

<h3><a name="Feb01"></a>July, 2001 changes</h3>

<ul>
  <li>Fix IO routines; other minor fixes</li>
  <li>Include <a href="format.htm">format program</a>, <a href="gstring.htm">
  gstring program</a>, <a href="#functions">string functions</a>, 
  <a href="#command">command line class</a></li>
</ul>
<p>&nbsp;</p>
<ul>
  <li><a href="#top">Go to top</a></li>
  <li><a HREF="ol_doc.htm">To online documentation page</a></li>
</ul>
</body>
</html>