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

Chapter 1. Language Basics 1.1 Compilation Steps 1.2 Tokens 1.3 Comments 1.4 Character Sets 1.5 Alternative Tokens 1.6 Trigraphs Chapter 2. Declarations 2.1 Declarations and Definitions 2.2 Scope 2.3 Name Lookup 2.4 Linkage 2.5 Type Declarations 2.6 Object Declarations 2.7 Namespaces Chapter 3. Expressions 3.1 Lvalues and Rvalues 3.2 Type Conversions 3.3 Constant Expressions 3.4 Expression Evaluation 3.5 Expression Rules Chapter 4. Statements 4.1 Expression Statements 4.2 Declarations 4.3 Compound Statements 4.4 Selections 4.5 Loops 4.6 Control Statements 4.7 Handling Exceptions Chapter 5. Functions 5.1 Function Declarations 5.2 Function Definitions 5.3 Function Overloading 5.4 Operator Overloading 5.5 The main Function Chapter 6. Classes 6.1 Class Definitions 6.2 Data Members 6.3 Member Functions 6.4 Inheritance 6.5 Access Specifiers 6.6 Friends 6.7 Nested Types Chapter 7. Templates 7.1 Overview of Templates 7.2 Template Declarations 7.3 Function Templates 7.4 Class Templates 7.5 Specialization 7.6 Partial Specialization 7.7 Instantiation 7.8 Name Lookup 7.9 Tricks with Templates 7.10 Compiling Templates Chapter 8. Standard Library 8.1 Overview of the Standard Library 8.2 C Library Wrappers 8.3 Wide and Multibyte Characters 8.4 Traits and Policies 8.5 Allocators 8.6 Numerics Chapter 9. Input and Output 9.1 Introduction to I/O Streams 9.2 Text I/O 9.3 Binary I/O 9.4 Stream Buffers 9.5 Manipulators 9.6 Errors and Exceptions Chapter 10. Containers, Iterators, and Algorithms 10.1 Containers 10.2 Iterators 10.3 Algorithms Chapter 11. Preprocessor Reference # operator and directive ## operator #define directive defined operator #elif directive #else directive #endif directive #error directive #if directive #ifdef directive #ifndef directive #include directive #line directive #pragma directive #undef directive Chapter 12. Language Reference and operator and_eq operator asm definition auto storage class bitand operator bitor operator bool type break statement case keyword catch keyword char type class keyword compl operator const qualifier const_cast operator continue statement declaration declarator default keyword delete operator do statement double type dynamic_cast operator else keyword enum keyword explicit specifier export specifier expression extern storage class false literal float type for statement friend specifier function goto statement identifier if statement inline specifier int type long type mutable specifier namespace keyword new operator not operator not_eq operator operator keyword or operator or_eq operator private access specifier protected access specifier public access specifier register storage class reinterpret_cast operator return statement short type signed specifier sizeof operator statement static storage class static_cast operator struct keyword switch statement template keyword this keyword throw operator true literal try statement type typedef keyword typeid operator typename keyword unsigned specifier union keyword using keyword virtual specifier void keyword volatile qualifier wchar_t type while statement xor operator xor_eq operator Chapter 13. Library Reference 13.1 <algorithm> 13.2 <bitset> 13.3 <cassert> 13.4 <cctype> 13.5 <cerrno> 13.6 <cfloat> 13.7 <ciso646> 13.8 <climits> 13.9 <clocale> 13.10 <cmath> 13.11 <complex> 13.12 <csetjmp> 13.13 <csignal> 13.14 <cstdarg> 13.15 <cstddef> 13.16 <cstdio> 13.17 <cstdlib> 13.18 <cstring> 13.19 <ctime> 13.20 <cwchar> 13.21 <cwctype> 13.22 <deque> 13.23 <exception> 13.24 <fstream> 13.25 <functional> 13.26 <iomanip> 13.27 <ios> 13.28 <iosfwd> 13.29 <iostream> 13.30 <istream> 13.31 <iterator> 13.32 <limits> 13.33 <list> 13.34 <locale> 13.35 <map> 13.36 <memory> 13.37 <new> 13.38 <numeric> 13.39 <ostream> 13.40 <queue> 13.41 <set> 13.42 <sstream> 13.43 <stack> 13.44 <stdexcept> 13.45 <streambuf> 13.46 <string> 13.47 <strstream> 13.48 <typeinfo> 13.49 <utility> 13.50 <valarray> 13.51 <vector> Appendix A. Compiler Extensions A.1 Borland C++ Builder and Kylix A.2 GNU Compiler Collection A.3 Microsoft Visual C++ Appendix B. Projects B.1 Blitz++ B.2 Boost B.3 STLport Glossary A-Z