### Strings and Buffers

This file contains the following subjects:

- Overview of Strings and Buffers
- String Buffers
- String Classes
- String Comparison
- String Indexes

#### Overview of Strings and Buffers

You can store and manage strings using the string and buffer classes. There are two type of string classes, two types of buffer classes, and two support classes. The two string classes, IString and I0String, are the main classes. The buffer and support classes are used to implement the string classes.

The IString class provides a wide range of string handling capabilities. Many of the IString operators and functions are overloaded to support both IStrings and arrays of characters as return types and arguments. For example, the comparison operators (==, >, <, >=, <=, !=) all support either two IString operands or one IString and one array of characters operand. The array of characters operand can be on either side of the comparison operator.

If you are using the string classes, DBCS support is nearly automatic and transparent. If the underlying operating system supports it, you can use enableInternationalization to turn DBCS support on.

The support classes, IStringEnum and IStringTest, provide data types and testing functions that are used in the string and buffer classes.

#### String Buffers

When you create an object of a string class, the actual characters that make up the string are not stored in the string object. Instead, the characters are stored in an object of a buffer class.

The use of a buffer object is transparent to you when using the string classes. A correctly sized buffer is automatically created when you create a string object. The buffer is destroyed when a string object is destroyed. When you manipulate or edit a string, you are actually manipulating and editing the buffer object that contains the characters of the string.

#### String Classes

The string classes define a data type for strings and provide member functions that let you perform a variety of data manipulation and management activities. They provide capabilities far beyond those available with standard C strings and the string.h library functions.

The string classes have the following capabilities:

- String buffers are handled automatically.
- Strings can contain both SBCS and DBCS characters.
- Strings can be indexed by character or by word.
- Strings can contain null characters. (There are no restrictions on the contents of a string object.)

Member functions of the string classes allow you to:

- Use strings in input and output
- Access information about strings
- Compare strings
- Test the characteristics of strings
- Search for characters or words within a string
- Manipulate and edit strings
- Convert strings to and from numeric types
- Format strings by adding or removing white space

There are two string classes: IString and I0String. They are identical except for the method each uses to index its characters. The characters of an IString object are indexed beginning at 1. I0String characters are indexed beginning at 0. The string class you should use depends on which indexing scheme you prefer or find easier to implement.

Objects of IString and objects of I0String can be freely intermixed in a program. Objects of one class can be assigned objects of the other. Arguments that require an object of one will accept objects of the other. You will only notice a difference between an IString and an I0String when you are using functions that use or return a character index value.

Each IString function has a corresponding I0String function with the same name. The I0String version of each function accepts the same arguments and has the same return type as the IString version except that all parameters of type IString become I0String.

#### String Comparison

The IStringTest class lets you define the matching function used in the searching and testing functions of the string and buffer classes. When a search string is passed to a searching or testing function, the search string and the string object are compared on a character-by-character basis. The characters are considered to match if they are identical. The IStringTest class allows you to define when characters are considered to match.

For example, you can implement a string test that locates a given occurrence of a particular character in a string:

    //Using the IStringTest class

    #include <istring.hpp>
    #include <iostream.h>

    class Nth : public IStringTest {
       char key;               // Specifies the character to look for
       unsigned count;         // Specifies which occurrence to find
       public:
          //
          // Construct an Nth object as follows:
          // 1. Create an IStringTest instance whose function type is user,
          //    with a null character to start;
          // 2. Initialize the count to n
          // 3. Initialize the key to c
          //
          Nth(char c, unsigned n)
          : IStringTest(user,0), count(n), key(c) {}

          //
          // test function: accepts an int (the character to look for)
          // checks if the character matches the key
          // if so, decrements count
          // eventually, count will equal zero if enough matches are found,
          // so "return !count" will return true (-1)
          // otherwise, "return !count" will return a value other than -1

          virtual Boolean test (int c) const
             {
             if (c == key)                // if it matches,
             ((Nth*)this)->count--;       // decrement count
             return !count;               // return complement of count
                                          // will be true (-1) if count==0
             }
    };

    void main() {
    IString text="this is a test string";
    cout << "The fourth appearance of the letter t in the string:\n"
         << tet << '\n' << "is at position "
         << text.indexOf(Nth('t',4)) << endl;
    }

This program produces the following output:

    The fourth appearance of the letter t in the string:
    this is a test string
    is at position 17

A derived template class, IStringTestMemberFn, is provided to support the use of the IStringTest class with any function that accepts its objects as an argument.

A constructor for IStringTest accepts a pointer to a C function. The C function must accept an integer as an argument and return a boolean. Such functions can be used anywhere an IStringTest can be used. Note that this is the type of the standard C library functions that check the type of C characters, for example, isalpha() and isupper().

#### String Indexes

Objects of the string classes are arrays of characters. There are two types of indexes used with the arrays. The first is a character index. Each character is numbered from left to right starting at the number 1 in the IString class and the number 0 in the I0String class. Therefore, in the IString "The dog is brown", the letter "i" has an index value of 9. In the I0String "The dog is brown", the letter "i" has an index value of 8.

The second type of index is the word index. In the word index, each white-space-delimited word is numbered from left to right starting at the number 1. The word index is the same for IString objects and I0String objects. Therefore in the IString "The dog is brown", the word "is" has an index value of 3. In the I0String "The dog is brown", the word "is" also has an index value of 3.

The only difference between objects of the IString class and objects of the I0String class is the starting value for the character index.

DBCS and National Language Support
String Formats