13.46 <string>

The <string> header declares the class templates and functions that support the string and wstring types, which are specializations of the basic_string class template. The string types are easier to use and safer than C-style character arrays. Another important class template is char_traits, which describes a character type and is used throughout the standard library.

The complete declarations of the overloaded operators can be daunting to read. To help you, each function template declaration is followed by a comment that shows the equivalent declaration that uses the common typedefs for narrow characters (e.g., string instead of basic_string<charT, traits, Allocator>).

Example 13-37 shows a function that classifies a string as an identifier, integer, floating point, or other. The example demonstrates the use of the string class and several of its member functions.

Example 13-37. Classifying a string

#include <iostream>
#include <string>
   
enum kind { empty, ident, integer, floatingpt, error };
   
kind classify(const std::string& s)
{
  using std::string;
  const string lower("abcdefghijklmnopqrstuvwxyz");
  const string upper("ABCDEFGHIJKLMNOPQRSTUVWXYZ");
  const string letters = lower + upper + '_';
  const string digits("0123456789");
  const string identchars = letters + digits;
   
  if (s.empty(  ))
    return empty;
   
  else if (letters.find_first_of(s[0]) != string::npos) {
    // Check for valid identifier.
    if (s.find_first_not_of(identchars, 1) == string::npos)
      return ident;
    else
      return error;
  }
   
  // Skip a leading sign, if present.
  string::size_type pos;
  if (s[0] == '+' or s[0] == '-')
    pos = 1;
  else
    pos = 0;
   
  // The number must start with a digit.
  if (pos == s.length(  ))
    return error;
  if (not digits.find_first_of(s[pos]))
    return error;
  // Find where the digit string ends.
  pos = s.find_first_not_of(digits, pos);
  if (pos == string::npos)
    // Only digits => integer
    return integer;
   
  else if (s[pos] == '.') {
    // There is a decimal point.
    pos = s.find_first_not_of(digits, pos+1);
    if (pos == string::npos)
      // Integer part "." fractional part
      return floatingpt;
  }
   
  // Look for optional exponent.
  if (s[pos] == 'e' or s[pos] == 'E') {
    if (pos == s.length(  ) - 1)
      return error; // 'e' or 'E' is last char
    else if (s[pos+1] == '+' or s[pos+1] == '-')
      ++pos;        // skip over sign;
    if (pos == s.length(  ) - 1)
      return error; // Sign is last char.
    pos = s.find_first_not_of(digits, pos+1);
    if (pos == string::npos)
      return floatingpt;
  }
   
  return error;
}

template<class charT, class traits = char_traits<charT>,
         class Alloc = allocator<charT> >
class basic_string {
public:
  typedef traits traits_type;
  typedef typename traits::char_type value_type;
  typedef Alloc allocator_type;
  typedef typename Alloc::size_type size_type;
  typedef typename Alloc::difference_type difference_type;
  typedef typename Alloc::reference reference;
  typedef typename Alloc::const_reference const_reference;
  typedef typename Alloc::pointer pointer;
  typedef typename Alloc::const_pointer const_pointer;
  typedef  . . .  iterator;
  typedef  . . .  const_iterator;
  typedef std::reverse_iterator<iterator> reverse_iterator;
  typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
  static const size_type npos = -1;
   
  explicit basic_string(const Alloc& a = Alloc(  ));
  basic_string(const basic_string& str);
  basic_string(const basic_string& str, size_type pos, size_type n = npos,
               const Alloc& a = Alloc(  ));
  basic_string(const charT* s, size_type n, const Alloc& a = Alloc(  ));
  basic_string(const charT* s, const Alloc& a = Alloc(  ));
  basic_string(size_type n, charT c, const Alloc& a=Alloc(  ));
  template<class InputIterator>
  basic_string(InputIterator begin, InputIterator end, 
               const Alloc& a = Alloc(  ));
  ~basic_string(  );
  basic_string& operator=(const basic_string& str);
  basic_string& operator=(const charT* s);
  basic_string& operator=(charT c);
   
