9 String Package

The String package consists of the single class String . This class provides ways to assign, concatenate, and compare character strings. This class also provides methods for substring creation and for vector access to a character string.

String class

Provides the capabilities for manipulating sequences of characters.

Header

#include <string.hxx>

Alternative Header

#include <String.h>

Declaration

class String
{
    friend ostream  &operator<<(ostream &, const String &);
    friend istream  &operator>>(istream &, String &);
    friend int      operator==(const String &, const String &);
    friend int      operator==(const String &, const char *);
    friend int      operator==(const char *, const String &);
    friend int      operator!=(const String &, const String &);
    friend int      operator!=(const String &, const char *);
    friend int      operator!=(const char *, const String &);
    friend int      operator<(const String &, const String &);
    friend int      operator<(const String &, const char *);
    friend int      operator<(const char *, const String &);
    friend int      operator>(const String &, const String &);
    friend int      operator>(const String &, const char *);
    friend int      operator>(const char *, const String &);
    friend int      operator<=(const String &, const String &);
    friend int      operator<=(const String &, const char *);
    friend int      operator<=(const char *, const String &);
    friend int      operator>=(const String &, const String &);
    friend int      operator>=(const String &, const char *);
    friend int      operator>=(const char *, const String &);
    friend String   operator+(const String &, const String &);
    friend String   operator+(const String &, const char *);
    friend String   operator+(const char *, const String &);

public:
                    String();
                    String(const String &);
                    String(const char *);
                    String(const char &);
                    ~String();

    String          &operator=(const String &);
    String          &operator=(const char *);
                    operator char * () const;
                    operator const char * () const;
    String          &operator+=(const String &);
    String          &operator+=(const char *);
    String          operator()(int, int) const;
    unsigned int    length() const;
    String          upper() const;
    String          lower() const;
    int             match(const String &) const;
    int             index(const String &) const;
    char            operator[](int) const;
    char            &operator[](int);
};

Description

This class provides the means for manipulating sequences of characters, each of which is of the type char . For some applications, the services provided are like those provided by the traditional C string library (strcpy , strcmp , and so forth), but are more efficient and convenient in the context of C++. Overloaded operators provide ways to assign, concatenate, and compare strings. New operators provide simple notations for substring creation and vector access into the string.

All comparisons are lexicographic, with the ordering dependent on the character set in which the string is encoded.

An index value of 0 indicates the first character in a string object.

Constructors and Destructors

String(): Constructs a String object initialized to an empty string.
String(const char *s): Constructs a String object and initializes it to the null-terminated sequence of characters.
String(const char &c): Constructs a String object with a reference to a char datum to initialize the string.
String(const String &x): Constructs a String object with a reference to another String to initialize the first String .
~String(): Deletes a String object; no user action is required.

Overloaded Operators

