• Table of Contents
• Previous Chapter
• Next Chapter

Chapter 4: The `string' data type

Don't hesitate to send in feedback: send an e-mail if you like the C++ Annotations; if you think that important material was omitted; if you find errors or typos in the text or the code examples; or if you just feel like e-mailing. Send your e-mail to Frank B. Brokken.

Please state the document version you're referring to, as found in the title (in this document: 6.5.0) and please state chapter and paragraph name or number you're referring to.

All received mail is processed conscientiously, and received suggestions for improvements will usually have been processed by the time a new version of the Annotations is released. Except for the incidental case I will normally not acknowledge the receipt of suggestions for improvements. Please don't interpret this as me not appreciating your efforts.

C++ offers a large number of facilities to implement solutions for common problems. Most of these facilities are part of the Standard Template Library or they are implemented as generic algorithms (see chapter 17).

Among the facilities C++ programmers have developed over and over again are those for manipulating chunks of text, commonly called strings. The C programming language offers rudimentary string support: the ASCII-Z terminated series of characters is the foundation on which a large amount of code has been built (We define an ASCII-Z string as a series of ASCII-characters terminated by the ASCII-character zero (hence -Z), which has the value zero, and should not be confused with character '0', which usually has the value 0x30).

Standard C++ now offers a string type. In order to use string-type objects, the header file string must be included in sources.

Actually, string objects are class type variables, and the class is formally introduced in chapter 6. However, in order to use a string, it is not necessary to know what a class is. In this section the operators that are available for strings and several other operations are discussed. The operations that can be performed on strings take the form

        stringVariable.operation(argumentList)

        string1.compare(string2)

4.1: Operations on strings

Note that in all operations with strings both string objects and char const * values and variables can be used.

Some string-members use iterators. Iterators will be covered in section 17.2. The member functions using iterators are listed in the next section (4.2), they are not further illustrated below.

The following operations can be performed on strings:

• Initialization: String objects can be initialized. For the initialization a plain ASCII-Z string, another string object, or an implicit initialization can be used. In the example, note that the implicit initialization does not have an argument, and may not use an argument list. Not even empty.

      #include <string>
  
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");  // using plain ascii-Z
          string stringTwo(stringOne);      // using another string object
          string stringThree;               // implicit initialization to "". Do
                                            // not use the form `stringThree()'
          return 0;
      }
  

• Assignment: String objects can be assigned to each other. For this the assignment operator (i.e., the = operator) can be used, which accepts both a string object and a C-style character string as its right-hand argument:

      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
          string stringTwo;
  
          stringTwo = stringOne;      // assign stringOne to stringTwo
          stringTwo = "Hello world";  // assign a C-string to StringTwo
  
          return 0;
      }
  

• String to ASCII-Z conversion: In the previous example a standard C-string (an ASCII-Z string) was implicitly converted to a string-object. The reverse conversion (converting a string object to a standard C-string) is not performed automatically. In order to obtain the C-string that is stored within the string object itself, the member function c_str(), which returns a char const *, can be used:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
          char const *cString = stringOne.c_str();
  
          cout << cString << endl;
  
          return 0;
      }
  

• String elements: The individual elements of a string object can be accessed for reading or writing. For this operation the subscript-operator ([]) is available, but there is no string pointer dereferencing operator (*). The subscript operator does not perform range-checking. If range checking is required the string::at() member function should be used:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
  
          stringOne[6] = 'w';         // now "Hello world"
          if (stringOne[0] == 'H')
              stringOne[0] = 'h';     // now "hello world"
  
          //  *stringOne = 'H';       // THIS WON'T COMPILE
  
          stringOne = "Hello World";  // Now using the at()
  
                                      // member function:
          stringOne.at(6) =
                  stringOne.at(0);    // now "Hello Horld"
          if (stringOne.at(0) == 'H')
              stringOne.at(0) = 'W';  // now "Wello Horld"
  
          return 0;
      }
  

  When an illegal index is passed to the at() member function, the program aborts (actually, an exception is generated, which could be caught. Exceptions are covered in chapter 8).
