C!T ROM 2/ctrom_ii_b.zip/ctrom_ii_b/PROGRAM/C/STRPP11/STR.DOC

Text File | 1992-03-24 | 11KB | 269 lines

                            String++ Version 1.1

                      Copyright 1992 by Carl Moreland
                                 03/23/92

    String++ is a public domain string class written in C++.  The distribu-
ted files are:

        str.h           header file for String++
        str.cpp         source code for String++
        str.doc         this file
        str.his         revision history
        str_test.exe    demonstration of strings
        str_test.cpp    demo source

To  use  the string class, simply #include "str.h" in your source  and  add
str.cpp to the project or make file. You may use and distribute  this  code
freely, but all distributed copies must be unmodified,  and there may be no
distribution  charges.  Comments, suggestions for improvement, and bug  re-
ports may be sent to me via CompuServe (72137,2657), or mail them to:

        Carl Moreland
        4314 Filmore Rd
        Greensboro, NC 27409

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Introduction:

---------------------------------------------------------------------------
    Strings may be declared or initialized in the following ways:

        string str;                     // NULL string
               str('H');                // single character
               str = 'H';               // single character
               str(ch);                 // single character ch
               str = ch;                // single character ch
               str(ch, 5);              // make 5 copies of ch
               str("Hello World");      // char*
               str = "Hello World";     // char*
               str(ptr);                // char *ptr
               str = ptr;               // char *ptr
               str(ptr, 5);             // make 5 copies of ptr
               str(str1);               // another string
               str = str1;              // another string
               str(str1, 5);            // make 5 copies of str

Unlike  many  other string classes, there is no provision  for  creating  a
string  using only a length parameter, such as "string str(80)".  I see  no
use  in this since the length would be dynamically adjusted as soon as  str
is set to something useful.

The following operators are available:

        =       see above
        ()      str() returns the char* of the string
        []      str[i] returns the ith character of str
        +  +=   concatenates
        *  *=   multiple duplicates
        == !=   comparisons
        <  >    comparisons
        <= >=   comparisons

The "+" operator and all comparison operators are declared as friend  func-
tions.  This enables them to accept char, char*, and string as valid  argu-
ments  on either side of the operator.  Therefore, each of these statements
is valid:

        str1 = "Hello" + str2;
        str1 = str2 + "World";
        str1 = "Hello" + str2 + "World";
        if(str1 == "Hello World") ...
        if("Hello World" == str1) ...

Technically,  most  of the operators do not need  overloading  because  the
string  constructors  will  automatically  convert the  arguments  to  type
string.  The advantage is that fewer functions must be coded,  which  saves
memory. The disadvantage is that there is a speed penalty because construc-
tors (might) have to be called to convert arguments.  The class was  tested
both ways and it was found that the added code was small, but the speed was
more than doubled when using overloaded operators. Therefore, the operators
are overloaded to accept string and char*.  There are no overloads for type
char parameters because it would most probably be a rare case, and the con-
structor can pick it up. Besides, the two following statements are entirely
equivalent:

        if(str1 == 'a') ...
        if(str1 == "a") ...

    Finally, the demo program str_test.cpp contains a suite of string mani-
pulations which demonstrate most of the string functions.

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Class Functions:

---------------------------------------------------------------------------
int length(void) const
int len(void)    const

Both functions return the length of the string:

        str = "Hello World";
        i = str.length();               // i = 11

---------------------------------------------------------------------------
string right(int len);
string left(int len);
string mid(int pos, int len);

These functions return substrings of a string:

        str = "This is a test";
        str1 = str.left(4);             // str1 = "This"
        str2 = str.mid(5, 4);           // str2 = "is a"
        str3 = str.right(4);            // str3 = "test"

---------------------------------------------------------------------------
string justify(int mode, int len, int clip=0);

This function justifies a string by padding it with spaces (0x20) until  it
is 'len' long.  If the original string had any leading  or  trailing  white
spaces then they are first removed.  If the original string is longer  than
'len' (after removal of white spaces) then it is clipped to len if  clip=1,
otherwise the trimmed string is returned.

        str = "Hello World";
        str1 = str.justify(LEFT_JUSTIFY, 20);
        str2 = str.justify(CENTER_JUSTIFY, 20);
        str3 = str.justify(RIGHT_JUSTIFY, 20);
    // str1 = "Hello World         "
    // str1 = "    Hello World     "
    // str1 = "         Hello World"

