______________________________________________________________________
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 (_lib.strings_), and
null-terminated sequence utilities (_lib.c.strings_).
21.1 String classes [lib.string.classes]
1 Headers:
--<string>
2 Table 1:
Table 1--Header <string> synopsis
+--------------------------------------------------------------+
| Type Name(s) |
+--------------------------------------------------------------+
|Types: string |
| wstring |
+--------------------------------------------------------------+
|Template class: basic_string |
+--------------------------------------------------------------+
|Operator functions: |
|operator!= (basic_string) [5] operator== (basic_string) [5] |
|operator+ (basic_string) [5] operator>> (basic_string) |
|operator<< (basic_string) |
+--------------------------------------------------------------+
|Function: getline |
+--------------------------------------------------------------+
3 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.
4 The header <string> defines a basic string class template and its bag
gage that can handle all ``char-like'' template arguments with several
function signatures for manipulating varying-length sequences of
``char-like'' objects.
5 The header <string> also defines two specific template classes string
and wstring and their special baggages.
21.1.1 Template class basic_string [lib.template.string]
21.1.1.1 Template class [lib.string.char.baggage]
string_char_baggage
+------- BEGIN BOX 1 -------+
At the Kitchener meeting, the Library WG decided to change the names
used from ``baggage'' to ``traits''. However, Tom Plum objected to
doing this without a formal proposal and vote. These names are there
fore unresolved, and subject to change.
+------- END BOX 1 -------+
template<class charT>
struct string_char_baggage {
typedef charT char_type;
// for users to acquire the basic character type
// constraints
static void assign(char_type& c1, const char_type& c2)
{ c1 = c2; }
static bool eq(const char_type& c1, const char_type& c2)
{ return (c1 == c2); }
static bool ne(const char_type& c1, const char_type& c2)
{ return !(c1 == c2); }
static bool lt(const char_type& c1, const char_type& c2)
{ return (c1 < c2); }
static char_type eos() { return char_type(); }
// the null character
static basic_istream<charT>&
char_in(basic_istream<charT>& is, charT& a) {
return is >> a; // extractor for a charT object
}
static basic_ostream<charT>&
char_out(basic_ostream<charT>& os, charT a) {
return os << a; // inserter for a charT object
}
static bool is_del(charT a) { return isspace(a); }
// characteristic function for delimiters of charT
// speed-up functions
static int compare(const char_type* s1, const char_type* s2,
size_t n) {
for (size_t i = 0; i < n; ++i, ++s1, ++s2)
if (ne(*s1, *s2)) {
return lt(*s1, *s2) ? -1 : 1;
}
return 0;
}
static size_t length(const char_type* s) {
size_t l = 0;
while (ne(*s++, eos()) ++l;
return l;
}
static char_type* copy(char_type* s1, const char_type* s2, size_t n) {
char_type* s = s1;
for (size_t i = 0; i < n; ++i) assign(*++s1, *++s2);
return s;
}
};
21.1.1.2 Template class basic_string [lib.basic.string]
template<class charT, class baggage = string_char_baggage<charT> >
class basic_string {
public:
typedef charT char_type;
typedef baggage baggage_type;
basic_string();
basic_string(size_t size, capacity cap);
basic_string(const basic_string& str, size_t pos = 0, size_t n = NPOS);
basic_string(const charT* s, size_t n);
basic_string(const charT* s);
basic_string(charT c, size_t rep = 1);
~basic_string();
basic_string& operator=(const basic_string& str);
basic_string& operator=(const charT* s);
basic_string& operator=(charT c);
basic_string& operator+=(const basic_string& rhs);
basic_string& operator+=(const charT* s);
basic_string& operator+=(charT c);
basic_string& append(const basic_string& str, size_t pos = 0, size_t n = NPOS);
basic_string& append(const charT* s, size_t n);
basic_string& append(const charT* s);
basic_string& append(charT c, size_t rep = 1);
basic_string& assign(const basic_string& str, size_t pos = 0, size_t n = NPOS);
basic_string& assign(const charT* s, size_t n);
basic_string& assign(const charT* s);
basic_string& assign(charT c, size_t rep = 1);
basic_string& insert(size_t pos1, const basic_string& str, size_t pos2 = 0,
size_t n = NPOS);
basic_string& insert(size_t pos, const charT* s, size_t n);
basic_string& insert(size_t pos, const charT* s);
basic_string& insert(size_t pos, charT c, size_t rep = 1);
basic_string& remove(size_t pos = 0, size_t n = NPOS);
basic_string& replace(size_t pos1, size_t n1, const basic_string& str,
size_t pos2 = 0, size_t n2 = NPOS);
basic_string& replace(size_t pos, size_t n1, const charT* s, size_t n2);
basic_string& replace(size_t pos, size_t n1, const charT* s);
basic_string& replace(size_t pos, size_t n, charT c, size_t rep = 1);
charT get_at(size_t pos) const;
void put_at(size_t pos, charT c);
charT operator[](size_t pos) const;
charT& operator[](size_t pos);
const charT* c_str() const;
const charT* data() const;
size_t length() const:
void resize(size_t n, charT c);
void resize(size_t n);
size_t reserve() const;
void reserve(size_t res_arg);
size_t copy(charT* s, size_t n, size_t pos = 0);
size_t find(const basic_string& str, size_t pos = 0) const;
size_t find(const charT* s, size_t pos, size_t n) const;
size_t find(const charT* s, size_t pos = 0) const;
size_t find(charT c, size_t pos = 0) const;
size_t rfind(const basic_string& str, size_t pos = NPOS) const;
size_t rfind(const charT* s, size_t pos, size_t n) const;
size_t rfind(const charT* s, size_t pos = NPOS) const;
size_t rfind(charT c, size_t pos = NPOS) const;
size_t find_first_of(const basic_string& str, size_t pos = 0) const;
size_t find_first_of(const charT* s, size_t pos, size_t n) const;
size_t find_first_of(const charT* s, size_t pos = 0) const;
size_t find_first_of(charT c, size_t pos = 0) const;
size_t find_last_of (const basic_string& str, size_t pos = NPOS) const;
size_t find_last_of (const charT* s, size_t pos, size_t n) const;
size_t find_last_of (const charT* s, size_t pos = NPOS) const;
size_t find_last_of (charT c, size_t pos = NPOS) const;
size_t find_first_not_of(const basic_string& str, size_t pos = 0) const;
size_t find_first_not_of(const charT* s, size_t pos, size_t n) const;
size_t find_first_not_of(const charT* s, size_t pos = 0) const;
size_t find_first_not_of(charT c, size_t pos = 0) const;
size_t find_last_not_of (const basic_string& str, size_t pos = NPOS) const;
size_t find_last_not_of (const charT* s, size_t pos, size_t n) const;
size_t find_last_not_of (const charT* s, size_t pos = NPOS) const;
size_t find_last_not_of (charT c, size_t pos = NPOS) const;
basic_string substr(size_t pos = 0, size_t n = NPOS) const;
int compare(const basic_string& str, size_t pos = 0, size_t n = NPOS) const;
int compare(charT* s, size_t pos, size_t n) const;
int compare(charT* s, size_t pos = 0) const;
int compare(charT c, size_t pos = 0, size_t rep = 1) const;
private:
static charT eos() { return baggage::eos(); }
// charT* ptr; exposition only
// size_t len, res; exposition only
};
1 For a char-like type charT, the template class
basic_string<charT,baggage> 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<charT,baggage>.
2 For the sake of exposition, the maintained data is presented here as:
--charT* ptr, points to the initial char-like object of the string;
--size_t len, counts the number of char-like objects currently in the
string;
--size_t res, for an unallocated string, holds the estimated maximum
size of the string, while for an allocated string, becomes the cur
rently allocated size.
3 In all cases, len <= res.
4 The functions described in this clause can report two kinds of errors,
each associated with a distinct exception:
--a length error is associated with exceptions of type length_error;
--an out-of-range error is associated with exceptions of type
out_of_range.
21.1.1.3 basic_string member functions [lib.string.members]
21.1.1.3.1 basic_string constructors [lib.string.cons]
basic_string();
1 Constructs an object of class basic_string<charT,baggage>.
2 The postconditions of this function are indicated in Table 2:
Table 2--basic_string() effects
+-------------------------------+
|Element Value |
+-------------------------------+
|ptr an unspecified value |
|len 0 |
|res an unspecified value |
+-------------------------------+
basic_string(size_t size, capacity cap);
3 Constructs an object of class basic_string<charT,baggage>. If cap is
default_size, the function either throws length_error if size equals
NPOS or initializes the string as indicated in Table 3:
Table 3--basic_string(size_t,capacity) effects
+-------------------------------------------+
|Element Value |
+-------------------------------------------+
|ptr points at the first element of |
| an allocated array of size ele |
| ments, each of which is initial |
| ized to zero |
|len size |
|res a value at least as large as len |
+-------------------------------------------+
4 Otherwise, cap shall be reserve and the function initializes the
string as indicated in Table 4:
Table 4--basic_string(size_t,capacity) effects
+-------------------------------+
|Element Value |
+-------------------------------+
|ptr an unspecified value |
|len 0 |
|res size |
+-------------------------------+
basic_string(const basic_string<charT,baggage>& str,
size_t pos = 0, size_t n = NPOS);
5 Throws out_of_range if pos > str.len. Otherwise, the function con
structs an object of class basic_string<charT,baggage> and determines
the effective length rlen of the initial string value as the smaller
of n and str.len - pos. Thus, the function initializes the string as
indicated in Table 5:
Table 5--basic_string(basic_string,size_t,size_t) effects
+-------------------------------------------+
|Element Value |
+-------------------------------------------+
|ptr points at the first element of |
| an allocated copy of rlen ele |
| ments of the string controlled |
| by str beginning at position pos |
|len rlen |
|res a value at least as large as len |
+-------------------------------------------+
basic_string(const charT* s, size_t n = NPOS);
6 Constructs an object of class basic_string<charT,baggage> and deter
mines its initial string value from the array of charT of length n
whose first element is designated by s. s shall not be a null
pointer. Thus, the function initializes the string as indicated in
Table 6:
Table 6--basic_string(const charT*,size_t) effects
+-------------------------------------------+
|Element Value |
+-------------------------------------------+
|ptr points at the first element of |
| an allocated copy of the array |
| whose first element is pointed |
| at by s |
|len n |
|res a value at least as large as len |
+-------------------------------------------+
basic_string(const charT* s);
7 Constructs an object of class basic_string<charT,baggage> and deter
mines its initial string value from the array of charT of length bag
gage::length(s) whose first element is designated by s. s shall not
be a null pointer. Thus, the function initializes the string as indi
cated in Table 7:
Table 7--basic_string(const charT*) effects
+-------------------------------------------+
|Element Value |
+-------------------------------------------+
|ptr points at the first element of |
| an allocated copy of the array |
| whose first element is pointed |
| at by s |
|len baggage::length(s) |
|res a value at least as large as len |
+-------------------------------------------+
8 Uses baggage::length().
basic_string(charT c, size_t rep = 1);
9 Throws length_error if rep equals NPOS. Otherwise, the function con
structs an object of class basic_string<charT,baggage> and determines
its initial string value by repeating the char-like object c for all
rep elements. Thus, the function initializes the string as indicated
in Table 8:
Table 8--basic_string(charT,size_t) effects
+-------------------------------------------+
|Element Value |
+-------------------------------------------+
|ptr points at the first element of |
| an allocated array of rep ele |
| ments, each storing the initial |
| value c |
|len rep |
|res a value at least as large as len |
+-------------------------------------------+
21.1.1.3.2 basic_string destructor [lib.string.des]
~basic_string();
1 Destroys an object of class basic_string<charT,baggage>.
21.1.1.3.3 basic_string::operator= [lib.string::op=]
basic_string<charT,baggage>& operator=(const basic_string<charT,baggage>& str);
1 Returns *this = basic_string<charT,baggage>(str).
basic_string<charT,baggage>& operator=(const charT* s);
2 Returns *this = basic_string<charT,baggage>(s).
3 Uses baggage::length().
basic_string<charT,baggage>& operator=(charT c);
4 Returns *this = basic_string<charT,baggage>(c).
21.1.1.3.4 basic_string::operator+= [lib.string::op+=]
basic_string<charT,baggage>& operator+=(const basic_string<charT,baggage>& rhs);
1 Returns append(rhs).
basic_string<charT,baggage>& operator+=(const charT* s);
2 Returns *this += basic_string<charT,baggage>(s).
3 Uses baggage::length().
basic_string<charT,baggage>& operator+=(charT c);
4 Returns *this += basic_string<charT,baggage>(c).
21.1.1.3.5 basic_string::append [lib.string::append]
basic_string<charT,baggage>& append(const basic_string<charT,baggage>& str,
size_t pos = 0, size_t n = NPOS);
1 Throws out_of_range if pos > str.len. Otherwise, the function deter
mines the effective length rlen of the string to append as the smaller
of n and str.len - pos. The function then throws length_error if len
>= NPOS - rlen.
2 Otherwise, the function replaces the string controlled by *this with a
string of length len + rlen whose first len 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.
3 Returns *this.
basic_string<charT,baggage>& append(const charT* s, size_t n);
4 Returns append(basic_string(s, n)).
basic_string<charT,baggage>& append(const charT* s);
5 Returns append(basic_string<charT,baggage>(s)).
6 Uses baggage::length().
basic_string<charT,baggage>& append(charT c, size_t rep = 1);
7 Returns append(basic_string<charT,baggage>(c, rep)).
21.1.1.3.6 basic_string::assign [lib.string::assign]
basic_string<charT,baggage>& assign(const basic_string<charT,baggage>& str,
size_t pos = 0, size_t n = NPOS);
1 Throws out_of_range if pos > str.len. Otherwise, the function deter
mines the effective length rlen of the string to assign as the smaller
of n and str.len - pos.
2 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.
3 Returns *this.
basic_string<charT,baggage>& assign(const charT* s, size_t n);
4 Returns assign(basic_string<charT,baggage>(s, n)).
basic_string<charT,baggage>& assign(const charT* s);
5 Returns assign(basic_string(s)).
6 Uses baggage::length().
basic_string<charT,baggage>& assign(charT c, size_t rep = 1);
7 Returns assign(basic_string<charT,baggage>(c, rep)).
21.1.1.3.7 basic_string::insert [lib.string::insert]
basic_string<charT,baggage>&
insert(size_t pos1, const basic_string<charT,baggage>& str,
size_t pos2 = 0, size_t n = NPOS);
1 Throws out_of_range if pos1 > len or pos2 > str.len. Otherwise, the
function determines the effective length rlen of the string to insert
as the smaller of n and str.len - pos2. Then throws length_error if
len >= NPOS - rlen.
2 Otherwise, the function replaces the string controlled by *this with a
string of length len + 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.
3 Returns *this.
basic_string<charT,baggage>& insert(size_t pos, const charT* s, size_t n);
4 Returns insert(pos, basic_string<charT,baggage>(s, n)).
basic_string<charT,baggage>& insert(size_t pos, const charT* s);
5 Returns insert(pos, basic_string(s)).
6 Uses baggage::length().
basic_string<charT,baggage>& insert(size_t pos, charT c, size_t rep = 1);
7 Returns insert(pos, basic_string<charT,baggage>(c, rep)).
21.1.1.3.8 basic_string::remove [lib.string::remove]
basic_string<charT,baggage>& remove(size_t pos = 0, size_t n = NPOS);
1 Throws out_of_range if pos > len. Otherwise, the function determines
the effective length xlen of the string to be removed as the smaller
of n and len - pos.
2 The function then replaces the string controlled by *this with a
string of length len - 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.
3 Returns *this.
21.1.1.3.9 basic_string::replace [lib.string::replace]
basic_string<charT,baggage>&
replace(size_t pos1, size_t n1,
const basic_string<charT,baggage>& str,
size_t pos2 = 0, size_t n2 = NPOS);
1 Throws out_of_range if pos1 > len or pos2 > str.len. Otherwise, the
function determines the effective length xlen of the string to be
removed as the smaller of n1 and len - pos1. It also determines the
effective length rlen of the string to be inserted as the smaller of
n2 and str.len - pos2. Then throws length_error if len - xlen >= NPOS
- rlen.
2 Otherwise, the function replaces the string controlled by *this with a
string of length len - 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.
3 Returns *this.
basic_string<charT,baggage>& replace(size_t pos, size_t n1,
const charT* s, size_t n2);
4 Returns replace(pos, n1, basic_string<charT,baggage>(s, n2)).
basic_string<charT,baggage>& replace(size_t pos, size_t n1, const charT* s);
5 Returns replace(pos, n1, basic_string<charT,baggage>(s)).
6 Uses baggage::length().
basic_string<charT,baggage>& replace(size_t pos, size_t n,
charT c, size_t rep = 1);
7 Returns replace(pos, n, basic_string<charT,baggage>(c, rep)).
21.1.1.3.10 basic_string::get_at [lib.string::get.at]
charT get_at(size_t pos) const;
1 Throws out_of_range if pos >= len. Otherwise, returns ptr[pos].
21.1.1.3.11 basic_string::put_at [lib.string::put.at]
void put_at(size_t pos, charT c);
1 Throws out_of_range if pos > len. 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].
21.1.1.3.12 basic_string::operator[] [lib.string::op.array]
charT operator[](size_t pos) const;
charT& operator[](size_t pos);
1 If pos < len, returns ptr[pos]. Otherwise, if pos == len, the const
version returns zero. Otherwise, the behavior is undefined.
2 The reference returned by the non-const version is invalid after any
subsequent call to c_str or any non-const member function for the
object.
21.1.1.3.13 basic_string::c_str [lib.string::c.str]
const charT* c_str() const;
1 Returns a pointer to the initial element of an array of length len + 1
whose first len elements equal the corresponding elements of the
string controlled by *this and whose last element is a null character
specified by eos(). 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 mem
ber function of the class basic_string<charT,baggage> that designates
the same object as this.
2 Uses baggage::eos().
21.1.1.3.14 basic_string::data [lib.string::data]
const charT* data() const;
1 Returns ptr if len is nonzero, otherwise a null pointer. 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 the class
basic_string<charT,baggage> that designates the same object as this.
21.1.1.3.15 basic_string::length [lib.string::length]
size_t length() const:
1 Returns len.
21.1.1.3.16 basic_string::resize [lib.string::resize]
void resize(size_t n, charT c);
1 Throws length_error if n equals NPOS. Otherwise, the function alters
the length of the string designated by *this as follows:
2 If n <= len, 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.
3 If n > len, the function replaces the string designated by *this with
a string of length n whose first len elements are a copy of the origi
nal string designated by *this, and whose remaining elements are all
initialized to c.
void resize(size_t n);
4 Returns resize(n, eos()).
5 Uses baggage::eos().
21.1.1.3.17 basic_string::reserve [lib.string::reserve]
size_t reserve() const;
1 Returns res.
void reserve(size_t res_arg);
2 If no string is allocated, the function assigns res_arg to res. Oth
erwise, whether or how the function alters res is unspecified.
21.1.1.3.18 basic_string::copy [lib.string::copy]
size_t copy(charT* s, size_t n, size_t pos = 0);
1 Throws out_of_range if pos > len. Otherwise, the function determines
the effective length rlen of the string to copy as the smaller of n
and len - pos. s shall designate an array of at least rlen elements.
2 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)
3 Returns rlen.
21.1.1.3.19 basic_string::find [lib.string::find]
size_t find(const basic_string<charT,baggage>& str, size_t pos = 0) const;
1 Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos + str.len <= len;
--baggage::eq(ptr[xpos + I], str.ptr[I]) for all elements I of the
string controlled by str.
2 Returns xpos if the function can determine such a value forxpos. Oth
erwise, returns NPOS.
size_t find(const charT* s, size_t pos, size_t n) const;
3 Returns find(basic_string(s, n), pos).
size_t find(const charT* s, size_t pos = 0) const;
_________________________
1) The function does not append a null object to the string.
4 Returns find(basic_string<charT,baggage>(s), pos).
5 Uses baggage::length().
size_t find(charT c, size_t pos = 0) const;
6 Returns find(basic_string<charT,baggage>(c), pos).
21.1.1.3.20 basic_string::rfind [lib.rfind]
size_t rfind(const basic_string<charT,baggage>& str, size_t pos = NPOS) const;
1 Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and xpos + str.len <= len;
--baggage::eq(ptr[xpos + I], str.ptr[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.
size_t rfind(const charT* s, size_t pos, size_t n) const;
3 Returns rfind(basic_string<charT,baggage>(s, n), pos).
size_t rfind(const charT* s, size_t pos = NPOS) const;
4 Returns rfind(basic_string(s), pos).
5 Uses baggage::length().
size_t rfind(charT c, size_t pos = NPOS) const;
6 Returns rfind(basic_string<charT,baggage>(c, n), pos).
21.1.1.3.21 [lib.string::find.first.of]
basic_string::find_first_of
size_t find_first_of(const basic_string<charT,baggage>& str,
size_t pos = 0) const;
1 Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos < len;
--baggage::eq(ptr[xpos], str.ptr[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.
size_t find_first_of(const charT* s, size_t pos, size_t n) const;
3 Returns find_first_of(basic_string(s, n), pos).
size_t find_first_of(const charT* s, size_t pos = 0) const;
4 Returns find_first_of(basic_string(s), pos).
5 Uses baggage::length().
size_t find_first_of(charT c, size_t pos = 0) const;
6 Returns find_first_of(basic_string(c), pos).
21.1.1.3.22 [lib.string::find.last.of]
basic_string::find_last_of
size_t find_last_of(const basic_string<charT,baggage>& str,
size_t pos = NPOS) const;
1 Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and pos < len;
--baggage::eq(ptr[xpos], str.ptr[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.
size_t find_last_of(const charT* s, size_t pos, size_t n) const;
3 Returns find_last_of(basic_string(s, n), pos).
size_t find_last_of(const charT* s, size_t pos = NPOS) const;
4 Returns find_last_of(basic_string(s), pos).
5 Uses baggage::length().
size_t find_last_of(charT c, size_t pos = NPOS) const;
6 Returns find_last_of(basic_string<charT,baggage>(c), pos).
21.1.1.3.23 [lib.string::find.first.not.of]
basic_string::find_first_not_of
size_t find_first_not_of(const basic_string<charT,baggage>& str,
size_t pos = 0) const;
1 Determines the lowest position xpos, if possible, such that both of
the following conditions obtain:
--pos <= xpos and xpos < len;
--baggage::eq(ptr[xpos], str.ptr[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.
size_t find_first_not_of(const charT* s, size_t pos, size_t n) const;
3 Returns find_first_not_of(basic_string<charT,baggage>(s, n), pos).
size_t find_first_not_of(const charT* s, size_t pos = 0) const;
4 Returns find_first_not_of(basic_string<charT,baggage>(s), pos).
5 Uses baggage::length().
size_t find_first_not_of(charT, size_t pos = 0) const;
6 Returns find_first_not_of(basic_string(c), pos).
21.1.1.3.24 [lib.string::find.last.not.of]
basic_string::find_last_not_of
size_t find_last_not_of(const basic_string<charT,baggage>& str,
size_t pos = NPOS) const;
1 Determines the highest position xpos, if possible, such that both of
the following conditions obtain:
--xpos <= pos and pos < len;
--baggage::eq(ptr[xpos], str.ptr[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.
size_t find_last_not_of(const charT* s, size_t pos, size_t n) const;
3 Returns find_last_not_of(basic_string(s, n), pos).
size_t find_last_not_of(const charT* s, size_t pos = NPOS) const;
4 Returns find_last_not_of(basic_string<charT,baggage>(s), pos).
5 Uses baggage::length().
size_t find_last_not_of(charT c, size_t pos = NPOS) const;
6 Returns find_last_not_of(basic_string<charT,baggage>(c), pos).
21.1.1.3.25 basic_string::substr [lib.string::substr]
basic_string<charT,baggage> substr(size_t pos = 0,
size_t n = NPOS) const;
1 Throws out_of_range if pos > len. Otherwise, the function determines
the effective length rlen of the string to copy as the smaller of n
and len - pos.
2 Returns basic_string(ptr + pos, rlen).
21.1.1.3.26 basic_string::compare [lib.string::compare]
int compare(const basic_string<charT,baggage>& str,
size_t pos = 0, size_t n = NPOS)
1 Throws out_of_range if pos > len. Otherwise, the function determines
the effective length rlen of the strings to compare as the smallest of
n, len - pos, and str.len. The function then compares the two strings
by calling baggage::compare(ptr + pos, str.ptr, rlen).
2 Returns the nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 9:
Table 9--compare() results
+----------------------------------------------+
| Condition Return Value |
+----------------------------------------------+
|len - pos < str.len a value less than 0 |
|len - pos == str.len 0 |
|len - pos > str.len a value greater than 0 |
+----------------------------------------------+
--if len < rlen, a value less than zero;
--if len == rlen, the value zero;
--if len > rlen, a value greater than zero.
3 Uses baggage::compare().
int compare(const charT* s, size_t pos, size_t n) const;
4 Returns compare(basic_string<charT,baggage>(s, n), pos).
5 Uses baggage::compare().
int compare(const charT* s, size_t pos = 0) const;
6 Returns compare(basic_string<charT,baggage>(s), pos).
7 Uses baggage::length() and baggage::compare().
int compare(charT c, size_t pos = 0, size_t rep = 1) const;
8 Returns compare(basic_string(c, rep), pos).
9 Uses baggage::compare().
21.1.1.4 basic_string non-member [lib.string.nonmembers]
functions
21.1.1.4.1 operator+ [lib.string::op+]
basic_string<charT,baggage>
operator+(const basic_string<charT,baggage>& lhs,
const basic_string<charT,baggage>& rhs);
1 Returns basic_string<charT,baggage>(lhs).append(rhs).
basic_string<charT,baggage>
operator+(const charT* lhs, const basic_string<charT,baggage>& rhs);
2 Returns basic_string<charT,baggage>(lhs) + rhs.
3 Uses baggage::length().
basic_string<charT,baggage>
operator+(charT lhs, const basic_string<charT,baggage>& rhs);
4 Returns basic_string<charT,baggage>(lhs) + rhs.
basic_string<charT,baggage>
operator+(const basic_string<charT,baggage>& lhs, const charT* rhs);
5 Returns basic_string(lhs) + basic_string(rhs).
6 Uses baggage::length().
basic_string<charT,baggage>
operator+(const basic_string<charT,baggage>& lhs, charT rhs);
7 Returns lhs + basic_string<charT,baggage>(rhs).
21.1.1.4.2 operator== [lib.string::operator==]
bool operator==(const basic_string<charT,baggage>& lhs,
const basic_string<charT,baggage>& rhs);
1 Returns the value true if lhs.compare(rhs) is zero.
bool operator==(const charT* lhs, const basic_string<charT,baggage>& rhs);
2 Returns basic_string<charT,baggage>(lhs) == rhs.
3 Uses baggage::length().
bool operator==(charT lhs, const basic_string<charT,baggage>& rhs);
4 Returns basic_string(lhs) == rhs.
bool operator==(const basic_string<charT,baggage>& lhs, const charT* rhs);
5 Returns lhs == basic_string<charT,baggage>(rhs).
6 Uses baggage::length().
bool operator==(const basic_string<charT,baggage>& lhs, charT rhs);
7 Returns lhs == basic_string<charT,baggage>(rhs).
21.1.1.4.3 operator!= [lib.string::op!=]
bool operator!=(const basic_string<charT,baggage>& lhs,
const basic_string<charT,baggage>& rhs);
1 Returns the value true if lhs.compare(rhs) is nonzero.
bool operator!=(const charT* lhs, const basic_string<charT,baggage>& rhs);
2 Returns basic_string<charT,baggage>(lhs) != rhs.
3 Uses baggage::length().
bool operator!=(charT lhs, const basic_string<charT,baggage>& rhs);
4 Returns basic_string<charT,baggage>(lhs) != rhs.
bool operator!=(const basic_string<charT,baggage>& lhs, const charT* rhs);
5 Returns lhs != basic_string<charT,baggage>(rhs).
6 Uses baggage::length().
bool operator!=(const basic_string<charT,baggage>& lhs, charT rhs);
7 Returns lhs != basic_string<charT,baggage>(rhs).
21.1.1.4.4 Inserters and extractors
1 template<class charT>
basic_istream<charT>&
operator>>(basic_istream<charT>& is, basic_string<charT>& a);
2 Implement with string_char_baggage<charT>::char_in and is_del().
template<class charT>
basic_ostream<charT>&
operator<<(basic_ostream<charT>& os, const basic_string<charT>& a);
3 Implement with string_char_baggage<charT>::char_out().
21.1.2 Class string [lib.string]
struct string_char_baggage<char> {
typedef char char_type;
static void assign(char_type& c1, const char_type& c2)
{ c1 = c2; }
static bool eq(const char_type& c1, const char_type& c2)
{ return (c1 == c2); }
static bool ne(const char_type& c1, const char_type& c2)
{ return (c1 != c2); }
static bool lt(const char_type& c1, const char_type& c2)
{ return (c1 < c2); }
static char_type eos() { return 0; }
static int compare(const char_type* s1, const char_type* s2,
size_t n) {
return memcmp(s1, s2, n);
}
static size_t length(const char_type* s) {
return strlen(s);
}
static char_type* copy(char_type* s1, const char_type* s2, size_t n) {
return memcpy(s1, s2, n);
}
};
typedef basic_string<char> string;
21.1.3 Class wstring [lib.wstring]
struct string_char_baggage<wchar_t> {
typedef wchar_t char_type;
static void assign(char_type& c1, const char_type& c2)
{ c1 = c2; }
static bool eq(const char_type& c1, const char_type& c2)
{ return (c1 == c2); }
static bool ne(const char_type& c1, const char_type& c2)
{ return (c1 != c2); }
static bool lt(const char_type& c1, const char_type& c2)
{ return (c1 < c2); }
static char_type eos() { return 0; }
static int compare(const char_type* s1, const char_type* s2, size_t n) {
return wmemcmp(s1, s2, n);
}
static size_t length(const char_type* s) {
return wcslen(s);
}
static char_type* copy(char_type* s1, const char_type* s2, size_t n) {
return wmemcpy(s1, s2, n);
}
};
typedef basic_string<wchar_t> wstring;
21.2 Null-terminated sequence utilities [lib.c.strings]
1 Headers:
--<cctype>
--<cwctype>
--<cstring>
--<cwchar>
--<cstdlib> multibyte conversions
--<ciso646>
2 Table 10:
Table 10--Header <cctype> synopsis
+-------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------+
|Functions: |
|isalnum isdigit isprint isupper tolower |
|isalpha isgraph ispunct isxdigit toupper |
|iscntrl islower isspace |
+-------------------------------------------------+
3 Table 11:
Table 11--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 |
+------------------------------------------------------------------+
4 Table 12:
Table 12--Header <cstring> synopsis
+-------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------+
|Macro: NULL <cstring> |
+-------------------------------------------------+
|Type: size_t <cstring> |
+-------------------------------------------------+
|Functions: |
|strcoll strlen strpbrk strtok |
|strcat strcpy strncat strrchr strxfrm |
|strchr strcspn strncmp strspn |
|strcmp strerror strncpy strstr |
+-------------------------------------------------+
5 Table 13:
Table 13--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 |
+------------------------------------------------------------------------+
6 Table 14:
Table 14--Header <cstdlib> synopsis
+-----------------------------------------+
| Type Name(s) |
+-----------------------------------------+
|Macros: MB_CUR_MAX |
+-----------------------------------------+
|Functions: |
|atol mblen strtod wctomb |
|atof mbstowcs strtol wcstombs |
|atoi mbtowc stroul |
+-----------------------------------------+
7 The contents are the same as the Standard C library, with the follow
ing modifications:
8 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);
9 both of which have the same behavior as the original declaration.
10The 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);
11both of which have the same behavior as the original declaration.
12The 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);
13both of which have the same behavior as the original declaration.
14The 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);
15both of which have the same behavior as the original declaration.
16The 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);
17both 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.