• Comparisons: Two strings can be compared for (in)equality or ordering, using the ==, !=, <, <=, > and >= operators or the string::compare() member function. The compare() member function comes in several flavors (see section 4.2.4 for details). E.g.:
  • int string::compare(string const &other): this variant offers a bit more information than the comparison-operators do. The return value of the string::compare() member function may be used for lexicographical ordering: a negative value is returned if the string stored in the string object using the compare() member function (in the example: stringOne) is located earlier in the ASCII collating sequence than the string stored in the string object passed as argument.

        #include <iostream>
        #include <string>
        using namespace std;
    
        int main()
        {
            string stringOne("Hello World");
            string stringTwo;
    
            if (stringOne != stringTwo)
                stringTwo = stringOne;
    
            if (stringOne == stringTwo)
                stringTwo = "Something else";
    
            if (stringOne.compare(stringTwo) > 0)
                cout << "stringOne after stringTwo in the alphabet\n";
            else if (stringOne.compare(stringTwo) < 0)
                cout << "stringOne before stringTwo in the alphabet\n";
            else
                cout << "Both strings are the same\n";
    
            // Alternatively:
    
            if (stringOne > stringTwo)
                cout <<
                "stringOne after stringTwo in the alphabet\n";
            else if (stringOne < stringTwo)
                cout <<
                "stringOne before stringTwo in the alphabet\n";
            else
                cout << "Both strings are the same\n";
    
            return 0;
        }
    

    Note that there is no member function to perform a case insensitive comparison of strings.
  • int string::compare(string::size_type pos, size_t n, string const &other): the first argument indicates the position in the current string that should be compared; the second argument indicates the number of characters that should be compared (if this value exceeds the number of characters that are actually available, only the available characters are compared); the third argument indicates the string which is compared to the current string.
  • More variants of string::compare() are available. As stated, refer to section 4.2.4 for details.
  The following example illustrates the compare() function:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
  
              // comparing from a certain offset in stringOne
          if (!stringOne.compare(1, stringOne.length() - 1, "ello World"))
              cout << "comparing 'Hello world' from index 1"
                      " to 'ello World': ok\n";
  
              // the number of characters to compare (2nd arg.)
              // may exceed the number of available characters:
          if (!stringOne.compare(1, string::npos, "ello World"))
              cout << "comparing 'Hello world' from index 1"
                      " to 'ello World': ok\n";
  
              // comparing from a certain offset in stringOne over a
              // certain number of characters in "World and more"
              // This fails, as all of the chars in stringOne
              // starting at index 6 are compared, not just
              // 3 chars in "World and more"
          if (!stringOne.compare(6, 3, "World and more"))
              cout <<
              "comparing 'Hello World' from index 6 over"
              " 3 positions to 'World and more': ok\n";
          else
              cout << "Unequal (sub)strings\n";
  
              // This one will report a match, as only 5 characters are
              // compared of the  source and target strings
          if (!stringOne.compare(6, 5, "World and more", 0, 5))
              cout <<
              "comparing 'Hello World' from index 6 over"
              " 5 positions to 'World and more': ok\n";
          else
              cout << "Unequal (sub)strings\n";
      }
      /*
              Generated output:
  
          comparing 'Hello world' from index 1 to 'ello World': ok
          comparing 'Hello world' from index 1 to 'ello World': ok
          Unequal (sub)strings
          comparing 'Hello World' from index 6 over 5 positions to
                      'World and more': ok
      */
  

• Appending: A string can be appended to another string. For this the += operator can be used, as well as the string &string::append() member function.

  Like the compare() function, the append() member function may have extra arguments. The first argument is the string to be appended, the second argument specifies the index position of the first character that will be appended. The third argument specifies the number of characters that will be appended. If the first argument is of type char const *, only a second argument may be specified. In that case, the second argument specifies the number of characters of the first argument that are appended to the string object. Furthermore, the + operator can be used to append two strings within an expression:

      #include <iostream>
      #include <string>
  
      using namespace std;
  
      int main()
      {
          string stringOne("Hello");
          string stringTwo("World");
  
          stringOne += " " + stringTwo;
  
          stringOne = "hello";
          stringOne.append(" world");
                                          // append 5 characters:
          stringOne.append(" ok. >This is not used<", 5);
  
          cout << stringOne << endl;
  
          string stringThree("Hello");
                                          // append " world":
          stringThree.append(stringOne, 5, 6);
  
          cout << stringThree << endl;
      }
  

  The + operator can be used in cases where at least one term of the + operator is a string object (the other term can be a string, char const * or char).

  When neither operand of the + operator is a string, at least one operand must be converted to a string object first. An easy way to do this is to use an anonymous string object:

          string("hello") + " world";
  

