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 ??:

Strings library summary
SubclauseHeader(s)
lib.char.traits Character traits<string>
lib.string.classes String classes<string>
lib.c.strings Null-terminated sequence utilities<cctype>
 <cwctype>
 <cstring>
 <cwchar>
 <cstdlib>

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.



Traits requirements
expressionreturn typeassertion/notecomplexity
  pre/post-condition
X::char_typecharT(described in lib.char.traits.typedefs)compile-time
X::int_type (described in lib.char.traits.typedefs)compile-time
X::off_type (described in lib.char.traits.typedefs)compile-time
X::pos_type (described in lib.char.traits.typedefs)compile-time
X::state_type (described in lib.char.traits.typedefs)compile-time
X::assign(c,d)(not used)assigns c=d.constant
X::eq(c,d)bool yields: whether c is to be treated as equal to d. constant
X::lt(c,d)bool yields: whether c is to be treated as less than d. constant
X::compare (p,q,n) int yields: 0 if for each i in [0,n), X::eq(p[i],q[i]) is true; else, a negative value if, for some j in [0,n), X::lt(p[j],q[j]) is true and for each i in [0,j) X::eq(p[i],q[i]) is true; else a positive value. linear
X::length(p)size_t yields: the smallest i such that X::eq(p[i],charT()) is true. linear
X::find(p,n,c) const X:: char_type* yields: the smallest q in [p,p+n) such that X::eq(*q,c) is true, zero otherwise. linear
X::move(s,p,n) X:: char_type* for each i in [0,n), performs X::assign(s[i],p[i]). Copies correctly even where p is in [s,s+n). yields: s. linear
X::copy(s,p,n) X:: char_type* pre: p not in [s,s+n). yields: s. for each i in [0,n), performs X::assign(s[i],p[i]). linear
X::assign (s,n,c) X:: char_type* for each i in [0,n), performs X::assign(s[i],c). yields: s. linear
X::not_eof(e)int_type yields: e if X::eq_int_type(e,X::eof()) is false, otherwise a value f such that X::eq_int_type(f,X::eof()) is false. constant
X::to_char_type (e) X:: char_type yields: if for some c, X::eq_int_type(e,X::to_int_type(c)) is true, c; else some unspecified value. constant
X::to_int_type (c) X:: int_type yields: some value e, constrained by the definitions of to_char_type and eq_int_type. constant
X::eq_int_type (e,f) bool yields: for all c and d, X::eq(c,d) is equal to X::eq_int_type(X::to_int_type(c), X::to_int_type(d)); otherwise, yields true if e and f are both copies of X::eof(); otherwise, yields false if one of e and f are copies of X::eof() and the other is not; otherwise the value is unspecified. constant
X::eof() X:: int_type yields: a value e such that X::eq_int_type(e,X::to_int_type(c)) is false for all values c. constant

-2- The struct template

template<class charT> struct char_traits;
shall be provided in the header <string> as a basis for explicit specializations.

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

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

typedef CHAR_T char_type;

-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]
typedef OFF_T off_type;
typedef POS_T pos_type;

-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();
  };
}
The header <string> (lib.string.classes) declares a specialization of the template struct char_traits for wchar_t. It is for wide-oriented iostream classes.

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

21.3 - Template class basic_string [lib.basic.string]

-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:

-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:

-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

--- end example]
--- end note]
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;
  };
}

21.3.1 - basic_string constructors [lib.string.cons]

-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 Allocator&) effects
ElementValue
data()a non-null pointer that is copyable and can have 0 added to it
size()0
capacity()an unspecified value

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(basic_string, size_type, size_type, const Allocator&) effects
ElementValue
data() points at the first element of an allocated copy of rlen consecutive elements of the string controlled by str beginning at position pos
size() rlen
capacity()a value at least as large as size()

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*, size_type, const Allocator&) effects
ElementValue
data() points at the first element of an allocated copy of the array whose first element is pointed at by s
size() n
capacity()a value at least as large as size()

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 ??:

