From 83fabe764ba491d2818473d5d8da912485d0ac64 Mon Sep 17 00:00:00 2001 From: Arjen Baart Date: Sat, 18 May 2019 16:40:48 +0200 Subject: [PATCH] Started String class documentation. --- doc/manual.xml | 11 +++ doc/string.xml | 245 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 doc/manual.xml create mode 100644 doc/string.xml diff --git a/doc/manual.xml b/doc/manual.xml new file mode 100644 index 0000000..a6a8574 --- /dev/null +++ b/doc/manual.xml @@ -0,0 +1,11 @@ + + + + + Andromeda Class Library + + + + + diff --git a/doc/string.xml b/doc/string.xml new file mode 100644 index 0000000..699f110 --- /dev/null +++ b/doc/string.xml @@ -0,0 +1,245 @@ + + +class String + +
+   #include <Stringc.h>
+
+ +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. + + +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. + + +
+Construction and assignment. + + + The default constructor creates an empty string. + + + + + + + + + +Other constructors are provided to initialize strings from character +pointers, single characters or other strings. These constuctors also take care +of typecasting: + + +String x; // Contruct an empty string +String abc("abc"); // Convert a char * to a string +String p('p'); // A string with one character in it. + + + +Another string (or string expression), a char* or a single character can be +assigned to a string: + + +String x, y; + +x = "abc"; +y = x; +x = 'p'; + +
+ +
+Relational operators. + + +All relational operators (==, != , <, <=, > and >=) 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. + +
+
+Adding strings together. + + +String can be added together, i.e. concatenated, with the + +operator. Of course, the += operator can be used as well. Example: + + +String x, y, z; + +x = "abc" +y = "def" +z = x + y; // z = "abcdef" +y += x; // y = "defabc" + +
+
+String length, testing and character access + + +The length of a string can be determined with the ~ operator. Do not +confuse this with the bit-wise inversion operator ! + + +String x = "Hello"; +int l = ~x; // l = 5 + + +The test for an empty string is done with the ! operator. Note that +there is no test for a non-empty string. + + +if (!x) + cout << "String x is empty\n"; + + +Access to individual characters is provided like in ordinary C strings. The +[] operator selects an individual character for both read and write access: + + +String x = "Hello"; + +char c = x[1]; // c = 'e' +x[2] = 'L'; // x = "HeLlo" + +
+
+Substring expressions. + + +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: + + +String x = "abcdefghijkl"; +String y = x(3,5); // y = "defgh" + + +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. + + +String x = "abcdefghijkl"; +String y = "12345678"; + +x(3,5) = y; // x = "abc12345678ijkl" + + +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: + + +x(n, ~x-n) = ""; + +
+ +
+Numerical Conversion + +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: + + +String n(12); // n = "12" +String x(2.32); // x = "2.32" + + +These functions use a default format to convert the number to a string. +Specifically, an integer is converted with the "%d" format from +printf and a floating point is converted with the "%g" format. + + +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. + + +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. + + +
+
+Shifting + + +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 n places either to the left or to the +right, renders the string n characters shorter. Example: + + +"abcdefgh" << 3 = "defgh" +"abcdefgh" >> 3 = "abcde" + + +The shift operators << and >> can be combined with assignment: +<<= and >>=. +Do not confuse these shift operators with stream I/O operators. + +
+
+Operations + + +Convert the string to all upper-case characters. + + +Convert the string to all lower-case characters. + + +
+ +
+Pattern matching + + +Find the string x within the string. Returns the index where x was +found. Returns -1 if x was not found in the string. see also strstr(). + + +
+
+Stream I/O + +A string can be written to a stream like any other type with the << +operator. The left hand side of the expression must be a stream. To read a +string from a stream, use the >> operator, with a stream on the +left hand side: + + +String x; + +cin >> x; +cout << x; + + +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. + +
+
+SEE ALSO + + Bjarne Stroustrup, Section 6.9 + DDJ October 1991, pg 24 + +
+ + -- 2.11.0