• Insertions: The string &string::insert() member function to insert (parts of) a string has at least two, and at most four arguments:
  • The first argument is the offset in the current string object where another string should be inserted.
  • The second argument is the string to be inserted.
  • The third argument specifies the index position of the first character in the provided string-argument that will be inserted.
  • The fourth argument specifies the number of characters that will be inserted.
  If the first argument is of type char const *, the fourth argument is not available. In that case, the third argument indicates the number of characters of the provided char const * value that will be inserted.

      #include <string>
  
      int main()
      {
          string
              stringOne("Hell ok.");
                              // Insert "o " at position 4
          stringOne.insert(4, "o ");
  
          string
              world("The World of C++");
  
                              // insert "World" into stringOne
          stringOne.insert(6, world, 4, 5);
  
          cout << "Guess what ? It is: " << stringOne << endl;
      }
  

  Several variants of string::insert() are available. See section 4.2 for details.
• Replacements: At times, the contents of string objects must be replaced by other information. To replace parts of the contents of a string object by another string the member function string &string::replace() can be used. The member function has at least three and possibly five arguments, having the following meanings (see section 4.2 for overloaded versions of replace(), using different types of arguments):
  • The first argument indicates the position of the first character that must be replaced
  • The second argument gives the number of characters that must be replaced.
  • The third argument defines the replacement text (a string or char const *).
  • The fourth argument specifies the index position of the first character in the provided string-argument that will be inserted.
  • The fifth argument can be used to specify the number of characters that will be inserted.
  If the third argument is of type char const *, the fifth argument is not available. In that case, the fourth argument indicates the number of characters of the provided char const * value that will be inserted.

  The following example shows a very simple file changer: it reads lines from cin, and replaces occurrences of a `searchstring' by a `replacestring'. Simple tests for the correct number of arguments and the contents of the provided strings (they should be unequal) are applied as well.

      #include <iostream>
      #include <string>
  
      using namespace std;
  
      int main(int argc, char **argv)
      {
          if (argc == 3)
          {
              cerr << "Usage: <searchstring> <replacestring> to process "
                                                                    "stdin\n";
              return 1;
          }
  
          string search(argv[1]);
          string replace(argv[2]);
  
          if (search == replace)
          {
              cerr << "The replace and search texts should be different\n";
              return 1;
          }
  
          string line;
          while (getline(cin, line))
          {
              string::size_type idx = 0;
              while (true)
              {
                  idx = line.find(search, idx); // find(): another string member
                                                //         see `searching' below
                  if (idx == string::npos)
                      break;
  
                  line.replace(idx, search.size(), replace);
                  idx += replace.length();     // don't change the replacement
              }
              cout << line << endl;
          }
          return 0;
      }
  

• Swapping: The member function string &string::swap(string &other) swaps the contents of two string-objects. For example:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello");
          string stringTwo("World");
  
          cout << "Before: stringOne: " << stringOne << ", stringTwo: "
              << stringTwo << endl;
  
          stringOne.swap(stringTwo);
  
          cout << "After: stringOne: " << stringOne << ", stringTwo: "
              << stringTwo << endl;
      }
  

• Erasing: The member function string &string::erase() removes characters from a string. The standard form has two optional arguments:
  • If no arguments are specified, the stored string is erased completely: it becomes the empty string (string() or string("")).
  • The first argument may be used to specify the offset of the first character that must be erased.
  • The second argument may be used to specify the number of characters that are to be erased.
  See section 4.2 for overloaded versions of erase(). An example of the use of erase() is given below:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello Cruel World");
  
          stringOne.erase(5, 6);
  
          cout << stringOne << endl;
  
          stringOne.erase();
  
          cout << "'" << stringOne << "'\n";
      }
  