basic_string(const charT*, const Allocator&) effects
ElementValue
data() points at the first element of an allocated copy of the array whose first element is pointed at by s
size() traits::length(s)
capacity()a value at least as large as size()

-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 ??:

basic_string(size_type, charT, const Allocator&) effects
ElementValue
data() points at the first element of an allocated array of n elements, each storing the initial value c
size() n
capacity()a value at least as large as size()

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))
Otherwise constructs a string from the values in the range [begin, end), as indicated in the Sequence Requirements table (see lib.sequence.reqmts):
basic_string<charT,traits,Allocator>&
  operator=(const basic_string<charT,traits,Allocator>& str);

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

operator=(const basic_string<charT, traits, Allocator>&) effects
ElementValue
data() points at the first element of an allocated copy of the array whose first element is pointed at by str.data()
size()str.size()
capacity()a value at least as large as size()

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);
Returns: *this = basic_string<charT,traits,Allocator>(1,c).

21.3.2 - basic_string iterator support [lib.string.iterators]

iterator       begin();
const_iterator begin() const;

-1- Returns: an iterator referring to the first character in the string.

iterator       end();
const_iterator end() const;

-2- Returns: an iterator which is the past-the-end value.

reverse_iterator       rbegin();
const_reverse_iterator rbegin() const;

-3- Returns: an iterator which is semantically equivalent to reverse_iterator(end()).

reverse_iterator       rend();
const_reverse_iterator rend() const;

-4- Returns: an iterator which is semantically equivalent to reverse_iterator(begin()).

21.3.3 - basic_string capacity [lib.string.capacity]

size_type size() const;

-1- Returns: a count of the number of char-like objects currently in the string.

size_type length() const;

-2- Returns: size().

size_type max_size() const;

-3- Returns: The maximum size of the string.

-4- Note: See Container requirements table (lib.container.requirements).

void resize(size_type n, charT c);

-5- Requires: n <= max_size()

-6- Throws: length_error if n > max_size().

-7- Effects: Alters the length of the string designated by *this as follows:

void resize(size_type n);

-8- Effects: resize(n,charT()).

size_type capacity() const;

-9- Returns: the size of the allocated storage in the string.

void reserve(size_type res_arg=0);

-10- The member function reserve() is a directive that informs a basic_string object of a planned change in size, so that it can manage the storage allocation accordingly.

-11- Effects: After reserve(), capacity() is greater or equal to the argument of reserve. [Note: Calling reserve() with a res_arg argument less than capacity() is in effect a non-binding shrink request. A call with res_arg <= size() is in effect a non-binding shrink-to-fit request.
--- end note]

-12- Throws: length_error if res_arg > max_size().*

[Footnote: reserve() uses Allocator::allocate() which may throw an appropriate exception. --- end foonote]
void clear();

-13- Effects: Behaves as if the function calls:

erase(begin(), end());
bool empty() const;

-14- Returns: size() == 0.

21.3.4 - basic_string element access [lib.string.access]

const_reference operator[](size_type pos) const;
reference       operator[](size_type pos);

-1- Returns: If pos < size(), returns data()[ pos ]. Otherwise, if pos == size(), the const version returns charT(). Otherwise, the behavior is undefined.

const_reference at(size_type pos) const;
reference       at(size_type pos);

-2- Requires: pos < size()

-3- Throws: out_of_range if pos >= size().

-4- Returns: operator[]( pos ).

21.3.5 - basic_string modifiers [lib.string.modifiers]

21.3.5.1 - basic_string::operator+= [lib.string::op+=]

basic_string<charT,traits,Allocator>&
  operator+=(const basic_string<charT,traits,Allocator>& str);

-1- Returns: append(str).

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

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

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

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

-4- Returns: *this += basic_string<charT,traits,Allocator>(1,c).

21.3.5.2 - basic_string::append [lib.string::append]

basic_string<charT,traits,Allocator>&
  append(const basic_string<charT,traits>& str);

-1- Returns: append(str, 0, npos).

basic_string<charT,traits,Allocator>&
  append(const basic_string<charT,traits>& str, size_type pos, size_type n);

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

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

