append
Syntax:
  #include <string>
  string& append( const string& str );
  string& append( const char* str );
  string& append( const string& str, size_type index, size_type len );
  string& append( const char* str, size_type num );
  string& append( size_type num, char ch );
  string& append( input_iterator start, input_iterator end );

The append() function either:

  • appends str on to the end of the current string,
  • appends a substring of str starting at index that is len characters long on to the end of the current string,
  • appends num characters of str on to the end of the current string,
  • appends num repititions of ch on to the end of the current string,
  • or appends the sequence denoted by start and end on to the end of the current string.

For example, the following code uses append() to add 10 copies of the '!' character to a string:

   string str = "Hello World";
   str.append( 10, '!' );
   cout << str << endl;             

That code displays:

   Hello World!!!!!!!!!!                

In the next example, append() is used to concatenate a substring of one string onto another string:

 string str1 = "Eventually I stopped caring...";
 string str2 = "but that was the '80s so nobody noticed.";

 str1.append( str2, 25, 15 );
 cout << "str1 is " << str1 << endl; 

When run, the above code displays:

 str1 is Eventually I stopped caring...nobody noticed.          

assign
Syntax:
  #include <string>
  void assign( size_type num, const char& val );
  void assign( input_iterator start, input_iterator end );
  string& assign( const string& str );
  string& assign( const char* str );
  string& assign( const char* str, size_type num );
  string& assign( const string& str, size_type index, size_type len );
  string& assign( size_type num, const char& ch );

The default assign() function gives the current string the values from start to end, or gives it num copies of val.

In addition to the normal assign functionality that all C++ containers have, strings possess an assign() function that also allows them to:

For example, the following code:

   string str1, str2 = "War and Peace";
   str1.assign( str2, 4, 3 );
   cout << str1 << endl;            

displays

   and          

This function will destroy the previous contents of the string.


at
Syntax:
  #include <string>
  TYPE& at( size_type loc );
  const TYPE& at( size_type loc ) const;

The at() function returns a reference to the element in the string at index loc. The at() function is safer than the [] operator, because it won't let you reference items outside the bounds of the string.

For example, consider the following code:

 vector<int> v( 5, 1 );
 for( int i = 0; i < 10; i++ ) {
   cout << "Element " << i << " is " << v[i] << endl;
 }              

This code overrunns the end of the vector, producing potentially dangerous results. The following code would be much safer:

 vector<int> v( 5, 1 );
 for( int i = 0; i < 10; i++ ) {
   cout << "Element " << i << " is " << v.at(i) << endl;
 }              

Instead of attempting to read garbage values from memory, the at() function will realize that it is about to overrun the vector and will throw an exception.


begin
Syntax:
  #include <string>
  iterator begin();
  const_iterator begin() const;

The function begin() returns an iterator to the first element of the string. begin() should run in constant time.

For example, the following code uses begin() to initialize an iterator that is used to traverse a list:

   // Create a list of characters
   list<char> charList;
   for( int i=0; i < 10; i++ ) {
     charList.push_front( i + 65 );
   }
   // Display the list
   list<char>::iterator theIterator;
   for( theIterator = charList.begin(); theIterator != charList.end(); theIterator++ ) {
     cout << *theIterator;
   }            

c_str
Syntax:
  #include <string>
  const char* c_str();

The function c_str() returns a const pointer to a regular C string, identical to the current string. The returned string is null-terminated.

Note that since the returned pointer is of type const, the character data that c_str() returns cannot be modified. Furthermore, you do not need to call free() or delete on this pointer.


capacity
Syntax:
  #include <string>
  size_type capacity() const;

The capacity() function returns the number of elements that the string can hold before it will need to allocate more space.

For example, the following code uses two different methods to set the capacity of two vectors. One method passes an argument to the constructor that suggests an initial size, the other method calls the reserve function to achieve a similar goal:

 vector<int> v1(10);
 cout << "The capacity of v1 is " << v1.capacity() << endl;
 vector<int> v2;
 v2.reserve(20);
 cout << "The capacity of v2 is " << v2.capacity() << endl;         

