The programmer's guide to C++

Strings

Appendix B, in the programmer's guide to C++, describes the C++ string class. Unfortunately, changes to the draft C++ standard have overtaken this description. The following is equivalent to Appendix B, and is compatible with the latest version of the draft standard.

The C++ string class is called string. To use it, the header file <string> must be included. It is part of the standard template library name space so std::string is its full name, or a suitably located using namespace statement can be used instead. Some C++ compilers have a slightly different string class, but most of the functions described below should be available.

The type size_type is used extensively in the following description. This is an implementation dependent unsigned integral type defined as part of the Standard Template Library. The constant string::npos is the largest representable value of type size_type.

Some of the string member functions are overloaded on the type of their input string parameters. These parameters have the following form:

A C++ string

const string& str, size_type pos = 0,
size_type n = string::npos

This is the string beginning at position pos in the C++ string str, and continuing for n characters, or to the end of str, whichever comes first. The parameters pos and n have default values that result in the following behavior. If n is omitted, as an argument, the string starts at pos and goes to the end of str. If both pos and n are omitted, the string is all of str. An out-of-range error is reported if pos is greater than the length of str.

Some implementations do not exactly support this behavior. A common aberration is that if pos is given, n must also be given. In this case, make the value of the last parameter string::npos.
A C string

const char s[], size_type n
const char s[]

This is the value of the C string. The parameter s should be an array of char holding a sequence of characters terminated with a '\0' character. The argument given for s shall not be a null pointer. If n is given as an argument, and s cannot fit into n characters, the string is truncated. Otherwise, if s is too short, it is padded with spaces. If n is not given as an argument, all of s is used.
A repeated character

size_type n, char c

This is the string composed of the character c repeated n times.

Constructors

string();