-4- Effects: Determines the effective length rlen of the string to append as the smaller of n and str .size() - pos . The function then throws length_error if size() >= npos - rlen .
Otherwise, the function replaces the string controlled by *this with a string of length size() + rlen whose first size() elements are a copy of the original string controlled by *this and whose remaining elements are a copy of the initial elements of the string controlled by str beginning at position pos .

-5- Returns: *this.

basic_string<charT,traits,Allocator>&
  append(const charT* s, size_type n);

-6- Returns: append(basic_string<charT,traits,Allocator>(s,n)).

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

-7- Returns: append(basic_string<charT,traits,Allocator>(s)).

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

basic_string<charT,traits,Allocator>&
  append(size_type n, charT c);

-9- Returns: append(basic_string<charT,traits,Allocator>(n,c)).

template<class InputIterator>
  basic_string& append(InputIterator first, InputIterator last);

-10- Returns: append(basic_string<charT,traits,Allocator>(first,last)).

21.3.5.3 - basic_string::assign [lib.string::assign]

basic_string<charT,traits,Allocator>&
  assign(const basic_string<charT,traits>& str);

-1- Returns: assign(str, 0, npos).

basic_string<charT,traits,Allocator>&
  assign(const basic_string<charT,traits>& str, size_type pos,
         size_type n);

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

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

-4- Effects: Determines the effective length rlen of the string to assign as the smaller of n and str .size() - pos .
The function then replaces the string controlled by *this with a string of length rlen whose elements are a copy of the string controlled by str beginning at position pos .

-5- Returns: *this.

basic_string<charT,traits,Allocator>&
  assign(const charT* s, size_type n);

-6- Returns: assign(basic_string<charT,traits,Allocator>(s,n)).

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

-7- Returns: assign(basic_string<charT, traits, Allocator>(s)).

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

basic_string<charT,traits,Allocator>&
  assign(size_type n, charT c);

-9- Returns: assign(basic_string<charT,traits,Allocator>(n,c)).

template<class InputIterator>
  basic_string& assign(InputIterator first, InputIterator last);

-10- Returns: assign(basic_string<charT,traits,Allocator>(first,last)).

21.3.5.4 - basic_string::insert [lib.string::insert]

basic_string<charT,traits,Allocator>&
  insert(size_type pos1,
         const basic_string<charT,traits,Allocator>& str);

-1- Returns: insert(pos1,str,0,npos).

basic_string<charT,traits,Allocator>&
  insert(size_type pos1,
         const basic_string<charT,traits,Allocator>& str,
         size_type pos2, size_type n);

-2- Requires pos1 <= size() and pos2 <= str.size()

-3- Throws: out_of_range if pos1 > size() or pos2 > str .size().

-4- Effects: Determines the effective length rlen of the string to insert as the smaller of n and str .size() - pos2 . Then throws length_error if size() >= npos - rlen .
Otherwise, the function replaces the string controlled by *this with a string of length size() + rlen whose first pos1 elements are a copy of the initial elements of the original string controlled by *this, whose next rlen elements are a copy of the elements of the string controlled by str beginning at position pos2 , and whose remaining elements are a copy of the remaining elements of the original string controlled by *this.

-5- Returns: *this.

basic_string<charT,traits,Allocator>&
  insert(size_type pos, const charT* s, size_type n);

-6- Returns: insert(pos,basic_string<charT,traits,Allocator>(s,n)).

basic_string<charT,traits,Allocator>&
  insert(size_type pos, const charT* s);

-7- Returns: insert(pos,basic_string<charT,traits,Allocator>(s)).

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

basic_string<charT,traits,Allocator>&
  insert(size_type pos, size_type n, charT c);

-9- Returns: insert(pos,basic_string<charT,traits,Allocator>(n,c)).

iterator insert(iterator p, charT c);

-10- Requires: p is a valid iterator on *this.

-11- Effects: inserts a copy of c before the character referred to by p.

-12- Returns: an iterator which refers to the copy of the inserted character.

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

-13- Requires: p is a valid iterator on *this.