• Searching: To find substrings in a string the member function string::size_type string::find() can be used. This function looks for the string that is provided as its first argument in the string object calling find() and returns the index of the first character of the substring if found. If the string is not found string::npos is returned. The member function rfind() looks for the substring from the end of the string object back to its beginning. An example using find() was given earlier.
• Substrings: To extract a substring from a string object, the member function stringstring::substr() is available. The returned string object contains a copy of the substring in the string-object calling substr() The substr() member function has two optional arguments:
  • Without arguments, a copy of the string itself is returned.
  • The first argument may be used to specify the offset of the first character to be returned.
  • The second argument may be used to specify the number of characters that are to be returned.
  For example:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
  
          cout << stringOne.substr(0, 5)  << endl
               << stringOne.substr(6)     << endl
               << stringOne.substr()      << endl;
      }
  

• Character set searches: Whereas find() is used to find a substring, the functions find_first_of(), find_first_not_of(), find_last_of() and find_last_not_of() can be used to find sets of characters (Unfortunately, regular expressions are not supported here). The following program reads a line of text from the standard input stream, and displays the substrings starting at the first vowel, starting at the last vowel, and starting at the first non-digit:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string line;
  
          getline(cin, line);
  
          string::size_type pos;
  
          cout << "Line: " << line << endl
              << "Starting at the first vowel:\n"
              << "'"
                  << (
                      (pos = line.find_first_of("aeiouAEIOU"))
                      != string::npos ?
                          line.substr(pos)
                      :
                          "*** not found ***"
                      ) << "'\n"
              << "Starting at the last vowel:\n"
              << "'"
                  << (
                      (pos = line.find_last_of("aeiouAEIOU"))
                      != string::npos ?
                          line.substr(pos)
                      :
                          "*** not found ***"
                      ) << "'\n"
              << "Starting at the first non-digit:\n"
              << "'"
                  << (
                      (pos = line.find_first_not_of("1234567890"))
                      != string::npos ?
                          line.substr(pos)
                      :
                          "*** not found ***"
                      ) << "'\n";
      }
  

• String size: The number of characters that are stored in a string are obtained by the size() member function, which, like the standard C function strlen() does not include the terminating ASCII-Z character. For example:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne("Hello World");
  
          cout << "The length of the stringOne string is "
              << stringOne.size() << " characters\n";
      }
  

• Empty strings: The size() member function can be used to determine whether a string holds no characters. Alternatively, the string::empty() member function can be used:

      #include <iostream>
      #include <string>
      using namespace std;
  
      int main()
      {
          string stringOne;
  
          cout << "The length of the stringOne string is "
              << stringOne.size() << " characters\n"
                  "It is " << (stringOne.empty() ? "" : " not ")
              << "empty\n";
  
          stringOne = "";
  
          cout << "After assigning a \"\"-string to a string-object\n"
                  "it is " << (stringOne.empty() ? "also" : " not")
              << " empty\n";
      }
  

• Resizing strings: If the size of a string is not enough (or if it is too large), the member function void string::resize() can be used to make it longer or shorter. Note that operators like += automatically resize a string when needed.
• Reading a line from a stream into a string: The function

      istream &getline(istream &instream, string &target, char delimiter)
  

  may be used to read a line of text (up to the first delimiter or the end of the stream) from instream (note that getline() is not a member function of the class string).

  The delimiter has a default value '\n'. It is removed from instream, but it is not stored in target. The member istream::eof() may be called to determine whether the delimiter was found. If it returns true the delimiter was not found (see chapter 5 for details about istream objects). The function getline() was used in several earlier examples (e.g., with the replace() member function).

• A string variables may be extracted from a stream. Using the construction

      istr >> str;
  

  where istr is an istream object, and str is a string, the next consecutive series of non-blank characters will be assigned to str. Note that by default the extraction operation will skip any blanks that precede the characters that are extracted from the stream.

4.2: Overview of operations on strings

The member functions are ordered alphabetically by the name of the operation. Below, object is a string-object, and argument is either a string const & or a char const *, unless overloaded versions tailored to string and char const * parameters are explicitly mentioned. Object is used in cases where a string object is initialized or given a new value. The entity referred to by argument always remains unchanged.

Furthermore, opos indicates an offset into the object string, apos indicates an offset into the argument string. Analogously, on indicates a number of characters in the object string, and an indicates a number of characters in the argument string. Both opos and apos must refer to existing offsets, or an exception will be generated. In contrast to this, an and on may exceed the number of available characters, in which case only the available characters will be considered.

When streams are involved, istr indicates a stream from which information is extracted, ostr indicates a stream into which information is inserted.