String operator + (const char *s, const String &x): Concatenates a null-terminated sequence of characters to a String object.
String operator + (const String &x, const char *s): Concatenates a String object with a null-terminated sequence of characters.
String operator + (const String &x, const String &y): Concatenates a String object with another String object.
String &operator = (const char *s): Assigns a String object to a null-terminated sequence of characters.
String &operator = (const String &x): Assigns a String object to another String object.
int operator < (const char *s, const String &x): Tests if a null-terminated sequence of characters is less than a String object; if so, it returns 1. Otherwise, it returns 0.
int operator < (const String &x, const char *s): Tests if a String object is less than a null- terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator < (const String &x, const String &y): Compares two String objects to determine if the first is less than the second; if so, it returns 1. Otherwise, it returns 0.
int operator > (const char *s, const String &x): Tests if a null-terminated sequence of characters is greater than a String object; if so, it returns 1. Otherwise, it returns 0.
int operator > (const String &x, const char *s): Tests if a String object is greater than a null- terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator > (const String &x, const String &y): Compares two String objects to determine if the first is greater than the second; if so, it returns 1. Otherwise, it returns 0.
String &operator += (const char *st2): Concatenates a null-terminated sequence of characters to a String object.
String &operator += (const String &st2): Concatenates a String object to another String object.
ostream &operator << (ostream &s, const String &x): Inserts the sequence of characters represented by x into the stream s.
istream &operator >> (istream &s, String &x): Extracts characters from s using the istream extraction operator, then stores characters in x, replacing the current contents of x and dynamically allocating x as necessary.
int operator == (const char *s, const String &x): Tests if a null-terminated sequence of characters is equal to a String object; if so, it returns 1. Otherwise, it returns 0.
int operator == (const String &x, const char *s): Tests if a String object is equal to a null- terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator == (const String &x, const String &y): Compares two String objects to determine equality. If one is equal to the other, it returns 1; otherwise, it returns 0.
int operator != (const char *s, const String &x): Tests if a null-terminated sequence of characters is not equal to a String object; if so, it returns 1. Otherwise, it returns 0.
int operator != (const String &x, const char *s): Tests if a String object is not equal to a null- terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator != (const String &x, const String &y): Compares two String objects to determine inequality. If they are not equal, the function returns 1; otherwise, it returns 0.
int operator <= (const char *s, const String &x): Tests if a null-terminated sequence of characters is less than or equal to a String object; if so, it returns 1. Otherwise, it returns 0.
int operator <= (const String &x, const char *s): Tests if a String object is less than or equal to a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator <= (const String &x, const String &y): Compares two String objects to determine if the first is less than or equal to the second; if so, it returns 1. Otherwise, it returns 0.
int operator >= (const char *s, const String &x): Tests if a null-terminated sequence of characters is equal to or greater than a String object; if so, it returns 1. Otherwise, it returns 0.
int operator >= (const String &x, const char *s): Tests if a String object is equal to or greater than a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.
int operator >= (const String &x, const String &y): Compares two String objects to determine if the first is equal to or greater than the second; if so, it returns 1. Otherwise, it returns 0.
String operator () (int index, int count) const: Creates a new String object defined as a substring of the current String , with index as the starting character and count as the length of the substring.
char operator [] (int position) const: Returns the character at the requested position within the string. If the position is past the end of the string, it returns 0. If the position is negative, the results are undefined.
char &operator [] (int position): Returns a reference to the character at the requested position within the string. This reference is potentially invalid after any subsequent call to a non-const member function for the object. If the position is past the end of the string or if the position is negative, the results are undefined.

Other Member Functions

int index(const String &x) const: Returns the index value of the first position where an element of a String object coincides with the value of x.
unsigned int length() const: Returns the length (number of characters) in a String object.
String lower() const: Returns a new String object constructed from a String except that every character is lowercase regardless of its original case.
int match(const String &x) const: Compares two strings and returns the first index position at which they differ; it returns -1 if the strings match completely. The String argument can be a character pointer.
String upper() const: Returns a new String constructed from a String except that every character is uppercase regardless of its original case.

Examples

```
String x ("The Times of John Doe");
char *y = "Pink Triangles";

if (x != y) cout << "We have two different strings.\n";

x = y;

cout << x;
```
The first line of this example provides a character string to the constructor for initialization. The overloaded operators (!=, <<, and =) accept either two String objects or a String and a null-terminate sequence of characters. The last line prints out the following character string:
```
Pink Triangles
```
```
String x ("The Times of John Doe");

String a (x(18,3));    // Substring is "Doe"
String b (x);          // b contains all of x
```
In this example, the creation of object a provides a substring of object x to the constructor for object a . The substring begins at position 18 and has a length of 3 characters. The next line creates the object b and initializes it to contain the same value as x .

String x ("World");
String y;

y = "Hello";
y += ", " + x + ".\n";

cout << y;

This example shows string concatenation. The last line prints out the following message:

Hello, World.

Previous Page | Next Page | Table of Contents