ANSI String Class

Dr. Mark J. Sebern

Version 1.7 (12/14/1999)


What is the STL? vector list

The ANSI string class implements a first-class character string data type that avoids many problems associated with simple character arrays ("C-style strings"). You can define a string object very simply, as shown in the following example:

#include <string>
using namespace std;
...
string first_name = "Bjarne";
string last_name;

last_name = "Stroustrup";

string names = first_name + " " + last_name;
cout << names << endl;

names = last_name + ", " + first_name;
cout << names << endl; 

Member functions

The string class defines many member functions. A few of the basic ones are described below:

Note: The string class is based on a template class named basic_string.
Some of the member function declarations below may be a little confusing
to those new to C++, even though they have been simplified somewhat.
Fortunately, these functions are quite easy to use in practice.

Initialization (constructor) A string object may defined without an initializing value, in which case its initial value is an empty string (zero length, no characters):
string str1; 

A string object may also be initialized with

  • a string expression:
    string str2 = str1;
    string str3 = str1 + str2;
    string str4 (str2);  // Alternate form 
  • a character string literal:
    string str4 = "Hello there";
    string str5 ("Goodbye");  // Alternate form 
  • a single character
    Unfortunately, the expected methods don't work:
    string str6 = 'A';  // Incorrect
    string str7 ('A');  // Also incorrect

    Instead, we must use a special form with two values:

    string str7 (1,'A'); // Correct

    The two values are the desired length of the string and a character to fill the string with. In this case, we are asking for a string of length one, filled with the character A.

  • a substring of another string object:
    string str8 = "ABCDEFGHIJKL";
    // Initialize str9 as "CDEFG"
    // Starts at character 2 ('C')
    // with a length of 5
    // (or the rest of the string, if shorter)
    string str9 (str8,2,5); 
length

size

size_type length() const;
size_type size() const;
Both of these functions return the length (number of characters) of the string. The size_type return type is an unsigned integral type. (The type name usually must be scoped, as in string::size_type.)
string str = "Hello";
string::size_type len;
len = str.length(); // len == 5 
len = str.size();   // len == 5 
c_str const char* c_str() const;
For compatibility with "older" code, including some C++ library routines, it is sometimes necessary to convert a string object into a pointer to a null-terminated character array ("C-style string"). This function does the conversion. For example, you might open a file stream with a user-specified file name:
string filename;
cout << "Enter file name: ";
cin >> filename;
ofstream outfile (filename.c_str());
outfile << "Data" << endl; 
insert string& insert(size_type pos, const string& str);
Inserts a string into the current string, starting at the specified position.
string str11 = "abcdefghi";
string str12 = "0123";
str11.insert (3,str12);
cout << str11 << endl; // "abc0123defghi"
str12.insert (1,"XYZ");
cout << str12 << endl; // "0XYZ123" 
erase string& erase(size_type pos=0, size_type n=npos);
Delete a substring from the current string. The substring to be deleted starts as position pos and is n characters in length. If n is larger than the number of characters between pos and the end of the string, it doesn't do any harm. Thus, the default argument values cause deletion of "the rest of the string" if only a starting position is specified, and of the whole string if no arguments are specified. (The special value string::npos represents the maximum number of characters there can be in a string, and is thus one greater than the largest possible character position.)
string str13 = "abcdefghi";
str12.erase (5,3);
cout << str12 << endl; // "abcdei" 
replace string& replace(size_type pos, size_type n, const string& str);
Delete a substring from the current string, and replace it with another string. The substring to be deleted is specified in the same way as in erase, except that there are no default values for pos and n.
string str14 = "abcdefghi";
string str15 = "XYZ";
str14.replace (4,2,str15);
cout << str14 << endl; // "abcdXYZghi" 

Note: if you want to replace only a single character at a time, you should use the subscript operator ([]) instead.

find

rfind

size_type find (const string& str, size_type pos=0) const;
size_type find (char ch, size_type pos=0) const;
size_type rfind (const string& str, size_type pos=npos) const;
size_type rfind (char ch, size_type pos=npos) const;
The find function searches for the first occurrence of the substring str (or the character ch) in the current string, starting at position pos. If found, return the position of the first character in the matching substring. If not found, return the value string::npos. The member function rfind does the same thing, but returns the position of the last occurrence of the specified string or character, searching backwards from pos.
string str16 = "abcdefghi";
string str17 = "def";
string::size_type pos = str16.find (str17,0);
cout << pos << endl; // 3
pos = str16.find ("AB",0);
if (pos == string::npos) cout << "Not found" << endl;
find_first_of

find_first_not_of

find_last_of

find_last_not_of