  iterator begin(  );
  const_iterator begin(  ) const;
  iterator end(  );
  const_iterator end(  ) const;
  reverse_iterator rbegin(  );
  const_reverse_iterator rbegin(  ) const;
  reverse_iterator rend(  );
  const_reverse_iterator rend(  ) const;
  // Size and capacity
  size_type size(  ) const;
  size_type length(  ) const;
  size_type max_size(  ) const;
  void resize(size_type n, charT c);
  void resize(size_type n);
  size_type capacity(  ) const;
  void reserve(size_type res_arg = 0);
  void clear(  );
  bool empty(  ) const;
  // Element access
  const_reference operator[](size_type pos) const;
  reference operator[](size_type pos);
  const_reference at(size_type n) const;
  reference at(size_type n);
  basic_string substr(size_type pos = 0, size_type n = npos) const;
  // Modifiers
  basic_string& operator+=(const basic_string& str);
  basic_string& operator+=(const charT* s);
  basic_string& operator+=(charT c);
  basic_string& append(const basic_string& str);
  basic_string& append(const basic_string& str, size_type pos, size_type n);
  basic_string& append(const charT* s, size_type n);
  basic_string& append(const charT* s);
  basic_string& append(size_type n, charT c);
  template<class InputIter>
  basic_string& append(InputIter first, InputIter last);
  void push_back(charT c);
  basic_string& assign(const basic_string& str);
  basic_string& assign(const basic_string& str, size_type pos, size_type n);
  basic_string& assign(const charT* s, size_type n);
  basic_string& assign(const charT* s);
  basic_string& assign(size_type n, charT c);
  template<class InputIter>
  basic_string& assign(InputIter first, InputIter last);
  basic_string& insert(size_type pos1, const basic_string& str);
  basic_string& insert(size_type pos1, const basic_string& str, size_type pos2,
                       size_type n);
  basic_string& insert(size_type pos, const charT* s, size_type n);
  basic_string& insert(size_type pos, const charT* s);
  basic_string& insert(size_type pos, size_type n, charT c);
  iterator insert(iterator p, charT c);
  void insert(iterator p, size_type n, charT c);
  template<class InputIter>
  void insert(iterator p, InputIter first, InputIter last);
  basic_string& erase(size_type pos = 0, size_type n = npos);
  iterator erase(iterator position);
  iterator erase(iterator first, iterator last);
  basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
  basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
                        size_type pos2,  size_type n2);
  basic_string& replace(size_type pos, size_type n1, const charT* s, 
                        size_type n2);
  basic_string& replace(size_type pos, size_type n1, const charT* s);
  basic_string& replace(size_type pos, size_type n1, size_type n2, charT c);
  basic_string& replace(iterator i1, iterator i2, const basic_string& str);
  basic_string& replace(iterator i1, iterator i2, const charT* s, size_type n);
  basic_string& replace(iterator i1, iterator i2, const charT* s);
  basic_string& replace(iterator i1, iterator i2, size_type n, charT c);
  template<class InputIterator>
  basic_string& replace(iterator i1, iterator i2, InputIterator j1,
                        InputIterator j2);
  size_type copy(charT* s, size_type n, size_type pos = 0) const;
  void swap(basic_string& str);
  // String operations
  const charT* c_str(  ) const;
  const charT* data(  ) const;
  allocator_type get_allocator(  ) const;
  // Searching
  size_type find(const basic_string& str, size_type pos = 0) const;
  size_type find(const charT* s, size_type pos, size_type n) const;
  size_type find(const charT* s, size_type pos = 0) const;
  size_type find(charT c, size_type pos = 0) const;
  size_type rfind(const basic_string& str, size_type pos = npos) const;
  size_type rfind(const charT* s, size_type pos, size_type n) const;
  size_type rfind(const charT* s, size_type pos=npos) const;
  size_type rfind(charT c, size_type pos = npos) const;
  size_type find_first_of(const basic_string& str, size_type pos = 0) const;
  size_type find_first_of(const charT* s, size_type pos, size_type n) const;
  size_type find_first_of(const charT* s, size_type pos = 0) const;
  size_type find_first_of(charT c, size_type pos = 0) const;
  size_type find_last_of(const basic_string& str, size_type pos = npos) const;
  size_type find_last_of(const charT* s, size_type pos, size_type n) const;
  size_type find_last_of(const charT* s, size_type pos = npos) const;
  size_type find_last_of(charT c, size_type pos=npos) const;
  size_type find_first_not_of(const basic_string& str, size_type pos = 0) const;
  size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
  size_type find_first_not_of(const charT* s, size_type pos = 0) const;
  size_type find_first_not_of(charT c, size_type pos = 0) const;
  size_type find_last_not_of(const basic_string& str, size_type pos = npos) 
                             const;
  size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
  size_type find_last_not_of(const charT* s, size_type pos = npos) const;
  size_type find_last_not_of(charT c, size_type pos = npos) const;
  // Comparisons
  int compare(const basic_string& str) const;
  int compare(size_type pos1, size_type n1, const basic_string& str) const;
  int compare(size_type pos1, size_type n1, const basic_string& str, 
              size_type pos2, size_type n2) const;
  int compare(const charT* s) const;
  int compare(size_type pos1, size_type n1, const charT* s) const;
  int compare(size_type pos1, size_type n1, const charT* s, size_type n2)
    const;
};