-14- Effects: inserts n copies of c before the character referred to by p.

template<class InputIterator>
  void insert(iterator p, InputIterator first, InputIterator last);

-15- Requires: p is a valid iterator on *this. [first,last) is a valid range.

-16- Returns: insert(p,basic_string< charT,traits,Allocator>(first,last)).

21.3.5.5 - basic_string::erase [lib.string::erase]

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

-1- Requires: pos <= size()

-2- Throws: out_of_range if pos > size().

-3- Effects: Determines the effective length xlen of the string to be removed as the smaller of n and size() - pos .
The function then replaces the string controlled by *this with a string of length size() - xlen whose first pos elements are a copy of the initial elements of the original string controlled by *this, and whose remaining elements are a copy of the elements of the original string controlled by *this beginning at position pos + xlen.

-4- Returns: *this.

iterator erase(iterator p);

-5- Requires: p is a valid iterator on *this.

-6- Effects: removes the character referred to by p.

-7- Returns: an iterator which points to the element immediately following p prior to the element being erased. If no such element exists, end() is returned.

iterator erase(iterator first, iterator last);

-8- Requires: first and last are valid iterators on *this, defining a range [first,last).

-9- Effects: removes the characters in the range [first,last).

-10- Returns: an iterator which points to the element immediately following last prior to the element being erased. If no such element exists, end() is returned.

21.3.5.6 - basic_string::replace [lib.string::replace]

basic_string<charT,traits,Allocator>&
  replace(size_type pos1, size_type n1,
          const basic_string<charT,traits,Allocator>& str);

-1- Returns: replace(pos1, n1, str, 0, npos).

basic_string<charT,traits,Allocator>&
  replace(size_type pos1, size_type n1,
          const basic_string<charT,traits,Allocator>& str,
          size_type pos2, size_type n2);

-2- Requires: pos1 <= size() && pos2 <= str.size().

-3- Throws: out_of_range if pos1 > size() or pos2 > str .size().

-4- Effects: Determines the effective length xlen of the string to be removed as the smaller of n1 and size() - pos1 . It also determines the effective length rlen of the string to be inserted as the smaller of n2 and str .size() - pos2 .

-5- Throws: length_error if size() - xlen >= npos - rlen .
Otherwise, the function replaces the string controlled by *this with a string of length size() - xlen + rlen whose first pos1 elements are a copy of the initial elements of the original string controlled by *this, whose next rlen elements are a copy of the initial elements of the string controlled by str beginning at position pos2 , and whose remaining elements are a copy of the elements of the original string controlled by *this beginning at position pos1 + xlen .

-6- Returns: *this.

basic_string<charT,traits,Allocator>&
  replace(size_type pos, size_type n1, const charT* s, size_type n2);

-7- Returns: replace(pos,n1,basic_string<charT,traits,Allocator>(s,n2)).

basic_string<charT,traits,Allocator>&
  replace(size_type pos, size_type n1, const charT* s);

-8- Returns: replace(pos,n1,basic_string<charT,traits,Allocator>(s)).

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

basic_string<charT,traits,Allocator>&
  replace(size_type pos, size_type n1,
          size_type n2, charT c);

-10- Returns: replace(pos,n1,basic_string<charT,traits,Allocator>(n2,c)).

basic_string& replace(iterator i1, iterator i2, const basic_string& str);

-11- Requires: The iterators i1 and i2 are valid iterators on *this, defining a range [i1,i2).

-12- Effects: Replaces the string controlled by *this with a string of length size() - (i2 - i1) + str.size() whose first begin() - i1 elements are a copy of the initial elements of the original string controlled by *this, whose next str.size() elements are a copy of the string controlled by str, and whose remaining elements are a copy of the elements of the original string controlled by *this beginning at position i2.

-13- Returns: *this.

-14- Notes: After the call, the length of the string will be changed by: str.size() - (i2 - i1).

basic_string&
  replace(iterator i1, iterator i2, const charT* s, size_type n);

-15- Returns: replace(i1,i2,basic_string(s,n)).

-16- Notes: Length change: n - (i2 - i1).

