The <
s
trin
g
>
header declares the class templates and functions that support the string
and wstring
types, which are specializations of the basic_string
class template. The string types offer greater ease-of-use and safety than C-style character arrays. Another important class template is char_traits
, which describes a character type and is used throughout the standard library.
Example 13-39 shows a function that classifies a string as an identifier, integer, floating point, or other.
Example 13-39: Classifying a string.
#include <iostream> #include <string> enum kind { empty, ident, integer, floatingpt, error }; kind classify(const std::string& s) { using std::string; const std::string lower("abcdefghijklmnopqrstuvwxyz"); const std::string upper("ABCDEFGHIJKLMNOPQRSTUVWXYZ"); const std::string letters = lower + upper + '_'; const std::string digits("0123456789"); const std::string identchars = letters + digits; if (s.empty()) return empty; else if (letters.find_first_of(s[0]) != string::npos) { // Check for valid identifier. if (s.find_first_not_of(identchars, 1) == string::npos) return ident; else return error; } // Skip a leading sign, if present. string::size_type pos; if (s[0] == '+' or s[0] == '-') pos = 1; else pos = 0; // The number must start with a digit. if (pos == s.length()) return error; if (not digits.find_first_of(s[pos])) return error; // Find where the digit string ends. pos = s.find_first_not_of(digits, pos); if (pos == string::npos) // Only digits => integer. return integer; else if (s[pos] == '.') { // There is a decimal point. pos = s.find_first_not_of(digits, pos+1); if (pos == string::npos) // Integer part "." fractional part return floatingpt; } // Look for optional exponent. if (s[pos] == 'e' or s[pos] == 'E') { if (pos == s.length() - 1) return error; // 'e' or 'E' is last char else if (s[pos+1] == '+' or s[pos+1] == '-') ++pos; // skip over sign; if (pos == s.length() - 1) return error; // sign is last char pos = s.find_first_not_of(digits, pos+1); if (pos == string::npos) return floatingpt; } return error; }
Base class for string types
template<class charT, class traits = char_traits<charT>, class Alloc = allocator<charT> > class basic_string { public: typedef traits traits_type; typedef typename traits::char_type value_type; typedef Alloc allocator_type; typedef typename Alloc::size_type size_type; typedef typename Alloc::difference_type difference_type; typedef typename Alloc::reference reference; typedef typename Alloc::const_reference const_reference; typedef typename Alloc::pointer pointer; typedef typename Alloc::const_pointer const_pointer; typedef ... iterator; typedef ... const_iterator; typedef std::reverse_iterator<iterator> reverse_iterator; typedef std::reverse_iterator<const_iterator> const_reverse_iterator; static const size_type npos = -1; explicit basic_string(const Alloc& a = Alloc()); basic_string(const basic_string& str); basic_string(const basic_string& str, size_type pos, size_type n = npos, const Alloc& a = Alloc()); basic_string(const charT* s, size_type n, const Alloc& a = Alloc()); basic_string(const charT* s, const Alloc& a = Alloc()); basic_string(size_type n, charT c, const Alloc& a=Alloc()); template<class InputIterator> basic_string(InputIterator begin, InputIterator end, const Alloc& a = Alloc()); ~basic_string(); basic_string& operator=(const basic_string& str); basic_string& operator=(const charT* s); basic_string& operator=(charT c); iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() const; reverse_iterator rbegin(); const_reverse_iterator rbegin() const; reverse_iterator rend(); const_reverse_iterator rend() const; // capacity: size_type size() const; size_type length() const; size_type max_size() const; void resize(size_type n, charT c); void resize(size_type n); size_type capacity() const; void reserve(size_type res_arg = 0); void clear(); bool empty() const; // element access: const_reference operator[](size_type pos) const; reference operator[](size_type pos); const_reference at(size_type n) const; reference at(size_type n); basic_string substr(size_type pos = 0, size_type n = npos) const; // modifiers: basic_string& operator+=(const basic_string& str); basic_string& operator+=(const charT* s); basic_string& operator+=(charT c); basic_string& append(const basic_string& str); basic_string& append(const basic_string& str, size_type pos, size_type n); basic_string& append(const charT* s, size_type n); basic_string& append(const charT* s); basic_string& append(size_type n, charT c); template<class InputIter> basic_string& append(InputIter first, InputIter last); void push_back(charT c); basic_string& assign(const basic_string& str); basic_string& assign(const basic_string& str, size_type pos, size_type n); basic_string& assign(const charT* s, size_type n); basic_string& assign(const charT* s); basic_string& assign(size_type n, charT c); template<class InputIter> basic_string& assign(InputIter first, InputIter last); basic_string& insert(size_type pos1, const basic_string& str); basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n); basic_string& insert(size_type pos, const charT* s, size_type n); basic_string& insert(size_type pos, const charT* s); basic_string& insert(size_type pos, size_type n, charT c); iterator insert(iterator p, charT c); void insert(iterator p, size_type n, charT c); template<class InputIter> void insert(iterator p, InputIter first, InputIter last); basic_string& erase(size_type pos = 0, size_type n = npos); iterator erase(iterator position); iterator erase(iterator first, iterator last); basic_string& replace(size_type pos1, size_type n1, const basic_string& str); basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2); basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2); basic_string& replace(size_type pos, size_type n1, const charT* s); basic_string& replace(size_type pos, size_type n1, size_type n2, charT c); basic_string& replace(iterator i1, iterator i2, const basic_string& str); basic_string& replace(iterator i1, iterator i2, const charT* s, size_type n); basic_string& replace(iterator i1, iterator i2, const charT* s); basic_string& replace(iterator i1, iterator i2, size_type n, charT c); template<class InputIterator> basic_string& replace(iterator i1, iterator i2, InputIterator j1, InputIterator j2); size_type copy(charT* s, size_type n, size_type pos = 0) const; void swap(basic_string& str); // string operations: const charT* c_str() const; const charT* data() const; allocator_type get_allocator() const; // Searching: size_type find(const basic_string& str, size_type pos = 0) const; size_type find(const charT* s, size_type pos, size_type n) const; size_type find(const charT* s, size_type pos = 0) const; size_type find(charT c, size_type pos = 0) const; size_type rfind(const basic_string& str, size_type pos = npos) const; size_type rfind(const charT* s, size_type pos, size_type n) const; size_type rfind(const charT* s, size_type pos=npos) const; size_type rfind(charT c, size_type pos = npos) const; size_type find_first_of(const basic_string& str, size_type pos = 0) const; size_type find_first_of(const charT* s, size_type pos, size_type n) const; size_type find_first_of(const charT* s, size_type pos = 0) const; size_type find_first_of(charT c, size_type pos = 0) const; size_type find_last_of(const basic_string& str, size_type pos = npos) const; size_type find_last_of(const charT* s, size_type pos, size_type n) const; size_type find_last_of(const charT* s, size_type pos = npos) const; size_type find_last_of(charT c, size_type pos=npos) const; size_type find_first_not_of(const basic_string& str, size_type pos = 0) const; size_type find_first_not_of(const charT* s, size_type pos, size_type n) const; size_type find_first_not_of(const charT* s, size_type pos = 0) const; size_type find_first_not_of(charT c, size_type pos = 0) const; size_type find_last_not_of(const basic_string& str, size_type pos = npos) const; size_type find_last_not_of(const charT* s, size_type pos, size_type n) const; size_type find_last_not_of(const charT* s, size_type pos = npos) const; size_type find_last_not_of(charT c, size_type pos = npos) const; // Comparisons: int compare(const basic_string& str) const; int compare(size_type pos1, size_type n1, const basic_string& str) const; int compare(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2) const; int compare(const charT* s) const; int compare(size_type pos1, size_type n1, const charT* s) const; int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const; };
The basic_string
class template is the base for the string
and wstring
types. A string is a sequence container of characters that provides a number of useful member functions for searching and modifying the string. You can also work with C-style null-terminated character strings as arguments to basic_string
members, including constructors. A basic_string object keeps track of an explicit length instead of using the C convention of null-terminated character arrays. Strings are therefore much easier to use, and offer greater safety (see the at
member function), while still offering ease-of-use with many functions taking C-style strings as arguments.
If you need a sequence of characters that you don't need to treat as a character string, you can use ve
ctor
<char>
or vector<wchar_t>
, but in most cases, you will probably find string
or wstring
to be more convenient.
Many of the member function can throw exceptions. Specifying an index out of range often throws out_of_range
. An attempt to construct a string or modify a string so its length exceeds max_string()
throws length_error
. The basic_string
classes uses an allocator object for memory allocation, which can throw an exception (such as bad_alloc
) almost any time the string is modified.
Following are the members of basic_string
. Several small examples appear throughout this section, with the relevant member function.
explicit
basic_string
(const Alloc& a = Alloc())
basi
c
_string
(const
basic_string&
str)
str
.
basi
c
_string
(
co
nst
basi
c
_string&
str,
size_
t
ype
po
s
,
siz
e
_type
n =
npos,
const
Alloc&
a
=
Alloc())
str
, starting at pos
. If pos is out of range (that is, pos
>
st
r
.size()
), ou
t
_of_
r
ange
is thrown. The number of characters copied is n
or the number of characters left in the string (str.size()
-
pos
), whichever is smaller.
basic_string
(const
charT*
s,
size_type
n,
const
Alloc&
a
=
Alloc())
n
characters from s
.
basic_string
(
c
onst
charT*
s,
const
Alloc&
a
=
Alloc())
trait
s
::length(s)
characters from s
.
basi
c
_string
(
si
ze_
t
ype
n, charT
c,
const
Alloc&
a
=
Alloc())
n
copies of the character c
.template<class InputIterator>
basic_string
(InputIterator
begin,
InputIterator
end,
const
Alloc&
a
=
Alloc())
InputIterator
:InputIterator
is an integral type, the string is initialized with static_cast<size_type>(begin)
copies of the character stati
c
_cast<value_type>(end)
;begin
, end
).basi
c
_string&
append
(
c
onst
basic_string&
str,
s
ize
_type
pos,
size_type
n)
pos
>
str.size
(
)
, out_of_
r
ange
is thrown. Otherwise up to n
characters are copied from str
, starting at position pos
. The return value is *this
.operato
r
+=
, later in this section.basi
c
_string&
append
(
c
onst
basic_string&
str)
append(str,
0,
npos)
.basi
c
_string&
append
(
c
onst
cha
rT
* s, size_type n)
basi
c
_string&
append
(
c
onst
cha
rT
* s)
bas
ic
_string&
append
(
si
ze_type
n,
charT
c)
templat
e
<class InputIter>
basic_string&
append
(
I
nputIter
firs
t
,
InputIter
last)
append(
str)
.basi
c
_string&
assign
(
c
onst
basi
c
_string&
str,
size_type
pos, size_type
n)
str
that starts at pos
and extends for up to n
characters. The return value is *this
.operato
r
=
, later in this section.basic_string&
assign
(
c
onst
basic_string& str)
assign(str,
0,
npos)
.basic_string&
assign
(const
ch
arT
* s, size_type n)
basi
c
_string&
assign
(
c
onst charT* s)
basi
c
_string&
assign
(
si
z
e
_type
n, charT c)
template<class InputIter>
basic_string&
assign
(InputIter
firs
t
,
InputIter
last)
assign(
str)
.const_reference
at
(size_type n)
const
reference
at
(size_type n)
n
. If n
>=
size()
, out_of_range
is thrown. See also operato
r[]
, later in this section.iterator
begin
()
const_iterator
begin
()
const
const
charT*
c_str
()
const
const
member of the string. The typical use of c_str
is to interface with C functions that require a null-terminated character string, e.g.,std::printf(fmtstr.c_str(), value);
size_type
capacity
()
const
capacity
tells you how much you can put in the string before it must grow again.void
clear
()
int
compare
(
c
onst
basic_string&
st
r
)
const
traits::compare(data(),
str.data(),
len)
, where len is the smaller of size()
and str.size()
.int
compare
(size_type
pos
1
,
size_type
n1,
const
basic_string&
str)
const
(*this,
pos
1
,
n
1
)
, and returns tmp.compare(str)
.int
compare
(const
charT*
s)
const
(
s
)
, and returns this->compare(
tmp)
.int
compare
(size_
t
ype
pos
1
,
size_type
n1,
const
basic_strin
g
&
st
r
,
size_type
pos2,
size_
t
ype
n2)
const
int
compare
(size_
typ
e
pos1,
size_type
n
1
,
const
charT*
s)
const
int
compare
(size_
ty
pe
pos1,
size
_type
n1,
const
charT*
s,
size_type
n2)
const
(*this,
pos1,
n1)
and tmp2: tmp2(str,
pos2,
n
2
)
, tmp2(s)
, or tmp2(s,
n2)
. It returns tmp1.compare(
tmp2)
.size_type
copy
(charT*
dst,
siz
e
_type
n,
size_type
pos
=
0)
const
n
characters from the string, starting at position pos
, to the character array dst
. If pos
>
siz
e
()
, out_of_
ra
nge
is thrown. The number of characters copied, len, is the smaller of n
and size()
-
pos
. The return value is len.const
cha
rT
*
data
()
const
size()
==
0, data
returns a valid pointer. Do not modify the contents of the data
string.bool
empty
()
const
size()
==
0
).iterator
end
()
const_iterator
end
()
const
basic_string&
erase
(size_type
pos
=
0,
size_type
n
=
npos)
pos
and erasing n
or size()
-
pos
characters, whichever is smaller. If pos
>
siz
e
()
, out_of_range
is thrown. The return value is *this
. For example,std::string s("hello, world"); s.erase(9, 1) == "hello, wold" s.erase(5) == "hello"
iterator
erase
(iterator
pos
ition
)
position
and returns an iterator that points to the next character or end()
.iterator
erase
(iterato
r
first, iterator last)
first
, last
) and returns an iterator that points to the character after last
or end()
.size_type
find
(
c
onst
basi
c
_string&
str,
size_
t
ype
pos
= 0)
const
size_type
find
(
c
onst
char
T
*
s,
size_type
po
s
, size_type
n)
const
size_type
find
(c
onst
char
T
*
s,
size_type
pos
= 0)
const
size_type
find
(
c
harT
c,
size_type
pos
=
0) const
npos
if not found. The search starts at position pos
. The string to search for is str
or a temporary string tmp constructed as tmp(s,
n)
, tmp(s)
, or tmp(1
, c)
. In other words, find
returns the smallest i such that i >= pos
and i + str
.size()
<= size()
and traits::eq
(at
(i+j), str.at
(j)) for all j in [0, str.size()
).rfind
, later in this section. For example,string("hello").find('l') == 2 string("hello").find("lo", 2) == 3 string("hello").find("low") == string::npos
siz
e
_type
fi
nd
_first_not_
o
f
(
c
onst
basic_string&
str,
size_type
pos
=
0)
const
pos
that does not appear in str
, or npos
if every character appears in str
. For example,string("hello").find_first_not_of("aeiou") == 0 string("hello").find_first_not_of("aeiou", 1) == 2 string("hello").find_first_not_of("aeiou", 6) == string::npos
siz
e
_type
fi
nd
_first_not_of
(
c
harT
c,
siz
e
_
t
ype
pos
=
0)
const
siz
e
_type
fin
d
_first_not_
o
f
(
co
nst
charT*
s,
si
ze
_
t
ype
pos
=
0) const
size_type
fi
nd
_first_not_
o
f
(
c
onst
charT*
s,
size_
t
ype
p
os
,
size_
t
ype
n) const
find_first_not_of(
tmp,
pos)
, where tmp is constructed as tmp(1,
c)
, tmp(s)
, or tmp(s,
n)
.si
ze
_type
fi
nd
_first_
o
f
(
c
onst
basic_string&
str,
size_type
pos
=
0)
const
pos
that does appears in str
, or npos
if no character appears in str
. For example,string("hello").find_first_of("aeiou") = 1 string("hello").find_first_of("aeiou", 2) = 4 string("hello").find_first_of("aeiou", 6) = string::npos
si
ze
_type
f
ind
_first_of
(charT
c,
size_type
pos
=
0) const
siz
e
_type
fin
d
_first_of
(
c
onst
char
T
*
s,
size_type
pos
=
0)
const
siz
e
_type
fin
d
_first_of
(
co
nst
charT*
s,
siz
e
_
t
ype
pos,
size_type
n)
const
find_first_of(
tmp,
pos)
, where tmp is constructed as tmp(1,
c)
, tmp(s)
, or tmp(s,
n)
.siz
e
_type
fin
d
_last_not_of
(
con
st
basi
c
_string& str
, size_type
pos
=
npos)
const
pos
that does not appear in str
, or npos
if every character appears in str
. For example,string("hello").find_last_not_of("aeiou") == 3 string("hello").find_last_not_of("aeiou", 1) == 0 string("hello").find_last_not_of("aeiou", 0) == 0
size_type
find_last_not_of
(
char
T
c, size_
t
ype
pos
=
npos) const
siz
e
_type
fin
d
_last_not_of
(const
char
T
*
s,
size_type
pos
=
npos)
const
si
ze
_type
find_last_not_of
(
c
onst
char
T
*
s,
size_type
pos,
size_type
n)
const
find_last_not_of(
tmp,
pos)
, where tmp is constructed as tmp(1,
c)
, tmp(s)
, or tmp(s,
n)
.size_type
find_last_of
(
c
onst
basi
c
_string&
st
r
,
s
ize
_type
pos
=
npos)
const
pos
that does appears in str
, or npos
if no character appears in str
. For example,string("hello").find_last_of("aeiou") == 4 string("hello").find_last_of("aeiou", 3) == 1 string("hello").find_last_of("aeiou", 0) == string::npos
si
ze
_type
fi
nd
_last_of
(charT
c,
siz
e
_type
pos
=
npo
s
)
const
size_type
fin
d
_last_of
(const
char
T
* s,
siz
e
_
t
ype
pos
=
npos) const
si
ze
_type
fi
nd
_last_of
(const
char
T
*
s,
siz
e
_type
po
s
,
size_type
n) const
find_last_of(
tmp,
pos)
, where tmp is constructed as tmp(1,
c)
, tmp(s)
, or tmp(s,
n)
.allocator_type
ge
t
_allocator
()
const
basi
c
_string&
insert
(size_type
pos1,
const
basic_string&
str,
size_type
pos2,
siz
e
_type
n)
str
into the string starting at position pos1
. The substring to insert starts at pos2
and extends for up to n
characters. If pos1
>
size()
or pos2
>
str.size()
, out_of_range
is thrown. The number of characters inserted is the smaller of n
and str.size()
-
pos2
. The return value is *this
. For example,string s("hello"); s.insert(5, ", world") // s == "hello, world" s.insert(5, "out there", 3, 42) // s == "hello there, world"
basi
c
_string&
insert
(size_type
pos,
const
basi
c
_string&
str)
bas
ic
_string&
insert
(size_type
pos,
const
charT*
s,
size_type
n)
basi
c
_string&
insert
(size_type
po
s
,
const
charT*
s)
basi
c
_string&
insert
(size_type
p
os
,
size_type
n,
charT
c)
insert(pos,
str,
0,
npos)
, where the last three versions construct the temporary string str
as str(s,
n)
, str(s)
, or str(n,
c)
.iterator
insert
(iterator p, charT c)
void
insert
(
i
terator
p,
size_type
n,
charT
c)
template<class InputIter>
void
insert
(
it
erator
p,
InputIter
first,
InputIter
last)
p
points to. The first version inserts the character c
and returns an iterator that points to c
. The second version inserts n
copies of the character c
, and the third version inserts the temporary string constructed from the arguments (first,
last)
.size_type
length
()
const
siz
e
()
.size_type
max_size
()
const
const_reference
operator[]
(size_type
po
s
)
const
reference
operato
r
[]
(
siz
e_type
pos)
pos
. If pos
==
size()
, the return value is charT()
, that is, a null character. The behavior is undefined if pos
>
size()
.basic_string&
operator=
(
co
nst
ba
sic
_string&
st
r
)
*
t
his
and str
are the same object, the assignment operator does nothing and returns *
t
his
. If they are different objects, the operator replaces the current string contents with the contents of str
and returns *this
.basic_string&
opera
tor
=
(
co
nst
charT*
s)
basic_string&
operator=
(
c
harT
c)
(s)
or tmp(1,
c)
and assigns *this
=
tmp. The return value is *this
.basic_string&
opera
tor
+=
(
c
onst
bas
ic
_string& str)
basic_string&
oper
ator
+=
(
c
onst
cha
rT
*
s)
basic_string&
opera
tor
+=
(
cha
rT
c)
append
with the same arguments and returns *this
.void
pus
h
_back
(
cha
rT
c)
c
to the end of the string. Its existence lets you use basic_string
with a push_back_
i
terator
.reverse_iterator
rbegin
()
const_reverse_iterator
rbegin
()
const
reverse_iterator
rend
()
const_reverse_iterator
rend
()
const
basic_string&
replace
(size_
t
ype
pos
1
,
size_
t
ype
n
1
,
const
basic_string&
st
r
,
size_type
pos
2
,
siz
e
_type
n2)
pos1
and extends for up to n1
characters (the smaller of n1
and size()
-
pos1
). The string to insert is a substring of str
, starting at pos2
and extending for up to n2
characters (the smaller of n2
and str.size
(
)
-
pos2
). The replacement string is inserted at pos1
. If pos1
>
size()
or pos2
>
str.size
(
)
, out_of_range
is thrown. The returns value is *this
.basic_string&
replace
(size_
ty
pe
pos,
size_type
n
1
,
const
basi
c
_string&
str)
basic_string&
replace
(size_
t
ype
po
s
,
size_type
n
1
,
const
charT*
str)
basic_string&
replace
(size_
t
ype
po
s
,
size_
t
ype
n
1
,
const
char
T
*
s,
siz
e
_
t
ype
n2)
basic_string&
replace
(size_
ty
pe
p
os
,
si
ze
_
t
ype
n
1
,
size_type
n
2
,
charT
c)
replace(pos,
n
1
,
tmp,
0,
npos)
, where tmp is a temporary string constructed as tmp(str)
, tmp(s,
n2)
, or tmp(n2,
c)
. For example,std::string s("hello"); s.replace(1, 4, "appy") s=="happy" s.replace(5, 0, "your birthday !", 4, 10) s=="happy birthday" s.replace(1, 1, 1, 'i') s=="hippy birthday"
basic_string&
replace
(
iter
ator
first,
iterator
last,
const
basic_string&
str)
first
, last
) and inserts str
at the position where first
pointed. The return value is *this
.basic_string&
replace
(
it
erator
first
,
iterator
last
,
const
charT*
s,
siz
e
_type
n)
basic_string&
replace
(
it
erator
first
,
iterator
last
,
const
char
T
*
s)
basic_string&
replace
(
i
terator
first
,
iterator
last
,
size_type
n,
charT
c)
template<class InputIterator>
basic_
string
&
replace
(
i
terator
first,
iterator last,
InputIterator
i
1
,
InputIterator
i2)
replace(first,
las
t
,
tmp)
, where tmp is a temporary string constructed as tmp(s,
n)
, tmp(s)
, tmp(n
, c)
, or tmp(i1,
i2)
.void
reserve
(size_type res_arg = 0)
capacity()
is at least as large as res_arg
. Call reserve
to avoid the need to reallocate the string data repeatedly when you know the string will grow by small increments to a large size. Note that size()
does not change.void
resize
(size_type n, charT c)
void
resize
(size_type
n)
n
characters. If n
<=
size()
, the new string has the first n
characters of the original string. If n
>
size()
, the new string has n
-
size()
copies of c
appended to the end. The second version returns resize(n,
charT())
.siz
e
_
t
ype
rfind
(
c
onst
basi
c
_string&
st
r
,
size_type
pos
=
npos)
const
siz
e
_
t
ype
rfind
(
c
onst
charT*
s,
size_type
pos,
size_type
n)
const
siz
e
_
t
ype
rfind
(
c
onst
char
T
*
s,
size_type
pos
=
npos)
const
siz
e
_
ty
pe
rfind
(charT
c,
size_
t
ype
pos
=
npo
s
)
const
pos
of a string or character or npos
if not found. The string to search for is str
or a temporary string tmp constructed as tmp(s,
n)
, tmp(s)
, or tmp(1
, c)
. In other words, rfind
returns the largest i such that i <= pos
and i + str
.size()
<= size()
and traits::eq
(at
(i+j), str.at
(j)) for all j in [0, str.size()
).find
, earlier in this section. For example,string("hello").rfind('l') == 3 string("hello").rfind("lo", 2) == string::npos string("hello").rfind("low") == string::npos
size_type
size
()
const
basic_string
substr
(size_type
pos
=
0,
size_type
n
=
npos)
const
pos
and extends for up to n
characters (the smaller of n
and size() -
pos
). If pos
>
size()
, out_of_range
is thrown.void
swap
(basic_string& str)
str
in constant time.char_traits class template, <sstream>, <vector>
Base class for character traits
template<typename charT> struct char_traits;
The cha
r
_traits
template describes a character type and provides basic functions for comparing, converting, and copying character values and arrays. See the char_traits<char>
and cha
r
_traits<wchar_t>
specializations, later in this section, for details.
char_traits<char> class, char_traits<wchar_t> class
Character traits of char type
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(charT& dst, const charT& src); static charT* assign(charT* dst, size_t n, const charT& c); static bool eq(const charT& c1, const charT& c2); static bool lt(const charT& c1, const charT& c2); static size_t length(const charT* str); static int compare(const charT* s1, const charT* s2, size_t n); static const charT* find(const charT* str, size_t n, const charT& c); static charT* copy(charT* dst, charT* src, size_t n); static charT* move(charT* dst, charT* src, size_t n); static bool eq_int_type(const int_type& i1, const int_type& i2); static int_type eof(); static int_type not_eof(const int_type& i); static char_type to_char_type(const int_type& i); static int_type to_int_type(const char_type& c); };
The cha
r
_traits<char>
class specializes char_traits for narrow characters. The streamoff
and streampos
types are implementation-defined. The other typedefs are self-explanatory. Following are the members:
static
void
assign
(charT& dst, const charT& src)
dst
=
src
.static
cha
rT
*
assign
(charT*
ds
t
,
siz
e
_t
n,
const
char
T
&
c)
dst
with n
copies of c
, that is, dst[0]
through dst[n-1]
=
c
.static
int
compare
(const
charT*
s
1
,
const
char
T
*
s
2
,
size_t n)
n
characters of the arrays s1
and s2
, returning an integer result as follows:eq(s
1
[
i],
s
2
[
i])
is true for all i in [0, n
);eq(s
1
[
i],
s
2
[
i])
is true for all i in [0, k), and lt(s1[
k],
s2[
k])
is true for some k in [0, n
);static
charT*
copy
(
charT
*
ds
t
,
charT*
sr
c
,
siz
e
_t
n)
n
characters from src
to dst
. The arrays src
and dst
must not overlap.static
int_type
eof
()
eq_int_type(eof(),
to_int_type(
c))
is false.static
bool
eq
(const charT& c1, const charT& c2)
c1
==
c2
.static
bool
eq_int_
t
ype
(const int_type& i1,
const int_type& i2)
i1
is the same as i2
. Specifically, for all character values c1 and c2, eq(
c1,
c2)
has the same value as eq_int_type(to_int_type(
c1),
to_int_type(
c2))
. Also, eof()
is always equal to eof()
and not equal to t
o
_int_type(
c)
for any character c. The value is unspecified for any other integer values.static
const
charT*
find
(const charT* str, size_t n,
const charT& c)
eq(*
p,
c)
is true. It returns a null pointer if there is no such character in the first n
characters of str
.static
siz
e
_t
length
(const charT* str)
str
, that is, it returns the smallest i such that eq(str[
i],
charT())
is true.static
bool
lt
(const charT& c1, const charT& c2)
c1
<
c2
.static
char
T
*
move
(
c
har
T
* ds
t
,
char
T
*
sr
c
,
size_t n)
n
characters from src
to dst
. The arrays src
and dst
are allowed to overlap.static
in
t
_type
not_eof
(const int_type& i)
eo
f
()
. If i
is not eof()
, i
is returned. Otherwise, some other value is returned.static
char_type
to_char_type
(const int_type& i)
i
to its equivalent character value (where eq_int_type(i,
to_int_type(to_char_type(i)))
is true). If i
is not equivalent to any character, the behavior is unspecified.static
int_type
to_
i
n
t
_type
(const char_type& c)
c
to its equivalent integer representation.mbstate_t in <cwchar>
Character traits of wchar_t type
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(charT& dst, const charT& src); static charT* assign(charT* dst, size_t n, const charT& c); static bool eq(const charT& c1, const charT& c2); static bool lt(const charT& c1, const charT& c2); static size_t length(const charT* str); static int compare(const charT* s1, const charT* s2, size_t n); static const charT* find(const charT* str, size_t n, const charT& c); static charT* copy(charT* dst, charT* src, size_t n); static charT* move(charT* dst, charT* src, size_t n); static bool eq_int_type(const int_type& i1, const int_type& i2); static int_type eof(); static int_type not_eof(const int_type& i); static char_type to_char_type(const int_type& i); static int_type to_int_type(const char_type& c); };
The cha
r
_traits<wchar_t>
class specializes char_traits for wide characters. The wstreamoff
and wstreampos
types are implementation-defined. The other typedefs are self-explanatory.
See char_traits<char>
, earlier in this section, for a description of the member functions.
char_traits<char> class, mbstate_t in <cwchar>
Read a line into a string
template<class charT, class traits, class Allocator> basic_istream<charT,traits>& getline(basic_istream<charT,traits>& in, basic_string<charT,traits,Allocator>& str, charT delim); // istream& getline(istream& in, string& str, char delim); template<class charT, class traits, class Allocator> basic_istream<charT,traits>& getline(basic_istream<charT,traits>& in, basic_string<charT,traits,Allocator>& str); // istream& getline(istream& in, string& str);
Reads a line of text from an input stream into the string str
. It starts by creating an basic_istrea
m
::sentry(in,
true)
object. If the sentry object is okay, getline
erases str
then reads characters from in
and appends them to str
until reaching end of file or until delim
is read. (The delim
character is read from the stream but not appended to the string.) Reading also stops if ma
x
_size
(
)
characters have been stored in the string, in which case io
s
_base::
f
ailbit
is set. If no characters are read from the stream, ios_base::
fa
ilbit
is set. The return value is in
.
The second form of getline
uses a newline as the delimiter, that is, it returns getlin
e
(in,
st
r
,
in.widen('\n'))
.
operator>> function template, basic_istream, basic_istream::sentry in <istream>
Concatenate two strings
template<class charT, class traits, class Allocator> basic_string<charT,traits,Allocator> operator+( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // string& operator+(const string& a, const string& b); template<class charT, class traits, class Allocator> basic_string<charT,traits,Allocator> operator+( const charT* a, const basic_string<charT,traits,Allocator>& b); // string& operator+(const char* a, const string& b); template<class charT, class traits, class Allocator> basic_string<charT,traits,Allocator> operator+( const basic_string<charT,traits,Allocator>& a, const charT* b); // string& operator+(const string& a, const char* b); template<class charT, class traits, class Allocator> basic_string<charT,traits,Allocator> operator+( const basic_string<charT,traits,Allocator>& a, charT b); // string& operator+(const string& a, char b);
Concatenates two strings and returns the result. It constructs a new string as a copy of a
, then calls a.append(b)
and returns the copy.
basic_string class template
Compare strings for equality
template<class charT, class traits, class Allocator> bool operator==( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator==(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator==(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator==(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator==( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator==(const string& a, conat char* b);
Compares two strings for equality or compares a string and a null-terminated character array. It returns a.compare(b)
==
0
, converting a
or b
from a character array to a string, as needed.
basic_string::compare, equals in <algorithm>
Compare strings for inequality
template<class charT, class traits, class Allocator> bool operator!=( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator!=(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator!=(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator!=(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator!=( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator!=(const string& a, conat char* b);
Compares two strings for inequality or compares a string and a null-terminated character array. It returns !(a
==
b)
.
basic_string::compare, mismatch in <algorithm>
Compare strings for less than
template<class charT, class traits, class Allocator> bool operator<( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator<(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator<(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator<(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator<( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator<(const string& a, conat char* b);
Compares two strings or compares a string and a null-terminated character array. It returns a.compare(b)
<
0
, converting a
or b
from a character array to a string, as needed.
basic_string::compare, lexicographical_compare in <algorithm>
Compare strings for less than or equal
template<class charT, class traits, class Allocator> bool operator<=( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator<=(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator<=(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator<=(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator<=( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator<=(const string& a, conat char* b);
Compares two strings or compares a string and a null-terminated character array. It returns a.compare(b)
<=
0
, converting a
or b
from a character array to a string, as needed.
basic_string::compare, lexicographical_compare in <algorithm>
Compare strings for greater than
template<class charT, class traits, class Allocator> bool operator>( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator>(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator>(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator>(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator>( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator>(const string& a, conat char* b);
Compares two strings or compares a string and a null-terminated character array. It returns a.compare(b)
>
0
, converting a
or b
from a character array to a string, as needed.
basic_string::compare, lexicographical_compare in <algorithm>
Compare strings for greater than or equal
template<class charT, class traits, class Allocator> bool operator>=( const basic_string<charT,traits,Allocator>& a, const basic_string<charT,traits,Allocator>& b); // bool operator>=(const string& a, const string& b); template<class charT, class traits, class Allocator> bool operator>=(const charT* a, const basic_string<charT,traits,Allocator>& b); // bool operator>=(const char* a, const string& b); template<class charT, class traits, class Allocator> bool operator>=( const basic_string<charT,traits,Allocator>& a, const charT* b); // bool operator>=(const string& a, conat char* b);
Compares two strings or compares a string and a null-terminated character array. It returns a.compare(b)
>=
0
, converting a
or b
from a character array to a string, as needed.
Write a string to an ostream
template<class charT, class traits, class Allocator> basic_ostream<charT, traits>& operator<<( basic_ostream<charT, traits>& out, const basic_string<charT,traits,Allocator>& str); // ostream& operator<<(ostream& out, const string& str);
Writes the string str
to out
. Like any formatted output function, it first creates a sentry object and if the sentry is okay, writes the string contents by calling out.rdbuf()->sputn
. If str.size
(
)
<
out.width()
, fill characters are added to achieve the desired width; otherwise, the entire string is written. If sputn
fails, ios_base::
f
ailbit
is set.
basic_ostream, basic_ostream::sentry in <ostream>
Read a string from an istream
template<class charT, class traits, class Allocator> basic_istream<charT,traits>& operator>>( basic_istream<charT,traits>& in, basic_string<charT,traits,Allocator>& str); // istream& operator>>(istream& in, string& str);
Reads a string from in
and stores the string in str
. Like any other formatted input operator, it first creates a sentry object basic_istr
eam
::sentry(in)
, and if the sentry is okay, erases str
then reads characters from in
and appends the characters to str
. If in.width
(
)
is greater than zero, no more than in.width
(
)
characters are read from in
; otherwise up to max_size
(
)
characters are read. Reading also stops at end of file or when reading a white space character (isspace
is true for locale in.getloc()
). The white space character is left in the input stream. The return value is in
.
getline function template, basic_istream, basic_istream::sentry in <istream>
Narrow character string class
typedef basic_string<char> string;
The string
class specializes basic_string
for type char
.
basic_string class template, wstring class
Swap two strings
template<class charT, class traits, class Allocator> void swap(basic_string<charT,traits,Allocator>& a, basic_string<charT,traits,Allocator>& b); // void swap(string& a, string& b);
The swap
function calls a
.
swap(b)
.
Wide character string class
typedef basic_string<wchar_t> wstring;
The wstring
class specializes basic_string
for type wchar_t
.
basic_string class template, string class