Started String class documentation.

diff --git a/doc/manual.xml b/doc/manual.xml
new file mode 100644 (file)
index 0000000..a6a8574
--- /dev/null
+++ b/doc/manual.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<doc>
+  <book>
+    <titlepage>
+    <title>Andromeda Class Library</title>
+    </titlepage>
+    <toc/>
+    <xi:include href="string.xml"
+         xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  </book>
+</doc>

diff --git a/doc/string.xml b/doc/string.xml
new file mode 100644 (file)
index 0000000..699f110
--- /dev/null
+++ b/doc/string.xml
@@ -0,0 +1,245 @@
+<?xml version="1.0"?>
+<chapter>
+<heading>class String</heading>
+
+<pre>
+   #include &lt;Stringc.h&gt;
+</pre>
+<para>
+The C++ String class can be used to represent character strings and perform
+operation upon them. Many operations are defined for normal operators but may
+have different semantics. E.g. the + operator is used to concatenate (add)
+strings together.
+</para>
+<para>
+Substrings may be selected from strings to create other strings. Also,
+substrings have lvalue semantics, meaning a string may be assigned to a
+substring expression.
+</para>
+
+<section>
+<heading>Construction and assignment.</heading>
+<description>
+<item tag="String()">
+  The default constructor creates an empty string.
+</item>
+<item tag="String(char)">
+</item>
+<item tag="String(const char *)">
+</item>
+<item tag="String(const String &amp;)">
+</item>
+
+<para>
+Other constructors are provided to initialize strings from character
+pointers, single characters or other strings. These constuctors also take care
+of typecasting:
+</para>
+<example>
+String x;          // Contruct an empty string
+String abc(&quot;abc&quot;); // Convert a char * to a string
+String p('p');     // A string with one character in it.
+</example>
+
+<para>
+Another string (or string expression), a char* or a single character can be
+assigned to a string:
+</para>
+<example>
+String x, y;
+
+x = &quot;abc&quot;;
+y = x;
+x = 'p';
+</example>
+</section>
+
+<section>
+<heading>Relational operators.</heading>
+
+<para>
+All relational operators (==, != , &lt;, &lt;=, &gt; and &gt;=) are
+available to compare strings alphabethically. Note that the comparison is done
+in the local character set, which will be ASCII in most cases. This also means
+that case is significant.
+</para>
+</section>
+<section>
+<heading>Adding strings together.</heading>
+
+<para>
+String can be added together, i.e. concatenated, with the <strong>+</strong>
+operator. Of course, the <strong>+= </strong>operator can be used as well. Example:
+</para>
+<example>
+String x, y, z;
+
+x = &quot;abc&quot;
+y = &quot;def&quot;
+z = x + y;   //  z = &quot;abcdef&quot;
+y += x;      //  y = &quot;defabc&quot;
+</example>
+</section>
+<section>
+<heading>String length, testing and character access</heading>
+
+<para>
+The length of a string can be determined with the <strong>~ </strong>operator. Do not
+confuse this with the bit-wise inversion operator !
+</para>
+<example>
+String x = &quot;Hello&quot;;
+int    l = ~x;      // l = 5
+</example>
+<para>
+The test for an empty string is done with the <strong>! </strong>operator. Note that
+there is no test for a non-empty string.
+</para>
+<example>
+if (!x)
+   cout &lt;&lt; &quot;String x is empty\n&quot;;
+</example>
+<para>
+Access to individual characters is provided like in ordinary C strings. The 
+<strong>[] </strong>operator selects an individual character for both read and write access:
+</para>
+<example>
+String x = &quot;Hello&quot;;
+
+char c = x[1];       // c = 'e'
+x[2] = 'L';          // x = &quot;HeLlo&quot;
+</example>
+</section>
+<section>
+<heading>Substring expressions.</heading>
+
+<para>
+A substring is a part of a string denoted by its start index and its
+length. The start index is counted from zero. To extract a substring from a
+string use:
+</para>
+<example>
+String x = &quot;abcdefghijkl&quot;;
+String y = x(3,5);         // y = &quot;defgh&quot;
+</example>
+<para>
+A substring expression can also be used as an lvalue. This means that a
+string can be assigned to a substring. The length of the substring does not
+need to be equal to the length of the string that is assigned to it.
+</para>
+<example>
+String x = &quot;abcdefghijkl&quot;;
+String y = &quot;12345678&quot;;
+
+x(3,5) = y;           // x = &quot;abc12345678ijkl&quot;
+</example>
+<para>
+Note that assigning a string to a zero-length substring will simply insert
+the a string into another string. Reversely, assigning an empty string to a
+substring will remove the characters from the original string. This property
+can be used to truncate a string to its first n characters by:
+</para>
+<example>
+x(n, ~x-n) = &quot;&quot;;
+</example>
+</section>
+
+<section>
+<heading>Numerical Conversion</heading>
+<para>
+Strings are coverted to and from numerical types (integer or floating
+point) by constructors and conversion operators. A numerical value is
+converted to a string with the number constructor:
+</para>
+<example>
+String n(12);   // n = &quot;12&quot;
+String x(2.32); // x = &quot;2.32&quot;
+</example>
+<para>
+These functions use a default format to convert the number to a string.
+Specifically, an integer is converted with the &quot;%d&quot; format from
+printf and a floating point is converted with the &quot;%g&quot; format.
+</para>
+<para>
+A string is converted to a number with the type-casting operators: operator
+long() and operator double(). The conversion to a long integer recognizes C
+syntax for numerical literals. Numbers starting with '0' are regarded as octal
+and numbers starting with '0x' are regarded as hexadecimal.
+</para>
+<para>
+Special member functions allow conversion of strings to and from numbers in
+a specific format. The functions dec(), oct() and hex() convert the string
+using decimal, octal and hexadecimal, respectively.
+</para>
+
+</section>
+<section>
+<heading>Shifting</heading>
+
+<para>
+Shifting a string moves all characters in the string a number of places to
+the left or to the right. Characters on the other end of the string simply
+fall off. Unlike shifting a binary number, shifting a string does not pad the
+string. Rather, shifting a string <emph>n</emph> places either to the left or to the
+right, renders the string <emph>n</emph> characters shorter. Example:
+</para>
+<example>
+&quot;abcdefgh&quot; &lt;&lt; 3 = &quot;defgh&quot;
+&quot;abcdefgh&quot; &gt;&gt; 3 = &quot;abcde&quot;
+</example>
+<para>
+The shift operators &lt;&lt; and &gt;&gt; can be combined with assignment:
+&lt;&lt;= and &gt;&gt;=.
+Do not confuse these shift operators with stream I/O operators.
+</para>
+</section>
+<section>
+<heading>Operations</heading>
+<description>
+<item tag="String upper(void)">
+Convert the string to all upper-case characters.
+</item>
+<item tag="String lower(void)">
+Convert the string to all lower-case characters.
+</item>
+</description>
+</section>
+
+<section>
+<heading>Pattern matching</heading>
+<description>
+<item tag="int in(String &amp;x)">
+Find the string x within the string. Returns the index where <emph>x</emph> was
+found. Returns -1 if x was not found in the string. see also strstr().
+</item>
+</description>
+</section>
+<section>
+<heading>Stream I/O</heading>
+<para>
+A string can be written to a stream like any other type with the <strong>&lt;&lt;
+</strong>operator. The left hand side of the expression must be a stream. To read a
+string from a stream, use the <strong>&gt;&gt; </strong>operator, with a stream on the
+left hand side:
+</para>
+<example>
+String x;
+
+cin &gt;&gt; x;
+cout &lt;&lt; x;
+</example>
+<para>
+Note that reading a string from a istream behaves like reading a character
+array from an istream. I.e., characters are read from the stream until the
+first whitespace character.
+</para>
+</section>
+<section>
+<heading>SEE ALSO</heading>
+<itemize>
+<item> Bjarne Stroustrup, Section 6.9 </item>
+<item> DDJ October 1991, pg 24 </item>
+</itemize>
+</section>
+</chapter>
+</doc>