The basic_string class template is the base for the string and wstring types. A string object holds a sequence, or string, of characters and provides a number of useful member functions for searching and modifying the string. You can also work with C-style, null-terminated character strings as arguments to basic_string members, including constructors. A basic_string object keeps track of an explicit length instead of using the C convention of null-terminated character arrays. The string and wstring types are therefore much easier to use and offer greater safety (see the at member function), while still offering ease-of-use with many functions that take C-style strings as arguments.

If you need a sequence of characters that you don't need to treat as a character string, you can use vector<char> or vector<wchar_t>, but in most cases you will probably find string or wstring to be more convenient. You can usually use a string or wstring as a container that supports random access iterators, so you can use strings with the standard algorithms.

Many of the member functions can throw exceptions. Specifying an index out of range often throws out_of_range. An attempt to construct a string or modify a string so its length exceeds max_string( ) throws length_error. The basic_string class uses an allocator object for memory allocation, which can throw an exception (such as bad_alloc) almost any time the string is modified.

Iterators, pointers, and references to elements of a string become invalid in the following situations:

• The string is the target of the swap member function or an argument to the swap function template.

• The string is an argument to operator>> or getline.

• You call the data or c_str member function.

• You call any non-const member function except operator[], at, begin, end, rbegin, or rend.

• Tou call the non-const version of operator[], at, begin, end, rbegin, or rend after any of the above situations, except after calling a form of insert or erase that returns an iterator (so the returned iterator remains valid).

The following are the members of basic_string. Several small examples appear throughout this section, illustrating the use of some of the more complex member functions. Some of the functions are described in terms of temporary string objects or calls to other member functions. The actual implementation might be different, provided the behavior is the same.

explicit basic_string(const Alloc& a = Alloc( ))

Constructs an empty string.

basic_string(const basic_string& str)

Constructs a string that is a copy of str, with Alloc( ) as the allocator.

basic_string(const basic_string& str, size_type pos, size_type n = npos, const Alloc& a = Alloc( ))

Copies a substring of str, starting at pos. If pos is out of range (that is, pos > str.size( )), out_of_range is thrown. The number of characters copied is n or the number of characters left in the string (str.size( ) - pos), whichever is smaller.

basic_string(const charT* s, size_type n, const Alloc& a = Alloc( ))

Copies the first n characters from s.

basic_string(const charT* s, const Alloc& a = Alloc( ))

Copies a null-terminated character array, s. More precisely, this constructor copies traits::length(s) characters from s.

basic_string(size_type n, charT c, const Alloc& a = Alloc( ))

Initializes the string with n copies of the character c.

template<class InputIterator>

basic_string(InputIterator begin, InputIterator end, const Alloc& a = Alloc( ))

The constructor depends on the type of InputIterator:

• For any input iterator, the string is initialized by copying the contents of the range [begin, end).

• If InputIterator is an integral type, the string is initialized with static_cast<size_type>(begin) copies of the character static_cast<value_type>(end).

basic_string& append(const basic_string& str, size_type pos, size_type n)

Appends characters to the end of the string. If pos > str.size( ), out_of_range is thrown. Otherwise, up to n characters are copied from str, starting at position pos. The return value is *this. See also operator+= later in this section.

basic_string& append(const basic_string& str)

Returns append(str, 0, npos).

basic_string& append(const charT* s, size_type n)

basic_string& append(const charT* s)

basic_string& append(size_type n, charT c)

template<class InputIter>

basic_string& append(InputIter first, InputIter last)

Constructs a temporary string str, passing the arguments to the constructor, and returns append(str).

basic_string& assign(const basic_string& str, size_type pos, size_type n)

Erases the current contents of the string and replaces them with the substring of str that starts at pos and extends for up to n characters. The return value is *this. See also operator= later in this section.

basic_string& assign(const basic_string& str)

Returns assign(str, 0, npos).

basic_string& assign(const charT* s, size_type n)

basic_string& assign(const charT* s)

basic_string& assign(size_type n, charT c)

template<class InputIter>

basic_string& assign(InputIter first, InputIter last)

Constructs a temporary string str, passing the arguments to the constructor, and returns assign(str).

const_reference at(size_type n) const

reference at(size_type n)

Returns the character at position n. If n >= size( ), out_of_range is thrown. See also operator[] later in this section.

iterator begin( )

const_iterator begin( ) const

Returns an iterator that points to the first character of the string.

const charT* c_str( ) const

