C++ Strings

  #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 );

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

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

 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; 

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

  #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:

• assign str to the current string,
• assign the first num characters of str to the current string,
• assign a substring of str starting at index that is len characters long to the current string,

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.

  #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.

  #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;
   }            

  #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.

  #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.

  #include <string>
  void clear();

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

  #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

The various functions either:

• compare str to the current string,
• compare str to a substring of the current string, starting at index for length characters,
• compare a substring of str to a substring of the current string, where index2 and length2 refer to str and index and length refer to the current string,
• or compare a substring of str to a substring of the current string, where the substring of str begins at zero and is length2 characters long, and the substring of the current string begins at index and is length characters long.

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:

  #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.

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

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

  #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

  #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.

  #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:

• removes the character pointed to by loc, returning an iterator to the next character,
• removes the characters between start and end (including the one at start but not the one at end), returning an iterator to the character after the last character removed,
• or removes num characters from the current string, starting at index, and returns *this.

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.

  #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:

• returns the first occurrence of str within the current string, starting at index, string::npos if nothing is found,
• if the length parameter is given, then find() returns the first occurrence of the first length characters of str within the current string, starting at index, string::npos if nothing is found,
• or returns the index of the first occurrence ch within the current string, starting at index, string::npos if nothing is found.

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;         
   }

  #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:

• returns the index of the first character within the current string that does not match any character in str, beginning the search at index, string::npos if nothing is found,
• searches the current string, beginning at index, for any character that does not match the first num characters in str, returning the index in the current string of the first character found that meets this criteria, otherwise returning string::npos,
• or returns the index of the first occurrence of a character that does not match ch in the current string, starting the search at index, string::npos if nothing is found.

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              

  #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:

• returns the index of the first character within the current string that matches any character in str, beginning the search at index, string::npos if nothing is found,
• searches the current string, beginning at index, for any of the first num characters in str, returning the index in the current string of the first character found, or string::npos if no characters match,
• or returns the index of the first occurrence of ch in the current string, starting the search at index, string::npos if nothing is found.

  #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:

• returns the index of the last character within the current string that does not match any character in str, doing a reverse search from index, string::npos if nothing is found,
• does a reverse search in the current string, beginning at index, for any character that does not match the first num characters in str, returning the index in the current string of the first character found that meets this criteria, otherwise returning string::npos,
• or returns the index of the last occurrence of a character that does not match ch in the current string, doing a reverse search from index, string::npos if nothing is found.

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               

  #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:

• does a reverse search from index, returning the index of the first character within the current string that matches any character in str, or string::npos if nothing is found,
• does a reverse search in the current string, beginning at index, for any of the first num characters in str, returning the index in the current string of the first character found, or string::npos if no characters match,
• or does a reverse search from index, returning the index of the first occurrence of ch in the current string, string::npos if nothing is found.

  #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

  #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:

• inserts ch before the character denoted by i,
• inserts str into the current string, at location index,
• inserts a substring of str (starting at index2 and num characters long) into the current string, at location index1,
• inserts num characters of str into the current string, at location index,
• inserts num copies of ch into the current string, at location index,
• inserts num copies of ch into the current string, before the character denoted by i,
• or inserts the characters denoted by start and end into the current string, before the character specified by i.

  #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.

  #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.

  #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.

  #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.

  #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.

  #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:

• replaces characters of the current string with up to num characters from str, beginning at index,
• replaces up to num1 characters of the current string (starting at index1) with up to num2 characters from str beginning at index2,
• replaces up to num characters of the current string with characters from str, beginning at index in str,
• replaces up to num1 characters in the current string (beginning at index1) with num2 characters from str beginning at index2,
• replaces up to num1 characters in the current string (beginning at index) with num2 copies of ch,
• replaces the characters in the current string from start to end with str,
• replaces characters in the current string from start to end with num characters from str,
• or replaces the characters in the current string from start to end with num copies of ch.

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;               

  #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.

  #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.

  #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:

• returns the location of the first occurrence of str in the current string, doing a reverse search from index, string::npos if nothing is found,
• returns the location of the first occurrence of str in the current string, doing a reverse search from index, searching at most num characters, string::npos if nothing is found,
• or returns the location of the first occurrence of ch in the current string, doing a reverse search from index, string::npos if nothing is found.

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;           

  #include <string>
  size_type size() const;

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

  #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:

• nothing; an empty string,
• a copy of the given string s,
• length copies of ch,
• a duplicate of str (optionally up to length characters long),
• a substring of str starting at index and length characters long
• a string of characters denoted by the start and end iterators

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.

  #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.

  #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            

  #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