basic_string& replace(iterator i1, iterator i2, const charT* s);

-17- Returns: replace(i1,i2,basic_string(s)).

-18- Notes: Length change: traits::length(s) - (i2 - i1).
Uses traits::length().

basic_string& replace(iterator i1, iterator i2, size_type n,
                      charT c);

-19- Returns: replace(i1,i2,basic_string(n,c)). Notes: Length change: n - (i2 - i1).

template<class InputIterator>
  basic_string& replace(iterator i1, iterator i2,
                        InputIterator j1, InputIterator j2);
Returns: replace(i1,i2,basic_string(j1,j2)). Notes: Length change: j2 - j1 - (i2 - i1).

21.3.5.7 - basic_string::copy [lib.string::copy]

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

-1- Requires: pos <= size()

-2- Throws: out_of_range if pos > size().

-3- Effects: Determines the effective length rlen of the string to copy as the smaller of n and size() - pos . s shall designate an array of at least rlen elements.
The function then replaces the string designated by s with a string of length rlen whose elements are a copy of the string controlled by *this beginning at position pos .
The function does not append a null object to the string designated by s .

-4- Returns: rlen .

21.3.5.8 - basic_string::swap [lib.string::swap]

void swap(basic_string<charT,traits,Allocator>& s);

-1- Effects: Swaps the contents of the two strings.

-2- Postcondition: *this contains the characters that were in s, s contains the characters that were in *this.

-3- Complexity: constant time.

21.3.6 - basic_string string operations [lib.string.ops]

const charT* c_str() const;

-1- Returns: A pointer to the initial element of an array of length size() + 1 whose first size() elements equal the corresponding elements of the string controlled by *this and whose last element is a null character specified by charT().

-2- Requires: The program shall not alter any of the values stored in the array. Nor shall the program treat the returned value as a valid pointer value after any subsequent call to a non-const member function of the class basic_string that designates the same object as this.

const charT* data() const;

-3- Returns: If size() is nonzero, the member returns a pointer to the initial element of an array whose first size() elements equal the corresponding elements of the string controlled by *this. If size() is zero, the member returns a non-null pointer that is copyable and can have zero added to it.

-4- Requires: The program shall not alter any of the values stored in the character array. Nor shall the program treat the returned value as a valid pointer value after any subsequent call to a non- const member function of basic_string that designates the same object as this.

allocator_type get_allocator() const;

-5- Returns: a copy of the Allocator object used to construct the string.

21.3.6.1 - basic_string::find [lib.string::find]

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