With member functions the types of the parameters are given in a function-prototypical way. With several member functions iterators are used. At this point in the Annotations it's a bit premature to discuss iterators, but for referential purposes they have to be mentioned nevertheless. So, a forward reference is used here: see section 17.2 for a more detailed discussion of iterators. Like apos and opos, iterators must also refer to an existing character, or to an available iterator range of the string to which they refer.

Finally, note that all string-member functions returning indices in object return the predefined constant string::npos if no suitable index could be found.

4.2.1: Initializers

• string object:

  Initializes object to an empty string.

• string object(string::size_type no, char c):

  Initializes object with no characters c.

• string object(string argument):

  Initializes object with argument.

• string object = argument:

  Initializes object with argument. This is an alternative form of the previous initialization.

• string object(string argument, string::size_type apos, string::size_type an = pos):

  Initializes object with argument, using an characters of argument, starting at index apos.

• string object(InputIterator begin, InputIterator end):

  Initializes object with the range of characters implied by the provided InputIterators. Iterators are covered in detail in section 17.2, but can (for the time being) be interpreted as pointers to characters. See also the next section.

4.2.2: Iterators

• Forward iterators are returned by the members:
  • string::begin(), pointing to the first character inside the string object.
  • string::end(), pointing beyond the last character inside the string object.
• Reverse iterators are also iterators, but they are used to step through a range in a reversed direction. Reverse iterators are returned by the members:
  • string::rbegin(), which can be considered to be an iterator pointing to the last character inside the string object.
  • string::rend(), which can be considered to be an iterator pointing before the first character inside the string object.

4.2.3: Operators

• object = argument.

  Assignment of argument to an existing string object.

• object = c.

  Assignment of char c to object.

• object += argument.

  Appends argument to object. Argument may also be a char expression.

• argument1 + argument2.

  Within expressions, strings may be added. At least one term of the expression (the left-hand term or the right-hand term) should be a string object. The other term may be a string, a char const * value or a char expression, as illustrated by the following example:

      void fun()
      {
          char const *asciiz = "hello";
          string first = "first";
          string second;
  
              // all expressions compile ok:
          second = first + asciiz;
          second = asciiz + first;
          second = first + 'a';
          second = 'a' + first;
      }
  

• object[string::size_type opos].

  The subscript-operator may be used to retrieve object's individual characters, or to assign new values to individual characters of object or to retrieve these characters. There is no range-checking. If range checking is required, use the at() member function.

• argument1 == argument2.

  The equality operator ( ==) may be used to compare a string object to another string or char const * value. The != operator is available as well. The return value for both is a bool. For two identical strings == returns true, and != returns false.

• argument1 < argument2.

  The less-than operator may be used to compare the ordering within the Ascii-character set of argument1 and argument2. The operators <=, > and >= are available as well.

• ostr << object.

  The insertion-operator may be used with string objects.

• istr >> object.

  The extraction-operator may be used with string objects. It operates analogously to the extraction of characters into a character array, but object is automatically resized to the required number of characters.

4.2.4: Member functions

The special value string::npos, defined by the string class, represents a non-existing index. This value is returned by all members returning indices when they could not perform their requested tasks. Note that the string's length is not returned as a valid index. E.g., when calling a member `find_first_not_of(" ")' (see below) on a string object holding 10 blank space characters, npos is returned, as the string only contains blanks. The final 0-byte that is used in C to indicate the end of a ASCII-Z string is not considered part of a C++ string, and so the member function will return npos, rather than length().

In the following overview, `size_type' should always be read as ` string::size_type'.

• char &string::at(size_type opos):

  The character (reference) at the indicated position is returned (it may be reassigned). The member function performs range-checking, aborting the program if an invalid index is passed.

• string &string::append(InputIterator begin, InputIterator end):

  Using this member function the range of characters implied by the begin and end InputIterators are appended to the string object.

• string &string::append(string argument, size_type apos, size_type an):

  • If only argument is provided, it is appended to the string object.
  • If apos is provided as well, argument is appended from index position apos until the end of argument.
  • If an is provided too, an characters of argument, starting at index position apos are appended to the string object.

  If argument is of type char const *, the second parameter apos is not available. So, with char const * arguments, either all characters or an initial subset of the characters of the provided char const * argument are appended to the string object. Of course, if apos and an are specified in this case, append() can still be used: the char const * argument will then implicitly be converted to a string const &.

