21 - Strings library [lib.strings]

-1- This clause describes components for manipulating sequences of ``characters,'' where characters may be of any POD (basic.types) type. In this clause such types are called char-like types, and objects of char-like types are called char-like objects or simply ``characters.''

-2- The following subclauses describe a character traits class, a string class, and null-terminated sequence utilities, as summarized in Table ??:

21.1 - Character traits [lib.char.traits]

-1- This subclause defines requirements on classes representing character traits, and defines a class template char_traits<charT>, along with two specializations, char_traits<char> and char_traits<wchar_t>, that satisfy those requirements.

-2- Most classes specified in clauses lib.string.classes and lib.input.output need a set of related types and functions to complete the definition of their semantics. These types and functions are provided as a set of member typedefs and functions in the template parameter `traits' used by each such template. This subclause defines the semantics guaranteed by these members.

-3- To specialize those templates to generate a string or iostream class to handle a particular character container type CharT, that and its related character traits class Traits are passed as a pair of parameters to the string or iostream template as formal parameters charT and traits. Traits::char_type shall be the same as CharT.

-4- This subclause specifies a struct template, char_traits<charT>, and two explicit specializations of it, char_traits<char> and char_traits<wchar_t>, all of which appear in the header <string> and satisfy the requirements below.

21.1.1 - Character traits requirements [lib.char.traits.require]

-1- In Table ??, X denotes a Traits class defining types and functions for the character container type CharT; c and d denote values of type CharT; p and q denote values of type const CharT*; s denotes a value of type CharT*; n, i and j denote values of type size_t; e and f denote values of type X::int_type; pos denotes a value of type X::pos_type; and state denotes a value of type X::state_type. Operations on Traits shall not throw exceptions.

-2- The struct template

template<class charT> struct char_traits;

-3- In the following subclauses, the token charT represents the parameter of the traits template.

21.1.2 - traits typedefs [lib.char.traits.typedefs]

-1- The type char_type is used to refer to the character container type in the implementation of the library classes defined in lib.string.classes and clause lib.input.output.

typedef INT_T int_type;

-2- Requires: For a certain character container type char_type, a related container type INT_T shall be a type or class which can represent all of the valid characters converted from the corresponding char_type values, as well as an end-of-file value, eof(). The type int_type represents a character container type which can hold end-of-file to be used as a return type of the iostream class member functions.*

[Footnote: If eof() can be held in char_type then some iostreams operations may give surprising results. --- end foonote]

-3- Requires: Requirements for off_type and pos_type are described in lib.iostreams.limits.pos.

typedef STATE_T state_type;

-4- Requires: state_type shall meet the requirements of CopyConstructible types (lib.copyconstructible).

21.1.3 - char_traits specializations [lib.char.traits.specializations]

namespace std {
  template<> struct char_traits<char>;
  template<> struct char_traits<wchar_t>;
}

-1- The header <string> declares two structs that are specializations of the template struct char_traits.

-2- The struct char_traits<char> is the char type specialization of the template struct char_traits, which contains all of the types and functions necessary to ensure the behavior of the classes in lib.string.classes and clause lib.input.output.

-3- The types and static member functions are described in detail in lib.char.traits.require.

21.1.3.1 - struct char_traits<char> [lib.char.traits.specializations.char]

namespace std {
  template<>
  struct char_traits<char> {
    typedef char        char_type;
    typedef int         int_type;
    typedef streamoff   off_type;
    typedef streampos   pos_type;
    typedef mbstate_t   state_type;

    static void assign(char_type& c1, const char_type& c2);
    static bool eq(const char_type& c1, const char_type& c2);
    static bool lt(const char_type& c1, const char_type& c2);

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
				 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static int_type not_eof(const int_type& c);
    static char_type to_char_type(const int_type& c);
    static int_type to_int_type(const char_type& c);
    static bool eq_int_type(const int_type& c1, const int_type& c2);
    static int_type eof();
  };
}

-1- The header <string> (lib.string.classes) declares a specialization of the template struct char_traits for char. It is for narrow-oriented iostream classes.

-2- The defined types for int_type, pos_type, off_type, and state_type are int, streampos, streamoff, and mbstate_t respectively.

-3- The type streampos is an implementation-defined type that satisfies the requirements for POS_T in lib.char.traits.typedefs.

-4- The type streamoff is an implementation-defined type that satisfies the requirements for OFF_T in lib.char.traits.typedefs.

-5- The type mbstate_t is defined in <cwchar> and can represent any of the conversion states possible to occur in an implementation-defined set of supported multibyte character encoding rules.

-6- The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and < respectively.

-7- The member eof() returns EOF.

21.1.3.2 - struct char_traits<wchar_t> [lib.char.traits.specializations.wchar.t]

namespace std {
  template<>
  struct char_traits<wchar_t> {
    typedef wchar_t      char_type;
    typedef wint_t       int_type;
    typedef streamoff   off_type;
    typedef wstreampos   pos_type;
    typedef mbstate_t    state_type;

    static void assign(char_type& c1, const char_type& c2);
    static bool eq(const char_type& c1, const char_type& c2);
    static bool lt(const char_type& c1, const char_type& c2);

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
				 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static int_type not_eof(const int_type& c);
    static char_type to_char_type(const int_type& c);
    static int_type to_int_type(const char_type& c);
    static bool eq_int_type(const int_type& c1, const int_type& c2);
    static int_type eof();
  };
}

-1- The defined types for int_type, pos_type, and state_type are wint_t, wstreampos, and mbstate_t respectively.

-2- The type wstreampos is an implementation-defined type that satisfies the requirements for POS_T in lib.char.traits.typedefs.

-3- The types streampos and wstreampos may be different if the implementation supports no shift encoding in narrow-oriented iostreams but supports one or more shift encodings in wide-oriented streams.

-4- The type mbstate_t is defined in <cwchar> and can represent any of the conversion states possible to occur in an implementation-defined set of supported multibyte character encoding rules.

-5- The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and < respectively.

-6- The member eof() returns WEOF.

21.2 - String classes [lib.string.classes]

-1- The header <string> defines a basic string class template and its traits that can handle all char-like (clause lib.strings) template arguments with several function signatures for manipulating varying-length sequences of char-like objects.

-2- The header <string> also defines two specific template classes string and wstring and their special traits.

Header <string> synopsis

namespace std {
  //  lib.char.traits, character traits:
  template<class charT>
    struct char_traits;
  template <> struct char_traits<char>;
  template <> struct char_traits<wchar_t>;

  //  lib.basic.string, basic_string:
  template<class charT, class traits = char_traits<charT>,
	   class Allocator = allocator<charT> >
    class basic_string;

  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs,
		const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const charT* lhs,
		const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(charT lhs, const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs,
		const charT* rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs, charT rhs);

  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator==(const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);

  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator< (const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);

  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator<=(const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
		    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
		    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const charT* lhs,
		    const basic_string<charT,traits,Allocator>& rhs);

  //  lib.string.special:
  template<class charT, class traits, class Allocator>
     void swap(basic_string<charT,traits,Allocator>& lhs,
	       basic_string<charT,traits,Allocator>& rhs);

  template<class charT, class traits, class Allocator>
   basic_istream<charT,traits>&
    operator>>(basic_istream<charT,traits>& is,
	       basic_string<charT,traits,Allocator>& str);
  template<class charT, class traits, class Allocator>
   basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>& os,
	       const basic_string<charT,traits,Allocator>& str);
  template<class charT, class traits, class Allocator>
   basic_istream<charT,traits>&
     getline(basic_istream<charT,traits>& is,
	     basic_string<charT,traits,Allocator>& str,
	     charT  delim);
  template<class charT, class traits, class Allocator>
   basic_istream<charT,traits>&
     getline(basic_istream<charT,traits>& is,
	     basic_string<charT,traits,Allocator>& str);

  typedef basic_string<char> string;
  typedef basic_string<wchar_t> wstring;
}

-1- For a char-like type charT, the template class basic_string describes objects that can store a sequence consisting of a varying number of arbitrary char-like objects (clause lib.strings). The first element of the sequence is at position zero. Such a sequence is also called a ``string'' if the given char-like type is clear from context. In the rest of this clause, charT denotes such a given char-like type. Storage for the string is allocated and freed as necessary by the member functions of class basic_string, via the Allocator class passed as template parameter. Allocator::value_type shall be the same as charT.

-2- The template class basic_string conforms to the requirements of a Sequence, as specified in (lib.sequence.reqmts). Additionally, because the iterators supported by basic_string are random access iterators (lib.random.access.iterators), basic_string conforms to the the requirements of a Reversible Container, as specified in (lib.container.requirements).

-3- In all cases, size() <= capacity().

-4- The functions described in this clause can report two kinds of errors, each associated with a distinct exception:

• a length error is associated with exceptions of type length_error (lib.length.error);

• an out-of-range error is associated with exceptions of type out_of_range (lib.out.of.range).

-5- References, pointers, and iterators referring to the elements of a basic_string sequence may be invalidated by the following uses of that basic_string object:

• As an argument to non-member functions swap() (lib.string.special), operator>>() (lib.string.io), and getline() (lib.string.io).

• As an argument to basic_string::swap().

• Calling data() and c_str() member functions.

• Calling non-const member functions, except operator[](), at(), begin(), rbegin(), end(), and rend().

• Subsequent to any of the above uses except the forms of insert() and erase() which return iterators, the first call to non-const member functions operator[](), at(), begin(), rbegin(), end(), or rend().

-6- [Note: These rules are formulated to allow, but not require, a reference counted implemenation. A reference counted implementation must have the same semantics as a non-reference counted implementation. [Example:

string s1("abc");

string::iterator i = s1.begin();
string s2 = s1;

*i = 'a';                       //  Must modify only  s1

namespace std {
  template<class charT, class traits = char_traits<charT>,
	   class Allocator = allocator<charT> >
  class basic_string {
  public:
    //  types:
    typedef          traits                     traits_type;
    typedef typename traits::char_type          value_type;
    typedef          Allocator                  allocator_type;
    typedef typename Allocator::size_type       size_type;
    typedef typename Allocator::difference_type difference_type;

    typedef typename Allocator::reference       reference;
    typedef typename Allocator::const_reference const_reference;
    typedef typename Allocator::pointer         pointer;
    typedef typename Allocator::const_pointer   const_pointer;

    typedef implementation defined             iterator;          //  See lib.container.requirements
    typedef implementation defined             const_iterator;    //  See lib.container.requirements
    typedef std::reverse_iterator<iterator> reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
    static const size_type npos = -1;

    //  lib.string.cons construct/copy/destroy:
    explicit basic_string(const Allocator& a = Allocator());
    basic_string(const basic_string& str, size_type pos = 0,
		 size_type n = npos, const Allocator& a = Allocator());
    basic_string(const charT* s,
		 size_type n, const Allocator& a = Allocator());
    basic_string(const charT* s, const Allocator& a = Allocator());
    basic_string(size_type n, charT c, const Allocator& a = Allocator());
    template<class InputIterator>
      basic_string(InputIterator begin, InputIterator end,
		   const Allocator& a = Allocator());
   ~basic_string();
    basic_string& operator=(const basic_string& str);
    basic_string& operator=(const charT* s);
    basic_string& operator=(charT c);

    //  lib.string.iterators iterators:
    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;

    //  lib.string.capacity 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;

    //  lib.string.access 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);

    //  lib.string.modifiers 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 InputIterator>
      basic_string& append(InputIterator first, InputIterator last);
    void push_back(const charT);

    basic_string& assign(const basic_string&);
    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 InputIterator>
      basic_string& assign(InputIterator first, InputIterator 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 InputIterator>
      void insert(iterator p, InputIterator first, InputIterator 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<charT,traits,Allocator>&);

    //  lib.string.ops string operations:
    const charT* c_str() const;         //  explicit
    const charT* data() const;
    allocator_type get_allocator() const;

    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;

    basic_string substr(size_type pos = 0, size_type n = npos) const;
    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, size_type n2 = npos) const;
  };
}

-1- In all basic_string constructors, a copy of the Allocator argument is used for any memory allocation performed by the constructor or member functions during the lifetime of the object.

explicit basic_string(const Allocator& a = Allocator());

-2- Effects: Constructs an object of class basic_string. The postconditions of this function are indicated in Table ??:

basic_string(const basic_string<charT,traits,Allocator>& str,
             size_type pos = 0, size_type n = npos,
             const Allocator& a = Allocator());

-3- Requires: pos <= str .size()

-4- Throws: out_of_range if pos > str .size().

-5- Effects: Constructs an object of class basic_string and determines the effective length rlen of the initial string value as the smaller of n and str .size() - pos , as indicated in Table ??:

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

-6- Requires: s shall not be a null pointer and n < npos.

-7- Throws: length_error if n == npos.

-8- Effects: Constructs an object of class basic_string and determines its initial string value from the array of charT of length n whose first element is designated by s , as indicated in Table ??:

basic_string(const charT* s, const Allocator& a = Allocator());

-9- Requires: s shall not be a null pointer.

-10- Effects: Constructs an object of class basic_string and determines its initial string value from the array of charT of length traits::length(s) whose first element is designated by s , as indicated in Table ??:

-11- Notes: Uses traits::length().

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

-12- Requires: n < npos

-13- Throws: length_error if n == npos.

-14- Effects: Constructs an object of class basic_string and determines its initial string value by repeating the char-like object c for all n elements, as indicated in Table ??:

template<class InputIterator>
  basic_string(InputIterator begin, InputIterator end,
               const Allocator& a = Allocator());

-15- Effects: If InputIterator is an integral type, equivalent to

basic_string(static_cast<size_type>(begin), static_cast<value_type>(end))

-16- Effects: If *this and str are not the same object, modifies *this as shown in Table ??:

If *this and str are the same object, the member has no effect.

-17- Returns: *this

basic_string<charT,traits,Allocator>&
  operator=(const charT* s);

-18- Returns: *this = basic_string<charT,traits,Allocator>(s).

-19- Notes: Uses traits::length().

basic_string<charT,traits,Allocator>& operator=(charT c);