Returns a pointer to a null-terminated (C-style) character array that contains the same characters as the string followed by a terminating null character. The pointer becomes invalid after calling any non-const member function of the string. The typical use of c_str is to interface with C functions that require a null-terminated character string:

std::printf(fmtstr.c_str(  ), value);

See also the data member function.

size_type capacity( ) const

Returns the number of characters allocated for use by the string. The string grows as needed; capacity tells you how much you can put in the string before it must grow again.

void clear( )

Erases all the characters in the string.

int compare(const basic_string& str) const

Returns traits::compare(data( ), str.data( ), len), in which len is the smaller of size( ) and str.size( ).

int compare(size_type pos1, size_type n1, const basic_string& str) const

Constructs a temporary string tmp(*this, pos1, n1), and returns tmp.compare(str).

int compare(const charT* s) const

Constructs a temporary string tmp(s), and returns this->compare(tmp).

int compare(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2) const

int compare(size_type pos1, size_type n1, const charT* s) const

int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const

Constructs two temporary strings tmp1(*this, pos1, n1) and tmp2: tmp2(str, pos2, n2), tmp2(s), or tmp2(s, n2). The function returns tmp1.compare(tmp2).

size_type copy(charT* dst, size_type n, size_type pos = 0) const

Copies up to n characters from the string, starting at position pos, to the character array dst. If pos > size( ), out_of_range is thrown. The number of characters copied, len, is the smaller of n and size( ) - pos. The return value is len.

const charT* data( ) const

Returns a pointer to a character array that has the same character contents as the string. Note that the character array is not null-terminated. If size( ) == 0, data returns a valid, non-null pointer. Do not modify the contents of the data string. The pointer becomes invalid after calling any non-const member function of the string. See also the c_str member function.

bool empty( ) const

Returns true if the string is empty (size( ) == 0).

iterator end( )

const_iterator end( ) const

Returns an iterator that points to one position past the end of the string.

basic_string& erase(size_type pos = 0, size_type n = npos)

Erases characters from the string, starting at position pos and erasing n or size( ) - pos characters, whichever is smaller. If pos > size( ), out_of_range is thrown. The return value is *this. For example:

std::string s("hello, world");
s.erase(9, 1) == "hello, wold"
s.erase(5)    == "hello"

iterator erase(iterator position)

Erases the character at position and returns an iterator that points to the next character (if there is one) or end( ).

iterator erase(iterator first, iterator last)

Erases characters in the range [first, last) and returns an iterator that points to the character that last pointed to (prior to the erasure) or end( ).

size_type find(const basic_string& str, size_type pos = 0) const

size_type find(const charT* s, size_type pos, size_type n) const

size_type find(const charT* s, size_type pos = 0) const

size_type find(charT c, size_type pos = 0) const

Returns the smallest index of a string or character, or npos if the search fails. The search starts at position pos. The string to search for is str or a temporary string tmp constructed as tmp(s, n), tmp(s), or tmp(1, c). In other words, find returns the smallest i such that i >= pos, i + str.size( ) <= size( ), and at(i+j) == str.at(j) for all j in [0, str.size( )). For example:

string("hello").find('l')     == 2
string("hello").find("lo", 2) == 3
string("hello").find("low")   == string::npos

See also rfind later in this section.

size_type find_first_not_of(const basic_string& str, size_type pos = 0) const

Finds the first character at or after position pos that does not appear in str, or npos if every character appears in str. For example:

string("hello").find_first_not_of("aeiou")    == 0
string("hello").find_first_not_of("aeiou", 1) == 2
string("hello").find_first_not_of("aeiou", 6) == string::npos

size_type find_first_not_of(charT c, size_type pos = 0) const

size_type find_first_not_of(const charT* s, size_type pos = 0) const

size_type find_first_not_of(const charT* s, size_type pos, size_type n) const

Constructs a temporary string tmp and returns find_first_not_of(tmp, pos), in which tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).

size_type find_first_of(const basic_string& str, size_type pos = 0) const

Finds the first character at or after position pos that appears in str, or npos if no character appears in str. For example:

string("hello").find_first_of("aeiou")    = 1
string("hello").find_first_of("aeiou", 2) = 4
string("hello").find_first_of("aeiou", 6) = string::npos

size_type find_first_of(charT c, size_type pos = 0) const

size_type find_first_of(const charT* s, size_type pos = 0) const

size_type find_first_of(const charT* s, size_type pos, size_type n) const

Constructs a temporary string tmp and returns find_first_of(tmp, pos), in which tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).

size_type find_last_not_of(const basic_string& str, size_type pos = npos) const

Finds the last character at or before position pos that does not appear in str, or npos if every character appears in str. For example:

string("hello").find_last_not_of("aeiou")    == 3
string("hello").find_last_not_of("aeiou", 1) == 0
string("hello").find_last_not_of("aeiou", 0) == 0

size_type find_last_not_of(charT c, size_type pos = npos) const

size_type find_last_not_of(const charT* s, size_type pos = npos) const

size_type find_last_not_of(const charT* s, size_type pos, size_type n) const

Constructs a temporary string tmp and returns find_last_not_of(tmp, pos), in which tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).

size_type find_last_of(const basic_string& str, size_type pos = npos) const

Finds the last character at or before position pos that appears in str, or npos if no character appears in str. For example:

string("hello").find_last_of("aeiou")    == 4
string("hello").find_last_of("aeiou", 3) == 1
string("hello").find_last_of("aeiou", 0) == string::npos

size_type find_last_of(charT c, size_type pos = npos) const

size_type find_last_of(const charT* s, size_type pos = npos) const

size_type find_last_of(const charT* s, size_type pos, size_type n) const

Constructs a temporary string tmp and returns find_last_of(tmp, pos), in which tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).

allocator_type get_allocator( ) const

Returns the string's allocator object.

basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n)

Inserts a substring of str into the string starting at position pos1. The substring to insert starts at pos2 and extends for up to n characters. If pos1 > size( ) or pos2 > str.size( ), out_of_range is thrown. The number of characters inserted is the smaller of n and str.size( ) - pos2. The return value is *this. For example:

string s("hello");
s.insert(5, ", world")          // s == "hello, world"
s.insert(5, "out there", 3, 42) // s == "hello there, world"

basic_string& insert(size_type pos, const basic_string& str)

basic_string& insert(size_type pos, const charT* s, size_type n)

basic_string& insert(size_type pos, const charT* s)

basic_string& insert(size_type pos, size_type n, charT c)

Returns insert(pos, str, 0, npos), in which the last three versions construct a temporary string tmp as tmp(s, n), tmp(s), or tmp(n, c), and then returns insert(pos, tmp, o, npos).

iterator insert(iterator p, charT c)

void insert(iterator p, size_type n, charT c)

template<class InputIter>

void insert(iterator p, InputIter first, InputIter last)

Inserts text before the character that p points to. The first version inserts the character c and returns an iterator that points to c, the second version inserts n copies of the character c, and the third version inserts the temporary string constructed from the arguments (first, last). If InputIter is an integral type, the temporary string contains static_cast<size_type>(first) copies of the character static_cast<value_type>(last).

size_type length( ) const

Returns size( ).

size_type max_size( ) const

Returns the size of the largest possible string.

const_reference operator[](size_type pos) const

reference operator[](size_type pos)

Returns the character at position pos. If pos == size( ), the return value is charT( ), that is, a null character. The behavior is undefined if pos > size( ).

basic_string& operator=(const basic_string& str)

If *this and str are the same object, the assignment operator does nothing and returns *this. If they are different objects, the operator replaces the current string contents with the contents of str and returns *this.

basic_string& operator=(const charT* s)

basic_string& operator=(charT c)

Constructs a temporary string, tmp(s) or tmp(1, c), and assigns *this = tmp. The return value is *this.

basic_string& operator+=(const basic_string& str)

basic_string& operator+=(const charT* s)

basic_string& operator+=(charT c)

Calls append with the same arguments and returns *this.

void push_back(charT c)

Appends c to the end of the string. Its existence lets you use basic_string with a back_insert_iterator.

reverse_iterator rbegin( )

const_reverse_iterator rbegin( ) const

Returns a reverse iterator that points to the last character of the string.

reverse_iterator rend( )

const_reverse_iterator rend( ) const

Returns a reverse iterator that points to one position before the first character of the string.

basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2)

Erases a substring and inserts another string in its place. The string to erase starts at pos1 and extends for up to n1 characters (the smaller of n1 and size( ) - pos1). The string to insert is a substring of str, starting at pos2 and extending for up to n2 characters (the smaller of n2 and str.size( ) - pos2). The replacement string is inserted at pos1. If pos1 > size( ) or pos2 > str.size( ), out_of_range is thrown. The return value is *this.

basic_string& replace(size_type pos, size_type n1, const basic_string& str)

basic_string& replace(size_type pos, size_type n1, const charT* str)

basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2)

basic_string& replace(size_type pos, size_type n1, size_type n2, charT c)

Returns replace(pos, n1, tmp, 0, npos), in which tmp is a temporary string constructed as tmp(str), tmp(s, n2), or tmp(n2, c). For example:

std::string s("hello");
s.replace(1, 4, "appy")                   s=="happy"
s.replace(5, 0, "your birthday !", 4, 10) s=="happy birthday"
s.replace(1, 1, 1, 'i')                   s=="hippy birthday"

basic_string& replace(iterator first, iterator last, const basic_string& str)

Erases the text in the range [first, last) and inserts str at the position first pointed to. The return value is *this.

basic_string& replace(iterator first, iterator last, const charT* s, size_type n)

basic_string& replace(iterator first, iterator last, const charT* s)

basic_string& replace(iterator first, iterator last, size_type n, charT c)

template<class InputIterator>

basic_string& replace(iterator first, iterator last, InputIterator i1, InputIterator i2)

Returns replace(first, last, tmp), in which tmp is a temporary string constructed as tmp(s, n), tmp(s), tmp(n, c), or tmp(i1, i2).

void reserve(size_type res_arg = 0)

Ensures that the capacity( ) is at least as large as res_arg. Call reserve to avoid the need to reallocate the string data repeatedly when you know the string will grow by small increments to a large size. Note that size( ) does not change.

void resize(size_type n, charT c)

void resize(size_type n)

Changes the size of the string to n characters. If n <= size( ), the new string has the first n characters of the original string. If n > size( ), the new string has n - size( ) copies of c appended to the end. The second version returns resize(n, charT( )).

size_type rfind(const basic_string& str, size_type pos = npos) const

size_type rfind(const charT* s, size_type pos, size_type n) const

size_type rfind(const charT* s, size_type pos = npos) const

size_type rfind(charT c, size_type pos = npos) const

Returns the largest index at or before pos of a string or character or npos if the search fails. The string to search for is str or a temporary string tmp constructed as tmp(s, n), tmp(s), or tmp(1, c). In other words, rfind returns the largest i such that i <= pos, i + str.size( ) <= size( ), and at(i+j) == str.at(j) for all j in [0, str.size( )). (See also find, earlier in this section.) For example:

string("hello").rfind('l')     == 3
string("hello").rfind("lo", 2) == string::npos
string("hello").rfind("low")   == string::npos

size_type size( ) const

Returns the number of characters (not bytes) in the string.

basic_string substr(size_type pos = 0, size_type n = npos) const

Returns a substring that starts at position pos and extends for up to n characters (the smaller of n and size( ) - pos). If pos > size( ), out_of_range is thrown.

void swap(basic_string& str)

Exchanges string contents with str in constant time.

See Also

char_traits class template, <sstream>, <vector>

template<typename charT> struct char_traits;

The char_traits template describes a character type and provides basic functions for comparing, converting, and copying character values and arrays. (See the char_traits<char> and char_traits<wchar_t> specializations later in this section for details.) If you create a custom character type, you should specialize char_traits<> or define your own traits class, which you can provide to basic_string and other templates as the traits template parameter. Your traits class should define the same members that char_traits<char> defines. See Chapter 8 for an example.

See Also

char_traits<char> class, char_traits<wchar_t> class

template<> struct char_traits<char> {
  typedef char char_type;
  typedef int int_type;
  typedef streamoff off_type;
  typedef streampos pos_type;
  typedef mbstate_t state_type;
   
  static void assign(char_type& dst, const char_type& src);
  static char_type* assign(char_type* dst, size_t n, const char_type& c);
  static bool eq(const char_type& c1, const char_type& c2);
  static bool lt(const char_type& c1, const char_type& c2);
  static size_t length(const char_type* str);
  static int compare(const char_type* s1, const char_type* s2, size_t n);
  static const char_type* find(const char_type* str, size_t n, 
                               const char_type& c);
  static char_type* copy(char_type* dst, char_type* src, size_t n);
  static char_type* move(char_type* dst, char_type* src, size_t n);
  static bool eq_int_type(const int_type& i1, const int_type& i2);
  static int_type eof(  );
  static int_type not_eof(const int_type& i);
  static char_type to_char_type(const int_type& i);
  static int_type to_int_type(const char_type& c);
};

The char_traits<char> class specializes char_traits for narrow characters. The streamoff type is implementation-defined. The streampos type is defined as fpos<mbstate_t> in <iosfwd>. The character traits are defined for the type char and have the same meaning in all locales. The other types are self-explanatory. The following are the member functions:

static void assign(char_type& dst, const char_type& src)

Assigns dst = src.

static char_type* assign(char_type* dst, size_t n, const char_type& c)

Fills dst with n copies of c, that is, dst[0] through dst[n-1] = c.

static int compare(const char_type* s1, const char_type* s2, size_t n)

Compares the first n characters of the arrays s1 and s2, returning an integer result:

• 0 if eq(s1[i], s2[i]) is true for all i in [0, n)

• Negative if eq(s1[i], s2[i]) is true for all i in [0, k), and lt(s1[k], s2[k]) is true for some k in [0, n)

• Positive otherwise

static char_type* copy(char_type* dst, char_type* src, size_t n)

Copies n characters from src to dst. The arrays src and dst must not overlap.

static int_type eof( )

Returns the end-of-file marker, EOF (in <cstdio>). The end-of-file marker is different from all characters, that is, for all character values c, eq_int_type(eof( ), to_int_type(c)) is false.

static bool eq(const char_type& c1, const char_type& c2)

Returns c1 == c2.

static bool eq_int_type(const int_type& i1, const int_type& i2)

Returns true if i1 is the same as i2. Specifically, for all character values c1 and c2, eq(c1, c2) has the same value as eq_int_type(to_int_type(c1), to_int_type(c2)). Also, eof( ) is always equal to eof( ) and not equal to to_int_type(c) for any character c. The value is unspecified for any other integer values.

static const char_type* find(const char_type* str, size_t n, const char_type& c)

Returns a pointer p to the first character in str such that eq(*p, c) is true. It returns a null pointer if there is no such character in the first n characters of str.

static size_t length(const char_type* str)

Returns the length of the null-terminated character string str, that is, it returns the smallest i such that eq(str[i], charT( )) is true.

static bool lt(const char_type& c1, const char_type& c2)

Returns c1 < c2.

static char_type* move(char_type* dst, char_type* src, size_t n)

Copies n characters from src to dst. The arrays src and dst are allowed to overlap.

static int_type not_eof(const int_type& i)

Returns a value that is guaranteed to be different from eof( ). If i is not eof( ), i is returned. Otherwise, some other value is returned.

static char_type to_char_type(const int_type& i)

Converts i to its equivalent character value (for which eq_int_type(i, to_int_type(to_char_type(i))) is true). If i is not equivalent to any character, the behavior is unspecified.

static int_type to_int_type(const char_type& c)

Converts c to its equivalent integer representation.

See Also

char_traits<wchar_t> class, mbstate_t in <cwchar>, fpos in <ios>, <iosfwd>

template<> struct char_traits<wchar_t> {
  typedef wchar_t char_type;
  typedef wint_t int_type;
  typedef streamoff off_type;
  typedef wstreampos pos_type;
  typedef mbstate_t state_type;
   
  static void assign(char_type& dst, const char_type& src);
  static char_type* assign(char_type* dst, size_t n, const char_type& c);
  static bool eq(const char_type& c1, const char_type& c2);
  static bool lt(const char_type& c1, const char_type& c2);
  static size_t length(const char_type* str);
  static int compare(const char_type* s1, const char_type* s2, size_t n);
  static const char_type* find(const char_type* str, size_t n, 
                               const char_type& c);
  static char_type* copy(char_type* dst, char_type* src, size_t n);
  static char_type* move(char_type* dst, char_type* src, size_t n);
  static bool eq_int_type(const int_type& i1, const int_type& i2);
  static int_type eof(  );
  static int_type not_eof(const int_type& i);
  static char_type to_char_type(const int_type& i);
  static int_type to_int_type(const char_type& c);
};

The char_traits<wchar_t> class specializes char_traits for wide characters. The wstreamoff type is implementation-defined. The wstreampos type is defined as fpos<mbstate_t> in <iosfwd>. The other types are self-explanatory. The character traits are defined for the type wchar_t and have the same meaning in all locales.

See char_traits<char> earlier in this section for a description of the member functions. The eof( ) function returns WEOF (in <cwchar>).

See Also

char_traits<char> class, mbstate_t in <cwchar>, fpos in <ios>, <iosfwd>

template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>& getline(basic_istream<charT,traits>& in, 
                                       basic_string<charT,traits,Allocator>& str,
                                       charT delim);
// istream& getline(istream& in, string& str, char delim);
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>& getline(basic_istream<charT,traits>& in,
                                       basic_string<charT,traits,Allocator>& 
                                       str);
// istream& getline(istream& in, string& str);

The getline function template reads a line of text from an input stream into the string str. It starts by creating a basic_istream::sentry(in, true) object. If the sentry object evaluates to true, getline erases str then reads characters from in and appends them to str until end-of-file is reached or delim is read. (The delim character is read from the stream but not appended to the string.) Reading also stops if max_size( ) characters have been stored in the string, in which case ios_base::failbit is set. If no characters are read from the stream, ios_base::failbit is set. The return value is in.

