Draft 2002-08-19

<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 offer greater ease-of-use and safety than C-style character arrays. Another important class template is char_traits, which describes a character type and is used throughout the standard library.

Example 13-39 shows a function that classifies a string as an identifier, integer, floating point, or other.

Example 13-39: Classifying a string.

#include <iostream>
#include <string>

enum kind { empty, ident, integer, floatingpt, error };

kind classify(const std::string& s)
{
  using std::string;
  const std::string lower("abcdefghijklmnopqrstuvwxyz");
  const std::string upper("ABCDEFGHIJKLMNOPQRSTUVWXYZ");
  const std::string letters = lower + upper + '_';
  const std::string digits("0123456789");
  const std::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;
}

basic_string class template

Base class for string types

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;
 // 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 is a sequence container of characters that 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. Strings are therefore much easier to use, and offer greater safety (see the at member function), while still offering ease-of-use with many functions taking 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.

Many of the member function 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 classes uses an allocator object for memory allocation, which can throw an exception (such as bad_alloc) almost any time the string is modified.

Following are the members of basic_string. Several small examples appear throughout this section, with the relevant member function.

explicit basic_string (const Alloc& a = Alloc())
Constructs an empty string.
basi c _string (const basic_string& str)
Constructs a string that is a copy of str.
basi c _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 traits::length(s) characters from s.
basi c _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:
basic_string& append (const basic_string& str, size_type pos, size_type n)
Adds 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, plus the terminating null character. The pointer becomes invalid after calling any non-const member of the string. The typical use of c_str is to interface with C functions that require a null-terminated character string, e.g.,
std::printf(fmtstr.c_str(), value);
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), where 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). It 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 pointer. Do not modify the contents of the data string.
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 character 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 or end().
iterator erase (iterator first, iterator last)
Erases characters in the range [first, last) and returns an iterator that points to the character after last 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 not found. 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 and i + str.size() <= size() and traits::eq(at(i+j), str.at(j)) for all j in [0, str.size()).
See also rfind, later in this section. For example,
string("hello").find('l')     == 2
string("hello").find("lo", 2) == 3
string("hello").find("low")   == string::npos
size_type fi nd _first_not_ o f (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 fi nd _first_not_of (charT c, size_type pos = 0) const
size_type fin d _first_not_ o f (const charT* s, size_type pos = 0) const
size_type fi nd _first_not_ o f (const charT* s, size_type pos, size_type n) const
Constructs a temporary string tmp and returns find_first_not_of(tmp, pos), where tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).
size_type fi nd _first_ o f (const basic_string& str, size_type pos = 0) const
Finds the first character at or after position pos that does 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 f ind _first_of (charT c, size_type pos = 0) const
size_type fin d _first_of (const charT* s, size_type pos = 0) const
size_type fin d _first_of (const charT* s, size_type pos, size_type n) const
Constructs a temporary string tmp and returns find_first_of(tmp, pos), where tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).
size_type fin d _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 fin d _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), where 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 does 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 fi nd _last_of (charT c, size_type pos = npos) const
size_type fin d _last_of (const charT* s, size_type pos = npos) const
size_type fi nd _last_of (const charT* s, size_type pos, size_type n) const
Constructs a temporary string tmp and returns find_last_of(tmp, pos), where tmp is constructed as tmp(1, c), tmp(s), or tmp(s, n).
allocator_type ge t _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), where the last three versions construct the temporary string str as str(s, n), str(s), or str(n, 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)
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).
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 operato r [] (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& opera tor = (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& opera tor += (const basic_string& str)
basic_string& oper ator += (const charT* s)
basic_string& opera tor += (charT c)
Calls append with the same arguments and returns *this.
void pus h _back (charT c)
Appends c to the end of the string. Its existence lets you use basic_string with a push_back_iterator.
reverse_iterator rbegin ()
const_reverse_iterator rbegin () const
Returns a reverse iterator that points to the end of the string.
reverse_iterator rend ()
const_reverse_iterator rend () const
Returns a reverse iterator that points to the beginning 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 returns 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), where 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 where first pointed. 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), where 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 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 not found. 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 and i + str.size() <= size() and traits::eq(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>

char_traits class template

Base class for character traits

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.

See Also

char_traits<char> class, char_traits<wchar_t> class

char_traits<char> class

Character traits of char type

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(charT& dst, const charT& src);
  static charT* assign(charT* dst, size_t n, const charT& c);
  static bool eq(const charT& c1, const charT& c2);
  static bool lt(const charT& c1, const charT& c2);
  static size_t length(const charT* str);
  static int compare(const charT* s1, const charT* s2,
                     size_t n);
  static const charT* find(const charT* str, size_t n,
                           const charT& c);
  static charT* copy(charT* dst, charT* src, size_t n);
  static charT* move(charT* dst, charT* 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 and streampos types are implementation-defined. The other typedefs are self-explanatory. Following are the members:

static void assign (charT& dst, const charT& src)
Assigns dst = src.
static charT* assign (charT* dst, size_t n, const charT& c)
Fills dst with n copies of c, that is, dst[0] through dst[n-1] = c.
static int compare (const charT* s1, const charT* s2,
size_t n)
Compares the first n characters of the arrays s1 and s2, returning an integer result as follows:
static charT* copy (charT* dst, charT* 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. 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 charT& c1, const charT& c2)
Returns c1 == c2.
static bool eq_int_ t ype (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 charT* find (const charT* str, size_t n,
const charT& 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 charT* 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 charT& c1, const charT& c2)
Returns c1 < c2.
static charT* move (charT* dst, charT* 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 (where 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_ i n t _type (const char_type& c)
Converts c to its equivalent integer representation.

See Also

mbstate_t in <cwchar>

char_traits<wchar_t> class

Character traits of wchar_t type

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(charT& dst, const charT& src);
  static charT* assign(charT* dst, size_t n, const charT& c);
  static bool eq(const charT& c1, const charT& c2);
  static bool lt(const charT& c1, const charT& c2);
  static size_t length(const charT* str);
  static int compare(const charT* s1, const charT* s2,
                     size_t n);
  static const charT* find(const charT* str, size_t n,
                           const charT& c);
  static charT* copy(charT* dst, charT* src, size_t n);
  static charT* move(charT* dst, charT* 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 and wstreampos types are implementation-defined. The other typedefs are self-explanatory.

See char_traits<char>, earlier in this section, for a description of the member functions.

See Also

char_traits<char> class, mbstate_t in <cwchar>

getline function template

Read a line into a string

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

Reads a line of text from an input stream into the string str. It starts by creating an basic_istream::sentry(in, true) object. If the sentry object is okay, getline erases str then reads characters from in and appends them to str until reaching end of file or until 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, basic_istream::sentry in <istream>

operator+ function template

Concatenate two strings

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

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

operator== function template

Compare strings for equality

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

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::compare, equals in <algorithm>

operator!= function template

Compare strings for inequality

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

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

See Also

basic_string::compare, mismatch in <algorithm>

operator< function template

Compare strings for less than

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

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::compare, lexicographical_compare in <algorithm>

operator<= function template

Compare strings for less than or equal

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

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::compare, lexicographical_compare in <algorithm>

operator> function template

Compare strings for greater than

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

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::compare, lexicographical_compare in <algorithm>

operator>= function template

Compare strings for greater than or equal

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

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.

operator<< function template

Write a string to an ostream

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

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

See Also

basic_ostream, basic_ostream::sentry in <ostream>

operator>> function template

Read a string from an istream

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

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 is okay, erases str then reads characters from in and appends the characters to str. If in.width() is greater than zero, 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 white space character (isspace is true for locale in.getloc()). The white space character is left in the input stream. The return value is in.

See Also

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

string class

Narrow character string class

typedef basic_string<char> string;

The string class specializes basic_string for type char.

See Also

basic_string class template, wstring class

swap function template

Swap two strings

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 calls a.swap(b).

wstring class

Wide character string class

typedef basic_string<wchar_t> wstring;

The wstring class specializes basic_string for type wchar_t.

See Also

basic_string class template, string class