size_type find_first_of (const string& str, size_type pos=0) const;
size_type find_first_not_of (const string& str, size_type pos=0) const;
size_type find_last_of (const string& str, size_type pos=npos) const;
size_type find_last_not_of (const string& str, size_type pos=npos) const;
Search for the first/last occurrence of a character that appears or does not appear in the str argument. If found, return the position of the character that satisfies the search condition; otherwise, return string::npos. The pos argument specifies the starting position for the search, which proceeds toward the end of the string (for "first" searches) or toward the beginning of the string (for "last" searches); note that the default values cause the whole string to be searched.
string str20 = "Hello there";
string str21 = "aeiou";
pos = str20.find_first_of (str21, 0);
cout << pos << endl; // 1
pos = str20.find_last_not_of ("eHhlort");
cout << pos << endl; // 5
substr string substr (size_type pos, size_type n) const;
Returns a substring of the current string, starting at position pos and of length n:
string str18 = "abcdefghi"
string str19 = str18.substr (6,2);
cout << str19 << endl; // "gh" 

Note: if you want to retrieve only a single character at a time, you should use the subscript operator ([]) instead.

begin

end

iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
Returns an iterator that specifies the position of the first character in the string (begin) or the position that is "just beyond" the last character in the string (end).

Iterators are special objects that are used in many STL algorithms.

Non-member functions and algorithms

In addition to member functions of the string class, some non-member functions and STL algorithms can be used with strings; some common examples are:

getline istream& getline (istream& is, string& str, char delim = '\n');
Reads characters from an input stream into a string, stopping when one of the following things happens:
  • An end-of-file condition occurs on the input stream
  • When the maximum number of characters that can fit into a string have been read
  • When a character read in from the string is equal to the specified delimiter (newline is the default delimiter); the delimiter character is removed from the input stream, but not appended to the string.

The return value is a reference to the input stream. If the stream is tested as a logical value (as in an if or while), it is equivalent to true if the read was successful and false otherwise (e.g., end of file). [Note: some libraries do not implement getline correctly for use with keyboard input, requiring that an extra "carriage return" be entered to terminate the read. Some patches are available.]

The most common use of this function is to do "line by line" reads from a file. Remember that the normal extraction operator (>>) stops on white space, not necessarily the end of an input line. The getline function can read lines of text with embedded spaces.

vector<string> vec1;
string line;
vec1.clear();
ifstream infile ("stl2in.txt");
while (getline(infile,line,'\n'))
{
  vec1.push_back (line);
}
transform OutputIterator transform (InputIterator first, InputIterator last, OutputIterator result, UnaryOperation op);
Iterate through a container (here, a string) from first to just before last, applying the operation op to each container element and storing the results through the result iterator, which is incremented after each value is stored.

This STL algorithm (from the <algorithm> library) is a little tricky, but simple uses are easy. For example, we can iterate through the characters in a string, modifying them in some way, and returning the modified characters back to their original positions. In this case, we set the result iterator to specify the beginning of the string. A common application is to convert a string to upper or lower case.

string str22 = "This IS a MiXed CaSE stRINg";
transform (str22.begin(),str22.end(), str22.begin(), tolower);
cout << "[" << str22 << "]" << endl; // [this is a mixed case string]

Note that the result iterator must specify a destination that is large enough to accept all the modified values; here it is not a problem, since we're putting them back in the same positions. The tolower function (along with toupper, isdigit, and other useful stuff) is in the <cctype> library; for more general case conversions, take a look at the <locale> library, which is beyond the scope of the present discussion.

Operators

A number of C++ operators also work with string objects:

= The assignment operator may be used in several ways:
  • Assigning one string object's value to another string object
    string string_one = "Hello";
    string string_two;
    string_two = string_one; 
  • Assigning a C++ string literal to a string object
    string string_three;
    string_three = "Goodbye"; 
  • Assigning a single character (char) to a string object
    string string_four;
    char ch = 'A';
    string_four = ch;
    string_four = 'Z'; 
+ The "plus" operator concatenates:
  • two string objects
    string str1 = "Hello ";
    string str2 = "there";
    string str3 = str1 + str2; // "Hello there" 
  • a string object and a character string literal
    string str1 = "Hello ";
    string str4 = str1 + "there"; 
  • a string object and a single character
    string str5 = "The End";
    string str6 = str5 + '!'; 
+= The "+=" operator combines the above assignment and concatenation operations in the way that you would expect, with a string object, a string literal, or a single character as the value on the right-hand side of the operator.

string str1 = "Hello ";
str1 += "there";
==
!=
<
>
<=
>=
The comparison operators return a bool (true/false) value indicating whether the specified relationship exists between the two operands. The operands may be:
  • two string objects
  • a string object and a character string literal
<< The insertion operator writes the value of a string object to an output stream (e.g., cout).

string str1 = "Hello there";
cout << str1 << endl;
>> The extraction operator reads a character string from an input stream and assigns the value to a string object.

string str1;
cin >> str1;
[]

(subscript)

The subscript operator accesses one character in a string, for inspection or modification:

string str10 = "abcdefghi";
char ch = str10[3];
cout << ch << endl; // 'd'
str10[5] = 'X';
cout << str10 << endl; // "abcdeXghi"

This page was last updated on December 15, 1999; send comments to Mark Sebern.