• string &string::append(size_type n, char c):

  Using this member function, n characters c can be appended to the string object.

• string &string::assign(string argument, size_type apos, size_type an):

  • If only argument is provided, it is assigned to the string object.
  • If apos is specified as well, a substring of argument object, starting at offset position apos, is assigned to the string object calling this member.
  • If an is provided too, a substring of argument object, starting at offset position apos, containing at most an characters, is assigned to the string object calling this member.

  If argument is of type char const *, no parameter apos is available. So, with char const * arguments, either all characters or an initial subset of the characters of the provided char const * argument are assigned to the string object. As with the string::append() member, a char const * argument may be used, but it will be converted to a string object first.

• string &string::assign(size_type n, char c):

  Using this member function, n characters c can be assigned to the string object.

• size_type string::capacity():

  returns the number of characters that can currently be stored inside the string object.

• int string::compare(string argument):

  This member function can be used to compare (according to the ASCII-character set) the text stored in the string object and in argument. The argument may also be a (non-0) char const *. 0 is returned if the characters in the string object and in argument are the same; a negative value is returned if the text in string is lexicographically before the text in argument; a positive value is returned if the text in string is lexicographically beyond the text in argument.

• int string::compare(size_type opos, size_type on, string argument):

  This member function can be used to compare a substring of the text stored in the string object with the text stored in argument. At most on characters, starting at offset opos, are compared with the text in argument. The argument may also be a (non-0) char const *.

• int string::compare(size_type opos, size_type on, string argument, size_type apos, size_type an):

  This member function can be used to compare a substring of the text stored in the string object with a substring of the text stored in argument. At most on characters of the string object, starting at offset opos, are compared with at most an characters of argument, starting at offset apos. Note that argument must also be a string object.

• int string::compare(size_type opos, size_type on, char const *argument, size_type an):

  This member function can be used to compare a substring of the text stored in the string object with a substring of the text stored in argument. At most on characters of the string object, starting at offset opos, are compared with at most an characters of argument. Argument must have at least an characters. However, the characters may have arbitrary values: the ASCII-Z value has no special meaning.

• size_type string::copy(char *argument, size_type on, size_type opos):

  The contents of the string object is (partially) copied to argument.

  • If on is provided, it refers to the maximum number of characters that will be copied. If omitted, all the string's characters, starting at offset opos, will be copied to argument. Also, string::npos may be specified to indicate that all available characters should be copied.
  • If both on and opos are provided, opos refers to the offset in the string object where copying should start.

  The actual number of characters that were copied is returned. Note: following the copying, no ASCII-Z will be appended to the copied string. A final ASCII-Z character can be appended to the copied text using the following construction:

      buffer[s.copy(buffer)] = 0;
  

• char const *string::c_str():

  the member function returns the contents of the string object as an ASCII-Z C-string.

• char const *string::data():

  returns the raw text stored in the string object. Since this member does not return an ascii-Z string (as c_str() does), it can be used to store and retrieve any kind of information, including, e.g., series of 0-bytes:

          string s;
          s.resize(2);
          cout << static_cast<int>(s.data()[1]) << endl;
  

• bool string::empty():

  returns true if the string object contains no data.

• string &string::erase(size_type opos; size_type on):

  This member function can be used to erase (a sub)string of the string object.

  • If no arguments are provided, the contents of the string object are completely erased.
  • If opos is specified, the contents of the string object are erased, starting from index position opos until (including) the object's final character.
  • If on is provided as well, on characters of the string object, starting at index position opos are erased.

• iterator string::erase(iterator obegin, iterator oend):

  • If only obegin is provided, the string object's character at iterator position obegin is erased.
  • If oend is provided as well, the range of characters of the string object, implied by the iterators obegin and oend are erased.

  The iterator obegin is returned, pointing to the character immediately following the last erased character.

• size_type string::find(string argument, size_type opos):

  Returns the index in the string object where argument is found.

  • If opos is provided, it refers to the index in the string object where the search for argument should start. If opos is omitted, searching starts at the beginning of the string object.

• size_type string::find(char const *argument, size_type opos, size_type an):

  Returns the index in the string object where argument is found.

  • If opos is provided, it refers to the index in the string object where the search for argument should start. If omitted, the string object is scanned completely.
  • If an is provided as well, it indicates the number of characters of argument that should be used in the search: it defines a partial string starting at the beginning of argument. If omitted, all characters in argument are used.