The default constructor. It creates an empty string.
string( const string& str, size_type pos = 0,
string( const char s[], size_t n );
string( const char s[] );

string( size_type n, char c );

Create a string and initialize it with the value of the string obtained from the parameters.
Some examples of string construction.

Assignment

Member function assign

string& assign( const string& str, size_type pos = 0,
string& assign( const char s[], size_type n );
string& assign( const char s[] );

string& assign( size_type n, char c );

Replace the value of the target string with the value of the string obtained from the parameters. This function returns a reference to the string object for which it was invoked.
Member functions operator=

string& operator=( const string& str );
string& operator=( const char* s );
string& operator=( char c );

Replace the value of the string with the value given by the parameters str, s or c. It returns a reference to the string for which the function was invoked. These overloaded operators have the same behavior as the equivalent assign functions.
Some examples of string assignment.

Concatenation

Member function append

string& append( const string& str, size_type pos = 0,
string& append( const char s[], size_type n );
string& append( const char s[] );

string& append( size_type n, char c );

Add the value of the string obtained from the parameters onto the end of the target string. This function returns a reference to the string object for which it was invoked.
Member function operator+=

string& operator+=( const string& str );
string& operator+=( const char s[] );
string& operator+=( char c );

This function adds a string value on to the end of the string for which this function is invoked, and returns a reference to this object. The behavior of this operator overload is the same as the equivalent append function.
Non-member function operator+

string operator+( const string& lhs, const string& rhs );
string operator+( const char lhs[], const string& rhs );
string operator+( char lhs, const string& rhs );
string operator+( const string& lhs, const char rhs[] );
string operator+( const string& lhs, char rhs );

This is the concatenation operator. This function returns a string that has a value calculated by adding the string value of the rhs parameter onto the end of the value of the lhs parameter. Arguments that are char arrays shall not be null pointers.
Some examples of string concatenation.

Substring operations

Member function substr

string substr( size_type pos = 0,
Returns a substring without modifying the string to which the function was applied. The substring starts at the character position pos, and finishes at the end of the string, or when the substring is n characters long, whichever is the smaller. If n is omitted, the substring is from character position pos to the end of the target string. If pos and n are both omitted, the value of the returned string is the same as the string for which substr was invoked.
Member function erase

string& erase( size_type pos = 0,
Remove at most n characters starting with the character at pos. An out-of-range error is reported if pos is greater than the length of the target string. If n is omitted, all characters from pos to the end are removed. If pos and n are both omitted, the all characters are removed. A reference to the string that this function was applied to is returned.
Member function insert

string& insert( size_type pos1, const string& str );
string& insert( size_type pos1, const string& str,
string& insert( size_type pos, const char[] s, size_type n );
string& insert( size_type pos, const char[] s );
string& insert( size_type pos, size_type n, char c );
Insert the string given by str, s or c, and their associated parameters, into the target string starting at character pos1. Existing characters in the target string are not overwritten. A reference to the resulting target string is returned. An out-of-range error is reported if pos1 is greater than the length of the target string, or pos2 is greater than the length of str.
Member function replace

string& replace( size_type pos1, size_type n1, const string& str );
string& replace( size_type pos1, size_type n1, const string& str,
string& replace( size_type pos, size_type n1, const char[] s,
string& replace( size_type pos, size_type n1, const char[] s );
string& replace( size_type pos, size_type n1, size_type n2, char c );
Remove the substring beginning at pos1 and continuing for at most n1 characters, and replace it with a substring from str beginning with pos2 and continuing for at most n2 characters. A reference to the resulting target string is returned. An out-of-range error is reported if pos1 is greater than the length of the target string, or pos2 is greater than the length of str.
Some examples of substring operations.

Character access

Member function operator[]

const char& operator[]( size_type pos ) const;
char& operator[]( size_type pos );

These allow C++ strings to be used like arrays of characters. A reference to the character at position pos is returned if pos is less than the length of the target string. This reference can be used to modify the character, but it should be used immediately. Any subsequent use of the target string might invalidate the reference. If pos is greater than of the target string, the behavior is undefined. The constant version returns 0 if pos is equal to the length of the target string. The behavior of the non-constant version is undefined in this case.
Member function at

const char* at( size_type n ) const;
char& at(size_type n);

These function have the same behavior as their operator[] equivalents, but if pos is greater than or equal to the length of the target string an out-of-range exception is thrown.
Some examples of string character access.

Utility functions

Member function c_str

const char* c_str() const;

Returns the value of the target string as a C string. This will be an array of char containing a sequence of characters terminated with the character '\0'. The returned C string must not be treated as valid after any subsequent use of a non-constant member function with the string object that provided the string. If its value is required for a longer period than this, a copy should be made with strcpy from <cstring>.
Member function data

const char* data() const;

This function is similar to c_str, but it does not terminate the character sequence returned in the array of char with a '\0' character, and it returns a null pointer if the length of the target string is zero. This means that data does not return a C string.
Member function length and size

size_type length() const;
size_type size() const;

Returns the number of characters in the string value stored in the target string.
Member function max_size

size_type max_size() const;

Returns the maximum size of the string.
Member function resize

void resize( size_type n, char c );
void resize( size_type n );

Alters the length of the target string. If n is less than or equal to the original length, the string is truncated to its first n characters. If n is greater than the original length, characters of value c are appended to make the string n characters long. If an argument for c is not provided, the appended character '\0'.
Member function capacity

size_type capacity() const;

Returns the size of the allocated storage in the string.
Member function reserve

void reserve( size_type res_arg = 0 );

This function informs a string of a planned change in size, so that it can manage the storage allocation accordingly. After reserve is used, the string's capacity is greater or equal to the argument of reserve.
Member function clear

void clear();

Clears the strings value. After this function is used the length of the string is zero. This function has the same behavior as erase().
Member function empty

bool empty();

Returns size() == 0.
Member function copy

size_type copy(char[] s, size_type n,
Copies a portion of the target string to the an array of char. The substring starts at pos and continues for n characters, or until the end of the string. The array s must be large enough to take the substring. The sequence of characters stored in s is not terminated y a '\0' character, so its not a C string. This function returns the length of the resulting string. It reports an out-of-range error if pos is greater than the target string length.
Some examples of string utility operations.

Comparison

Member function compare

int compare( const string& str ) const;
int compare( size_type pos1, size_type n1,

const string& str ) const;

These functions compare the target string with the string given by the parameters str, pos1, and n1. For the strings to be evaluated as equal they must be the same length and have identical character sequences. The order of unequal strings is determined by the ordering of the first unequal character. If the strings being compared are not of equal length, the longer one is considered to be the greater. The value returned by compare is:

string relationship	return value
target < parameter	less than 0
target == parameter	0
target > parameter	greater than 0

The other compare functions behave in a similar way:

int compare( size_type pos1, size_type n1,

const string& str, size_type pos2, size_type n2 ) const;

This function compares the portion of the target string given by pos1 and n1, with the string given by the parameters str, pos2, and n2.

int compare( const char[] s) const;

This functions compares the target string with the C string given s.

int compare( size_type pos1, size_type n1,

const char[] s, size_type n2 = string::npos ) const;

This functions compares the the portion of the target string given by pos1 and n1, with the C string given by the parameters s, and length n2. if n2 is not give all of s is used.

Non-member functions operator==, operator!=, operator<, operator<=, operator> and operator>=

These functions have the following forms, where $ is the operation:

bool operator$( const string& lhs, const string& rhs);
bool operator$( const char[] lhs, const string& rhs);
bool operator$( const string& lhs, const char[] rhs);
bool operator$( char lhs, const string& rhs);
bool operator$( const string& lhs, char rhs);

They all alphabetically compare the string values given by the rhs and lhs parameters. Their behavior is similar to the standard arithmetic comparison operators. They return true if the condition holds, otherwise they return false.
Some examples of string comparison.

Search operations

Member function find

size_type find( const string& str, size_type pos = 0 ) const;
size_type find( const char s[], size_type pos, size_type n ) const;
size_type find( const char s[], size_type pos = 0 ) const;
size_type find( char c, size_type pos = 0 ) const;

Search for the first occurrence of str, s or c in the target string beginning on or after character position pos. If this string is found, the position of its first character is returned, otherwise string::npos is returned. If an argument is not given for pos, the search starts at the beginning of the target string. For the C string version of find, with the parameter n, the string s is truncated or padded with spaces to make it n characters long before the search is performed.
Member function rfind

size_type rfind( const string& str, size_type pos = string::npos) const;
size_type rfind( const char s[], size_type pos, size_type n) const;
size_type rfind( const char s[], size_type pos = string::npos) const;
size_type rfind( char c, size_type pos = string::npos ) const;

Almost the same as find, but this function searches for the last occurrence of str, s or c in the target string beginning on or before character position pos. The search starts at the end of the target string if an argument is not given for pos.
Member function find_first_of

size_type find_first_of( const string& str,
size_type find_first_of( const char s[], size_type pos,
size_type find_first_of( const char s[],
size_type find_first_of( char c, size_type pos = 0 ) const;
This function treats the string given by str, s or c as a set of characters. It returns the location of the first character in the target string that matches any element in this set. If no match is found, it returns string::npos. The search starts at character position pos, and proceeds to the end of the target string. If pos is not given as an argument, the search starts at the beginning of the target string. For the C string version of find_first_of, with the parameter n, the string s is truncated or padded with spaces to make it n characters long before the search is performed.
Member function find_first_not_of

size_type find_first_not_of( const string& str,
size_type find_first_not_of( const char s[], size_type pos,
size_type find_first_not_of( const char[] s,
size_type find_first_not_of( char c, size_type pos = 0 ) const;
Almost the same as find_first_of, but this function searches for the first character in the target string that matches no elements in the set given by str, s or c.
Member function find_last_of

size_type find_last_of( const string& str,
size_type find_last_of( const char s[], size_type pos,
size_type find_last_of( const char s[],
size_type find_last_of( char c, size_type pos = string::npos ) const;
Almost the same as find_first_of, but this function searches for the last character in the target string that matches an element in the set given by str, s or c.
Member function find_last_not_of

size_type find_last_not_of( const string& str,
size_type find_last_not_of( const char s[], size_type pos,
size_type find_last_not_of( const char s[],
size_type find_last_not_of( char c, size_type pos = string::npos) const;
Almost the same as find_first_of, but this function searches for the last character in the target string that matches no element in the set given by str, s or c.
Some examples of string searching.

Input and output

Non-member function operator>>

istream& operator>>( istream& is, string& str);

This extractor function gets a string value from the input stream is, and assigns it to str. Input stops when a whitespace character (space, horizontal tab, vertical tab, form-feed or new-line) is encountered, or end of file occurs. The whitespace character is not extracted from the stream. At most string::npos-1 characters are input. If no characters are input, the failbit for set in the input stream. It returns a reference to the input stream.
Non-member function getline

istream& getline( istream& is, string& str,
This function inputs a string value from is and assign the value to str. Input stops when the character delim is encountered, or end of file occurs. If a delim character is not given as an argument, input stops at end of line. The delim character is extracted from the stream but it is not appended to the string value. At most string::npos-1 characters are input, in which case the failbit is set for the input stream. If end of file occurs, the eofbit is set. It returns a reference to the input stream is.
Non-member function operator<<

ostream& operator<<( ostream& os, const string& str);

This inserter function writes the value of str to the output stream os, and returns a reference to this stream.
Some examples of string input and output.