-1- Effects: Determines the lowest position xpos , if possible, such that both of the following conditions obtain:

  • pos <= xpos and xpos + str.size() <= size();
  • at(xpos+I) == str.at(I) for all elements I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: find(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: find(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: find(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.2 - basic_string::rfind [lib.string::rfind]

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

-1- Effects: Determines the highest position xpos , if possible, such that both of the following conditions obtain:

  • xpos <= pos and xpos + str .size() <= size();
  • at(xpos+I) == str.at(I) for all elements I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: rfind(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: rfind(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: rfind(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.3 - basic_string::find_first_of [lib.string::find.first.of]

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

-1- Effects: Determines the lowest position xpos , if possible, such that both of the following conditions obtain:

  • pos <= xpos and xpos < size();
  • at(xpos) == str.at(I) for some element I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: find_first_of(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: find_first_of(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: find_first_of(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.4 - basic_string::find_last_of [lib.string::find.last.of]

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

-1- Effects: Determines the highest position xpos , if possible, such that both of the following conditions obtain:

  • xpos <= pos and pos < size();
  • at(xpos) == str.at(I) for some element I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: find_last_of(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: find_last_of(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: find_last_of(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.5 - basic_string::find_first_not_of [lib.string::find.first.not.of]

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

-1- Effects: Determines the lowest position xpos , if possible, such that both of the following conditions obtain:

  • pos <= xpos and xpos < size();
  • at(xpos) == str.at(I) for no element I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: find_first_not_of(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: find_first_not_of(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: find_first_not_of(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.6 - basic_string::find_last_not_of [lib.string::find.last.not.of]

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

-1- Effects: Determines the highest position xpos , if possible, such that both of the following conditions obtain:

  • xpos <= pos and pos < size();
  • at(xpos) == str.at(I)) for no element I of the string controlled by str .

-2- Returns: xpos if the function can determine such a value for xpos . Otherwise, returns npos.

-3- Notes: Uses traits::eq().

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

-4- Returns: find_last_not_of(basic_string<charT,traits,Allocator>(s,n),pos).

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

-5- Returns: find_last_not_of(basic_string<charT,traits,Allocator>(s),pos).

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

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

-7- Returns: find_last_not_of(basic_string<charT,traits,Allocator>(1,c),pos).

21.3.6.7 - basic_string::substr [lib.string::substr]

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

-1- Requires: pos <= size()

-2- Throws: out_of_range if pos > size().

-3- Effects: Determines the effective length rlen of the string to copy as the smaller of n and size() - pos .

-4- Returns: basic_string<charT,traits,Allocator>(data()+pos,rlen).

21.3.6.8 - basic_string::compare [lib.string::compare]

int compare(const basic_string<charT,traits,Allocator>&  str ) const

-1- Effects: Determines the effective length rlen of the strings to compare as the smallest of size() and str.size(). The function then compares the two strings by calling traits::compare(data(), str.data(), rlen).

-2- Returns: the nonzero result if the result of the comparison is nonzero. Otherwise, returns a value as indicated in Table ??:

compare() results
ConditionReturn Value
size() < str .size()< 0
size() == str .size() 0
size() > str .size()> 0

int compare(size_type pos1, size_type n1,
            const basic_string<charT,traits,Allocator>&  str ) const;

-3- Returns:

basic_string<charT,traits,Allocator>(*this,pos1,n1).compare(
             str) .
int compare(size_type pos1, size_type n1,
            const basic_string<charT,traits,Allocator>&  str ,
            size_type  pos2 , size_type  n2 ) const;

-4- Returns:

basic_string<charT,traits,Allocator>(*this,pos1,n1).compare(
             basic_string<charT,traits,Allocator>(str,pos2,n2)) .
int compare(const charT *s) const;

-5- Returns: this->compare(basic_string<charT,traits,Allocator>(s)).

int compare(size_type pos, size_type n1,
            charT *s, size_type n2 = npos) const;

-6- Returns:

basic_string<charT,traits,Allocator>(*this,pos,n1).compare(
             basic_string<charT,traits,Allocator>(s,n2))

21.3.7 - basic_string non-member functions [lib.string.nonmembers]

21.3.7.1 - operator+ [lib.string::op+]

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

-1- Returns: basic_string<charT,traits,Allocator>(lhs).append(rhs)

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) + rhs.

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

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

-4- Returns: basic_string<charT,traits,Allocator>(1,lhs) + rhs.

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

-5- Returns: lhs + basic_string<charT,traits,Allocator>(rhs).

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

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

-7- Returns: lhs + basic_string<charT,traits,Allocator>(1,rhs).

21.3.7.2 - operator== [lib.string::operator==]

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

-1- Returns: lhs .compare(rhs) == 0.

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) == rhs .

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

-3- Returns: lhs == basic_string<charT,traits,Allocator>(rhs).

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

21.3.7.3 - operator!= [lib.string::op!=]

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

-1- Returns: !(lhs == rhs).

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) != rhs .

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

-3- Returns: lhs != basic_string<charT,traits,Allocator>(rhs).

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

21.3.7.4 - operator< [lib.string::op<]

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

-1- Returns: lhs .compare(rhs) < 0.

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) < rhs .

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

-3- Returns: lhs < basic_string<charT,traits,Allocator>(rhs).

21.3.7.5 - operator> [lib.string::op>]

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

-1- Returns: lhs .compare(rhs) > 0.

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) > rhs .

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

-3- Returns: lhs > basic_string<charT,traits,Allocator>(rhs).

21.3.7.6 - operator<= [lib.string::op<=]

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

-1- Returns: lhs .compare(rhs) <= 0.

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) <= rhs .

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

-3- Returns: lhs <= basic_string<charT,traits,Allocator>(rhs).

21.3.7.7 - operator>= [lib.string::op>=]

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

-1- Returns: lhs .compare(rhs) >= 0.

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

-2- Returns: basic_string<charT,traits,Allocator>(lhs) >= rhs .

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

-3- Returns: lhs >= basic_string<charT,traits,Allocator>(rhs).

21.3.7.8 - swap [lib.string.special]

  template<class charT, class traits, class Allocator>
     void swap(basic_string<charT,traits,Allocator>& lhs,
	       basic_string<charT,traits,Allocator>& rhs);

-1- Effects: lhs .swap( rhs );

21.3.7.9 - Inserters and extractors [lib.string.io]

template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    operator>>(basic_istream<charT,traits>&  is,
               basic_string<charT,traits,Allocator>&  str);

-1- Effects: Begins by constructing a sentry object k as if k were constructed by typename basic_istream<charT,traits>::sentry k(is). If bool(k) is true, it calls str.erase() and then extracts characters from is and appends them to str as if by calling str.append(1,c). If is.width() is greater than zero, the maximum number n of characters appended is is.width(); otherwise n is str.max_size(). Characters are extracted and appended until any of the following occurs:

  • n characters are stored;
  • end-of-file occurs on the input sequence;
  • isspace(c,getloc()) is true for the next available input character c.

    After the last character (if any) is extracted, is.width(0) is called and the sentry object k is destroyed.

-2- Returns: is

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

-3- Effects: Begins by constructing a sentry object k as if k were constructed by typename basic_ostream<charT,traits>::sentry k(os). If bool(k) is true, inserts characters as if by calling os.rdbuf()->sputn(str.data(), n), padding as described in stage 3 of lib.facet.num.put.virtuals, where n is the smaller of os.width() and str.size(); then calls os.width(0). If the call to sputn fails, calls os.setstate(ios_base::failbit).

-4- Returns: os

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

-5- Effects: Begins by constructing a sentry object k as if by typename basic_istream<charT,traits>::sentry k(is, true). If bool(k) is true, it calls str.erase() and then extracts characters from is and appends them to str as if by calling str.append(1,c) until any of the following occurs:

  • end-of-file occurs on the input sequence (in which case, the getline function calls is.setstate(ios_base::eofbit)).
  • c == delim for the next available input character c (in which case, c is extracted but not appended) (lib.iostate.flags)
  • str.max_size() characters are stored (in which case, the function calls is.setstate(ios_base::failbit) (lib.iostate.flags)

-6- The conditions are tested in the order shown. In any case, after the last character is extracted, the sentry object k is destroyed.

-7- If the function extracts no characters, it calls is.setstate(ios_base::failbit) which may throw ios_base::failure (lib.iostate.flags).

-8- Returns: is.

template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline(basic_istream<charT,traits>& is,
            basic_string<charT,traits,Allocator>& str)

-9- Returns: getline(is,str,is.widen('\n'))

21.4 - Null-terminated sequence utilities [lib.c.strings]

-1- Tables ??, ??, ??, ??, and ?? describe headers <cctype>, <cwctype>, <cstring>, <cwchar>, and <cstdlib> (multibyte conversions), respectively.

Header <cctype> synopsis
TypeName(s)
Functions:
isalnumisdigitisprintisuppertolower
isalphaisgraphispunctisxdigittoupper
iscntrlislowerisspace

Header <cwctype> synopsis
TypeName(s)
Macro:WEOF <cwctype>
Types:wctrans_twctype_twint_t <cwctype>
Functions:
iswalnumiswctypeiswloweriswspacetowctranswctrans
iswalphaiswdigitiswprintiswuppertowlowerwctype
iswcntrliswgraphiswpunctiswxdigittowupper

Header <cstring> synopsis
TypeName(s)
Macro:NULL <cstring>
Type:size_t <cstring>
Functions:
memchrstrcatstrcspnstrncpystrtok
memcmpstrchrstrerrorstrpbrkstrxfrm
memcpystrcmpstrlen strrchr
memmovestrcollstrncatstrspn
memsetstrcpystrncmpstrstr

Header <cwchar> synopsis
TypeName(s)
Macros:NULL <cwchar>WCHAR_MAXWCHAR_MINWEOF <cwchar>
Types:mbstate_twint_t <cwchar>size_t
Functions:
btowcgetwcharungetwcwcscpywcsrtombswmemchr
fgetwcmbrlenvfwprintfwcscspnwcsspnwmemcmp
fgetwsmbrtowcvswprintfwcsftimewcsstrwmemcpy
fputwcmbsinitvwprintfwcslenwcstodwmemmove
fputwsmbsrtowcswcrtombwcsncatwcstokwmemset
fwideputwcwcscatwcsncmpwcstolwprintf
fwprintfputwcharwcschrwcsncpywcstoulwscanf
fwscanfswprintfwcscmpwcspbrkwcsxfrm
getwcswscanfwcscollwcsrchrwctob

Header <cstdlib> synopsis
TypeName(s)
Macros:MB_CUR_MAX
Functions:
atolmblenstrtodwctomb
atofmbstowcsstrtolwcstombs
atoimbtowcstrtoul

-2- The contents of these headers are the same as the Standard C library headers <ctype.h>, <wctype.h>, <string.h>, <wchar.h> and <stdlib.h> respectively, with the following modifications:

-3- None of the headers shall define the type wchar_t (lex.key).

-4- The function signature strchr(const char*, int) is replaced by the two declarations:

const char* strchr(const char* s, int c);
      char* strchr(      char* s, int c);

-5- both of which have the same behavior as the original declaration.

-6- The function signature strpbrk(const char*, const char*) is replaced by the two declarations:

const char* strpbrk(const char* s1, const char* s2);
      char* strpbrk(      char* s1, const char* s2);

-7- both of which have the same behavior as the original declaration.

-8- The function signature strrchr(const char*, int) is replaced by the two declarations:

const char* strrchr(const char* s, int c);
      char* strrchr(      char* s, int c);

-9- both of which have the same behavior as the original declaration.

-10- The function signature strstr(const char*, const char*) is replaced by the two declarations:

const char* strstr(const char* s1, const char* s2);
      char* strstr(      char* s1, const char* s2);

-11- both of which have the same behavior as the original declaration.

-12- The function signature memchr(const void*, int, size_t) is replaced by the two declarations:

const void* memchr(const void* s, int c, size_t n);
      void* memchr(      void* s, int c, size_t n);

-13- both of which have the same behavior as the original declaration.

-14- The function signature wcschr(const wchar_t*, wchar_t) is replaced by the two declarations:

const wchar_t* wcschr(const wchar_t* s, wchar_t c);
      wchar_t* wcschr(      wchar_t* s, wchar_t c);

-15- both of which have the same behavior as the original declaration.

-16- The function signature wcspbrk(const wchar_t*, const wchar_t*) is replaced by the two declarations:

const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);
      wchar_t* wcspbrk(      wchar_t* s1, const wchar_t* s2);

-17- both of which have the same behavior as the original declaration.

-18- The function signature wcsrchr(const wchar_t*, wchar_t) is replaced by the two declarations:

const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);
      wchar_t* wcsrchr(      wchar_t* s, wchar_t c);

-19- both of which have the same behavior as the original declaration. The function signature wcsstr(const wchar_t*, const wchar_t*) is replaced by the two declarations:

const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);
      wchar_t* wcsstr(      wchar_t* s1, const wchar_t* s2);
both of which have the same behavior as the original declaration. The function signature wmemchr(const wwchar_t*, int, size_t) is replaced by the two declarations:
const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);
      wchar_t* wmemchr(      wchar_t* s, wchar_t c, size_t n);
both of which have the same behavior as the original declaration.

See also ISO C subclauses 7.3, 7.10.7, 7.10.8, and 7.11. Amendment 1 subclauses 4.4, 4.5, and 4.6.