Name

basic_string class template — Base class for string types

Synopsis

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.

  • You 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.