When run, the above code produces the following output:

 The capacity of v1 is 10
 The capacity of v2 is 20               

C++ containers are designed to grow in size dynamically. This frees the programmer from having to worry about storing an arbitrary number of elements in a container. However, sometimes the programmer can improve the performance of her program by giving hints to the compiler about the size of the containers that the program will use. These hints come in the form of the reserve() function and the constructor used in the above example, which tell the compiler how large the container is expected to get.

The capacity() function runs in constant time.


clear
Syntax:
  #include <string>
  void clear();

The function clear() deletes all of the elements in the string. clear() runs in linear time.


compare
Syntax:
  #include <string>
  int compare( const string& str );
  int compare( const char* str );
  int compare( size_type index, size_type length, const string& str );
  int compare( size_type index, size_type length, const string& str, size_type index2,
  size_type length2 );
  int compare( size_type index, size_type length, const char* str, size_type length2 );

The compare() function either compares str to the current string in a variety of ways, returning

Return Value Case
less than zero this < str
zero this == str
greater than zero this > str

The various functions either:

For example, the following code uses compare() to compare four strings with eachother:

 string names[] = {"Homer", "Marge", "3-eyed fish", "inanimate carbon rod"};            

 for( int i = 0; i < 4; i++ ) {
   for( int j = 0; j < 4; j++ ) {
     cout << names[i].compare( names[j] ) << " ";
   }
   cout << endl;
 }              

Data from the above code was used to generate this table, which shows how the various strings compare to eachother:

Homer Marge 3-eyed fish inanimate carbon rod
"Homer".compare( x ) 0 -1 1 -1
"Marge".compare( x ) 1 0 1 -1
"3-eyed fish".compare( x ) -1 -1 0 -1
"inanimate carbon rod".compare( x ) 1 1 1 0

copy
Syntax:
  #include <string>
  size_type copy( char* str, size_type num, size_type index = 0 );