---------------------------------------------------------------------------
void toupper(void);
void tolower(void);

These functions convert the string to upper or lower case,  and also return
the converted string.

        str1 = "uppercase";
        str2 = "LOWERCASE";
        str1.toupper();                 // str1 is now "UPPERCASE"
        str2.tolower();                 // str2 is now "lowercase"

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Awk-style Functions:

Note: AWK  begins array indexing at 1, whereas C/C++ begins array  indexing
      at 0.  Therefore, most of the implemented AWK functions return values
      that correspond to C-style indexing.  An AWK function that might nor-
      mally return a 0 as a failure indicator will return a -1 here.

---------------------------------------------------------------------------
int length(string& s);

Returns the length of a string:

        str = "Hello World";
        i = length(str);                // i = 11

---------------------------------------------------------------------------
int index(string& s, string& t);

Returns the position of 't' in 's' if it exists, or -1 if it doesn't:

        str = "d:\\prog\\str"
        i = index(str, ":");            // i = 1

---------------------------------------------------------------------------
string substr(string& s, unsigned int p, unsigned int n=10000);

Returns the substring of 's' beginning at position 'p' with length 'n':

        str1 = "Don't just stand there...";
        str2 = substr(str, 11, 5);      // str2 = "stand"

---------------------------------------------------------------------------
int split(string& s, string **a, string& fs);

Splits  string 's' into an array 'a' on field separator 'fs'.  Array 'a' is
normally  declared  as  an uninitialized pointer in  the  calling  function
(string *a),  and  the address of the pointer (&a) is  passed  to  split().
split() will then allocate memory for the correct array size and return the
number of fields:

        string *array;
        str = "d:\\prog\\str";
        i = split(str, &array, "\\";    // i = 3
        // array[0] = "d:"
    // array[1] = "prog"
    // array[2] = "str"

---------------------------------------------------------------------------
int sub(string& from, string& to, string& str);

Substitute  'to'  for the leftmost substring of 'str' that  is  matched  by
'from'. Return the number of substitutions (0 or 1). This function actually
calls gsub() with num=1;

        str = "d:\\prog\\str";
        i = sub("\\", "/", str);        // i = 1
        // str = "d:/prog\str"

---------------------------------------------------------------------------
int gsub(string& from, string& to, string& str, int num=10000);

Substitute 'to' for 'from' globally in string 'str' up to 'num' times.  Re-
turn the number of substitutions.

        str = "d:\\prog\\str";
        i = gsub("\\", "/", str);       // i = 2
        // str = "d:/prog/str"

---------------------------------------------------------------------------
---------------------------------------------------------------------------

C-Style Functions:

---------------------------------------------------------------------------
string toupper(string& s);
string tolower(string& s);

These  functions return the upper- or lowercase versions of a  string.  The
string itself is not modified.

        str1 = "uppercase";
        str2 = "LOWERCASE";
        str3 = toupper(str1);           // str3 = "UPPERCASE"
        str4 = tolower(str2);           // str4 = "lowercase"

---------------------------------------------------------------------------
string right(string& s, int n);
string left(string& s, int n);
string mid(const string& s, int p, int n);

These functions return substrings of a string:

        str = "This is a test";
        str1 = left(str, 4);            // str1 = "This"
        str2 = mid(str, 5, 4);          // str2 = "is a"
        str3 = right(str, 4);           // str3 = "test"

---------------------------------------------------------------------------
string justify(string& s, int mode, int len, int clip=0);

This function justifies a string by padding it with spaces (0x20) until  it
is 'len' long.  If the original string had any leading  or  trailing  white
spaces then they are first removed.  If the original string is longer  than
'len' (after removal of white spaces)  then it is clipped to len if clip=1,
otherwise the trimmed string is returned.

        str = "Hello World";
        str1 = justify(str, LEFT_JUSTIFY, 20);
        str2 = justify(str, CENTER_JUSTIFY, 20);
        str3 = justify(str, RIGHT_JUSTIFY, 20);
    // str1 = "Hello World         "
    // str1 = "    Hello World     "
    // str1 = "         Hello World"

---------------------------------------------------------------------------