• size_type string::find(char c, size_type opos):

  Returns the index in the string object where c is found.

  • If opos is provided it refers to the index in the string object where the search for the character should start. If omitted, searching starts at the beginning of the string object.

• size_type string::find_first_of(string argument, size_type opos):

  Returns the index in the string object where any character in argument is found.

  • If opos is provided, it refers to the index in the string object where the search for argument should start. If omitted, searching starts at the beginning of the string object.

• size_type string::find_first_of(char const *argument, size_type opos, size_type an):

  Returns the index in the string object where a character of argument is found, no matter which character.

  • If opos is provided it refers to the index in the string object where the search for argument should start. If omitted, the string object is scanned completely.
  • If an is provided it indicates the number of characters of the char const * argument that should be used in the search: it defines a partial string starting at the beginning of the char const * argument. If omitted, all of argument's characters are used.

• size_type string::find_first_of(char c, size_type opos):

  Returns the index in the string object where character c is found.

  • If opos is provided, it refers to the index in the string object where the search for c should start. If omitted, searching starts at the beginning of the string object.

• size_type string::find_first_not_of(string argument, size_type opos):

  Returns the index in the string object where a character not appearing in argument is found.

  • If opos is provided, it refers to the index in the string object where the search for argument should start. If omitted, searching starts at the beginning of the string object.

• size_type string::find_first_not_of(char const *argument, size_type opos, size_type an):

  Returns the index in the string object where any character not appearing in argument is found.

  • If opos is provided it refers to the index in the string object where the search for characters not specified in argument should start. If omitted, the string object is scanned completely.
  • If an is provided it indicates the number of characters of the char const * argument that should be used in the search: it defines a partial string starting at the beginning of the char const * argument. If omitted, all of argument's characters are used.

• size_type string::find_first_not_of(char c, size_type opos):

  Returns the index in the string object where another character than c is found.

  • If opos is provided, it refers to the index in the string object where the search for c should start. If omitted, searching starts at the beginning of the string object.

• size_type string::find_last_of(string argument, size_type opos):

  Returns the last index in the string object where one of argument's characters is found.

  • If opos is provided it refers to the index in the string object where the search for argument should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.

• size_type string::find_last_of(char const* argument, size_type opos, size_type an):

  Returns the last index in the string object where one of argument's characters is found.

  • If opos is provided it refers to the index in the string object where the search for argument should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.
  • If an is provided it indicates the number of characters of argument that should be used in the search: it defines a partial string starting at the beginning of the char const * argument. If omitted, all of argument's characters are used.

• size_type string::find_last_of(char c, size_type opos):

  Returns the last index in the string object where character c is found.

  • If opos is provided it refers to the index in the string object where the search for character c should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.

• size_type string::find_last_not_of(string argument, size_type opos):

  Returns the last index in the string object where any character not appearing in argument is found.

  • If opos is provided it refers to the index in the string object where the search for characters not appearing in argument should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.

• size_type string::find_last_not_of(char const *argument, size_type opos, size_type an):

  Returns the last index in the string object where any character not appearing in argument is found.

  • If opos is provided it refers to the index in the string object where the search for characters not appearing in argument should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.
  • If an is provided it indicates the number of characters of argument that should be used in the search: it defines a partial string starting at the beginning of the char const * argument. If omitted, all of argument's characters are used.

• size_type string::find_last_not_of(char c, size_type opos):

  Returns the last index in the string object where another character than c is found.

  • If opos is provided it refers to the index in the string object where the search for a character unequal to character c should start, proceeding backwards to the string's first character. If omitted, searching starts at the the string object's last character.