The copy() function copies num characters of the current string (starting at index if it's specified, 0 otherwise) into str.

The return value of copy() is the number of characters copied.

For example, the following code uses copy() to extract a substring of a string into an array of characters:

 char buf[30];
 memset( buf, '\0', 30 );
 string str = "Trying is the first step towards failure.";
 str.copy( buf, 24 );
 cout << buf << endl;               

When run, this code displays:

 Trying is the first step               

Note that before calling copy(), we first call (Standard C String and Character) memset() to fill the destination array with copies of the NULL character. This step is included to make sure that the resulting array of characters is NULL-terminated.


data
Syntax:
  #include <string>
  const char *data();

The function data() returns a pointer to the first character in the current string.


empty
Syntax:
  #include <string>
  bool empty() const;

The empty() function returns true if the string has no elements, false otherwise.

For example:

  string s1;
  string s2("");
  string s3("This is a string");
  cout.setf(ios::boolalpha);
  cout << s1.empty() << endl;
  cout << s2.empty() << endl;
  cout << s3.empty() << endl;

When run, this code produces the following output:

  true
  true
  false

end
Syntax:
  #include <string>
  iterator end();
  const_iterator end() const;

The end() function returns an iterator just past the end of the string.

Note that before you can access the last element of the string using an iterator that you get from a call to end(), you'll have to decrement the iterator first.

For example, the following code uses begin() and end() to iterate through all of the members of a vector:

 vector<int> v1( 5, 789 );
 vector<int>::iterator it;
 for( it = v1.begin(); it != v1.end(); it++ ) {
   cout << *it << endl;
 }              

The iterator is initialized with a call to begin(). After the body of the loop has been executed, the iterator is incremented and tested to see if it is equal to the result of calling end(). Since end() returns an iterator pointing to an element just after the last element of the vector, the loop will only stop once all of the elements of the vector have been displayed.

end() runs in constant time.


erase
Syntax:
  #include <string>
  iterator erase( iterator loc );
  iterator erase( iterator start, iterator end );
  string& erase( size_type index = 0, size_type num = npos );

The erase() function either:

The parameters index and num have default values, which means that erase() can be called with just index to erase all characters after index or with no arguments to erase all characters.

For example:

   string s("So, you like donuts, eh? Well, have all the donuts in the world!");
   cout << "The original string is '" << s << "'" << endl;          

   s.erase( 50, 14 );
   cout << "Now the string is '" << s << "'" << endl;
   s.erase( 24 );
   cout << "Now the string is '" << s << "'" << endl;
   s.erase();
   cout << "Now the string is '" << s << "'" << endl;               

will display

   The original string is 'So, you like donuts, eh? Well, have all the donuts in the world!'
   Now the string is 'So, you like donuts, eh? Well, have all the donuts'
   Now the string is 'So, you like donuts, eh?'
   Now the string is ''         

erase() runs in linear time.


find
Syntax:
  #include <string>
  size_type find( const string& str, size_type index );
  size_type find( const char* str, size_type index );
  size_type find( const char* str, size_type index, size_type length );
  size_type find( char ch, size_type index );

The function find() either:

For example:

   string str1( "Alpha Beta Gamma Delta" );
   string::size_type loc = str1.find( "Omega", 0 );
   if( loc != string::npos ) {
     cout << "Found Omega at " << loc << endl;
   } else {
     cout << "Didn't find Omega" << endl;         
   }

find_first_not_of
Syntax:
  #include <string>
  size_type find_first_not_of( const string& str, size_type index = 0 );
  size_type find_first_not_of( const char* str, size_type index = 0 );
  size_type find_first_not_of( const char* str, size_type index, size_type num );
  size_type find_first_not_of( char ch, size_type index = 0 );

The find_first_not_of() function either:

For example, the following code searches a string of text for the first character that is not a lower-case character, space, comma, or hypen:

  string lower_case = "abcdefghijklmnopqrstuvwxyz ,-";
  string str = "this is the lower-case part, AND THIS IS THE UPPER-CASE PART";
  cout << "first non-lower-case letter in str at: " << str.find_first_not_of(lower_case) << endl;            

When run, find_first_not_of() finds the first upper-case letter in str at index 29 and displays this output:

  first non-lower-case letter in str at: 29              

find_first_of
Syntax:
  #include <string>
  size_type find_first_of( const string &str, size_type index = 0 );
  size_type find_first_of( const char* str, size_type index = 0 );
  size_type find_first_of( const char* str, size_type index, size_type num );
  size_type find_first_of( char ch, size_type index = 0 );

The find_first_of() function either:


find_last_not_of
Syntax:
  #include <string>
  size_type find_last_not_of( const string& str, size_type index = npos );
  size_type find_last_not_of( const char* str, size_type index = npos);
  size_type find_last_not_of( const char* str, size_type index, size_type num );
  size_type find_last_not_of( char ch, size_type index = npos );

The find_last_not_of() function either:

For example, the following code searches for the last non-lower-case character in a mixed string of characters:

  string lower_case = "abcdefghijklmnopqrstuvwxyz";
  string str = "abcdefgABCDEFGhijklmnop";
  cout << "last non-lower-case letter in str at: " << str.find_last_not_of(lower_case) << endl;              

This code displays the following output:

  last non-lower-case letter in str at: 13               

find_last_of
Syntax:
  #include <string>
  size_type find_last_of( const string& str, size_type index = npos );
  size_type find_last_of( const char* str, size_type index = npos );
  size_type find_last_of( const char* str, size_type index, size_type num );
  size_type find_last_of( char ch, size_type index = npos );

The find_last_of() function either:


getline
Syntax:
  #include <string>
  istream& getline( istream& is, string& s, char delimiter = '\n' );

The C++ string class defines the global function getline() to read strings from an I/O stream. The getline() function, which is not part of the string class, reads a line from is and stores it into s. If a character delimiter is specified, then getline() will use delimiter to decide when to stop reading data.

For example, the following code reads a line of text from stdin and displays it to stdout:

 string s;
 getline( cin, s );
 cout << "You entered " << s << endl;

After getting a line of data in a string, you may find that string streams are useful in extracting data from that string. For example, the following code reads numbers from standard input, ignoring any "commented" lines that begin with double slashes:

  // expects either space-delimited numbers or lines that start with
  // two forward slashes (//)
  string s;
  while( getline(cin,s) ) {
    if( s.size() >= 2 && s[0] == '/' && s[1] == '/' ) {
      cout << "  ignoring comment: " << s << endl;
    } else {
      istringstream ss(s);
      double d;
      while( ss >> d ) {
        cout << "  got a number: " << d << endl;
      }
    }
  }

When run with a user supplying input, the above code might produce this output:

  // test
    ignoring comment: // test
  23.3 -1 3.14159
    got a number: 23.3
    got a number: -1
    got a number: 3.14159
  // next batch
    ignoring comment: // next batch
  1 2 3 4 5
    got a number: 1
    got a number: 2
    got a number: 3
    got a number: 4
    got a number: 5
  50
    got a number: 50

insert
Syntax:
  #include <string>
  iterator insert( iterator i, const char& ch );
  string& insert( size_type index, const string& str );
  string& insert( size_type index, const char* str );
  string& insert( size_type index1, const string& str, size_type index2, size_type num );
  string& insert( size_type index, const char* str, size_type num );
  string& insert( size_type index, size_type num, char ch );
  void insert( iterator i, size_type num, const char& ch );
  void insert( iterator i, iterator start, iterator end );

The very multi-purpose insert() function either:


length
Syntax:
  #include <string>
  size_type length() const;

The length() function returns the number of elements in the current string, performing the same role as the size() function.


max_size
Syntax:
  #include <string>
  size_type max_size() const;

The max_size() function returns the maximum number of elements that the string can hold. The max_size() function should not be confused with the size() or capacity() functions, which return the number of elements currently in the string and the the number of elements that the string will be able to hold before more memory will have to be allocated, respectively.


push_back
Syntax:
  #include <string>
  void push_back( char c );

The push_back() function appends c to the end of the string.

For example, the following code adds 10 characters to a string:

   string the_string;
   for( int i = 0; i < 10; i++ )
     the_string.push_back( i+'a' );           

When displayed, the resulting string would look like this:

  abcdefghij

push_back() runs in constant time.


rbegin
Syntax:
  #include <string>
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;

The rbegin() function returns a reverse_iterator to the end of the current string.

rbegin() runs in constant time.


rend
Syntax:
  #include <string>
  reverse_iterator rend();
  const_reverse_iterator rend() const;

The function rend() returns a reverse_iterator to the beginning of the current string.

rend() runs in constant time.


replace
Syntax:
  #include <string>
  string& replace( size_type index, size_type num, const string& str );
  string& replace( size_type index1, size_type num1, const string& str, size_type index2, size_type num2 );
  string& replace( size_type index, size_type num, const char* str );
  string& replace( size_type index, size_type num1, const char* str, size_type num2 );
  string& replace( size_type index, size_type num1, size_type num2, char ch );
  string& replace( iterator start, iterator end, const string& str );
  string& replace( iterator start, iterator end, const char* str );
  string& replace( iterator start, iterator end, const char* str, size_type num );
  string& replace( iterator start, iterator end, size_type num, char ch );

The function replace() either:

For example, the following code displays the string "They say he carved it himself...find your soul-mate, Homer."

   string s = "They say he carved it himself...from a BIGGER spoon";
   string s2 = "find your soul-mate, Homer.";
   s.replace( 32, s2.length(), s2 );
   cout << s << endl;               

reserve
Syntax:
  #include <string>
  void reserve( size_type size );

The reserve() function sets the capacity of the string to at least size.

reserve() runs in linear time.


resize
Syntax:
  #include <string>
  void resize( size_type size, const TYPE& val = TYPE() );

The function resize() changes the size of the string to size. If val is specified then any newly-created elements will be initialized to have a value of val.

This function runs in linear time.


rfind
Syntax:
  #include <string>
  size_type rfind( const string& str, size_type index );
  size_type rfind( const char* str, size_type index );
  size_type rfind( const char* str, size_type index, size_type num );
  size_type rfind( char ch, size_type index );

The rfind() function either:

For example, in the following code, the first call to rfind() returns string::npos, because the target word is not within the first 8 characters of the string. However, the second call returns 9, because the target word is within 20 characters of the beginning of the string.

   int loc;
   string s = "My cat's breath smells like cat food.";
   loc = s.rfind( "breath", 8 );
   cout << "The word breath is at index " << loc << endl;
   loc = s.rfind( "breath", 20 );
   cout << "The word breath is at index " << loc << endl;           

size
Syntax:
  #include <string>
  size_type size() const;

The size() function returns the number of elements in the current string.


String constructors
Syntax:
  #include <string>
  string();
  string( const string& s );
  string( size_type length, const char& ch );
  string( const char* str );
  string( const char* str, size_type length );
  string( const string& str, size_type index, size_type length );
  string( input_iterator start, input_iterator end );
  ~string();

The string constructors create a new string containing:

For example,

   string str1( 5, 'c' );
   string str2( "Now is the time..." );
   string str3( str2, 11, 4 );
   cout << str1 << endl;
   cout << str2 << endl;
   cout << str3 << endl;            

displays

   ccccc
   Now is the time...
   time         

The string constructors usually run in linear time, except the empty constructor, which runs in constant time.


String operators
Syntax:
  #include <string>
  bool operator==(const string& c1, const string& c2);
  bool operator!=(const string& c1, const string& c2);
  bool operator<(const string& c1, const string& c2);
  bool operator>(const string& c1, const string& c2);
  bool operator<=(const string& c1, const string& c2);
  bool operator>=(const string& c1, const string& c2);
  string operator+(const string& s1, const string& s2 );
  string operator+(const char* s, const string& s2 );
  string operator+( char c, const string& s2 );
  string operator+( const string& s1, const char* s );
  string operator+( const string& s1, char c );
  ostream& operator<<( ostream& os, const string& s );
  istream& operator>>( istream& is, string& s );
  string& operator=( const string& s );
  string& operator=( const char* s );
  string& operator=( char ch );
  char& operator[]( size_type index );

C++ strings can be compared and assigned with the standard comparison operators: ==, !=, <=, >=, <, >, and =. Performing a comparison or assigning one string to another takes linear time.

Two strings are equal if:

  1. Their size is the same, and
  2. Each member in location i in one string is equal to the the member in location i in the other string.              

Comparisons among strings are done lexicographically.

In addition to the normal container operators, strings can also be concatenated with the + operator and fed to the C++ I/O stream classes with the << and >> operators.

For example, the following code concatenates two strings and displays the result:

 string s1 = "Now is the time...";
 string s2 = "for all good men...";
 string s3 = s1 + s2;
 cout << "s3 is " << s3 << endl;            

Futhermore, strings can be assigned values that are other strings, character arrays, or even single characters. The following code is perfectly valid:

 char ch = 'N';
 string s;
 s = ch;         

Individual characters of a string can be examined with the [] operator, which runs in constant time.


substr
Syntax:
  #include <string>
  string substr( size_type index, size_type length = npos );

The substr() function returns a substring of the current string, starting at index, and length characters long. If length is omitted, it will default to string::npos, and the substr() function will simply return the remainder of the string starting at index.

For example:

   string s("What we have here is a failure to communicate");
   string sub = s.substr(21);
   cout << "The original string is " << s << endl;
   cout << "The substring is " << sub << endl;              

displays

   The original string is What we have here is a failure to communicate
   The substring is a failure to communicate            

swap
Syntax:
  #include <string>
  void swap( container& from );

The swap() function exchanges the elements of the current string with those of from. This function operates in constant time.

For example, the following code uses the swap() function to exchange the values of two strings:

   string first( "This comes first" );
   string second( "And this is second" );
   first.swap( second );
   cout << first << endl;
   cout << second << endl;          

The above code displays:

   And this is second
   This comes first