The second form of getline uses a newline as the delimiter, that is, it returns getline(in, str, in.widen('\n')).

See Also

operator>> function template, basic_istream in <istream>, basic_istream::sentry in <istream>

template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator> operator+(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// string& operator+(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator> operator+(const charT* a,
  const basic_string<charT,traits,Allocator>& b);
// string& operator+(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator> operator+(
   const basic_string<charT,traits,Allocator>& a, const charT* b);
// string& operator+(const string& a, const char* b);
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator> operator+(
    const basic_string<charT,traits,Allocator>& a, charT b);
// string& operator+(const string& a, char b);

The + operator concatenates two strings and returns the result. It constructs a new string as a copy of a, then calls a.append(b) and returns the copy.

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  bool operator==(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator==(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator==(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator==(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator==(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator==(const string& a, conat char* b);

The == operator compares two strings for equality or compares a string and a null-terminated character array. It returns a.compare(b) == 0, converting a or b from a character array to a string, as needed.

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  bool operator!=(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator!=(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator!=(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator!=(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator!=(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator!=(const string& a, conat char* b);

The != operator compares two strings for inequality or compares a string and a null-terminated character array. It returns !(a == b).

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  bool operator<(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator<(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator<(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator<(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator<(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator<(const string& a, conat char* b);

The < operator compares two strings or compares a string and a null-terminated character array. It returns a.compare(b) < 0, converting a or b from a character array to a string, as needed.

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  bool operator<=(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator<=(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator<=(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator<=(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator<=(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator<=(const string& a, conat char* b);

The <= operator compares two strings or compares a string and a null-terminated character array. It returns a.compare(b) <= 0, converting a or b from a character array to a string, as needed.

See Also

basic_string class template,

template<class charT, class traits, class Allocator>
  bool operator>(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator>(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator>(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator>(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator>(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator>(const string& a, conat char* b);

The > operator compares two strings or compares a string and a null-terminated character array. It returns a.compare(b) > 0, converting a or b from a character array to a string, as needed.

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  bool operator>=(
    const basic_string<charT,traits,Allocator>& a,
    const basic_string<charT,traits,Allocator>& b);
// bool operator>=(const string& a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator>=(const charT* a, const basic_string<charT,traits,Allocator>& b);
// bool operator>=(const char* a, const string& b);
template<class charT, class traits, class Allocator>
  bool operator>=(const basic_string<charT,traits,Allocator>& a, const charT* b);
// bool operator>=(const string& a, conat char* b);

The >= operator compares two strings or compares a string and a null-terminated character array. It returns a.compare(b) >= 0, converting a or b from a character array to a string, as needed.

See Also

basic_string class template

template<class charT, class traits, class Allocator>
  basic_ostream<charT, traits>& operator<<(
    basic_ostream<charT, traits>& out, 
    const basic_string<charT,traits,Allocator>& str);
// ostream& operator<<(ostream& out, const string& str);

The << operator writes the string str to out. Like any formatted output function, it first creates a sentry object, and if the sentry evaluates to true, it writes the string contents by calling out.rdbuf( )->sputn. If str.size( ) < out.width( ), fill characters are added to achieve the desired width. If sputn fails, ios_base::failbit is set.

See Also

ios_base in <ios>, basic_ostream in <ostream>, basic_ostream::sentry in <ostream>

template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>& operator>>(
    basic_istream<charT,traits>& in, 
    basic_string<charT,traits,Allocator>& str);
// istream&  operator>>(istream& in,  string& str);

The >> operator reads a string from in and stores the string in str. Like any other formatted input operator, it first creates a sentry object basic_istream::sentry(in), and if the sentry evaluates to true, it erases str and then reads characters from in and appends the characters to str. If in.width( ) is greater than 0, no more than in.width( ) characters are read from in; otherwise, up to max_size( ) characters are read. Reading also stops at end-of-file or when reading a whitespace character (isspace is true for locale in.getloc( )). The whitespace character is left in the input stream. The return value is in.

See Also

getline function template, basic_istream in <istream>, basic_istream::sentry in <istream>

typedef basic_string<char> string;

The string class specializes basic_string for type char.

See Also

basic_string class template, wstring class

template<class charT, class traits, class Allocator>
  void swap(basic_string<charT,traits,Allocator>& a,
            basic_string<charT,traits,Allocator>& b);
// void swap(string& a, string& b);

The swap function template specialization is equivalent to calling a.swap(b).

See Also

swap in <algorithm>

typedef basic_string<wchar_t> wstring;

The wstring class specializes basic_string for type wchar_t.

See Also

basic_string class template, string class