• istream &getline(istream &istr, string object, char delimiter):

  This function (note that it's not a member function of the class string) can be used to read a line of text from istr. All characters until delimiter (or the end of the stream, whichever comes first) are read from istr and are stored in object. The delimiter, when present, is removed from the stream, but is not stored in line. The delimiter's default value is '\n'.
  If the delimiter is not found, istr.fail() returns 1 (see section 5.3.1). Note that the contents of the last line, whether or not it was terminated by a delimiter, will always be assigned to object.
  

• string &string::insert(size_type opos, string argument, size_type apos, size_type an):

  This member function can be used to insert (a sub)string of argument into the string object, at the string object's index position opos. The arguments apos and an must either be specified or they must both be omitted. If specified, an characters of argument, starting at index position apos are inserted into the string object.
  If argument is of type char const *, no parameter apos is available. So, with char const * arguments, either all characters or an initial subset of an characters of the provided char const * argument are inserted into the string object. In this case, the prototype of the member function is:

      string &string::insert(size_type opos, char const *argument,
                             size_type an)
  

  (As before, an implicit conversion from char const * to string will occur if apos and an are provided).

• string &string::insert(size_type opos, size_type n, char c):

  Using this member function, n characters c can be inserted to the string object.

• iterator string::insert(iterator obegin, char c):

  The character c is inserted at the (iterator) position obegin in the string object. The iterator obegin is returned.

• iterator string::insert(iterator obegin, size_type n, char c):

  At the (iterator) position obegin of object n characters c are inserted. The iterator obegin is returned.

• iterator string::insert(iterator obegin, InputIterator abegin, InputIterator aend):

  The range of characters implied by the InputIterators abegin and aend are inserted at the (iterator) position obegin in object. The iterator obegin is returned.

• size_type string::length():

  returns the number of characters stored in the string object.

• size_type string::max_size():

  returns the maximum number of characters that can be stored in the string object.

• string &string::replace(size_type opos, size_type on, string argument, size_type apos, size_type an):

  The arguments apos and an are optional. If omitted, argument is considered completely. The substring of on characters of the string object, starting at position opos is replaced by argument. If on is set to 0, the member function inserts argument into object.
  

  • If apos and an are provided, an characters of argument, starting at index position apos will replace the indicated range of characters of object.

  If argument is of type char const *, no parameter apos is available. So, with char const * arguments, either all characters or an initial subset of the characters of an characters of the provided char const * argument will replace the indicated range of characters in object. In that case, the prototype of the member function is:

      string &string::replace(size_type opos, size_type on,
                              char const *argument, size_type an)
  

• string &string::replace(size_type opos, size_type on, size_type n, char c):

  This member function can be used to replace on characters of the string object, starting at index position opos, by n characters having values c.

• string &string::replace (iterator obegin, iterator oend, string argument):

  Here, the string implied by the iterators obegin and oend are replaced by argument. If argument is a char const *, an extra argument n may be used, specifying the number of characters of argument that are used in the replacement.

• string &string::replace(iterator obegin, iterator oend, size_type n, char c):

  The range of characters of the string object, implied by the iterators obegin and oend are replaced by n characters having values c.

• string string::replace(iterator obegin, iterator oend, InputIterator abegin, InputIterator aend):

  Here the range of characters implied by the iterators obegin and oend is replaced by the range of characters implied by the InputIterators abegin and aend.

• void string::resize(size_type n, char c):

  The string stored in the string object is resized to n characters. The second argument is optional, in which case the value c = 0 is used. If provided and the string is enlarged, the extra characters are initialized to c.

• size_type string::rfind(string argument, size_type opos):

  Returns the index in the string object where argument is found. Searching proceeds either from the end of the string object or from its offset opos back to the beginning. If the argument opos is omitted, searching starts at the end of object.

• size_type string::rfind(char const *argument, size_type opos, size_type an):

  Returns the index in the string object where argument is found. Searching proceeds either from the end of the string object or from offset opos back to the beginning. The parameter an indicates the number of characters of argument that should be used in the search: it defines a partial string starting at the beginning of argument. If omitted, all characters in argument are used.

• size_type string::rfind(char c, size_type opos):

  Returns the index in the string object where c is found. Searching proceeds either from the end of the string object or from offset opos back to the beginning.

• size_type string::size():

  returns the number of characters stored in the string object. This member is a synonym of string::length().

• string string::substr(size_type opos, size_type on):

  Returns (using a value return type) a substring of the string object. The parameter on may be used to specify the number of characters of object that are returned. The parameter opos may be used to specify the index of the first character of object that is returned. Either on or both arguments may be omitted. The string object itself is not modified by substr().

• size_type string::swap(string argument):

  swaps the contents of the string object and argument. In this case, argument must be a string and cannot be a char const *. Of course, both strings (object and argument) are modified by this member function.

• Table of Contents
• Previous Chapter
• Next Chapter