______________________________________________________________________
21 Strings library [lib.strings]
______________________________________________________________________
1 This clause describes components for manipulating sequences of ``char
acters,'' where characters may be of type char, wchar_t, or of a type
defined in a C++ program.
2 The following subclauses describe string classes, and null-terminated
sequence utilities, as summarized in Table 1:
Table 1--Strings library summary
+---------------------------------------------------------------+
| Subclause Header(s) |
+---------------------------------------------------------------+
|_lib.string.classes_ String classes <string> |
+---------------------------------------------------------------+
| <cctype> |
| <cwctype> |
|_lib.c.strings_ Null-terminated sequence utilities <cstring> |
| <cwchar> |
| <cstdlib> |
+---------------------------------------------------------------+
21.1 String classes [lib.string.classes]
Header <string> synopsis
#include <memory> // for allocator
namespace std {
// subclause _lib.template.string_, basic_string:
template<class charT> struct string_char_traits;
template<class charT, class Allocator = allocator,
class traits = string_char_traits<charT> >
class basic_string;
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const_pointer lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(charT lhs, const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs,
const_pointer rhs);
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs, charT rhs);
template<class charT, class Allocator, class traits>
bool operator==(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator==(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator==(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator!=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator!=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator!=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator< (const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator< (const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator< (const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator> (const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator> (const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator> (const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator<=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator<=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator<=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator>=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator>=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator>=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
basic_istream<charT>&
operator>>(basic_istream<charT>& is,
basic_string<charT,Allocator,traits>& a);
template<class charT, class Allocator, class traits>
basic_ostream<charT>&
operator<<(basic_ostream<charT>& os,
const basic_string<charT,Allocator,traits>& a);
// subclause _lib.string_, string:
struct string_char_traits<char>;
typedef basic_string<char> string;
// subclause _lib.wstring_, wstring:
struct string_char_traits<wchar_t>;
typedef basic_string<wchar_t> wstring;
}
1 In this subclause, we call the basic character types ``char-like''
types, and also call the objects of char-like types ``char-like''
objects or simply ``character''s.
2 The header <string> defines a basic string class template and its
traits that can handle all ``char-like'' template arguments with sev
eral function signatures for manipulating varying-length sequences of
``char-like'' objects.
3 The header <string> also defines two specific template classes string
and wstring and their special traits.
21.1.1 Template class basic_string [lib.template.string]
21.1.1.1 Template class [lib.string.char.traits]
string_char_traits
namespace std {
template<class charT> struct string_char_traits {
typedef charT char_type; // for users to acquire the basic character type
// constraints
static void assign(char_type& c1, const char_type& c2)
static bool eq(const char_type& c1, const char_type& c2)
static bool ne(const char_type& c1, const char_type& c2)
static bool lt(const char_type& c1, const char_type& c2)
static char_type eos(); // the null character
static basic_istream<charT>&
char_in(basic_istream<charT>& is, charT& a);
static basic_ostream<charT>&
char_out(basic_ostream<charT>& os, charT a);
static bool is_del(charT a);
// characteristic function for delimiters of charT
// speed-up functions
static int compare(const char_type* s1, const char_type* s2,
size_t n);
static size_t length(const char_type* s);
static char_type* copy(char_type* s1, const char_type* s2, size_t n);
};
}
21.1.1.2 string_char_traits [lib.string.char.traits.members]
members
1 Default definitions.
21.1.1.2.1 assign [lib.char.traits::assign]
static void assign(char_type& c1, const char_type& c2)
Effects:
Assigns c2 to c1.
21.1.1.2.2 eq [lib.char.traits::eq]
static bool eq(const char_type& c1, const char_type& c2)
Returns
c1 == c2
21.1.1.2.3 ne [lib.char.traits::ne]
static bool ne(const char_type& c1, const char_type& c2)
Returns:
!(c1 == c2)
21.1.1.2.4 lt [lib.char.traits::lt]
static bool lt(const char_type& c1, const char_type& c2)
Returns:
c1 < c2
21.1.1.2.5 eos [lib.char.traits::eos]
static char_type eos();
Returns
The null character, char_type()
21.1.1.2.6 char_in [lib.char.traits::char.in]
static basic_istream<charT>&
char_in(basic_istream<charT>& is, charT& a);
Effects:
Extracts a charT object.
Returns:
is >> a
21.1.1.2.7 char_out [lib.char.traits::char.out]
static basic_ostream<charT>&
char_out(basic_ostream<charT>& os, charT a);
Effects:
Inserts a charT object.
Returns:
os << a
21.1.1.2.8 is_del [lib.char.traits::is.del]
static bool is_del(charT a);
Effects:
Characteristic function for delimiters of charT.
Returns:
isspace(a)
21.1.1.2.9 compare [lib.char.traits::compare]
static int compare(const char_type* s1, const char_type* s2,
size_t n);
Effects:
for (size_t i = 0; i < n; ++i, ++s1, ++s2)
if (ne(*s1, *s2)) {
return lt(*s1, *s2) ? -1 : 1;
}
return 0;
21.1.1.2.10 length [lib.char.traits::length]
static size_t length(const char_type* s);
Effects:
size_t l = 0;
while (ne(*s++, eos()) ++l;
return l;
21.1.1.2.11 copy [lib.char.traits::copy]
static char_type* copy(char_type* s1, const char_type* s2, size_t n);
Effects:
char_type* s = s1;
for (size_t i = 0; i < n; ++i) assign(*++s1, *++s2);
return s;
21.1.1.3 Template class basic_string [lib.basic.string]
namespace std {
template<class charT, class Allocator = allocator,
class traits = string_char_traits<charT> >
class basic_string {
public:
// typedefs:
typedef traits traits_type;
typedef traits::char_type value_type;
typedef value_type* iterator;
typedef value_type* const const_iterator;
typedef allocator::size_type size_type;
typedef allocator::difference_type difference_type;
// Added to make the typedefs work:
typedef allocator::types<charT> alloc_type;
typedef alloc_type::reference reference;
typedef alloc_type::const_reference const_reference;
typedef alloc_type::pointer pointer;
typedef alloc_type::const_pointer pointer;
basic_string();
basic_string(const basic_string& str, size_type pos = 0,
size_type n = NPOS);
basic_string(const_pointer s, size_type n);
basic_string(const_pointer s);
basic_string(size_type n, charT c);
~basic_string();
basic_string& operator=(const basic_string& str);
basic_string& operator=(const_pointer s);
basic_string& operator=(charT c);
basic_string& operator+=(const basic_string& rhs);
basic_string& operator+=(const_pointer s);
basic_string& operator+=(charT c);
basic_string& append(const basic_string& str, size_type pos = 0,
size_type n = NPOS);
basic_string& append(const_pointer s, size_type n);
basic_string& append(const_pointer s);
basic_string& append(size_type pos, size_type n, const charT c = charT());
basic_string& assign(const basic_string& str, size_type pos = 0,
size_type n = NPOS);
basic_string& assign(const_pointer s, size_type n);
basic_string& assign(const_pointer s);
basic_string& assign(size_type pos, size_type n, const charT c = charT());
basic_string& insert(size_type pos1, const basic_string& str,
size_type pos2 = 0, size_type n = NPOS);
basic_string& insert(size_type pos, const_pointer s, size_type n);
basic_string& insert(size_type pos, const_pointer s);
basic_string& insert(size_type pos, size_type n, const charT c = charT() );
basic_string& remove(size_type pos = 0, size_type n = NPOS);
basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
size_type pos2 = 0, size_type n2 = NPOS);
basic_string& replace(size_type pos, size_type n1, const_pointer s,
size_type n2);
basic_string& replace(size_type pos, size_type n1, const_pointer s);
basic_string& replace(size_type pos, size_type n, charT c = charT());
charT operator[](size_type pos) const;
reference operator[](size_type pos);
const_reference at(size_type n) const;
reference at(size_type n);
const_pointer c_str() const;
const_pointer data() const;
size_type size() 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);
bool empty() const;
size_type copy(pointer s, size_type n, size_type pos = 0);
void swap(basic_string<charT,Allocator,traits>&);
size_type find(const basic_string& str, size_type pos = 0) const;
size_type find(const_pointer s, size_type pos, size_type n) const;
size_type find(const_pointer 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_pointer s, size_type pos, size_type n) const;
size_type rfind(const_pointer 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_pointer s, size_type pos, size_type n) const;
size_type find_first_of(const_pointer 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_pointer s, size_type pos, size_type n) const;
size_type find_last_of (const_pointer 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_pointer s, size_type pos,
size_type n) const;
size_type find_first_not_of(const_pointer 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_pointer s, size_type pos,
size_type n) const;
size_type find_last_not_of (const_pointer s, size_type pos = NPOS) const;
size_type find_last_not_of (charT c, size_type pos = NPOS) const;
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. 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 a such given char-like type. Storage for the
string is allocated and freed as necessary by the member functions of
class basic_string.
2 In all cases, size() <= capacity().
3 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;
--an out-of-range error is associated with exceptions of type
out_of_range .
21.1.1.4 basic_string member functions [lib.string.members]
21.1.1.4.1 basic_string constructors [lib.string.cons]
basic_string();
Effects:
Constructs an object of class basic_string. The postconditions of
this function are indicated in Table 2:
Table 2--basic_string() effects
+----------------------------------+
| Element Value |
+----------------------------------+
|data() an unspecified value |
|size() 0 |
|capacity() an unspecified value |
+----------------------------------+
basic_string(const basic_string<charT,Allocator,traits>& str,
size_type pos = 0, size_type n = NPOS);
Requires:
pos <= size()
Throws:
out_of_range if pos > str .size().
Effects:
Constructs an object of class basic_string and determines the effec
tive length rlen of the initial string value as the smaller of n and
str .size() - pos, as indicated in Table 3:
Table 3--basic_string(basic_string,size_type,size_type) effects
+----------------------------------------------+
| Element Value |
+----------------------------------------------+
|data() points at the first element of |
| an allocated copy of rlen ele |
| ments of the string controlled |
| by str beginning at position pos |
|size() rlen |
|capacity() a value at least as large as len |
+----------------------------------------------+
basic_string(const_pointer s, size_type n = NPOS);
Requires:
s shall not be a null pointer.
Effects:
Constructs an object of class basic_string and determines its ini
tial string value from the array of charT of length n whose first
element is designated by s, as indicated in Table 4:
Table 4--basic_string(const_pointer,size_type) effects
+----------------------------------------------+
| Element Value |
+----------------------------------------------+
|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 len |
+----------------------------------------------+
basic_string(const_pointer s);
Requires:
s shall not be a null pointer.
Effects:
Constructs an object of class basic_string and determines its ini
tial string value from the array of charT of length
traits::length(s) whose first element is designated by s, as indi
cated in Table 5:
Table 5--basic_string(const_pointer) effects
+----------------------------------------------+
| Element Value |
+----------------------------------------------+
|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 len |
+----------------------------------------------+
Notes:
Uses traits::length().
basic_string(size_type n, charT c);
Requires:
n < NPOS
Throws:
length_error if n == NPOS.
Effects:
Constructs an object of class basic_string and determines its ini
tial string value by repeating the char-like object c for all n ele
ments, as indicated in Table 6:
Table 6--basic_string(charT,size_type) effects
+----------------------------------------------+
| Element Value |
+----------------------------------------------+
|data() points at the first element of |
| an allocated array of n ele |
| ments, each storing the initial |
| value c |
|size() n |
|capacity() a value at least as large as len |
+----------------------------------------------+
21.1.1.4.2 basic_string::operator= [lib.string::op=]
basic_string<charT,Allocator,traits>&
operator=(const basic_string<charT,Allocator,traits>& str);
Returns:
*this = basic_string<charT,Allocator,traits>(str).
basic_string<charT,Allocator,traits>&
operator=(const_pointer s);
Returns:
*this = basic_string<charT,Allocator,traits>(s).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>& operator=(charT c);
Returns:
*this = basic_string<charT,Allocator,traits>(c).
21.1.1.4.3 basic_string::operator+= [lib.string::op+=]
basic_string<charT,Allocator,traits>&
operator+=(const basic_string<charT,Allocator,traits>& rhs);
Returns:
append(rhs).
basic_string<charT,Allocator,traits>& operator+=(const_pointer s);
Returns:
*this += basic_string<charT,Allocator,traits>(s).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>& operator+=(charT c);
Returns:
*this += basic_string<charT,Allocator,traits>(c).
21.1.1.4.4 basic_string::append [lib.string::append]
basic_string<charT,Allocator,traits>&
append(const basic_string<charT,traits>& str,
size_type pos = 0, size_type n = NPOS);
Requires:
pos <= size()
Throws:
out_of_range if pos > str .size().
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 len elements are a copy
of the original string controlled by *this and whose remaining ele
ments are a copy of the initial elements of the string controlled by
str beginning at position pos.
Returns:
*this.
basic_string<charT,Allocator,traits>&
append(const_pointer s, size_type n);
Returns:
append(basic_string<charT,Allocator,traits>(s,n)).
basic_string<charT,Allocator,traits>& append(const_pointer s);
Returns:
append(basic_string<charT,Allocator,traits>(s)).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>&
append(size_type pos, size_type n, const charT c = charT());
Returns:
append(basic_string<charT,Allocator,traits>(c,n),pos).
21.1.1.4.5 basic_string::assign [lib.string::assign]
basic_string<charT,Allocator,traits>&
assign(const basic_string<charT,traits>& str,
size_type pos = 0, size_type n = NPOS);
Requires:
pos <= size()
Throws:
out_of_range if pos > str .size().
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 con
trolled by str beginning at position pos.
Returns:
*this.
basic_string<charT,Allocator,traits>&
assign(const_pointer s, size_type n);
Returns:
assign(basic_string<charT,Allocator,traits>(s,n)).
basic_string<charT,Allocator,traits>& assign(const_pointer s);
Returns:
assign(basic_string(s)).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>&
assign(size_type pos, size_type n, const charT c = charT());
Returns:
assign(basic_string<charT,Allocator,traits>(c,n),pos).
21.1.1.4.6 basic_string::insert [lib.string::insert]
basic_string<charT,Allocator,traits>&
insert(size_type pos1,
const basic_string<charT,Allocator,traits>& str,
size_type pos2 = 0, size_type n = NPOS);
Requires
pos1 <= size()
Throws:
out_of_range if pos1 > size() or pos2 > str .size().
Effects:
Determines the effective length rlen of the string to insert as the
smaller of n and str .len - 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 orig
inal string controlled by *this.
Returns:
*this.
basic_string<charT,Allocator,traits>&
insert(size_type pos, const_pointer s, size_type n);
Returns:
insert(pos,basic_string<charT,Allocator,traits>(s,n)).
basic_string<charT,Allocator,traits>&
insert(size_type pos, const_pointer s);
Returns:
insert(pos,basic_string(s)).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>&
insert(size_type pos, size_type n, const charT c = charT());
Returns:
insert(pos,basic_string<charT,Allocator,traits>(c,n)).
21.1.1.4.7 basic_string::remove [lib.string::remove]
basic_string<charT,Allocator,traits>&
remove(size_type pos = 0, size_type n = NPOS);
Requires:
pos <= size()
Throws:
out_of_range if pos > size().
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 orig
inal string controlled by *this beginning at position pos + xlen.
Returns:
*this.
21.1.1.4.8 basic_string::replace [lib.string::replace]
basic_string<charT,Allocator,traits>&
replace(size_type pos1, size_type n1,
const basic_string<charT,Allocator,traits>& str,
size_type pos2 = 0, size_type n2 = NPOS);
Requires:
pos1 <= size() && pos2 <= size().
Throws:
out_of_range if pos1 > size() or pos2 > str .size().
Effects:
Determines the effective length xlen of the string to be removed as
the smaller of n1 and size() - &pos1. It also determines the effec
tive length rlen of the string to be inserted as the smaller of n2
and str .size() - pos2. Then throws length_error if size() - xlen
>= NPOS - rlen.
Otherwise, the function replaces the string controlled by *this with
a string of length size() - xlen 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.
Returns:
*this.
basic_string<charT,Allocator,traits>&
replace(size_type pos, size_type n1, const_pointer s, size_type n2);
Returns:
replace(pos,n1,basic_string<charT,Allocator,traits>(s,n2)).
basic_string<charT,Allocator,traits>&
replace(size_type pos, size_type n1, const_pointer s);
Returns:
replace(pos,n1,basic_string<charT,Allocator,traits>(s)).
Notes:
Uses traits::length().
basic_string<charT,Allocator,traits>&
replace(size_type pos, size_type n, charT c = charT());
Returns:
replace(pos,n,basic_string<charT,Allocator,traits>(c,n)).
21.1.1.4.9 basic_string::operator[] [lib.string::op.array]
charT operator[](size_type pos) const;
reference operator[](size_type pos);
Returns:
If pos < size(), returns data()[pos ]. Otherwise, if pos ==
size(), the const version returns traits::eos(). Otherwise, the
behavior is undefined.
Notes:
The reference returned by the non- const version is invalid after
any subsequent call to c_str(), data(), or any non- const member
function for the object.
21.1.1.4.10 basic_string::at [lib.string::at]
const_reference at(size_type n) const;
reference at(size_type n);
Requires:
pos < size()
Throws:
out_of_range if pos >= size().
Returns:
operator[](pos ).
+------- BEGIN BOX 1 -------+
Previous definition of put_at(): Otherwise, if pos == len, the func
tion replaces the string controlled by *this with a string of length
len + 1 whose first len elements are a copy of the original string and
whose remaining element is initialized to c. Otherwise, the function
assigns c to ptr[pos].
+------- END BOX 1 -------+
21.1.1.4.11 basic_string::c_str [lib.string::c.str]
const charT* c_str() const;
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 charac
ter specified by traits::eos().
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.
Notes:
Uses traits::eos().
21.1.1.4.12 basic_string::data [lib.string::data]
const charT* data() const;
Returns:
c_str() if size()is
Requires:
The program shall not alter any of the values stored in the charac
ter 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.
21.1.1.4.13 basic_string::size [lib.string::size]
size_type size() const:
Returns:
a count of the number of char-like objects currently in the string.
Notes:
Uses traits::length().
21.1.1.4.14 basic_string::max_size [lib.string::max.size]
size_type max_size() const:
Returns:
The maximum size of the string.
21.1.1.4.15 basic_string::resize [lib.string::resize]
void resize(size_type n, charT c);
Requires:
n != NPOS
Throws:
length_error if n == NPOS.
Effects:
Alters the length of the string designated by *this as follows:
--If n <= size(), the function replaces the string designated by
*this with a string of length n whose elements are a copy of the
initial elements of the original string designated by *this.
--If n > size(), the function replaces the string designated by *this
with a string of length n whose first size() elements are a copy of
the original string designated by *this, and whose remaining ele
ments are all initialized to c.
void resize(size_type n);
Returns:
resize(n, eos()).
Notes:
Uses traits::eos().
21.1.1.4.16 basic_string::reserve [lib.string::reserve]
size_type capacity() const;
Returns:
the size of the allocated storage in the string.
void reserve(size_type res_arg);
1 The member function reserve() is a directive that informs a
basic_string of a planned change in size, so that it can manage the
storage allocation accordingly.
Effects:
After reserve(), capacity() is greater or equal to the argument of
reserve if reallocation happens; and equal to the previous value of
capacity() otherwise.
Reallocation happens at this point if and only if the current capac
ity is less than the argument of reserve().
Complexity:
It does not change the size of the sequence and takes at most linear
time in the size of the sequence.
Notes:
Reallocation invalidates all the references, pointers, and iterators
referring to the elements in the sequence. It is guaranteed that no
reallocation takes place during the insertions that happen after
reserve() takes place till the time when the size of the string
reaches the size specified by reserve().
21.1.1.4.17 basic_string::empty [lib.string::empty]
bool empty() const;
Returns:
size() == 0.
21.1.1.4.18 basic_string::copy [lib.string::copy]
size_type copy(pointer s, size_type n, size_type pos = 0);
Requires:
pos <= size()
Throws:
out_of_range if pos > size().
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.1)
Returns:
rlen.
21.1.1.4.19 basic_string::swap [lib.string::swap]
void swap(basic_string<charT,Allocator,traits>& s);
Effects:
Swaps the contents of the two strings.
Postcondition:
*this contains the characters that were in s, s contains the charac
ters that were in *this.
Complexity:
Constant time.
21.1.1.4.20 basic_string::find [lib.string::find]
size_type find(const basic_string<charT,Allocator,traits>& str,
size_type pos = 0) const;
Effects:
Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos + str.size() <= size();
--traits::eq(at(xpos+I),str.at(I)) for all elements I of the string
controlled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
_________________________
1) The function does not append a null object to the string.
size_type find(const_pointer s, size_type pos, size_type n) const;
Returns:
find(basic_string<charT,Allocator,tratis>(s,n)pos).
size_type find(const_pointer s, size_type pos = 0) const;
Returns:
find(basic_string<charT,Allocator,traits>(s),pos).
Notes:
Uses traits::length().
size_type find(charT c, size_type pos = 0) const;
Returns:
find(basic_string<charT,Allocator,traits>(c),pos).
21.1.1.4.21 basic_string::rfind [lib.rfind]
size_type rfind(const basic_string<charT,Allocator,traits>& str,
size_type pos = NPOS) const;
Effects:
Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and xpos + &str .size() <= size();
--traits::eq(at(xpos+I),str.at(I)) for all elements I of the string
controlled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
size_type rfind(const_pointer s, size_type pos, size_type n) const;
Returns:
rfind(basic_string<charT,Allocator,traits>(s,n),pos).
size_type rfind(const_pointer s, size_type pos = NPOS) const;
Returns:
rfind(basic_string<charT,Allocator,traits>(s),pos).
Notes:
Uses traits::length().
size_type rfind(charT c, size_type pos = NPOS) const;
Returns:
rfind(basic_string<charT,Allocator,traits>(c,n),pos).
21.1.1.4.22 [lib.string::find.first.of]
basic_string::find_first_of
size_type
find_first_of(const basic_string<charT,Allocator,traits>& str,
size_type pos = 0) const;
Effects:
Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos < size();
--traits::eq(at(xpos), str.at(I)) for some element I of the string
controlled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
size_type
find_first_of(const_pointer s, size_type pos, size_type n) const;
Returns:
find_first_of(basic_string<charT,Allocator,tratis>(s,n),pos).
size_type find_first_of(const_pointer s, size_type pos = 0) const;
Returns:
find_first_of(basic_string<charT,Allocator,tratis>(s),pos).
Notes:
Uses traits::length().
size_type find_first_of(charT c, size_type pos = 0) const;
Returns:
find_first_of(basic_string<charT,Allocator,tratis>(c),pos).
21.1.1.4.23 [lib.string::find.last.of]
basic_string::find_last_of
size_type
find_last_of(const basic_string<charT,Allocator,traits>& str,
size_type pos = NPOS) const;
Effects:
Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and pos < size();
--traits::eq(at(xpos),str.at(I)) for some element I of the string con
trolled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
size_type find_last_of(const_pointer s, size_type pos, size_type n) const;
Returns:
find_last_of(basic_string<charT,Allocator,tratis>(s,n),pos).
size_type find_last_of(const_pointer s, size_type pos = NPOS) const;
Returns:
find_last_of(basic_string<charT,Allocator,tratis>(s),pos).
Notes:
Uses traits::length().
size_type find_last_of(charT c, size_type pos = NPOS) const;
Returns:
find_last_of(basic_string<charT,Allocator,traits>(c),pos).
21.1.1.4.24 [lib.string::find.first.not.of]
basic_string::find_first_not_of
size_type
find_first_not_of(const basic_string<charT,Allocator,traits>& str,
size_type pos = 0) const;
Effects:
Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos < size();
--traits::eq(at(xpos), str.at(I)) for no element I of the string con
trolled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
size_type
find_first_not_of(const_pointer s, size_type pos, size_type n) const;
Returns:
find_first_not_of(basic_string<charT,Allocator,traits>(s,n),pos).
size_type find_first_not_of(const_pointer s, size_type pos = 0) const;
Returns:
find_first_not_of(basic_string<charT,Allocator,traits>(s),pos).
Notes:
Uses traits::length().
size_type find_first_not_of(charT, size_type pos = 0) const;
Returns:
find_first_not_of(basic_string<charT,Allocator,tratis>(c),pos).
21.1.1.4.25 [lib.string::find.last.not.of]
basic_string::find_last_not_of
size_type
find_last_not_of(const basic_string<charT,Allocator,traits>& str,
size_type pos = NPOS) const;
Effects:
Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and pos < size();
--traits::eq(at(xpos), str.at(I)) for no element I of the string con
trolled by str.
Returns:
xpos if the function can determine such a value for xpos. Other
wise, returns NPOS.
size_type find_last_not_of(const_pointer s, size_type pos, size_type n) const;
Returns:
find_last_not_of(basic_string<charT,Allocator,traits>(s,n),pos).
size_type find_last_not_of(const_pointer s, size_type pos = NPOS) const;
Returns:
find_last_not_of(basic_string<charT,Allocator,traits>(s),pos).
Notes:
Uses traits::length().
size_type find_last_not_of(charT c, size_type pos = NPOS) const;
Returns:
find_last_not_of(basic_string<charT,Allocator,traits>(c),pos).
21.1.1.4.26 basic_string::substr [lib.string::substr]
basic_string<charT,Allocator,traits>
substr(size_type pos = 0, size_type n = NPOS) const;
Requires:
pos <= size()
Throws:
out_of_range if pos > size().
Effects:
Determines the effective length rlen of the string to copy as the
smaller of n and size() - pos.
Returns:
basic_string<charT,Allocator,traits>(data()+pos,rlen).
21.1.1.4.27 basic_string::compare [lib.string::compare]
int compare(const basic_string<charT,Allocator,traits>& str,
size_type pos = 0, size_type n = NPOS)
Requires:
pos <= size()
Throws:
out_of_range if pos > size().
Effects:
Determines the effective length rlen of the strings to compare as
the smallest of n, size() - pos, and str .size(). The function then
compares the two strings by calling
traits::compare(data()+pos,str.data(),rlen).
Returns:
the nonzero result if the result of the comparison is nonzero. Oth
erwise, returns a value as indicated in Table 7:
Table 7--compare() results
+------------------------------------------+
| Condition Return Value |
+------------------------------------------+
|size() - pos < str.size() a value < 0 |
|size() - pos == str.size() 0 |
|size() - pos > str.size() a value > 0 |
+------------------------------------------+
1 Uses traits::compare().
int compare(const_pointer s, size_type pos, size_type n) const;
Returns:
compare(basic_string<charT,Allocator,traits>(s, n), pos).
Notes:
Uses traits::compare().
int compare(const_pointer s, size_type pos = 0) const;
Returns:
compare(basic_string<charT,Allocator,traits>(s), pos).
Notes:
Uses traits::length() and traits::compare().
21.1.1.5 basic_string non-member [lib.string.nonmembers]
functions
21.1.1.5.1 operator+ [lib.string::op+]
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(lhs).append(rhs).
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const_pointer lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(lhs) + rhs.
Notes:
Uses traits::length().
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(charT lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(lhs)+rhs.
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs,
const_pointer rhs);
Returns:
basic_string<charT,Allocator,tratis>(lhs)+
basic_string<charT,Allocator,tratis>(rhs).
Notes:
Uses traits::length().
template<class charT, class Allocator, class traits>
basic_string<charT,Allocator,traits>
operator+(const basic_string<charT,Allocator,traits>& lhs,
charT rhs);
Returns:
lhs + basic_string<charT,Allocator,traits>(rhs).
21.1.1.5.2 operator== [lib.string::operator==]
template<class charT, class Allocator, class traits>
bool operator==(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
lhs .compare(rhs) == 0.
template<class charT, class Allocator, class traits>
bool operator==(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,tratis>(lhs) == rhs.
template<class charT, class Allocator, class traits>
bool operator==(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
Returns:
lhs == basic_string<charT,Allocator,traits>(rhs).
Notes:
Uses traits::length().
21.1.1.5.3 operator!= [lib.string::op!=]
template<class charT, class Allocator, class traits>
bool operator!=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator!=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator!=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
Returns:
basic_string<charT,Allocator,traits>(lhs).compare(rhs) != 0.
Notes:
Uses traits::length().
21.1.1.5.4 operator< [lib.string::op<]
template<class charT, class Allocator, class traits>
bool operator< (const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator< (const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator< (const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(f6lhs).compare(rhs) < 0.
21.1.1.5.5 operator> [lib.string::op>]
template<class charT, class Allocator, class traits>
bool operator> (const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator> (const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator> (const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(f6lhs).compare(rhs) > 0.
21.1.1.5.6 operator<= [lib.string::op<=]
template<class charT, class Allocator, class traits>
bool operator<=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator<=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator<=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(f6lhs).compare(rhs) <= 0.
21.1.1.5.7 operator>= [lib.string::op>=]
template<class charT, class Allocator, class traits>
bool operator>=(const basic_string<charT,Allocator,traits>& lhs,
const basic_string<charT,Allocator,traits>& rhs);
template<class charT, class Allocator, class traits>
bool operator>=(const basic_string<charT,Allocator,traits>& lhs,
const charT* rhs);
template<class charT, class Allocator, class traits>
bool operator>=(const charT* lhs,
const basic_string<charT,Allocator,traits>& rhs);
Returns:
basic_string<charT,Allocator,traits>(f6lhs).compare(rhs) >= 0.
21.1.1.5.8 Inserters and extractors
1 Notes:
Uses traits::char_in and is_del().
template<class charT, class Allocator, class traits>
basic_ostream<charT>&
operator<<(basic_ostream<charT>& os,
const basic_string<charT,Allocator,traits>& a);
Notes:
Uses traits::char_out().
21.1.2 Class string [lib.string]
namespace std {
struct string_char_traits<char> {
typedef char char_type;
static void assign(char_type& c1, const char_type& c2);
static bool eq(const char_type& c1, const char_type& c2);
static bool ne(const char_type& c1, const char_type& c2);
static bool lt(const char_type& c1, const char_type& c2);
static char_type eos();
static int compare(const char_type* s1, const char_type* s2,
size_type n);
static size_type length(const char_type* s);
static char_type* copy(char_type* s1, const char_type* s2, size_type n);
};
typedef basic_string<char> string;
}
21.1.3 string_char_traits<char> [lib.string.traits.members]
members
21.1.3.1 assign [lib.string.traits::assign]
static void assign(char_type& c1, const char_type& c2);
Effects:
c1 = c2
21.1.3.2 eq [lib.string.traits::eq]
static bool eq(const char_type& c1, const char_type& c2);
Returns:
c1 == c2
21.1.3.3 ne [lib.string.traits::ne]
static bool ne(const char_type& c1, const char_type& c2);
Returns:
c1 != c2
21.1.3.4 lt [lib.string.traits::lt]
static bool lt(const char_type& c1, const char_type& c2);
Returns:
c1 < c2
21.1.3.5 eos [lib.string.traits::eos]
static char_type eos();
Returns:
0
21.1.3.6 compare [lib.string.traits::compare]
static int compare(const char_type* s1, const char_type* s2,
size_type n);
Returns:
memcmp(s1,s2,n)
21.1.3.7 length [lib.string.traits::length]
static size_type length(const char_type* s);
Returns:
strlen(s)
21.1.3.8 copy [lib.string.traits::copy]
static char_type* copy(char_type* s1, const char_type* s2, size_type n);
Returns:
memcpy(s1,s2,n)
21.1.4 Class wstring [lib.wstring]
namespace std {
struct string_char_traits<wchar_t> {
typedef wchar_t char_type;
static void assign(char_type& c1, const char_type& c2);
static bool eq(const char_type& c1, const char_type& c2);
static bool ne(const char_type& c1, const char_type& c2);
static bool lt(const char_type& c1, const char_type& c2);
static char_type eos();
static int compare(const char_type* s1, const char_type* s2, size_type n);
static size_type length(const char_type* s);
static char_type* copy(char_type* s1, const char_type* s2, size_type n);
};
typedef basic_string<wchar_t> wstring;
}
21.1.5 string_char_traits<wchar_t> members [lib.wstring.members]
21.1.5.1 assign [lib.wstring::assign]
static void assign(char_type& c1, const char_type& c2);
Effects:
c1 = c2
21.1.5.2 eq [lib.wstring::eq]
static bool eq(const char_type& c1, const char_type& c2);
Returns:
c1 == c2
21.1.5.3 ne [lib.wstring::ne]
static bool ne(const char_type& c1, const char_type& c2);
Returns:
c1 != c2
21.1.5.4 lt [lib.wstring::lt]
static bool lt(const char_type& c1, const char_type& c2);
Returns:
c1 < c2
21.1.5.5 eos [lib.wstring::eos]
static char_type eos();
Returns:
0
21.1.5.6 compare [lib.wstring::compare]
static int compare(const char_type* s1, const char_type* s2,
size_type n);
Returns:
wmemcmp(s1,s2,n)
21.1.5.7 length [lib.wstring::length]
static size_type length(const char_type* s);
Returns:
wcslen(s)
21.1.5.8 copy [lib.wstring::copy]
static char_type* copy(char_type* s1, const char_type* s2,
size_type n);
Returns:
wmemcpy(s1,s2,n)
21.2 Null-terminated sequence utilities [lib.c.strings]
1 Headers <cctype>, <cwctype>, <cstring>, <cwchar>, <cstdlib>( multibyte
conversions), and <ciso646>.
Table 7--Header <cctype> synopsis
+-------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------+
|Functions: |
|isalnum isdigit isprint isupper tolower |
|isalpha isgraph ispunct isxdigit toupper |
|iscntrl islower isspace |
+-------------------------------------------------+
Table 7--Header <cwctype> synopsis
+------------------------------------------------------------------+
| Type Name(s) |
+------------------------------------------------------------------+
|Macro: WEOF <cwctype> |
+------------------------------------------------------------------+
|Types: wctrans_t wctype_t wint_t <cwctype> |
+------------------------------------------------------------------+
|Functions: |
|iswalnum iswctype iswlower iswspace towctrans wctrans |
|iswalpha iswdigit iswprint iswupper towlower wctype |
|iswcntrl iswgraph iswpunct iswxdigit towupper |
+------------------------------------------------------------------+
Table 7--Header <cstring> synopsis
+-------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------+
|Macro: NULL <cstring> |
+-------------------------------------------------+
|Type: size_type <cstring> |
+-------------------------------------------------+
|Functions: |
|strcoll strlen strpbrk strtok |
|strcat strcpy strncat strrchr strxfrm |
|strchr strcspn strncmp strspn |
|strcmp strerror strncpy strstr |
+-------------------------------------------------+
Table 7--Header <cwchar> synopsis
+------------------------------------------------------------------------+
| Type Name(s) |
+------------------------------------------------------------------------+
|Macros: NULL <cwchar> WCHAR_MAX WCHAR_MIN WEOF <cwchar> |
+------------------------------------------------------------------------+
|Types: mbstate_t wint_t <cwchar> |
+------------------------------------------------------------------------+
|Struct: tm <cwchar> |
+------------------------------------------------------------------------+
|Functions: |
|btowc getwchar ungetwc wcscpy wcsrtombs wmemchr |
|fgetwc mbrlen vfwprintf wcscspn wcsspn wmemcmp |
|fgetws mbrtowc vswprintf wcsftime wcsstr wmemcpy |
|fputwc mbsinit vwprintf wcslen wcstod wmemmove |
|fputws mbsrtowcs wcrtomb wcsncat wcstok wmemset |
|fwide putwc wcscat wcsncmp wcstol wprintf |
|fwprintf putwchar wcschr wcsncpy wcstoul wscanf |
|fwscanf swprintf wcscmp wcspbrk wcsxfrm |
|getwc swscanf wcscoll wcsrchr wctob |
+------------------------------------------------------------------------+
Table 7--Header <cstdlib> synopsis
+-----------------------------------------+
| Type Name(s) |
+-----------------------------------------+
|Macros: MB_CUR_MAX |
+-----------------------------------------+
|Functions: |
|atol mblen strtod wctomb |
|atof mbstowcs strtol wcstombs |
|atoi mbtowc stroul |
+-----------------------------------------+
2 The contents are the same as the Standard C library, with the follow
ing 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.
10The 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);
11both of which have the same behavior as the original declaration.
12The function signature memchr(const void*, int, size_type) is replaced
by the two declarations:
const void* memchr(const void* s, int c, size_type n);
void* memchr( void* s, int c, size_type n);
13both 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.