 |
Standard C++ Library Header Files:bitset, conj, cos, showpoint, streampos |
| << Preprocessing |
| Standard Template Library C++:adjacent_find, copy_backward, lexicographical_compare >> |
Chapter
12. Standard C++ Library
Header Files
The
Standard C++ Library is
composed of eight special-purpose
libraries:
v
The
Language Support
Library
v
The
Diagnostics Library
v
The
General Utilities
Library
v
The
Standard String
Templates
v
Localization
Classes and Templates
v
The
Containers, Iterators and Algorithms
Libraries (the Standard
Template
Library)
v
The
Standard Numerics
Library
v
The
Standard Input/Output Library
v
C++
Headers for the Standard C
Library
The
Language Support
Library
The
Language Support Library
defines types and functions
that will be used
implicitly
by C++ programs that employ
such C++ language features
as operators
new
and delete, exception handling and
runtime type information
(RTTI).
Standard
C++
Equivalent
in previous versions
header
<exception>
(page
AIX
<stdexcept.h>
390
no
equivalent
<limits>
(page 114)
no
equivalent
<new>
(page 164)
<new.h>
<typeinfo>
(page
<typeinfo.h>
390
no
equivalent
The
Diagnostics Library
The
Diagnostics Library is used to
detect and report error
conditions in C++
programs.
Standard
C++
Equivalent
in previous versions
header
<stdexcept>
(page
AIX
<stdexcept.h>
390
no
equivalent
The
General Utilities
Library
The
General Utilities Library is
used by other components of
the Standard C++
Library,
especially the Containers,
Iterators and Algorithms Libraries
(the Standard
Template
Library).
Standard
C++ header
Equivalent
in previous versions
<utility>
(page 400)
no
equivalent
<functional>
(page 282)
no
equivalent
51
<memory>
(page 336)
no
equivalent
The
Standard String
Templates
The
Strings Library is a facility for
the manipulation of character
sequences.
Standard
C++ header
Equivalent
in previous versions
<string>
(page 195)
no
equivalent
Localization
Classes and
Templates
The
Localization Library permits a
C++ program to address the
cultural differences
of
its various users.
Standard
C++ header
Equivalent
in previous versions
<locale>
(page 119)
no
equivalent
The
Containers, Iterators and
Algorithms Libraries (the
Standard Template
Library)
The
Standard Template Library
(STL) is a facility for the
management and
manipulation
of collections of objects.
Standard
C++ header
Equivalent
in previous versions
<algorithm>
(page 249)
no
equivalent
<bitset>
(page 54)
no
equivalent
<deque>
(page 274)
no
equivalent
<iterator>
(page 293)
no
equivalent
<list>
(page 310)
no
equivalent
<map>
(page 320)
no
equivalent
<queue>
(page 353)
no
equivalent
<set>
(page 353)
no
equivalent
<stack>
(page 368)
no
equivalent
<unordered_map>
(page 371)
no
equivalent
<unordered
set> (page 386)
no
equivalent
<vector>
(page 403)
no
equivalent
The
Standard Numerics
Library
The
Numerics Library is a facility for
performing seminumerical
operations.
Users
who require library facilities for
complex arithmetic but wish
to maintain
compatibility
with older compilers may use
the compatibility complex
numbers
library
whose types are defined in
the non-standard header file
<complex.h>.
Although
the header files
<complex> and <complex.h> are
similar in purpose,
they
are
mutually incompatible.
Standard
C++ header
Equivalent
in previous versions
<complex>
(page 61)
no
equivalent
<numeric>
(page 345)
no
equivalent
<valarray>
(page 225)
no
equivalent
52
Standard
C++ Library
The
Standard Input/Output
Library
The
standard iostreams library
differs from the compatibility
iostreams in a
number
of important respects. To maintain
compatibility between such a
product
and
VisualAge C++ Version 5.0 or
z/OS C/C++ Version 1.2, use
instead the
compatibility
iostreams library.
Standard
C++ header
Equivalent
in previous versions
<fstream>
(page 76)
no
equivalent
<iomanip>
(page 85)
no
equivalent
<ios>
(page 86)
no
equivalent
<iosfwd>
(page 102)
no
equivalent
<iostream>
(page 103)
no
equivalent
<istream>
(page 105)
no
equivalent
<ostream>
(page 168)
no
equivalent
<streambuf>
(page 185)
no
equivalent
<sstream>
(page 176)
no
equivalent
C++
Headers for the Standard C
Library
The
C International Standard specifies 18
headers which must be
provided by a
conforming
hosted implementation. The
name of each of these
headers is of the
form
name.h.
The C++ Standard Library
includes the C Standard
Library and,
hence,
includes these 18 headers.
Additionally, for each of the 18
headers specified
by
the C International Standard,
the C++ standard specifies a
corresponding
header
that is functionally equivalent to
its C library counterpart,
but which locates
all
of the declarations that it
contains within the std
namespace. The name of
each
of
these C++ headers is of the
form cname,
where name
is
the string that
results
when
the ".h" extension is removed from
the name of the equivalent C
Standard
Library
header. For example, the
header files <stdlib.h> and
<cstdlib> are
both
provided
by the C++ Standard Library
and are equivalent in function, with
the
exception
that all declarations in
<cstdlib> are located
within the std
namespace.
Standard
C++ Header
Corresponding
Standard C & C++
Header
<cassert>
(page 59)
<assert.h>
<cctype>
(page 59)
<ctype.h>
<cerrno>
(page 59)
<errno.h>
<cfloat>
(page 59)
<float.h>
<ciso646>
(page 60)
<iso646.h>
<climits>
(page 60)
<limits.h>
<clocale>
(page 60)
<locale.h>
<cmath>
(page 60)
<math.h>
<csetjmp>
(page 72)
<setjmp.h>
<csignal>
(page 72)
<signal.h>
<cstdarg>
(page 72)
<stdarg.h>
<cstddef>
(page 72)
<stddef.h>
<cstdio>
(page 72)
<stdio.h>
<cstdlib>
(page 73)
<stdlib.h>
53
Chapter
12. Standard C++ Library
Header Files
<cstring>
(page 73)
<string.h>
<ctime>
(page 73)
<time.h>
<cwchar>
(page 74)
<wchar.h>
<cwctype>
(page 74)
<wctype.h>
<bitset>
namespace
std {
template<size_t
N>
class
bitset;
//
TEMPLATE FUNCTIONS
template<class
E, class T, size_t N>
basic_istream<E,
T>&
operator>>(basic_istream<E,
>& is,
bitset<N>&
x);
template<class
E, class T, size_t N>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
bitset<N>& x);
};
Include
the standard header
<bitset>
to
define the template class bitset
and
two
supporting
templates.
bitset
template<size_t
N>
class
bitset
{
public:
typedef
bool element_type;
class
reference;
bitset();
bitset(unsigned
long val);
template<class
E, class T, class A>
explicit
bitset(const
basic_string<E, T, A>& str,
typename
basic_string<E, T,
A>::size_type
pos
= 0,
typename
basic_string<E, T,
A>::size_type
n
= basic_string<E, T,
A>::npos);
bitset<N>&
operator&=(const
bitset<N>& rhs);
bitset<N>&
operator|=(const
bitset<N>& rhs);
bitset<N>&
operator^=(const
bitset<N>& rhs);
bitset<N>&
operator<<=(const
bitset<N>& pos);
bitset<N>&
operator>>=(const
bitset<N>& pos);
bitset<N>&
set();
bitset<N>&
set(size_t
pos, bool val = true);
bitset<N>&
reset();
bitset<N>&
reset(size_t
pos);
bitset<N>&
flip();
bitset<N>&
flip(size_t
pos);
reference
operator[](size_t
pos);
bool
operator[](size_t
pos) const;
reference
at(size_t
pos);
54
Standard
C++ Library
bool
at(size_t
pos) const;
unsigned
long to_ulong()
const;
template<class
E, class T, class A>
basic_string<E,
T, A> to_string()
const;
size_t
count()
const;
size_t
size()
const;
bool
operator==(const
bitset<N>& rhs)
const;
bool
operator!=(const
bitset<N>& rhs)
const;
bool
test(size_t
pos) const;
bool
any()
const;
bool
none()
const;
bitset<N>
operator<<(size_t
pos) const;
bitset<N>
operator>>(size_t
pos) const;
bitset<N>
operator~();
static
const size_t bitset_size
=
N;
};
The
template class describes an object
that stores a sequence of N bits. A
bit is set
if
its
value is 1, reset
if
its value is 0. To flip
a
bit is to change its value
from 1 to 0
or
from 0 to 1. When converting between an
object of class bitset<N>
and
an
object
of some integral type, bit
position j
corresponds
to the bit value 1
<< j.
The
integral
value corresponding to two or more
bits is the sum of their
bit values.
bitset::any
bool
any()
const;
The
member function returns true
if any bit is set in the
bit sequence.
bitset::at
bool
at(size_type
pos) const;
reference
at(size_type
pos);
The
member function returns an
object of class reference (page 57),
which
designates
the bit at position pos, if the
object can be modified.
Otherwise, it
returns
the value of the bit at
position pos
in
the bit sequence. If that
position is
invalid,
the function throws an
object of class out_of_range (page 185).
bitset::bitset
bitset();
bitset(unsigned
long val);
template<class
E, class T, class A>
explicit
bitset(const
basic_string<E, T, A>& str,
typename
basic_string<E, T,
A>::size_type
pos
= 0,
typename
basic_string<E, T,
A>::size_type
n
= basic_string<E, T,
A>::npos);
The
first constructor resets all
bits in the bit sequence.
The second constructor
sets
only
those bits at position j
for
which val
& 1 << j is
nonzero.
The
third constructor determines
the initial bit values from
elements of a string
determined
from str. If str.size
(page 210)()
< pos,
the constructor throws
an
object
of class out_of_range (page 185).
Otherwise, the effective
length of the string
rlen
is
the smaller of n
and
str.size() -
pos.
If any of the rlen
elements
beginning
at position pos
is
other than 0
or
1, the
constructor throws an object
of
class
invalid_argument (page 184).
Otherwise, the constructor sets
only those bits
at
position j
for
which the element at
position pos
+ j is
1.
55
Chapter
12. Standard C++ Library
Header Files
bitset::bitset_size
static
const size_t bitset_size
=
N;
The
const static member is
initialized to the template
parameter N.
bitset::count
size_t
count()
const;
The
member function returns the
number of bits set in the
bit sequence.
bitset::element_type
typedef
bool element_type;
The
type is a synonym for bool.
bitset::flip
bitset<N>&
flip();
bitset<N>&
flip(size_t
pos);
The
first member function flips
all bits in the bit
sequence, then returns *this.
The
second
member function throws
out_of_range (page 185)
if size()
<= pos.
Otherwise,
it flips the bit at position
pos, then
returns *this.
bitset::none
bool
none()
const;
The
member function returns true
if none of the bits are
set in the bit
sequence.
bitset::operator!=
bool
operator
!=(const
bitset<N>& rhs)
const;
The
member operator function
returns true only if the
bit sequence stored in *this
differs
from the one stored in rhs.
bitset::operator&=
bitset<N>&
operator&=(const
bitset<N>& rhs);
The
member operator function
replaces each element of the
bit sequence stored
in
*this
with
the logical AND of its
previous value and the
corresponding bit in rhs.
The
function returns *this.
bitset::operator<<
bitset<N>
operator<<(const
bitset<N>& pos);
The
member operator function
returns bitset(*this)
<<= pos.
bitset::operator<<=
bitset<N>&
operator<<=(const
bitset<N>& pos);
The
member operator function
replaces each element of the
bit sequence stored
in
*this
with
the element pos
positions
earlier in the sequence. If no
such earlier
element
exists, the function clears
the bit. The function
returns *this.
bitset::operator==
bool
operator
==(const
bitset<N>& rhs)
const;
56
Standard
C++ Library
The
member operator function
returns true only if the
bit sequence stored in *this
is
the same as the one
stored in rhs.
bitset::operator>>
bitset<N>
operator>>(const
bitset<N>& pos);
The
member operator function
returns bitset(*this)
>>= (page 57)
pos.
bitset::operator>>=
bitset<N>&
operator>>=(const
bitset<N>& pos);
The
member function replaces
each element of the bit
sequence stored in *this
with
the element pos
positions
later in the sequence. If no
such later element
exists,
the
function clears the bit.
The function returns *this.
bitset::operator[]
bool
operator[](size_type
pos) const;
reference
operator[](size_type
pos);
The
member function returns an
object of class reference, which
designates the bit
at
position pos, if the
object can be modified.
Otherwise, it returns the
value of the
bit
at position pos
in
the bit sequence. If that
position is invalid, the
behavior is
undefined.
bitset::operator^=
bitset<N>&
operator^=(const
bitset<N>& rhs);
The
member operator function
replaces each element of the
bit sequence stored
in
*this
with
the logical EXCLUSIVE OR of
its previous value and the
corresponding
bit
in rhs. The
function returns *this.
bitset::operator|=
bitset<N>&
operator|=(const
bitset<N>& rhs);
The
member operator function
replaces each element of the
bit sequence stored
in
*this
with
the logical OR of its
previous value and the
corresponding bit in rhs.
The
function returns *this.
bitset::operator~
bitset<N>
operator~();
The
member operator function
returns bitset(*this).flip().
bitset::reference
class
reference
{
public:
reference&
operator=(bool
b};
reference&
operator=(const
reference& x);
bool
operator~()
const;
operator
bool()
const;
reference&
flip();
};
The
member class describes an object
that designates an individual
bit within the
bit
sequence. Thus, for b
an
object of type bool, x
and
y
objects
of type bitset<N>,
and
i
and
j
valid
positions within such an
object, the member functions
of class
reference
ensure
that (in order):
v
x[i]
= b stores
b
at
bit position i
in
x
57
Chapter
12. Standard C++ Library
Header Files
x[i]
= y[j] stores
the value of the bit
y[j]
at
bit position i
in
x
v
b
= ~x[i] stores
the flipped value of the
bit x[i]
in
b
v
b
= x[i] stores
the value of the bit
x[i]
in
b
v
x[i].flip()
stores
the flipped value of the
bit x[i]
back at
bit position i
in
x
v
bitset::reset
bitset<N>&
reset();
bitset<N>&
reset(size_t
pos);
The
first member function resets
(or clears) all bits in
the bit sequence, then
returns
*this. The
second member function
throws out_of_range
if
size() <=
pos.
Otherwise,
it resets the bit at
position pos, then
returns *this.
bitset::set
bitset<N>&
set();
bitset<N>&
set(size_t
pos, bool val = true);
The
first member function sets
all bits in the bit
sequence, then returns *this.
The
second
member function throws out_of_range
if
size() <=
pos.
Otherwise, it
stores
val
in
the bit at position pos, then
returns *this.
bitset::size
size_t
size()
const;
The
member function returns N.
bitset::test
bool
test(size_t
pos, bool val = true);
The
member function throws out_of_range
(page 185)
if size() <= pos.
Otherwise,
it returns true only if the
bit at position pos
is
set.
bitset::to_string
template<class
E, class T, class A>
basic_string<E,
T, A> to_string()
const;
The
member function constructs str, an
object of class basic_string<E,
T, A>.
For
each
bit in the bit sequence,
the function appends 1
if
the bit is set, otherwise 0.
The
last
element
appended to str
corresponds
to bit position zero. The
function
returns
str.
bitset::to_ulong
unsigned
long to_ulong()
const;
The
member function throws
overflow_error (page 185)
if any bit in the
bit
sequence
has a bit value that
cannot be represented as a value of
type unsigned
long.
Otherwise, it returns the
sum of the bit values in
the bit sequence.
operator<<
template<class
E, class T, size_t N>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
bitset<N>& x);
58
Standard
C++ Library
The
template function overloads operator<<
to
insert a text representation of
the
bit
sequence in os. It
effectively executes os
<< x.to_string<E, T,
allocator<E>
>(), then
returns os.
operator>>
template<class
E, class T, size_t N>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is,
bitset<N>&
x);
The
template function overloads operator>>
to
store in x
the
value bitset(str),
where
str
is an
object of type basic_string<E,
T, allocator<E> >& extracted
from
is. The
function extracts elements and
appends them to str
until:
v
N
elements
have been extracted and
stored
v
end-of-file
occurs on the input
sequence
v
the
next input element is
neither 0
not
1, in
which case the input
element is not
extracted
If
the function stores no
characters in str, it
calls is.setstate(ios_base::failbit).
In
any case, it returns is.
<cassert>
#include
<assert.h>
Include
the standard header <cassert>
to
effectively include the
standard header
<assert.h>.
<cctype>
#include
<ctype.h>
namespace
std {
using
::isalnum;
using
::isalpha;
using ::iscntrl;
using
::isdigit;
using
::isgraph;
using ::islower;
using
::isprint;
using
::ispunct;
using ::isspace;
using
::isupper;
using
::isxdigit;
using ::tolower;
using
::toupper;
};
Include
the standard header
<cctype>
to
effectively include the
standard header
<ctype.h>
within the std namespace
(page 6).
<cerrno>
#include
<errno.h>
Include
the standard header <cerrno>
to
effectively include the
standard header
<errno.h>.
<cfloat>
#include
<float.h>
Include
the standard header <cfloat>
to
effectively include the
standard header
<float.h>.
59
Chapter
12. Standard C++ Library
Header Files
<ciso646>
#include
<iso646.h>
Include
the standard header
<ciso646>
to
effectively include the
standard header
<iso646.h>.
<climits>
#include
<limits.h>
Include
the standard header
<climits>
to
effectively include the
standard header
<limits.h>.
<clocale>
#include
<locale.h>
namespace
std {
using
::lconv; using ::localeconv; using
::setlocale;
};
Include
the standard header
<clocale>
to
effectively include the
standard header
<locale.h>
within the std namespace
(page 6).
<cmath>
#include
<math.h>
namespace
std {
using
::abs; using ::acos; using
::asin;
using
::atan; using ::atan2; using
::ceil;
using
::cos; using ::cosh; using
::exp;
using
::fabs; using ::floor; using
::fmod;
using
::frexp; using ::ldexp; using
::log;
using
::log10; using ::modf; using
::pow;
using
::sin; using ::sinh; using ::sqrt;
using
::tan; using ::tanh;
using
::acosf;
using ::asinf;
using
::atanf;
using ::atan2f; using ::ceilf;
using
::cosf;
using ::coshf; using ::expf;
using
::fabsf;
using ::floorf; using
::fmodf;
using
::frexpf;
using ::ldexpf; using ::logf;
using
::log10f;
using ::modff; using
::powf;
using
::sinf;
using ::sinhf; using ::sqrtf;
using
::tanf;
using ::tanhf;
using
::acosl; using ::asinl;
using
::atanl; using ::atan2l; using
::ceill;
using
::cosl; using ::coshl; using
::expl;
using
::fabsl; using ::floorl; using
::fmodl;
using
::frexpl; using ::ldexpl; using
::logl;
using
::log10l; using ::modfl; using
::powl;
using
::sinl; using ::sinhl; using
::sqrtl;
using
::tanl; using ::tanhl;
};
Include
the standard header
<cmath>
to
effectively include the
standard header
<math.h>
within the std namespace
(page 6).
60
Standard
C++ Library
<complex>
namespace
std {
#define
__STD_COMPLEX
//
TEMPLATE CLASSES
template<class
T>
class
complex;
template<>
class
complex<float>;
template<>
class
complex<double>;
template<>
class
complex<long
double>;
//
TEMPLATE FUNCTIONS
template<class
T>
complex<T>
operator+(const
complex<T>&
lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator+(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
complex<T>
operator+(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator-(const
complex<T>&
lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator-(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
complex<T>
operator-(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator*(const
complex<T>&
lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator*(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
complex<T>
operator*(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator/(const
complex<T>&
lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator/(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
complex<T>
operator/(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator+(const
complex<T>&
lhs);
template<class
T>
complex<T>
operator-(const
complex<T>&
lhs);
template<class
T>
61
Chapter
12. Standard C++ Library
Header Files
bool
operator==(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
bool
operator==(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
bool
operator==(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
bool
operator!=(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
bool
operator!=(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
bool
operator!=(const
T& lhs,
const
complex<T>& rhs);
template<class
U, class E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is,
complex<U>&
x);
template<class
U, class E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
complex<U>& x);
template<class
T>
T
real(const
complex<T>& x);
template<class
T>
T
imag(const
complex<T>& x);
template<class
T>
T
abs(const
complex<T>& x);
template<class
T>
T
arg(const
complex<T>& x);
template<class
T>
T
norm(const
complex<T>& x);
template<class
T>
complex<T>
conj(const
complex<T>& x);
template<class
T>
complex<T>
polar(const
T& rho, const T& theta =
0);
template<class
T>
complex<T>
cos(const
complex<T>& x);
template<class
T>
complex<T>
cosh(const
complex<T>& x);
template<class
T>
complex<T>
exp(const
complex<T>& x);
template<class
T>
complex<T>
log(const
complex<T>& x);
template<class
T>
complex<T>
log10(const
complex<T>& x);
template<class
T>
complex<T>
pow(const
complex<T>& x, int y);
template<class
T>
complex<T>
pow(const
complex<T>& x, const T&
y);
template<class
T>
complex<T>
pow(const
complex<T>& x,
const
complex<T>& y);
template<class
T>
complex<T>
pow(const
T& x, const complex<T>&
y);
template<class
T>
complex<T>
sin(const
complex<T>& x);
template<class
T>
complex<T>
sinh(const
complex<T>& x);
template<class
T>
complex<T>
sqrt(const
complex<T>& x);
};
62
Standard
C++ Library
Include
the standard header
<complex>
to
define template class complex
and a
host
of
supporting template functions.
Unless otherwise specified,
functions that can
return
multiple values return an
imaginary part in the
half-open interval (-pi,
pi].
abs
template<class
T>
T
abs(const
complex<T>& x);
The
function returns the
magnitude of x.
arg
template<class
T>
T
arg(const
complex<T>& x);
The
function returns the phase
angle of x.
complex
template<class
T>
class
complex
{
public:
typedef
T value_type;
T
real()
const;
T
imag()
const;
complex(const
T& re = 0, const T& im = 0);
template<class
U>
complex(const
complex<U>& x);
template<class
U>
complex&
operator=(const
complex<U>& rhs);
template<class
U>
complex&
operator+=(const
complex<U>& rhs);
template<class
U>
complex&
operator-=(const
complex<U>& rhs);
template<class
U>
complex&
operator*=(const
complex<U>& rhs);
template<class
U>
complex&
operator/=(const
complex<U>& rhs);
complex&
operator=(const
T& rhs);
complex&
operator+=(const
T& rhs);
complex&
operator-=(const
T& rhs);
complex&
operator*=(const
T& rhs);
complex&
operator/=(const
T& rhs);
friend
complex<T>
operator+(const
complex<T>& lhs, const T&
rhs);
friend
complex<T>
operator+(const
T& lhs, const complex<T>&
rhs);
friend
complex<T>
operator-(const
complex<T>& lhs, const T&
rhs);
friend
complex<T>
operator-(const
T& lhs, const complex<T>&
rhs);
friend
complex<T>
operator*(const
complex<T>& lhs, const T&
rhs);
friend
complex<T>
operator*(const
T& lhs, const complex<T>&
rhs);
friend
complex<T>
operator/(const
complex<T>& lhs, const T&
rhs);
friend
complex<T>
operator/(const
T& lhs, const complex<T>&
rhs);
friend
bool
operator==(const
complex<T>& lhs, const T&
rhs);
friend
bool
operator==(const
T& lhs, const complex<T>&
rhs);
63
Chapter
12. Standard C++ Library
Header Files
friend
bool
operator!=(const
complex<T>& lhs, const T&
rhs);
friend
bool
operator!=(const
T& lhs, const complex<T>&
rhs);
};
The
template class describes an object
that stores two objects of
type T, one
that
represents
the real part of a complex
number and one that
represents the
imaginary
part. An object of class T:
v
has a
public default constructor,
destructor, copy constructor, and
assignment
operator
-- with conventional behavior
v
can be
assigned integer or floating-point
values, or type cast to such
values --
with
conventional behavior
v
defines
the arithmetic operators and
math functions, as needed,
that are defined
for
the floating-point types -- with
conventional behavior
In
particular, no subtle differences
may exist between copy
construction and
default
construction followed by assignment. And
none of the operations
on
objects
of class T
may
throw exceptions.
Explicit
specializations of template class complex
exist
for the three
floating-point
types.
In this implementation (page 3),
a value of any other
type T
is
type cast to
double
for
actual calculations, with the
double
result
assigned back to the
stored
object
of type T.
complex::complex
complex(const
T& re = 0, const T& im = 0);
template<class
U>
complex(const
complex<U>& x);
The
first constructor initializes
the stored real part to
re
and
the stored imaginary
part
to im. The
second constructor initializes
the stored real part to
x.real()
and
the
stored imaginary part to x.imag().
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex(const
complex<U>& x);
is
replaced by:
complex(const
complex& x);
which
is the copy
constructor.
complex::imag
T
imag()
const;
The
member function returns the
stored imaginary
part.
complex::operator*=
template<class
U>
complex&
operator*=(const
complex<U>& rhs);
complex&
operator*=(const
T& rhs);
The
first member function
replaces the stored real and
imaginary parts with
those
corresponding
to the complex product of *this
and
rhs. It
then returns *this.
64
Standard
C++ Library
The
second member function
multiplies both the stored
real part and the
stored
imaginary
part with rhs. It
then returns *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex&
operator*=(const
complex<U>& rhs);
is
replaced by:
complex&
operator*=(const
complex& rhs);
complex::operator+=
template<class
U>
complex&
operator+=(const
complex<U>& rhs);
complex&
operator+=(const
T& rhs);
The
first member function
replaces the stored real and
imaginary parts with
those
corresponding
to the complex sum of *this
and
rhs. It
then returns *this.
The
second member function adds
rhs
to
the stored real part. It
then returns *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex&
operator+=(const
complex<U>& rhs);
is
replaced by:
complex&
operator+=(const
complex& rhs);
complex::operator-=
template<class
U>
complex&
operator-=(const
complex<U>& rhs);
complex&
operator-=(const
T& rhs);
The
first member function
replaces the stored real and
imaginary parts with
those
corresponding
to the complex difference of *this
and
rhs. It
then returns *this.
The
second member function
subtracts rhs
from
the stored real part. It
then returns
*this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex&
operator-=(const
complex<U>& rhs);
is
replaced by:
complex&
operator-=(const
complex& rhs);
complex::operator/=
template<class
U>
complex&
operator/=(const
complex<U>& rhs);
complex&
operator/=(const
T& rhs);
The
first member function
replaces the stored real and
imaginary parts with
those
corresponding
to the complex quotient of *this
and
rhs. It
then returns *this.
65
Chapter
12. Standard C++ Library
Header Files
The
second member function
multiplies both the stored
real part and the
stored
imaginary
part with rhs. It
then returns *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex&
operator/=(const
complex<U>& rhs);
is
replaced by:
complex&
operator/=(const
complex& rhs);
complex::operator=
template<class
U>
complex&
operator=(const
complex<U>& rhs);
complex&
operator=(const
T& rhs);
The
first member function
replaces the stored real
part with rhs.real()
and
the
stored
imaginary part with rhs.imag(). It
then returns *this.
The
second member function
replaces the stored real
part with rhs
and
the stored
imaginary
part with zero. It then
returns *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
U>
complex&
operator=(const
complex<U>& rhs);
is
replaced by:
complex&
operator=(const
complex& rhs);
which
is the default assignment
operator.
complex::real
T
real()
const;
The
member function returns the
stored real part.
complex::value_type
typedef
T value_type;
The
type is a synonym for the
template parameter T.
complex<double>
template<>
class
complex<double>
{
public:
complex(double
re = 0, double im = 0);
complex(const
complex<float>& x);
explicit
complex(const
complex<long double>&
x);
//
rest same as template class
complex
};
The
explicitly specialized template class
describes an object that
stores two objects
of
type double, one
that represents the real
part of a complex number and
one that
represents
the imaginary part. The
explicit specialization differs
only in the
constructors
it defines. The first
constructor initializes the
stored real part to re
and
66
Standard
C++ Library
the
stored imaginary part to im. The
remaining two constructors initialize
the
stored
real part to x.real()
and
the stored imaginary part to
x.imag().
complex<float>
template<>
class
complex<float>
{
public:
complex(float re = 0,
float im = 0);
explicit
complex(const
complex<double>& x);
explicit
complex(const
complex<long double>&
x);
//
rest same as template class
complex
};
The
explicitly specialized template class
describes an object that
stores two objects
of
type float, one
that represents the real
part of a complex number and
one that
represents
the imaginary part. The
explicit specialization differs
only in the
constructors
it defines. The first
constructor initializes the
stored real part to re
and
the
stored imaginary part to im. The
remaining two constructors initialize
the
stored
real part to x.real()
and
the stored imaginary part to
x.imag().
complex<long
double>
template<>
class
complex<long
double> {
public:
complex(long
double re = 0, long double im =
0);
complex(const
complex<float>& x);
complex(const
complex<double>& x);
//
rest same as template class
complex
};
The
explicitly specialized template class
describes an object that
stores two objects
of
type long
double, one
that represents the real
part of a complex number
and
one
that represents the
imaginary part. The explicit
specialization differs only
in
the
constructors it defines. The
first constructor initializes
the stored real part to
re
and
the stored imaginary part to
im. The
remaining two constructors initialize
the
stored
real part to x.real()
and
the stored imaginary part to
x.imag().
conj
template<class
T>
complex<T>
conj(const
complex<T>& x);
The
function returns the
conjugate of x.
cos
template<class
T>
complex<T>
cos(const
complex<T>& x);
The
function returns the cosine
of x.
cosh
template<class
T>
complex<T>
cosh(const
complex<T>& x);
The
function returns the
hyperbolic cosine of x.
67
Chapter
12. Standard C++ Library
Header Files
exp
template<class
T>
complex<T>
exp(const
complex<T>& x);
The
function returns the
exponential of x.
imag
template<class
T>
T
imag(const
complex<T>& x);
The
function returns the
imaginary part of x.
log
template<class
T>
complex<T>
log(const
complex<T>& x);
The
function returns the
logarithm of x. The
branch cuts are along
the negative real
axis.
log10
template<class
T>
complex<T>
log10(const
complex<T>& x);
The
function returns the base 10
logarithm of x. The
branch cuts are along
the
negative
real axis.
norm
template<class
T>
T
norm(const
complex<T>& x);
The
function returns the squared
magnitude of x.
operator!=
template<class
T>
bool
operator!=(const
complex<T>&
lhs,
const
complex<T>&
rhs);
template<class
T>
bool
operator!=(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
bool
operator!=(const
T&
lhs,
const
complex<T>&
rhs);
The
operators each return true
only if real(lhs)
!= real(rhs) || imag(lhs) !=
imag(rhs).
operator*
template<class
T>
complex<T>
operator*(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator*(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
complex<T>
operator*(const
T& lhs,
const
complex<T>& rhs);
68
Standard
C++ Library
The
operators each convert both
operands to the return type,
then return the
complex
product of the converted lhs and rhs.
operator+
template<class
T>
complex<T>
operator+(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator+(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
complex<T>
operator+(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator+(const
complex<T>& lhs);
The
binary operators each
convert both operands to the
return type, then
return
the
complex sum of the converted
lhs
and
rhs.
The
unary operator returns lhs.
operator-
template<class
T>
complex<T>
operator-(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator-(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
complex<T>
operator-(const
T& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator-(const
complex<T>& lhs);
The
binary operators each
convert both operands to the
return type, then
return
the
complex difference of the
converted lhs
and
rhs.
The
unary operator returns a
value whose real part is
-real(lhs)
and
whose
imaginary
part is -imag(lhs).
operator/
template<class
T>
complex<T>
operator/(const
complex<T>& lhs,
const
complex<T>& rhs);
template<class
T>
complex<T>
operator/(const
complex<T>& lhs,
const
T& rhs);
template<class
T>
complex<T>
operator/(const
T& lhs,
const
complex<T>& rhs);
The
operators each convert both
operands to the return type,
then return the
complex
quotient of the converted lhs and rhs.
operator<<
template<class
U, class E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
complex<U>& x);
69
Chapter
12. Standard C++ Library
Header Files
The
template function inserts
the complex value x
in
the output stream os,
effectively
by executing:
basic_ostringstream<E,
T> ostr;
ostr.flags(os.flags());
ostr.imbue(os.imbue());
ostr.precision(os.precision());
ostr
<< '(' << real(x) << ','
<<
imag(x) << ')';
os
<< ostr.str().c_str();
Thus,
if os.width()
is
greater than zero, any
padding occurs either before
or after
the
parenthesized pair of values,
which itself contains no
padding. The function
returns
os.
operator==
template<class
T>
bool
operator==(const
complex<T>&
lhs,
const
complex<T>&
rhs);
template<class
T>
bool
operator==(const
complex<T>&
lhs,
const
T& rhs);
template<class
T>
bool
operator==(const
T&
lhs,
const
complex<T>&
rhs);
The
operators each return true
only if real(lhs)
== real(rhs) && imag(lhs) ==
imag(rhs).
operator>>
template<class
U, class E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is,
complex<U>&
x);
The
template function attempts to
extract a complex value from
the input stream
is,
effectively by executing:
is
>> ch && ch == '('
&&
is >> re >> ch && ch == ','
&&
is >> im >> ch && ch == ')'
Here,
ch
is an
object of type E, and re and im are
objects of type U.
If
the result of this
expression is true, the
function stores re
in
the real part and im
in
the imaginary part of x. In any
event, the function returns
is.
polar
template<class
T>
complex<T>
polar(const
T& rho,
const
T& theta = 0);
The
function returns the complex
value whose magnitude is rho and
whose phase
angle
is theta.
pow
template<class
T>
complex<T>
pow(const
complex<T>& x, int y);
template<class
T>
complex<T>
pow(const
complex<T>& x,
70
Standard
C++ Library
const
T& y);
template<class
T>
complex<T>
pow(const
complex<T>& x,
const
complex<T>& y);
template<class
T>
complex<T>
pow(const
T& x,
const
complex<T>& y);
The
functions each effectively
convert both operands to the
return type, then
return
the converted x
to
the power y. The
branch cut for x
is
along the negative
real
axis.
real
template<class
T>
T
real(const
complex<T>& x);
The
function returns the real
part of x.
sin
template<class
T>
complex<T>
sin(const
complex<T>& x);
The
function returns the sine of
x.
sinh
template<class
T>
complex<T>
sinh(const
complex<T>& x);
The
function returns the
hyperbolic sine of x.
sqrt
template<class
T>
complex<T>
sqrt(const
complex<T>& x);
The
function returns the square
root of x, with
phase angle in the
half-open
interval
(-pi/2,
pi/2].
The branch cuts are
along the negative real
axis.
__STD_COMPLEX
#define
__STD_COMPLEX
The
macro is defined, with an unspecified
expansion, to indicate compliance
with
the
specifications of this
header.
tan
template<class
T>
complex<T>
tan(const
complex<T>& x);
The
function returns the tangent
of x.
tanh
template<class
T>
complex<T>
tanh(const
complex<T>& x);
The
function returns the
hyperbolic tangent of x.
71
Chapter
12. Standard C++ Library
Header Files
<csetjmp>
#include
<setjmp.h>
namespace
std {
using
::jmp_buf; using
::longjmp;
};
Include
the standard header
<csetjmp>
to
effectively include the
standard header
<setjmp.h>
within the std namespace
(page 6).
<csignal>
#include
<signal.h>
namespace
std {
using
::sig_atomic_t; using ::raise; using
::signal;
};
Include
the standard header
<csignal>
to
effectively include the
standard header
<signal.h>
within the std namespace
(page 6).
<cstdarg>
#include
<stdarg.h>
namespace
std {
using
::va_list;
};
Include
the standard header
<cstdarg>
to
effectively include the
standard header
<stdarg.h>
within the std namespace
(page 6).
<cstddef>
#include
<stddef.h>
namespace
std {
using
::ptrdiff_t; using ::size_t;
};
Include
the standard header
<cstddef>
to
effectively include the
standard header
<stddef.h>
within the std namespace
(page 6).
<cstdio>
#include
<stdio.h>
namespace
std {
using
::size_t; using ::fpos_t; using
::FILE;
using
::clearerr; using ::fclose; using
::feof;
using
::ferror; using ::fflush; using
::fgetc;
using
::fgetpos; using ::fgets; using
::fopen;
using
::fprintf; using ::fputc; using
::fputs;
using
::fread; using ::freopen; using
::fscanf;
using
::fseek; using ::fsetpos; using
::ftell;
using
::fwrite; using ::gets; using
::perror;
using
::printf; using ::puts; using
::remove;
using
::rename; using ::rewind;
using ::scanf;
using
::setbuf; using ::setvbuf; using
::sprintf;
72
Standard
C++ Library
using
::sscanf; using ::tmpfile; using
::tmpnam;
using
::ungetc; using ::vfprintf; using
::vprintf;
using
::vsprintf;
};
Include
the standard header
<cstdio>
to
effectively include the
standard header
<stdio.h>
within the std namespace
(page 6).
<cstdlib>
#include
<stdlib.h>
namespace
std {
using
::size_t; using ::div_t; using
::ldiv_t;
using
::abort; using ::abs; using
::atexit;
using
::atof; using ::atoi; using
::atol;
using
::bsearch; using ::calloc; using
::div;
using
::exit; using ::free; using
::getenv;
using
::labs; using ::ldiv; using
::malloc;
using
::mblen; using ::mbstowcs;
using ::mbtowc;
using
::qsort; using ::rand; using
::realloc;
using
::srand; using ::strtod; using
::strtol;
using
::strtoul; using ::system;
using
::wcstombs; using
::wctomb;
};
Include
the standard header
<cstdlib>
to
effectively include the
standard header
<stdlib.h>
within the std namespace
(page 6).
<cstring>
#include
<string.h>
namespace
std {
using
::size_t; using ::memcmp; using
::memcpy;
using
::memmove; using ::memset; using
::strcat;
using
::strcmp; using ::strcoll; using
::strcpy;
using
::strcspn; using ::strerror; using
::strlen;
using
::strncat; using ::strncmp; using
::strncpy;
using
::strspn; using ::strtok; using
::strxfrm;
};
Include
the standard header
<cstring>
to
effectively include the
standard header
<string.h>
within the std namespace
(page 6).
<ctime>
#include
<time.h>
namespace
std {
using
::clock_t; using ::size_t;
using
::time_t; using ::tm;
using
::asctime; using ::clock; using
::ctime;
using
::difftime; using ::gmtime; using
::localtime;
using
::mktime; using ::strftime; using
::time;
};
Include
the standard header
<ctime>
to
effectively include the
standard header
<time.h>
within the std namespace
(page 6).
73
Chapter
12. Standard C++ Library
Header Files
<cwchar>
#include
<wchar.h>
namespace
std {
using
::mbstate_t; using ::size_t; using
::wint_t;
using
::fgetwc; using ::fgetws;
using ::fputwc;
using
::fputws; using ::fwide; using
::fwprintf;
using
::fwscanf; using ::getwc;
using ::getwchar;
using
::mbrlen; using ::mbrtowc;
using ::mbsrtowcs;
using
::mbsinit; using ::putwc;
using ::putwchar;
using
::swprintf; using ::swscanf; using
::ungetwc;
using
::vfwprintf; using ::vswprintf; using
::vwprintf;
using
::wcrtomb; using ::wprintf; using
::wscanf;
using
::wcsrtombs; using ::wcstol;
using ::wcscat;
using
::wcschr; using ::wcscmp;
using ::wcscoll;
using
::wcscpy; using ::wcscspn;
using ::wcslen;
using
::wcsncat; using ::wcsncmp;
using ::wcsncpy;
using
::wcspbrk; using ::wcsrchr;
using ::wcsspn;
using
::wcsstr; using ::wcstok;
using ::wcsxfrm;
using
::wmemchr; using ::wmemcmp;
using ::wmemcpy;
using
::wmemmove; using ::wmemset;
using ::wcsftime;
};
Include
the standard header
<cwchar>
to
effectively include the
standard header
<wchar.h>
within the std namespace
(page 6).
<cwctype>
#include
<wctype.h>
namespace
std {
using
::wint_t; using ::wctrans_t; using
::wctype_t;
using
::iswalnum; using ::iswalpha;
using ::iswcntrl;
using
::iswctype; using ::iswdigit; using
::iswgraph;
using
::iswlower; using ::iswprint; using
::iswpunct;
using
::iswspace; using ::iswupper;
using ::iswxdigit;
using
::towctrans; using ::towlower;
using ::towupper;
using
::wctrans; using
::wctype;
};
Include
the standard header
<cwctype>
to
effectively include the
standard header
<wctype.h>
within the std namespace
(page 6).
<exception>
namespace
std {
class
exception;
class
bad_exception;
//
FUNCTIONS
typedef
void (*terminate_handler)();
typedef
void (*unexpected_handler)();
terminate_handler
set_terminate(terminate_handler
ph) throw();
unexpected_handler
set_unexpected(unexpected_handler
ph) throw();
void
terminate();
void
unexpected();
bool
uncaught_exception();
};
Include
the standard header
<exception>
to
define several types and
functions
related
to the handling of
exceptions.
74
Standard
C++ Library
bad_exception
class
bad_exception
:
public exception {
};
The
class describes an exception that
can be thrown from an unexpected
handler
(page
76).
The value returned by what()
is an
implementation-defined C string.
None
of the member functions throw
any exceptions.
exception
class
exception
{
public:
exception()
throw();
exception(const
exception& rhs)
throw();
exception&
operator=(const
exception& rhs)
throw();
virtual
~exception()
throw();
virtual
const char *what()
const throw();
};
The
class serves as the base class for
all exceptions thrown by certain
expressions
and
by the Standard C++ library.
The C string value returned
by what()
is
left
unspecified
by the default constructor,
but may be defined by the
constructors for
certain
derived classes as an implementation-defined C
string.
None
of the member functions throw
any exceptions.
set_terminate
terminate_handler
set_terminate(terminate_handler
ph) throw();
The
function establishes a new terminate
handler (page 75)
as the function *ph.
Thus,
ph
must
not be a null pointer. The
function returns the address
of the
previous
terminate handler.
set_unexpected
unexpected_handler
set_unexpected(unexpected_handler
ph) throw();
The
function establishes a new unexpected
handler (page 76)
as the function *ph.
Thus,
ph
must
not be a null pointer. The
function returns the address
of the
previous
unexpected handler.
terminate
void
terminate();
The
function calls a terminate
handler, a
function of type void
(). If
terminate
is
called
directly by the program, the
terminate handler is the one
most recently set
by
a call to set_terminate (page 75).
If terminate
is
called for any of several
other
reasons
during evaluation of a throw expression,
the terminate handler is the
one
in
effect immediately after
evaluating the throw
expression.
A
terminate handler may not
return to its caller. At
program startup, the
terminate
handler
is a function that calls abort().
terminate_handler
typedef
void (*terminate_handler)();
75
Chapter
12. Standard C++ Library
Header Files
The
type describes a pointer to a
function suitable for use as a
terminate handler
(page
75).
uncaught_exception
bool
uncaught_exception();
The
function returns true only
if a thrown exception is being currently
processed.
Specifically,
it returns true after
completing evaluation of a throw
expression and
before
completing initialization of the
exception declaration in the
matching
handler
or calling unexpected (page 76)
as a result of the throw
expression.
unexpected
void
unexpected();
The
function calls an unexpected
handler, a
function of type void
().
If
unexpected
is
called directly by the
program, the unexpected
handler is the one
most
recently set by a call to
set_unexpected (page 75).
If unexpected
is
called
when
control leaves a function by a thrown
exception of a type not
permitted by
an
exception
specification for the
function, as in:
void
f() throw()
//
function may throw no
exceptions
{throw
"bad"; }
//
throw calls
unexpected()
the
unexpected handler is the
one in effect immediately
after evaluating the
throw
expression.
An
unexpected handler may not
return to its caller. It may
terminate execution
by:
v
throwing
an object of a type listed in
the exception specification
(or an object of
any
type if the unexpected
handler is called directly by
the program)
v
throwing
an object of type bad_exception
v
calling
terminate(), abort(), or exit(int)
At
program startup, the
unexpected handler is a function
that calls terminate().
unexpected_handler
typedef
void (*unexpected_handler)();
The
type describes a pointer to a
function suitable for use as an
unexpected
handler.
<fstream>
namespace
std {
template<class
E, class T = char_traits<E>
>
class
basic_filebuf;
typedef
basic_filebuf<char> filebuf;
typedef
basic_filebuf<wchar_t> wfilebuf;
template<class
E, class T = char_traits<E>
>
class
basic_ifstream;
typedef
basic_ifstream<char> ifstream;
typedef
basic_ifstream<wchar_t> wifstream;
template<class
E, class T = char_traits<E>
>
class
basic_ofstream;
typedef
basic_ofstream<char> ofstream;
typedef
basic_ofstream<wchar_t> wofstream;
template<class
E, class T = char_traits<E>
>
76
Standard
C++ Library
class
basic_fstream;
typedef
basic_fstream<char> fstream;
typedef
basic_fstream<wchar_t> wfstream;
};
Include
the iostreams (page 7)
standard header <fstream>
to
define several classes
that
support iostreams operations on
sequences stored in external
files (page 17).
basic_filebuf
template
<class E, class T =
char_traits<E> >
class
basic_filebuf
:
public basic_streambuf<E, T>
{
public:
typedef
typename basic_streambuf<E,
T>::char_type
char_type;
typedef
typename basic_streambuf<E,
T>::traits_type
traits_type;
typedef
typename basic_streambuf<E,
T>::int_type
int_type;
typedef
typename basic_streambuf<E,
T>::pos_type
pos_type;
typedef
typename basic_streambuf<E,
T>::off_type
off_type;
basic_filebuf();
bool
is_open()
const;
basic_filebuf
*open(const
char *s,
ios_base::openmode
mode);
basic_filebuf
*close();
protected:
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
pos_type seekpos(pos_type
pos,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
int_type underflow();
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
virtual
int_type overflow(int_type
c =
traits_type::eof());
virtual
int sync();
virtual
basic_streambuf<E, T>
*setbuf(E *s,
streamsize n);
};
The
template class describes a stream
buffer (page 187)
that
controls the
transmission
of elements of type E, whose
character traits (page 211)
are
determined
by the class T, to and from a
sequence of elements stored in
an
external
file (page 17).
An
object of class basic_filebuf<E,
T> stores a
file
pointer, which
designates the
file.
It also stores pointers to two
file
conversion facets (page 79)
for
use by the
basic_filebuf::basic_filebuf
basic_filebuf();
The
constructor stores a null pointer in
all the pointers controlling
the input buffer
pointer
(page 77).
77
Chapter
12. Standard C++ Library
Header Files
basic_filebuf::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
basic_filebuf::close
basic_filebuf
*close();
The
member function returns a null
pointer if the file pointer
(page 77)
fp is a
null
pointer.
Otherwise, it calls fclose(fp). If
that function returns a
nonzero value, the
function
returns a null pointer. Otherwise, it
returns this
to
indicate that the
file
was
successfully closed (page 19).
For
a wide stream, if any insertions
have occured since the
stream was opened, or
since
the last call to streampos, the
function calls overflow(). It
also inserts any
sequence
needed to restore the
initial conversion state
(page 12),
by using the file
conversion
facet (page 79)
fac to call
fac.unshift
as
needed. Each element x
of
type
char
thus
produced is written to the
associated stream designated by
the file
pointer
fp
as if by
successive calls of the form fputc(x,
fp). If
the call to
fac.unshift
or
any write fails, the
function does not
succeed.
basic_filebuf::int_type
typedef
typename traits_type::int_type int_type;
The
type is a synonym for traits_type::int_type.
basic_filebuf::is_open
bool
is_open();
The
member function returns true
if the file pointer is not a
null pointer.
basic_filebuf::off_type
typedef
typename traits_type::off_type off_type;
The
type is a synonym for traits_type::off_type.
basic_filebuf::open
basic_filebuf
*open(const
char *s,
ios_base::openmode
mode);
The
member function endeavors to
open the file with filename
s, by
calling
fopen(s,
strmode).
Here strmode
is
determined from mode
& ~(ate & | binary):
v
ios_base::in
becomes
"r"
(open
existing file for
reading).
v
ios_base::out
or
ios_base::out
| ios_base::trunc becomes
"w"
(truncate
existing
file or create for
writing).
v
ios_base::out
| app becomes
"a"
(open
existing file for appending
all writes).
v
ios_base::in
| ios_base::out becomes
"r+"
(open
existing file for reading
and
writing).
v
ios_base::in
| ios_base::out | ios_base::trunc becomes
"w+"
(truncate
existing
file or create for reading and
writing).
v
ios_base::in
| ios_base::out | ios_base::app becomes
"a+"
(open
existing
file
for reading and for appending all
writes).
If
mode
& ios_base::binary is
nonzero, the function
appends b
to
strmode
to
open
78
Standard
C++ Library
value
returned by fopen
in
the file pointer (page 77)
fp. If mode
& ios_base::ate is
nonzero
and the file pointer is not
a null pointer, the function
calls fseek(fp,
0,
SEEK_END
to
position the stream at
end-of-file. If that positioning
operation fails, the
function
calls close(fp)
and
stores a null pointer in the
file pointer.
If
the file pointer is not a
null pointer, the function
determines the file
conversion
facet:
use_facet<
codecvt<E, char, traits_type:: state_type>
>(getloc()),
for
use
by underflow
and
overflow.
If
the file pointer is a null
pointer, the function
returns a null pointer. Otherwise,
it
returns
this.
basic_filebuf::overflow
virtual
int_type overflow(int_type
c =
traits_type::eof());
If
c !=
traits_type::eof(),
the protected virtual member
function endeavors to
insert
the element traits_type::to_char_type(c)
into
the output buffer (page 187).
It
can do so in various
ways:
v
If a
write position (page 188)
is available, it can store
the element into the
write
position
and increment the next
pointer for the output
buffer.
v
It
can make a write position
available by allocating new or additional
storage for
the
output buffer.
v
It
can convert any pending
output in the output buffer,
followed by c, by
using
the
file conversion facet (page
79)
fac to call
fac.out
as
needed. Each element x
of
type char
thus
produced is written to the
associated stream designated by
the
file
pointer fp
as if by
successive calls of the form fputc(x,
fp). If
any
conversion
or write fails, the function
does not succeed.
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(c).
basic_filebuf::pbackfail
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
The
protected virtual member
function endeavors to put back an
element into the
input
buffer (page 187),
then make it the current
element (pointed to by the
next
pointer).
If c
== traits_type::eof(),
the element to push back is
effectively the
one
already in the stream before
the current element.
Otherwise, that element
is
replaced
by x
= traits_type::to_char_type(c).
The function can put back
an
element
in various ways:
v
If a
putback position (page 188)
is available, and the element
stored there
compares
equal to x, it can
simply decrement the next
pointer for the input
buffer.
v
If
the function can make a
putback position available, it
can do so, set the
next
pointer
to point at that position, and
store x
in
that position.
v
If
the function can push
back an element onto the
input stream, it can do
so,
such
as by calling ungetc for an element of
type char.
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(c).
79
Chapter
12. Standard C++ Library
Header Files
basic_filebuf::pos_type
typedef
typename traits_type::pos_type pos_type;
The
type is a synonym for traits_type::pos_type.
basic_filebuf::seekoff
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class basic_filebuf<E,
T>, a
stream
position
can be represented by an object of
type fpos_t, which stores an
offset and
any
state information needed to
parse a wide stream (page 18).
Offset zero
designates
the first element of the
stream. (An object of type
pos_type (page 190)
stores
at least an fpos_t
object.)
For
a file opened for both
reading and writing, both
the input and output
streams
are
positioned in tandem. To switch
(page 20)
between inserting and
extracting,
pubseekoff
(and
hence to seekoff) have
various limitations for text
streams (page
If
the file pointer (page 77)
fp is a null
pointer, the function fails.
Otherwise, it
endeavors
to alter the stream position
by calling fseek(fp,
off, way).
If that
function
succeeds and the resultant
position fposn
can be
determined by calling
fgetpos(fp,
&fposn),
the function succeeds. If
the function succeeds, it
returns a
value
of type pos_type
containing
fposn.
Otherwise, it returns an invalid
stream
position.
basic_filebuf::seekpos
virtual
pos_type seekpos(pos_type
pos,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class basic_filebuf<E,
T>, a
stream
position
can be represented by an object of
type fpos_t, which stores an
offset and
any
state information needed to
parse a wide stream (page 18).
Offset zero
designates
the first element of the
stream. (An object of type
pos_type (page 190)
stores
at least an fpos_t
object.)
For
a file opened for both
reading and writing, both
the input and output
streams
are
positioned in tandem. To switch
(page 20)
between inserting and
extracting,
pubseekoff
(and
hence to seekoff) have
various limitations for text
streams (page
For
a wide stream, if any insertions
have occured since the
stream was opened, or
since
the last call to streampos, the
function calls overflow(). It
also inserts any
sequence
needed to restore the
initial conversion state
(page 12),
by using the file
conversion
facet (page 79)
fac to call
fac.unshift
as
needed. Each element x
of
type
char
thus
produced is written to the
associated stream designated by
the file
pointer
fp
as if by
successive calls of the form fputc(x,
fp). If
the call to
fac.unshift
or
any write fails, the
function does not
succeed.
80
Standard
C++ Library
If
the file pointer (page 77)
fp is a null
pointer, the function fails.
Otherwise, it
endeavors
to alter the stream position
by calling fsetpos(fp,
&fposn),
where
fposn
is
the fpos_t
object
stored in pos. If
that function succeeds, the
function
returns
pos.
Otherwise, it returns an invalid
stream position.
basic_filebuf::setbuf
virtual
basic_streambuf<E, T>
*setbuf(E *s,
streamsize n);
The
protected member function
returns zero if the file
pointer (page 77)
fp is a
null
pointer.
Otherwise, it calls setvbuf(fp,
(char *)s, _IOFBF, n * sizeof (E)) to
offer
the array of n
elements
beginning at s
as a
buffer for the stream. If
that
function
returns a nonzero value, the
function returns a null pointer.
Otherwise, it
returns
this
to
signal success.
basic_filebuf::sync
int
sync();
The
protected member function
returns zero if the file
pointer (page 77)
fp is a
null
pointer.
Otherwise, it returns zero
only if calls to both overflow()
and
fflush(fp)
succeed
in flushing any pending
output to the stream.
basic_filebuf::traits_type
typedef
T traits_type;
The
type is a synonym for the
template parameter T.
basic_filebuf::underflow
virtual
int_type underflow();
The
protected virtual member
function endeavors to extract
the current element c
from
the input stream, and return
the element as traits_type::to_int_type(c).
It
can
do so in various ways:
v
If a
read position (page 188)
is available, it takes c
as
the element stored in
the
read
position and advances the
next pointer for the input
buffer (page 187).
v
It
can read one or more
elements of type char,
as if by successive calls of
the
form
fgetc(fp), and
convert them to an element c of type
E
by
using the file
conversion
facet (page 79)
fac to call
fac.in
as
needed. If any read
or
conversion
fails, the function does
not succeed.
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
c,
converted as described
above.
basic_fstream
template
<class E, class T =
char_traits<E> >
class
basic_fstream
:
public basic_iostream<E, T>
{
public:
basic_fstream();
explicit
basic_fstream(const
char *s,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
basic_filebuf<E,
T> *rdbuf()
const;
bool
is_open()
const;
void
open(const
char *s,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
void
close();
};
81
Chapter
12. Standard C++ Library
Header Files
The
template class describes an object
that controls insertion and
extraction of
elements
and encoded objects using a
stream buffer (page 187)
of class
basic_filebuf<E,
T>,
with elements of type E, whose
character traits (page 211)
are
determined
by the class T. The
object stores an object of class
basic_filebuf<E,
T>.
basic_fstream::basic_fstream
basic_fstream();
explicit
basic_fstream(const
char *s,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
The
first constructor initializes
the base class by calling basic_iostream(sb),
where
sb
is
the stored object of class basic_filebuf<E,
T>.
It also initializes sb
by
calling
basic_filebuf<E,
T>().
The
second constructor initializes
the base class by calling basic_iostream(sb).
It
also
initializes sb
by
calling basic_filebuf<E,
T>(),
then sb.open(s,
mode).
If the
latter
function returns a null pointer,
the constructor calls setstate(failbit).
basic_fstream::close
voidclose();
The
member function calls rdbuf()->
close().
basic_fstream::is_open
bool
is_open();
The
member function returns rdbuf()->
is_open().
basic_fstream::open
void
open(const
char *s,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
The
member function calls rdbuf()->
open(s, mode).
If that function returns a
null
pointer,
the function calls setstate(failbit).
basic_fstream::rdbuf
basic_filebuf<E,
T> *rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to basic_filebuf<E,
T>.
basic_ifstream
template
<class E, class T =
char_traits<E> >
class
basic_ifstream
:
public basic_istream<E, T> {
public:
basic_filebuf<E,
T> *rdbuf()
const;
basic_ifstream();
explicit
basic_ifstream(const
char *s,
ios_base::openmode
mode = ios_base::in);
bool
is_open()
const;
void
open(const
char *s,
ios_base::openmode
mode = ios_base::in);
void
close();
};
The
template class describes an object
that controls extraction of
elements and
encoded
objects from a stream buffer of class
basic_filebuf<E,
T>,
with elements
82
Standard
C++ Library
of
type E, whose
character traits (page 211)
are determined by the class
T.
The
object
stores an object of class basic_filebuf<E,
T>.
basic_ifstream::basic_ifstream
basic_ifstream();
explicit
basic_ifstream(const
char *s,
ios_base::openmode
mode = ios_base::in);
The
first constructor initializes
the base class by calling basic_istream(sb),
where
sb
is
the stored object of class basic_filebuf<E,
T>.
It also initializes sb
by
calling
basic_filebuf<E,
T>().
The
second constructor initializes
the base class by calling basic_istream(sb).
It
also
initializes sb
by
calling basic_filebuf<E,
T>(),
then sb.open(s,
mode |
ios_base::in). If the
latter function returns a null
pointer, the constructor
calls
setstate(failbit).
basic_ifstream::close
void
close();
The
member function calls rdbuf()->
close().
basic_ifstream::is_open
bool
is_open();
The
member function returns rdbuf()->
is_open().
basic_ifstream::open
void
open(const
char *s,
ios_base::openmode
mode = ios_base::in);
The
member function calls rdbuf()->
open(s, mode | ios_base::in). If
that
function
returns a null pointer, the
function calls setstate(failbit).
basic_ifstream::rdbuf
basic_filebuf<E,
T> *rdbuf()
const
The
member function returns the
address of the stored stream
buffer.
basic_ofstream
template
<class E, class T =
char_traits<E> >
class
basic_ofstream
:
public basic_ostream<E, T> {
public:
basic_filebuf<E,
T> *rdbuf()
const;
basic_ofstream();
explicit
basic_ofstream(const
char *s,
ios_base::openmode
mode = ios_base::out);
bool
is_open()
const;
void
open(const
char *s,
ios_base::openmode
mode = ios_base::out);
void
close();
};
The
template class describes an object
that controls insertion of
elements and
encoded
objects into a stream buffer
of class basic_filebuf<E,
T>,
with elements
of
type E, whose
character traits (page 211)
are determined by the class
T.
The
object
stores an object of class basic_filebuf<E,
T>.
83
Chapter
12. Standard C++ Library
Header Files
basic_ofstream::basic_ofstream
basic_ofstream();
explicit
basic_ofstream(const
char *s,
ios_base::openmode
which = ios_base::out);
The
first constructor initializes
the base class by calling basic_ostream(sb),
where
sb
is
the stored object of class basic_filebuf<E,
T>.
It also initializes sb
by
calling
basic_filebuf<E,
T>().
The
second constructor initializes
the base class by calling basic_ostream(sb).
It
also
initializes sb
by
calling basic_filebuf<E,
T>(),
then sb.open(s,
mode |
ios_base::out). If the
latter function returns a null
pointer, the constructor
calls
setstate(failbit).
basic_ofstream::close
void
close();
The
member function calls rdbuf()->
close().
basic_ofstream::is_open
bool
is_open();
The
member function returns rdbuf()->
is_open().
basic_ofstream::open
void
open(const
char *s,
ios_base::openmode
mode = ios_base::out);
The
member function calls rdbuf()->
open(s, mode | ios_base::out). If
that
function
returns a null pointer, the
function calls setstate(failbit).
basic_ofstream::rdbuf
basic_filebuf<E,
T> *rdbuf()
const
The
member function returns the
address of the stored stream
buffer.
filebuf
typedef
basic_filebuf<char, char_traits<char> >
filebuf;
The
type is a synonym for template class
basic_filebuf (page 77),
specialized for
elements
of type char
with
default character traits
(page 211).
fstream
typedef
basic_fstream<char, char_traits<char> >
fstream;
The
type is a synonym for template class
basic_fstream (page 81),
specialized for
elements
of type char
with
default character traits
(page 211).
ifstream
typedef
basic_ifstream<char, char_traits<char> >
ifstream;
The
type is a synonym for template class
basic_ifstream (page 82),
specialized for
elements
of type char
with
default character traits
(page 211).
84
Standard
C++ Library
ofstream
typedef
basic_ofstream<char, char_traits<char>
>
ofstream;
The
type is a synonym for template class
basic_ofstream (page 83),
specialized for
elements
of type char
with
default character traits
(page 211).
wfstream
typedef
basic_fstream<wchar_t, char_traits<wchar_t>
>
wfstream;
The
type is a synonym for template class
basic_fstream (page 81),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
wifstream
typedef
basic_ifstream<wchar_t, char_traits<wchar_t>
>
wifstream;
The
type is a synonym for template class
basic_ifstream (page 82),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
wofstream
typedef
basic_ofstream<wchar_t, char_traits<wchar_t>
>
wofstream;
The
type is a synonym for template class
basic_ofstream (page 83),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
wfilebuf
typedef
basic_filebuf<wchar_t, char_traits<wchar_t>
>
wfilebuf;
The
type is a synonym for template class
basic_filebuf (page 77),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
<iomanip>
namespace
std {
T1
resetiosflags(ios_base::fmtflags
mask);
T2
setiosflags(ios_base::fmtflags
mask);
T3
setbase(int
base);
template<class
E>
T4
setfill(E
c);
T5
setprecision(streamsize
n);
T6
setw(streamsize
n);
};
Include
the iostreams (page 7)
standard header <iomanip>
to
define several
manipulators
(page 87)
that each take a single
argument. Each of
these
manipulators
returns an unspecified type,
called T1
through
T6
here,
that overloads
both
basic_istream<E,
T>::operator>> and
basic_ostream<E,
T>::operator<<.
Thus,
you can write extractors and
inserters such as:
cin
>> setbase(8);
cout
<< setbase(8);
85
Chapter
12. Standard C++ Library
Header Files
resetiosflags
T1
resetiosflags(ios_base::fmtflags
mask);
The
manipulator returns an object
that, when extracted from or inserted
into the
stream
str, calls
str.setf(ios_base::
fmtflags(), mask),
then returns str.
setbase
T3
setbase(int
base);
The
manipulator returns an object
that, when extracted from or inserted
into the
stream
str, calls
str.setf(mask,
ios_base::basefield),
then returns str.
Here,
mask
is
determined as follows:
If
is
8,
then mask
is
ios_base::oct
v
base
If
is
10,
then mask
is
ios_base::dec
v
base
If
is
16,
then mask
is
ios_base::hex
v
base
If
is
any
other value, then mask
is
ios_base::fmtflags(0)
v
base
setfill
template<class
E>
T4
setfill(E
fillch);
The
template manipulator returns an
object that, when extracted from or
inserted
into
the stream str, calls
str.fill(fillch), then
returns str. The
type E
must
be
the
same as the element type for
the stream str.
setiosflags
T2
setiosflags(ios_base::fmtflags
mask);
The
manipulator returns an object
that, when extracted from or inserted
into the
stream
str, calls
str.setf(mask), then
returns str.
setprecision
T5
setprecision(streamsize
prec);
The
manipulator returns an object
that, when extracted from or inserted
into the
stream
str, calls
str.precision(prec), then
returns str.
setw
T6
setw(streamsize
wide);
The
manipulator returns an object
that, when extracted from or inserted
into the
stream
str, calls
str.width(wide), then
returns str.
<ios>
wstreampos
(page 101)
86
Standard
C++ Library
namespace
std {
typedef
T1 streamoff;
typedef
T2 streamsize;
class
ios_base;
//
TEMPLATE CLASSES
template
<class E, class T =
char_traits<E> >
class
basic_ios;
typedef
basic_ios<char, char_traits<char> >
ios;
typedef
basic_ios<wchar_t, char_traits<wchar_t>
>
wios;
template
<class St>
class
fpos;
typedef
fpos<mbstate_t> streampos;
typedef
fpos<mbstate_t> wstreampos;
//
MANIPULATORS
ios_base&
boolalpha(ios_base&
str);
ios_base&
noboolalpha(ios_base&
str);
ios_base&
showbase(ios_base&
str);
ios_base&
noshowbase(ios_base&
str);
ios_base&
showpoint(ios_base&
str);
ios_base&
noshowpoint(ios_base&
str);
ios_base&
showpos(ios_base&
str);
ios_base&
noshowpos(ios_base&
str);
ios_base&
skipws(ios_base&
str);
ios_base&
noskipws(ios_base&
str);
ios_base&
unitbuf(ios_base&
str);
ios_base&
nounitbuf(ios_base&
str);
ios_base&
uppercase(ios_base&
str);
ios_base&
nouppercase(ios_base&
str);
ios_base&
internal(ios_base&
str);
ios_base&
left(ios_base&
str);
ios_base&
right(ios_base&
str);
ios_base&
dec(ios_base&
str);
ios_base&
hex(ios_base&
str);
ios_base&
oct(ios_base&
str);
ios_base&
fixed(ios_base&
str);
ios_base&
scientific(ios_base&
str);
};
Include
the iostreams (page 7)
standard header <ios>
to
define several types
and
functions
basic to the operation of
iostreams. (This header is
typically included for
you
by another of the iostreams
headers. You seldom have
occasion to include it
directly.)
A
large group of functions are
manipulators.
A manipulator declared in <ios>
alters
the values stored in its
argument object of class ios_base
(page 94).
Other
manipulators
perform actions on streams
controlled by objects of a type
derived
from
this class, such as a specialization of
one of the template classes
basic_istream
format
flag ios_base::skipws
in
the object str, which
might be of one of
these
types.
You
can also call a manipulator
by inserting it into an output
stream or extracting
it
from an input stream, thanks to
some special machinery
supplied in the classes
derived
from ios_base. For
example:
istr
>> noskipws;
87
Chapter
12. Standard C++ Library
Header Files
calls
noskipws(istr).
basic_ios
template
<class E, class T =
char_traits<E> >
class
basic_ios
:
public ios_base {
public:
typedef
E char_type;
typedef
T traits_type;
typedef
typename T::int_type int_type;
typedef
typename T::pos_type pos_type;
typedef
typename T::off_type off_type;
explicit
basic_ios(basic_streambuf<E,
T> *sb);
virtual
~basic_ios();
operator
void *()
const;
bool
operator!()
const;
iostate
rdstate()
const;
void
clear(iostate
state = goodbit);
void
setstate(iostate
state);
bool
good()
const;
bool
eof()
const;
bool
fail()
const;
bool
bad()
const;
iostate
exceptions()
const;
iostate
exceptions(iostate
except);
basic_ios&
copyfmt(const
basic_ios& rhs);
locale
imbue(const
locale& loc);
char_type
widen(char
ch);
char
narrow(char_type
ch, char dflt);
char_type
fill()
const;
char_type
fill(char_type
ch);
basic_ostream<E,
T> *tie()
const;
basic_ostream<E,
T> *tie(basic_ostream<E,
T> *str);
basic_streambuf<E,
T> *rdbuf()
const;
basic_streambuf<E,
T>
*rdbuf(basic_streambuf<E,
T> *sb);
E
widen(char
ch);
char
narrow(E ch,
char dflt);
protected:
void
init(basic_streambuf<E,
T> *sb);
basic_ios();
basic_ios(const
facet&);
//
not defined
void
operator=(const
facet&) // not defined
};
The
template class describes the
storage and member functions
common to both
input
streams (of template class
basic_istream (page 106))
and output streams
(of
template
class basic_ostream (page 169))
that depend on the
template parameters.
(The
class ios_base (page 94)
describes what is common and
not
dependent
on
template
parameters.) An object of class basic_ios<E,
T> helps
control a stream
with
elements of type E, whose
character traits (page 211)
are determined by
the
class
T.
An
object of class basic_ios<E,
T> stores:
v
a
tie
pointer to an
object of type basic_ostream<E,
T>
v
a
stream
buffer pointer to an
object of type basic_streambuf<E,
T>
88
Standard
C++ Library
v
formatting
information (page 95)
v
a
fill
character in an
object of type char_type
basic_ios::bad
bool
bad()
const;
The
member function returns true
if rdstate() &
badbit is
nonzero.
basic_ios::basic_ios
explicit
basic_ios(basic_streambuf<E,
T> *sb);
basic_ios();
The
first constructor initializes
its member objects by
calling init(sb). The
second
(protected)
constructor leaves its
member objects uninitialized. A
later call to init
must
initialize
the object before it can be
safely destroyed.
basic_ios::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
basic_ios::clear
void
clear(iostate
state = goodbit);
The
member function replaces the
stored stream state
information (page 95)
with
state
| (rdbuf() != 0 ? goodbit : badbit).
If state &
exceptions() is
nonzero,
it
then throws an object of class
failure (page 95).
basic_ios::copyfmt
basic_ios&
copyfmt(const
basic_ios& rhs);
then
copies from rhs
into
*this
the
fill character (page 89),
the tie pointer
(page
complete,
state &
exceptions() is
nonzero, the function
effectively calls
clear
(page
89)
with the argument rdstate(). It
returns *this.
basic_ios::eof
bool
eof()
const;
The
member function returns true
if rdstate() &
eofbit is
nonzero.
basic_ios::exceptions
iostate
exceptions()
const;
iostate
exceptions(iostate
except);
The
first member function
returns the stored exception
mask (page 95).
The second
member
function stores except
in
the exception mask and
returns its previous
stored
value. Note that storing a
new exception mask can throw an
exception just
like
the call clear(
rdstate()).
89
Chapter
12. Standard C++ Library
Header Files
basic_ios::fail
bool
fail()
const;
The
member function returns true
if rdstate() &
failbit is
nonzero.
basic_ios::fill
char_type
fill()
const;
char_type
fill(char_type
ch);
The
first member function
returns the stored fill
character (page 89).
The second
member
function stores ch
in
the fill character and
returns its previous
stored
value.
basic_ios::good
bool
good()
const;
The
member function returns true
if rdstate() ==
goodbit (no
state flags are
set).
basic_ios::imbue
locale
imbue(const
locale& loc);
If
rdbuf (page 91)
is not a null pointer, the
member function calls
rdbuf()->pubimbue(loc). In any
case, it returns ios_base::imbue(loc).
basic_ios::init
void
init(basic_streambuf<E,
T> *sb);
The
member function stores
values in all member
objects, so that:
v
rdbuf()
returns
sb
v
tie()
returns
a null pointer
v
rdstate()
returns
goodbit
if
sb
is
nonzero; otherwise, it returns
badbit
v
exceptions()
returns
goodbit
v
flags()
returns
skipws
| dec
v
width()
returns
zero
v
precision()
returns
6
v
fill()
returns
the space character
v
getloc()
returns
locale::classic()
v
iword
returns
zero and pword
returns
a null pointer for all argument
value
basic_ios::int_type
typedef
typename T::int_type int_type;
The
type is a synonym for T::int_type.
basic_ios::narrow
char
narrow(char_type
ch, char dflt);
The
member function returns use_facet<
ctype<E> >( getloc()).
narrow(ch,
dflt).
basic_ios::off_type
typedef
typename T::off_type off_type;
The
type is a synonym for T::off_type.
90
Standard
C++ Library
basic_ios::operator
void *
operator
void *()
const;
The
operator returns a null pointer
only if fail().
basic_ios::operator!
bool
operator!()
const;
The
operator returns fail().
basic_ios::pos_type
typedef
typename T::pos_type pos_type;
The
type is a synonym for T::pos_type.
basic_ios::rdbuf
basic_streambuf<E,
T> *rdbuf()
const;
basic_streambuf<E,
T> *rdbuf(basic_streambuf<E,
T> *sb);
The
first member function
returns the stored stream
buffer pointer.
The
second member function
stores sb
in
the stored stream
buffer pointer and
returns
the previously stored
value.
basic_ios::rdstate
iostate
rdstate()
const;
The
member function returns the
stored stream
state information.
basic_ios::setstate
void
setstate(iostate
state);
The
member function effectively
calls clear(state
| rdstate()).
basic_ios::tie
basic_ostream<E,
T> *tie()
const;
basic_ostream<E,
T> *tie(basic_ostream<E,
T> *str);
The
first member function
returns the stored tie
pointer (page 88).
The second
member
function stores str
in
the tie pointer and returns
its previous stored
value.
basic_ios::traits_type
typedef
T traits_type;
The
type is a synonym for the
template parameter T.
basic_ios::widen
char_type
widen(char
ch);
The
member function returns use_facet<
ctype<E> >( getloc()). widen(ch).
boolalpha
ios_base&
boolalpha(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
boolalpha),
then returns
str.
91
Chapter
12. Standard C++ Library
Header Files
dec
ios_base&
dec(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
dec, ios_base::
basefield), then
returns str.
fixed
ios_base&
fixed(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
fixed, ios_base::
floatfield), then
returns str.
fpos
template
<class St>
class
fpos
{
public:
fpos(streamoff
off);
explicit
fpos(St
state);
St
state()
const;
void
state(St
state);
operator
streamoff()
const;
streamoff
operator-(const
fpos& rhs) const;
fpos&
operator+=(streamoff
off);
fpos&
operator-=(streamoff
off);
fpos
operator+(streamoff
off) const;
fpos
operator-(streamoff
off) const;
bool
operator==(const
fpos& rhs) const;
bool
operator!=(const
fpos& rhs) const;
};
The
template class describes an object
that can store all
the information needed
to
restore
an arbitrary file-position indicator
(page 19)
within any stream. An
object of
class
fpos<St>
effectively
stores at least two member
objects:
v
a
byte offset, of type
streamoff (page 101)
v
a
conversion state, for use by an
object of class basic_filebuf, of
type St,
typically
mbstate_t
It
can also store an arbitrary
file position, for use by an
object of class basic_filebuf
(page
77),
of type fpos_t. For an
environment with limited file
size, however,
streamoff
and
fpos_t
may
sometimes be used interchangeably. And
for an
environment
with no streams that have a
state-dependent encoding (page 12),
mbstate_t
may
actually be unused. So the
number of member objects
stored may
vary.
fpos::fpos
fpos(streamoff
off);
explicit
fpos(St
state);
The
first constructor stores the
offset off,
relative to the beginning of
file and in
the
initial conversion state
(page 12)
(if that matters). If off
is
-1, the resulting
object
represents an invalid stream
position.
The
second constructor stores a
zero offset and the object
state.
92
Standard
C++ Library
fpos::operator!=
bool
operator!=(const
fpos& rhs) const;
The
member function returns !(*this ==
rhs).
fpos::operator+
fpos
operator+(streamoff
off) const;
The
member function returns fpos(*this) +=
off.
fpos::operator+=
fpos&
operator+=(streamoff
off);
The
member function adds off
to
the stored offset member
object, then returns
*this. For
positioning within a file,
the result is generally valid
only for binary
fpos::operator-
streamoff
operator-(const
fpos& rhs) const;
fpos
operator-(streamoff
off) const;
The
first member function
returns (streamoff)*this
- (streamoff)rhs.
The
second
member function returns fpos(*this) -=
off.
fpos::operator-=
fpos&
operator-=(streamoff
off);
The
member function returns fpos(*this) -=
off.
For positioning within a
file, the
result
is generally valid only for binary
streams (page 18)
that do not have
a
state-dependent
encoding (page 12).
fpos::operator==
bool
operator==(const
fpos& rhs) const;
The
member function returns (streamoff)*this
== (streamoff)rhs.
fpos::operator
streamoff
operator
streamoff()
const;
The
member function returns the
stored offset member object,
plus any additional
offset
stored as part of the fpos_t
member
object.
fpos::state
St
state()
const;
void
state(St
state);
The
first member function
returns the value stored in
the St
member
object. The
second
member function stores state
in
the St
member
object.
hex
ios_base&
hex(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
hex, ios_base::
basefield), then
returns str.
93
Chapter
12. Standard C++ Library
Header Files
internal
ios_base&
internal(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
internal, ios_base::
adjustfield), then
returns str.
ios
typedef
basic_ios<char, char_traits<char> >
ios;
The
type is a synonym for template class
basic_ios (page 88),
specialized for
elements
of type char
with
default character traits
(page 211).
ios_base
(page
99)
class
ios_base
{
public:
class
failure;
typedef
T1 fmtflags;
static
const fmtflags boolalpha,
dec,
fixed,
hex,
internal,
left,
oct,
right,
scientific,
showbase,
showpoint,
showpos,
skipws,
unitbuf,
uppercase,
adjustfield,
basefield,
floatfield;
typedef
T2 iostate;
static
const iostate badbit,
eofbit,
failbit,
goodbit;
typedef
T3 openmode;
static
const openmode app,
ate,
binary,
in,
out,
trunc;
typedef
T4 seekdir;
static
const seekdir beg,
cur,
end;
typedef
T5 event;
static
const event copyfmt_event,
erase_event,
copyfmt_event;
class
Init;
fmtflags
flags()
const;
fmtflags
flags(fmtflags
fmtfl);
fmtflags
setf(fmtflags
fmtfl);
fmtflags
setf(fmtflags
fmtfl, fmtflags mask);
void
unsetf(fmtflags
mask);
streamsize
precision()
const;
streamsize
precision(streamsize
prec);
streamsize
width()
const;
stramsize
width(streamsize
wide);
locale
imbue(const
locale& loc);
locale
getloc()
const;
static
int xalloc();
long&
iword(int
idx);
void
*& pword(int
idx);
typedef
void *(event_callback(event
ev,
ios_base&
ios, int idx);
void
register_callback(event_callback
pfn, int idx);
static
bool sync_with_stdio(bool
sync = true);
protected:
ios_base();
94
Standard
C++ Library
private:
ios_base(const
ios_base&);
ios_base&
operator=(const
ios_base&);
};
The
class describes the storage and
member functions common to
both input and
output
streams that does not
depend on the template
parameters. (The
template
class
basic_ios (page 88)
describes what is common and
is
dependent
on template
parameters.)
An
object of class ios_base
stores
formatting
information, which
consists of:
v
format
flags in an
object of type fmtflags
(page 96)
an
exception
mask in an
object of type iostate (page
97)
v
a
field
width in an
object of type int
v
a
display
precison in an
object of type int
v
v
two
extensible
arrays, with
elements of type long
and
void
pointer
v
An
object of class ios_base
also
stores stream
state information, in an
object of
type
iostate (page 97),
and a callback
stack.
ios_base::event
typedef
T5 event;
static
const event copyfmt_event,
erase_event,
imbue_event;
The
type is an enumerated type T5 that
describes an object that can
store the
callback
event used as
an argument to a function registered with
register_callback
(page
98).
The distinct event
values are:
v
copyfmt_event, to
identify a callback that
occurs near the end of a
call to
copyfmt, just
before the exception
mask is
copied.
v
erase_event, to
identify a callback that
occurs at the beginning of a
call to
copyfmt, or at
the beginning of a call to
the destructor for *this.
v
imbue_event, to
identify a callback that
occurs at the end of a call
to imbue (page
96),
just before the function
returns.
ios_base::event_callback
typedef
void *(event_callback(event
ev,
ios_base&
ios, int idx);
The
type describes a pointer to a
function that can be
registered with
register_callback
(page 98).
Such a function must not
throw an exception.
ios_base::failure
class
failure
:
public exception {
public:
explicit
failure(const string& what_arg)
{
};
The
member class serves as the
base class for all exceptions thrown by
the member
by
what()
is
what_arg.data().
ios_base::flags
fmtflags
flags()
const;
fmtflags
flags(fmtflags
fmtfl);
95
Chapter
12. Standard C++ Library
Header Files
The
first member function
returns the stored format
flags (page 95).
The second
member
function stores fmtfl
in
the format flags and returns
its previous stored
value.
ios_base::fmtflags
typedef
T1 fmtflags;
static
const fmtflags boolalpha,
dec,
fixed,
hex,
internal,
left,
oct,
right,
scientific,
showbase,
showpoint,
showpos,
skipws,
unitbuf,
uppercase,
adjustfield,
basefield,
floatfield;
The
type is a bitmask type (page
6)
T1 that
describes an object that can
store
format
flags. The distinct flag
values (elements)
are:
v
boolalpha, to
insert or extract objects of
type bool
as
names (such as true
and
false) rather
than as numeric
values
v
dec, to
insert or extract integer
values in decimal
format
v
fixed, to
insert floating-point values in
fixed-point format (with no
exponent
field)
v
hex, to
insert or extract integer
values in hexadecimal
format
v
internal, to pad to a
field width (page 95)
as needed by inserting fill
characters
(page
89)
at a point internal to a generated
numeric field
v
left, to pad to a
field width (page 95)
as needed by inserting fill
characters
(page
89)
at the end of a generated
field (left
justification)
v
oct, to
insert or extract integer
values in octal
format
v
right, to pad to a
field width (page 95)
as needed by inserting fill
characters
(page
89)
at the beginning of a generated
field (right
justification)
v
scientific, to
insert floating-point values in
scientific format (with an
exponent
field)
v
showbase, to
insert a prefix that reveals
the base of a generated
integer field
v
showpoint, to
insert a decimal point
unconditionally in a generated
floating-point
field
v
showpos, to
insert a plus sign in a
non-negative generated numeric
field
v
skipws, to
skip leading white space
(page 31)
before certain
extractions
v
unitbuf, to
flush output after each
insertion
v
uppercase, to
insert uppercase equivalents of
lowercase letters in
certain
insertions
In
addition, several useful
values are:
v
adjustfield, internal
| left | right
v
basefield, dec
| hex | oct
v
floatfield, fixed
| scientific
ios_base::getloc
locale
getloc()
const;
The
member function returns the
stored locale object.
ios_base::imbue
locale
imbue(const
locale& loc);
The
member function stores loc
in
the locale object, then
reports the callback
event
96
Standard
C++ Library
ios_base::Init
class
Init
{
};
The
nested class describes an object
whose construction ensures
that the standard
iostreams
objects are properly
constructed (page 104),
even before the
execution of
a
constructor for an arbitrary static
object.
ios_base::ios_base
ios_base();
The
(protected) constructor does
nothing. A later call to basic_ios::init
must
initialize
the object before it can be
safely destroyed. Thus, the
only safe use for
class
ios_base
is as a
base class for template class basic_ios
(page 88).
ios_base::iostate
typedef
T2 iostate;
static
const iostate badbit,
eofbit,
failbit,
goodbit;
The
type is a bitmask type (page
6)
T2 that
describes an object that can
store
stream
state information (page 95).
The distinct flag values
(elements) are:
v
badbit, to
record a loss of integrity of
the stream buffer
v
eofbit, to
record end-of-file while
extracting from a stream
v
failbit, to
record a failure to extract a valid
field from a stream
In
addition, a useful value
is:
v
goodbit, no
bits set
ios_base::iword
long&
iword(int
idx);
The
member function returns a
reference to element idx
of
the extensible array
(page
95)
with elements of type long.
All elements are effectively
present and
initially
store the value zero.
The returned reference is
invalid after the next
call to
iword
for
the object, after the
object is altered by a call to
basic_ios::copyfmt,
or
after
the object is
destroyed.
If
idx
is
negative, or if unique storage is
unavailable for the element,
the function
calls
setstate(badbit)
and
returns a reference that
might not be unique.
To
obtain a unique index, for
use across all objects of
type ios_base, call
xalloc
(page
99).
ios_base::openmode
typedef
T3 openmode;
static
const openmode app,
ate,
binary,
in,
out,
trunc;
The
type is a bitmask type (page
6)
T3 that
describes an object that can
store the
opening
mode for
several iostreams objects.
The distinct flag values
(elements) are:
v
app, to
seek to the end of a stream
before each insertion
v
ate, to
seek to the end of a stream
when its controlling object is
first created
v
binary, to
read a file as a binary
stream (page 18),
rather than as a text
stream
(page
17)
v
in, to
permit extraction from a
stream
97
Chapter
12. Standard C++ Library
Header Files
v
out, to
permit insertion to a
stream
v
trunc, to
truncate an existing file when
its controlling object is
first created
ios_base::precision
streamsize
precision()
const;
streamsize
precision(streamsize
prec);
The
first member function
returns the stored display
precision (page 95).
The
second
member function stores prec
in
the display precision and
returns its
previous
stored value.
ios_base::pword
void
*& pword(int
idx);
The
member function returns a
reference to element idx
of
the extensible array
(page
95)
with elements of type void
pointer.
All elements are effectively
present
and
initially store the null
pointer. The returned
reference is invalid after
the next
call
to pword
for
the object, after the
object is altered by a call
to
basic_ios::copyfmt, or
after the object is
destroyed.
If
idx
is
negative, or if unique storage is
unavailable for the element,
the function
calls
setstate(badbit)
and
returns a reference that
might not be unique.
To
obtain a unique index, for
use across all objects of
type ios_base, call
xalloc
(page
99).
ios_base::register_callback
void
register_callback(event_callback
pfn, int idx);
The
member function pushes the
pair {pfn,
idx} onto
the stored callback
stack
in
reverse order of registry, by
the expression (*pfn)(ev,
*this, idx).
ios_base::seekdir
typedef
T4 seekdir;
static
const seekdir beg,
cur,
end;
The
type is an enumerated type T4 that
describes an object that can
store the seek
mode
used
as an argument to the member
functions of several iostreams
classes.
The
distinct flag values
are:
v
beg, to
seek (alter the current
read or write position)
relative to the beginning
oc
a
sequence (array, stream, or
file)
v
cur, to
seek relative to the current
position within a
sequence
v
end, to
seek relative to the end of
a sequence
ios_base::setf
void
setf(fmtflags
mask);
fmtflags
setf(fmtflags
fmtfl, fmtflags mask);
The
first member function
effectively calls flags(mask
| flags()) (set
selected
bits),
then returns the previous
format flags (page 95).
The second member
function
effectively calls flags(mask
& fmtfl, flags() & ~mask) (replace
selected
bits
under a mask), then returns
the previous format
flags.
ios_base::sync_with_stdio
static
bool sync_with_stdio(bool
sync = true);
98
Standard
C++ Library
The
static member function
stores a stdio
sync flag, which
is initially true.
When
true,
this flag ensures that
operations on the same file
are properly
synchronized
between
the iostreams (page 7)
functions and those defined in
the Standard C
library.
Otherwise, synchronization may or
may not be guaranteed,
but
performance
may be improved. The
function stores sync
in
the stdio sync flag
and
returns
its previous stored value.
You can call it reliably
only before
performing
any
operations on the standard
streams.
ios_base::unsetf
void
unsetf(fmtflags
mask);
The
member function effectively
calls flags(~mask
& flags()) (clear
selected bits).
ios_base::width
streamsize
width()
const;
streamsize
width(streamsize
wide);
The
first member function
returns the stored field
width (page 95).
The second
member
function stores wide
in
the field width and returns
its previous stored
value.
ios_base::xalloc
static
int xalloc();
The
static member function
returns a stored static
value, which it increments
on
each
call. You can use
the return value as a unique
index argument when
calling
left
ios_base&
left(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::
left, ios_base::
adjustfield), then
returns str.
noboolalpha
ios_base&
noboolalpha(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::boolalpha), then
returns
str.
noshowbase
ios_base&
noshowbase(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::showbase), then
returns
str.
noshowpoint
ios_base&
noshowpoint(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::showpoint), then
returns
str.
noshowpos
ios_base&
noshowpos(ios_base&
str);
99
Chapter
12. Standard C++ Library
Header Files
The
manipulator effectively calls
str.unsetf(ios_base::showpos"), then
returns
str.
noskipws
ios_base&
noskipws(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::skipws), then
returns str.
nounitbuf
ios_base&
nounitbuf(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::unitbuf), then
returns str.
nouppercase
ios_base&
nouppercase(ios_base&
str);
The
manipulator effectively calls
str.unsetf(ios_base::uppercase), then
returns
str.
oct
ios_base&
oct(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::oct,
ios_base::basefield),
then
returns str.
right
ios_base&
right(ios_base&
str);
The
maiipulator effectively calls
str.setf(ios_base::right,
ios_base::adjustfield), then
returns str.
scientific
ios_base&
scientific(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::scientific,
ios_base::floatfield), then
returns str.
showbase
ios_base&
showbase(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::showbase), then
returns str.
showpoint
ios_base&
showpoint(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::showpoint), then
returns str.
showpos
ios_base&
showpos(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::showpos), then
returns str.
100
Standard
C++ Library
skipws
ios_base&
skipws(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::skipws), then
returns str.
streamoff
typedef
T1 streamoff;
The
type is a signed integer
type T1
that
describes an object that can
store a byte
offset
involved in various stream positioning
operations. Its representation
has at
least
32 value bits. It is not
necessarily
large enough to represent an
arbitrary byte
position
within a stream. The value
streamoff(-1)
generally
indicates an erroneous
offset.
streampos
typedef
fpos<mbstate_t> streampos;
The
type is a synonym for fpos<
mbstate_t>.
streamsize
typedef
T2 streamsize;
The
type is a signed integer
type T3
that
describes an object that can
store a count
of
the number of elements involved in
various stream operations.
Its representation
has
at least 16 bits. It is not
necessarily
large enough to represent an
arbitrary byte
position
within a stream.
unitbuf
ios_base&
unitbuf(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::unitbuf), then
returns str.
uppercase
ios_base&
uppercase(ios_base&
str);
The
manipulator effectively calls
str.setf(ios_base::uppercase), then
returns str.
wios
typedef
basic_ios<wchar_t, char_traits<wchar_t> >
wios;
The
type is a synonym for template class
basic_ios (page 88),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
wstreampos
typedef
fpos<mbstate_t> wstreampos;
The
type is a synonym for fpos<
wmbstate_t>.
101
Chapter
12. Standard C++ Library
Header Files
<iosfwd>
namespace
std {
typedef
T1 streamoff;
typedef
T2 streamsize;
typedef
fpos streampos;
//
TEMPLATE CLASSES
template<class
E>
class
char_traits;
class
char_traits<char>;
class
char_traits<wchar_t>;
template<class
E, class T = char_traits<E>
>
class
basic_ios;
template<class
E, class T = char_traits<E>
>
class
istreambuf_iterator;
template<class
E, class T = char_traits<E>
>
class
ostreambuf_iterator;
template<class
E, class T = char_traits<E>
>
class
basic_streambuf;
template<class
E, class T = char_traits<E>
>
class
basic_istream;
template<class
E, class T = char_traits<E>
>
class
basic_ostream;
template<class
E, class T = char_traits<E>
>
class
basic_iostream;
template<class
E, class T = char_traits<E>
>
class
basic_stringbuf;
template<class
E, class T = char_traits<E>
>
class
basic_istringstream;
template<class
E, class T = char_traits<E>
>
class
basic_ostringstream;
template<class
E, class T = char_traits<E>
>
class
basic_stringstream;
template<class
E, class T = char_traits<E>
>
class
basic_filebuf;
template<class
E, class T = char_traits<E>
>
class
basic_ifstream;
template<class
E, class T = char_traits<E>
>
class
basic_ofstream;
template<class
E, class T = char_traits<E>
>
class
basic_fstream;
//
char TYPE DEFINITIONS
typedef
basic_ios<char, char_traits<char> >
ios;
typedef
basic_streambuf<char, char_traits<char>
>
streambuf;
typedef
basic_istream<char, char_traits<char>
>
istream;
typedef
basic_ostream<char, char_traits<char>
>
ostream;
typedef
basic_iostream<char, char_traits<char>
>
iostream;
typedef
basic_stringbuf<char, char_traits<char>
>
stringbuf;
typedef
basic_istringstream<char, char_traits<char>
>
istringstream;
typedef
basic_ostringstream<char, char_traits<char>
>
ostringstream;
typedef
basic_stringstream<char, char_traits<char>
>
stringstream;
typedef
basic_filebuf<char, char_traits<char>
>
filebuf;
typedef
basic_ifstream<char, char_traits<char>
>
ifstream;
typedef
basic_ofstream<char, char_traits<char>
>
ofstream;
102
Standard
C++ Library
typedef
basic_fstream<char, char_traits<char>
>
fstream;
//
wchar_t TYPE DEFINITIONS
typedef
basic_ios<wchar_t, char_traits<wchar_t> >
wios;
typedef
basic_streambuf<wchar_t, char_traits<wchar_t>
>
wstreambuf;
typedef
basic_istream<wchar_t, char_traits<wchar_t>
>
wistream;
typedef
basic_ostream<wchar_t, char_traits<wchar_t>
>
wostream;
typedef
basic_iostream<wchar_t, char_traits<wchar_t>
>
wiostream;
typedef
basic_stringbuf<wchar_t, char_traits<wchar_t>
>
wstringbuf;
typedef
basic_istringstream<wchar_t,
char_traits<wchar_t>
> wistringstream;
typedef
basic_ostringstream<wchar_t,
char_traits<wchar_t>
> wostringstream;
typedef
basic_stringstream<wchar_t,
char_traits<wchar_t>
> wstringstream;
typedef
basic_filebuf<wchar_t, char_traits<wchar_t>
>
wfilebuf;
typedef
basic_ifstream<wchar_t, char_traits<wchar_t>
>
wifstream;
typedef
basic_ofstream<wchar_t, char_traits<wchar_t>
>
wofstream;
typedef
basic_fstream<wchar_t, char_traits<wchar_t>
>
wfstream;
};
Include
the iostreams (page 7)
standard header <iosfwd>
to
declare forward
references
to several template classes used
throughout iostreams. All such
template
classes
are defined in other
standard headers. You
include this header
explicitly
only
when you need one of the
above declarations, but not
its definition.
<iostream>
namespace
std {
extern
istream cin;
extern
ostream cout;
extern
ostream cerr;
extern
ostream clog;
extern
wistream
wcin;
extern
wostream
wcout;
extern
wostream
wcerr;
extern
wostream
wclog;
};
Include
the iostreams (page 7)
standard header <iostream>
to
declare objects that
control
reading from and writing to the
standard streams. This is
often the only
header
you need include to perform
input and output from a C++
program.
The
objects fall into two
groups:
oriented
(page 17),
performing conventional
byte-at-a-time transfers
that
the program manipulates
internally
103
Chapter
12. Standard C++ Library
Header Files
Once
you perform certain operations
(page 20)
on a stream, such as the
standard
input,
you cannot perform operations of a
different orientation on the
same stream.
Hence,
a program cannot operate
interchangeably on both cin
and
wcin,
for
example.
All
the objects declared in this
header share a peculiar
property -- you can
assume
they
are constructed
before
any static objects you
define, in a translation unit
that
includes
<iostreams>.
Equally, you can assume that
these objects are not
destroyed
before
the destructors for any such
static objects you define.
(The output streams
are,
however, flushed during
program termination.) Hence, you
can safely read
from
or write to the standard
streams prior to program
startup and after
program
termination.
This
guarantee is not
universal,
however. A static constructor
may call a function
in
another
translation unit. The called
function cannot assume that
the objects
declared
in this header have been
constructed, given the
uncertain order in
which
translation
units participate in static
construction. To use these
objects in such a
context,
you must first construct an
object of class ios_base::Init
(page 97),
as in:
#include
<iostream>
void
marker()
{
//
called by some
constructor
ios_base::Init
unused_name;
cout
<< "called fun" <<
endl;
}
cerr
extern
ostream cerr;
The
object controls unbuffered
insertions to the standard
error output as a
byte
stream
(page 18).
Once the object is
constructed, the expression cerr.flags()
&
unitbuf
is
nonzero.
cin
extern
istream cin;
The
object controls extractions from
the standard input as a byte
stream (page 18).
Once
the object is constructed,
the call cin.tie()
returns
&cout.
clog
extern
ostream clog;
The
object controls buffered
insertions to the standard
error output as a
byte
stream
(page 18).
cout
extern
ostream cout;
The
object controls insertions to
the standard output as a
byte stream (page 18).
wcerr
extern
wostream wcerr;
104
Standard
C++ Library
The
object controls unbuffered
insertions to the standard
error output as a wide
stream
(page 18).
Once the object is
constructed, the expression wcerr.flags()
&
unitbuf
is
nonzero.
wcin
extern
wistream wcin;
The
object controls extractions from
the standard input as a wide
stream (page 18).
Once
the object is constructed,
the call wcin.tie()
returns
&wcout.
wclog
extern
wostream wclog;
The
object controls buffered
insertions to the standard
error output as a wide
stream.
wcout
extern
wostream wcout;
The
object controls insertions to
the standard output as a wide
stream (page 18).
<istream>
namespace
std {
template<class
E, class T = char_traits<E>
>
class
basic_istream;
typedef
basic_istream<char, char_traits<char>
>
istream;
typedef
basic_istream<wchar_t, char_traits<wchar_t>
>
wistream;
template<class
E, class T = char_traits<E>
>
class
basic_iostream;
typedef
basic_iostream<char, char_traits<char>
>
iostream;
typedef
basic_iostream<wchar_t, char_traits<wchar_t>
>
wiostream;
//
EXTRACTORS
template<class
E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is, E *s);
template<class
E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is, E& c);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char *s);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char& c);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char *s);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char& c);
105
Chapter
12. Standard C++ Library
Header Files
//
MANIPULATORS
template
class<E, T>
basic_istream<E,
T>& ws(basic_istream<E,
T>& is);
};
Include
the iostreams (page 7)
standard header <istream>
to
define template class
basic_istream
(page 106),
which mediates extractions for
the iostreams, and
the
template
class. basic_iostream (page 106),
which mediates both
insertions and
extractions.
The header also defines a
related manipulator (page 87).
(This header
is
typically included for you by another of
the iostreams headers. You
seldom have
occasion
to include it directly.)
basic_iostream
template
<class E, class T =
char_traits<E> >
class
basic_iostream
:
public basic_istream<E,
T>,
public
basic_ostream<E, T> {
public:
explicit
basic_iostream(basic_streambuf<E,
T>& *sb);
virtual
~basic_iostream();
};
The
template class describes an object
that controls insertions,
through its base
object
basic_ostream<E,
T> (page 169), and
extractions, through its
base object
basic_istream<E,
T>.
The two objects share a
common virtual base
object
basic_ios<E,
T>.
They also manage a common
stream buffer (page 187),
with
elements
of type E, whose
character traits (page 211)
are determined by the class
T.
The
constructor initializes its
base objects via basic_istream(sb)
and
basic_ostream(sb).
basic_istream
template
<class E, class T =
char_traits<E> >
class
basic_istream
:
virtual public basic_ios<E, T>
{
public:
typedef
typename basic_ios<E, T>::char_type
char_type;
typedef
typename basic_ios<E, T>::traits_type
traits_type;
typedef
typename basic_ios<E, T>::int_type
int_type;
typedef
typename basic_ios<E, T>::pos_type
pos_type;
typedef
typename basic_ios<E, T>::off_type
off_type;
explicit
basic_istream(basic_streambuf<E,
T> *sb);
class
sentry;
virtual
~istream();
bool
ipfx(bool
noskip = false);
void
isfx();
basic_istream&
operator>>(
basic_istream&
(*pf)(basic_istream&));
basic_istream&
operator>>(
ios_base&
(*pf)(ios_base&));
basic_istream&
operator>>(
basic_ios<E,
T>& (*pf)(basic_ios<E, T>&));
basic_istream&
operator>>(
basic_streambuf<E,
T> *sb);
basic_istream&
operator>>(bool&
n);
basic_istream&
operator>>(short&
n);
basic_istream&
operator>>(unsigned
short& n);
basic_istream&
operator>>(int&
n);
basic_istream&
operator>>(unsigned
int& n);
106
Standard
C++ Library
basic_istream&
operator>>(long&
n);
basic_istream&
operator>>(unsigned
long& n);
basic_istream&
operator>>(void
*& n);
basic_istream&
operator>>(float&
n);
basic_istream&
operator>>(double&
n);
basic_istream&
operator>>(long
double& n);
streamsize
gcount()
const;
int_type
get();
basic_istream&
get(char_type&
c);
basic_istream&
get(char_type
*s, streamsize n);
basic_istream&
get(char_type
*s, streamsize n, char_type
delim);
basic_istream&
get(basic_streambuf<char_type,
T> *sb);
basic_istream&
get(basic_streambuf<E,
T> *sb, char_type
delim);
basic_istream&
getline(char_type
*s, streamsize n);
basic_istream&
getline(char_type
*s, streamsize n,
char_type
delim);
basic_istream&
ignore(streamsize
n = 1,
int_type
delim = traits_type::eof());
int_type
peek();
basic_istream&
read(char_type
*s, streamsize n);
streamsize
readsome(char_type
*s, streamsize n);
basic_istream&
putback(char_type
c);
basic_istream&
unget();
pos_type
tellg();
basic_istream&
seekg(pos_type
pos);
basic_istream&
seekg(off_type
off,
ios_base::seek_dir
way);
int
sync();
};
The
template class describes an object
that controls extraction of
elements and
encoded
objects from a stream buffer
(page 187)
with elements of type E,
also
the
class T, also
known as traits_type (page 91).
Most
of the member functions that
overload operator>> (page 110)
are formatted
input
functions. They
follow the pattern:
iostate
state = goodbit;
const
sentry ok(*this);
if
(ok)
{try
{<extract
elements and convert
accumulate
flags in state
store
a successful conversion>}
catch
(...)
{try
{setstate(badbit);
}
catch
(...)
{}
if
((exceptions() & badbit) != 0)
throw;
}}
setstate(state);
return
(*this);
Many
other member functions are
unformatted
input functions. They
follow the
pattern:
iostate
state = goodbit;
count
= 0;
//
the value returned by
gcount
const
sentry ok(*this, true);
if
(ok)
{try
107
Chapter
12. Standard C++ Library
Header Files
{<extract
elements and deliver
count
extracted elements in
count
accumulate
flags in state>}
catch
(...)
{try
{setstate(badbit);
}
catch
(...)
{}
if
((exceptions() & badbit) != 0)
throw;
}}
setstate(state);
Both
groups of functions call setstate(eofbit)
if
they encounter end-of-file
while
extracting
elements.
An
object of class basic_istream<E,
T> stores:
v
a
virtual public base object
of class basic_ios<E,
T>
v
an
extraction
count for the
last unformatted input
operation (called count
in
the
code
above
basic_istream::basic_istream
explicit
basic_istream(basic_streambuf<E,
T> *sb);
The
constructor initializes the
base class by calling init(sb). It
also stores zero in
the
extraction count (page 108).
basic_istream::gcount
streamsize
gcount()
const;
The
member function returns the
extraction count (page 108).
basic_istream::get
int_type
get();
basic_istream&
get(char_type&
c);
basic_istream&
get(char_type
*s, streamsize n);
basic_istream&
get(char_type
*s, streamsize n,
char_type
delim);
basic_istream&
get(basic_streambuf<E,
T> *sb);
basic_istream&
get(basic_streambuf<E,
T> *sb,
char_type
delim);
The
first of these unformatted
input functions (page 107)
extracts an element, if
possible,
as if by returning rdbuf()->sbumpc().
Otherwise, it returns
traits_type::eof(). If the
function extracts no element, it
calls setstate(failbit).
The
second function extracts the
int_type (page 90)
element x
the
same way. If x
compares
equal to traits_type::eof(x), the
function calls setstate(failbit).
Otherwise,
it stores traits_type::to_char_type(x)
in
c. The
function returns
*this.
The
third function returns get(s,
n, widen('\n')).
The
fourth function extracts up to
n -
1 elements
and stores them in the
array
beginning
at s. It
always stores char_type()
after
any extracted elements it
stores.
In
order of testing, extraction
stops:
1.
at
end of file
2.
after
the function extracts an
element that compares equal
to delim, in
which
case
the element is put back to
the controlled
sequence
108
Standard
C++ Library
3.
after
the function extracts n
- 1 elements
If
the function extracts no
elements, it calls setstate(failbit). In any
case, it
returns
*this.
The
fifth function returns get(sb,
widen('\n')).
The
sixth function extracts
elements and inserts them in sb.
Extraction stops on
end-of-file
or on an element that compares
equal to delim
(which
is not extracted).
It
also stops, without
extracting the element in
question, if an insertion fails
or
throws
an exception (which is caught
but not rethrown). If the
function extracts no
elements,
it calls setstate(failbit). In any
case, the function returns
*this.
basic_istream::getline
basic_istream&
getline(char_type
*s, streamsize n);
basic_istream&
getline(char_type
*s, streamsize n,
char_type
delim);
The
first of these unformatted
input functions (page 107)
returns getline(s,
n,
widen('\n')).
The
second function extracts up to
n -
1 elements
and stores them in the
array
beginning
at s. It
always stores char_type()
after
any extracted elements it
stores.
In
order of testing, extraction
stops:
1.
at
end of file
2.
after
the function extracts an
element that compares equal
to delim, in
which
case
the element is neither put
back nor appended to the
controlled sequence
3.
after
the function extracts n
- 1 elements
If
the function extracts no
elements or n
- 1 elements,
it calls setstate(failbit).
In
any case, it returns *this.
basic_istream::ignore
basic_istream&
ignore(streamsize
n = 1,
int_type
delim = traits_type::eof());
The
unformatted input function
(page 107)
extracts up to n
elements
and discards
them.
If n
equals
numeric_limits<int>::max(),
however, it is taken as
arbitrarily
large.
Extraction stops early on
end-of-file or on an element x
such
that
traits_type::to_int_type(x)
compares
equal to delim
(which
is also extracted).
The
function returns *this.
basic_istream::ipfx
bool
ipfx(bool
noskip = false);
input.
If good()
is
true, the function:
v
calls
tie-> flush()
if
tie()
is
not a null pointer
v
effectively
calls ws(*this)
if
flags() &
skipws is
nonzero
If,
after any such preparation,
good()
is
false, the function calls
setstate(failbit).
In
any case, the function
returns good().
You
should not call ipfx
directly.
It is called as needed by an object of
class sentry
(page
112).
109
Chapter
12. Standard C++ Library
Header Files
basic_istream::isfx
void
isfx();
The
member function has no
official duties, but an
implementation may depend
on
to
tidy up after an extraction.
You should not call
isfx
directly.
It is called as
needed
by an object of class sentry (page 112).
basic_istream::operator>>
basic_istream&
operator>>(
basic_istream&
(*pf)(basic_istream&));
basic_istream&
operator>>(
ios_base&
(*pf)(ios_base&));
basic_istream&
operator>>(
basic_ios<E,
T>& (*pf)(basic_ios<E, T>&));
basic_istream&
operator>>(
basic_streambuf<E,
T> *sb);
basic_istream&
operator>>(bool&
n);
basic_istream&
operator>>(short&
n);
basic_istream&
operator>>(unsigned
short& n);
basic_istream&
operator>>(int&
n);
basic_istream&
operator>>(unsigned
int& n);
basic_istream&
operator>>(long&
n);
basic_istream&
operator>>(unsigned
long& n);
basic_istream&
operator>>(void
*& n);
basic_istream&
operator>>(float&
n);
basic_istream&
operator>>(double&
n);
basic_istream&
operator>>(long
double& n);
The
first member function
ensures that an expression of
the form istr
>> ws calls
ws(istr), then
returns *this. The
second and third functions
ensure that other
functions
constitute the formatted
input functions (page 107).
The
function:
basic_istream&
operator>>(
basic_streambuf<E,
T> *sb);
extracts
elements, if sb
is
not a null pointer, and inserts
them in sb.
Extraction
stops
on end-of-file. It also stops,
without extracting the
element in question, if an
insertion
fails or throws an exception
(which is caught but not
rethrown). If the
function
extracts no elements, it calls
setstate(failbit). In any
case, the function
returns
*this.
The
function:
basic_istream&
operator>>(bool&
n);
extracts
a field and converts it to a boolean
value by calling use_facet<num_get<E,
InIt>(getloc()).
get(InIt( rdbuf()), Init(0), *this, getloc(), n).
Here,
InIt
is
defined as istreambuf_iterator<E,
T>.
The function returns *this.
The
functions:
basic_istream&
operator>>(short&
n);
basic_istream&
operator>>(unsigned
short& n);
basic_istream&
operator>>(int&
n);
basic_istream&
operator>>(unsigned
int& n);
basic_istream&
operator>>(long&
n);
basic_istream&
operator>>(unsigned
long& n);
basic_istream&
operator>>(void
*& n);
110
Standard
C++ Library
each
extract a field and convert it to a
numeric value by
calling
use_facet<num_get<E,
InIt>(getloc()). get(InIt( rdbuf()), Init(0), *this,
getloc(),
x).
Here, InIt
is
defined as istreambuf_iterator<E,
T>,
and x has
type
long,
unsigned long, or
void
* as
needed.
If
the converted value cannot
be represented as the type of
n, the
function calls
setstate(failbit). In any
case, the function returns
*this.
The
functions:
basic_istream&
operator>>(float&
n);
basic_istream&
operator>>(double&
n);
basic_istream&
operator>>(long
double& n);
each
extract a field and convert it to a
numeric value by
calling
use_facet<num_get<E,
InIt>(getloc()). get(InIt( rdbuf()), Init(0), *this,
getloc(),
x).
Here, InIt
is
defined as istreambuf_iterator<E,
T>,
and x has
type
double
or
long
double as
needed.
If
the converted value cannot
be represented as the type of
n, the
function calls
setstate(failbit). In any
case, it returns *this.
basic_istream::peek
int_type
peek();
The
unformatted input function
(page 107)
extracts an element, if possible, as
if by
returning
rdbuf()->sgetc().
Otherwise, it returns traits_type::eof().
basic_istream::putback
basic_istream&
putback(char_type
c);
The
unformatted input function
(page 107)
puts back c, if
possible, as if by calling
rdbuf()->sputbackc(). If rdbuf()
is a
null pointer, or if the call to
sputbackc
returns
traits_type::eof(), the
function calls setstate(badbit). In any
case, it
returns
*this.
basic_istream::read
basic_istream&
read(char_type
*s, streamsize n);
The
unformatted input function
(page 107)
extracts up to n
elements
and stores
them
in the array beginning at s.
Extraction stops early on
end-of-file, in which
case
the function calls setstate(failbit). In any
case, it returns *this.
basic_istream::readsome
streamsize
readsome(char_type
*s, streamsize n);
The
member function extracts up to
n
elements
and stores them in the
array
beginning
at s. If rdbuf()
is a
null pointer, the function
calls setstate(failbit).
Otherwise,
it assigns the value of rdbuf()->in_avail()
to
N. if N <
0,
the function
calls
setstate(eofbit).
Otherwise, it replaces the
value stored in N
with
the
smaller
of n
and
N, then
calls read(s,
N). In
any case, the function
returns
gcount().
basic_istream::seekg
basic_istream&
seekg(pos_type
pos);
basic_istream&
seekg(off_type
off,
ios_base::seek_dir
way);
111
Chapter
12. Standard C++ Library
Header Files
If
fail()
is
false, the first member
function calls rdbuf()->
pubseekpos(pos).
If
fail()
is
false, the second function
calls rdbuf()->
pubseekoff(off, way).
Both
functions
return *this.
basic_istream::sentry
class
sentry
{
public:
explicit
sentry(basic_istream&
is,
bool
noskip
= false);
operator
bool()
const;
};
The
nested class describes an object
whose declaration structures
the formatted
constructor
effectively calls is.ipfx(noskip)
and
stores the return value.
operator
bool()
delivers
this return value. The
destructor effectively calls is.isfx().
basic_istream::sync
int
sync();
If
rdbuf()
is a
null pointer, the function
returns -1. Otherwise, it
calls
rdbuf()->pubsync(). If
that returns -1, the
function calls setstate(badbit)
and
returns
-1. Otherwise, the function
returns zero.
basic_istream::tellg
pos_type
tellg();
If
fail()
is
false, the member function
returns rdbuf()->
pubseekoff(0, cur, in).
Otherwise,
it returns pos_type(-1).
basic_istream::unget
basic_istream&
unget();
The
unformatted input function
(page 107)
puts back the previous
element in the
stream,
if possible, as if by calling rdbuf()->sungetc(). If rdbuf()
is a
null pointer,
or
if the call to sungetc
returns
traits_type::eof(), the
function calls
setstate(badbit). In any
case, it returns *this.
iostream
typedef
basic_iostream<char, char_traits<char> >
iostream;
The
type is a synonym for template class
basic_iostream (page 106),
specialized for
elements
of type char
with
default character traits
(page 211).
istream
typedef
basic_istream<char, char_traits<char> >
istream;
The
type is a synonym for template class
basic_istream (page 106),
specialized for
elements
of type char
with
default character traits
(page 211).
operator>>
template<class
E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is, E *s);
template<class
E, class T>
basic_istream<E,
T>&
112
Standard
C++ Library
operator>>(basic_istream<E,
T>& is, E& c);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char *s);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char& c);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char *s);
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char& c);
The
template function:
template<class
E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is, E *s);
extracts
up to n
- 1 elements
and stores them in the array
beginning at s.
If
is.width()
is
greater than zero, n
is
is.width();
otherwise it is the largest
array of
E
that
can be declared. The
function always stores E()
after
any extracted
elements
it
stores. Extraction stops
early on end-of-file or on any
element (which is not
extracted)
that would be discarded by ws (page 114).
If the function extracts
no
elements,
it calls is.setstate(failbit). In any
case, it calls is.width(0)
and
returns
is.
The
template function:
template<class
E, class T>
basic_istream<E,
T>&
operator>>(basic_istream<E,
T>& is, char& c);
extracts
an element, if possible, and stores it in
c.
Otherwise, it calls
is.setstate(failbit). In any
case, it returns is.
The
template function:
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char *s);
returns
is
>> (char *)s.
The
template function:
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
signed
char& c);
returns
is
>> (char&)c.
The
template function:
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char *s);
113
Chapter
12. Standard C++ Library
Header Files
returns
is
>> (char *)s.
The
template function:
template<class
T>
basic_istream<char,
T>&
operator>>(basic_istream<char,
T>& is,
unsigned
char& c);
returns
is
>> (char&)c.
wiostream
typedef
basic_iostream<wchar_t, char_traits<wchar_t>
>
wiostream;
The
type is a synonym for template class
basic_iostream (page 106),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
wistream
typedef
basic_istream<wchar_t, char_traits<wchar_t>
>
wistream;
The
type is a synonym for template class
basic_istream (page 106),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
ws
template
class<E, T>
basic_istream<E,
T>& ws(basic_istream<E,
T>& is);
The
manipulator extracts and discards
any elements x
for
which use_facet<
ctype<E>
>( getloc()). is( ctype<E>::space, x) is
true.
The
function calls setstate(eofbit)
if it
encounters end-of-file while
extracting
elements.
It returns is.
<limits>
namespace
std {
enum
float_denorm_style;
enum
float_round_style;
template<class
T>
class
numeric_limits;
};
Include
the standard header
<limits>
to
define the template class numeric_limits.
Explicit
specializations of this class describe
many arithmetic properties of
the
scalar
types (other than
pointers).
float_denorm_style
enum
float_denorm_style {
denorm_indeterminate
=
-1,
denorm_absent
=
0,
denorm_present
=
1
};
114
Standard
C++ Library
The
enumeration describes the
various methods that an
implementation can
choose
for
representing a denormalized
floating-point value -- one
too small to
represent
as
a normalized value:
v
denorm_indeterminate
--
presence or absence of denormalized
forms cannot be
determined
at translation time
v
denorm_absent
--
denormalized forms are
absent
v
denorm_present
--
denormalized forms are
present
float_round_style
enum
float_round_style {
round_indeterminate
=
-1,
round_toward_zero
=
0,
round_to_nearest
=
1,
round_toward_infinity
=
2,
round_toward_neg_infinity
=
3
};
The
enumeration describes the
various methods that an
implementation can
choose
for
rounding a floating-point value to an
integer value:
v
round_indeterminate
--
rounding method cannot be
determined
v
round_toward_zero
-- round
toward zero
v
round_to_nearest
-- round to
nearest integer
v
round_toward_infinity
-- round
away from zero
v
round_toward_neg_infinity
-- round to
more negative integer
numeric_limits
template<class
T>
class
numeric_limits {
public:
static
const float_denorm_style has_denorm
=
denorm_absent;
static
const bool has_denorm_loss
=
false;
static
const bool has_infinity
=
false;
static
const bool has_quiet_NaN
=
false;
static
const bool has_signaling_NaN
=
false;
static
const bool is_bounded
=
false;
static
const bool is_exact
=
false;
static
const bool is_iec559
=
false;
static
const bool is_integer
=
false;
static
const bool is_modulo
=
false;
static
const bool is_signed
=
false;
static
const bool is_specialized
=
false;
static
const bool tinyness_before
=
false;
static
const bool traps
=
false;
static
const float_round_style round_style
=
round_toward_zero;
static
const int digits
=
0;
static
const int digits10
=
0;
static
const int max_exponent
=
0;
static
const int max_exponent10
=
0;
static
const int min_exponent
=
0;
static
const int min_exponent10
=
0;
static
const int radix
=
0;
static
T denorm_min()
throw();
static
T epsilon()
throw();
static
T infinity()
throw();
static
T max()
throw();
static
T min()
throw();
115
Chapter
12. Standard C++ Library
Header Files
static
T quiet_NaN()
throw();
static
T round_error()
throw();
static
T signaling_NaN()
throw();
};
The
template class describes many
arithmetic properties of its
parameter type T.
The
header defines explicit
specializations for the types
wchar_t,
bool,
char, signed
char,
unsigned char, short,
unsigned short, int,
unsigned int, long, unsigned
long, float,
double,
and
long
double. For
all these explicit
specializations, the
member
is_specialized
is
true, and all relevant
members have meaningful
values. The
program
can supply additional
explicit specializations.
For
an arbitrary specialization, no members
have meaningful values. A
member
object
that does not have a
meaningful value stores zero
(or false) and a
member
function
that does not return a
meaningful value returns T(0).
numeric_limits::denorm_min
static
T denorm_min()
throw();
The
function returns the minimum
value for the type (which is
the same as min()
if
has_denorm is not equal to
denorm_present).
numeric_limits::digits
static
const int digits
=
0;
The
member stores the number of
radix (page 119)
digits that the type
can
represent
without change (which is the
number of bits other than
any sign bit for a
predefined
integer type, or the number
of mantissa digits for a
predefined
floating-point
type).
numeric_limits::digits10
static
const int digits10
=
0;
The
member stores the number of
decimal digits that the
type can represent
without
change.
numeric_limits::epsilon
static
T epsilon()
throw();
The
function returns the
difference between 1 and the
smallest value greater than
1
that
is representable for the type
(which is the value
FLT_EPSILON for type float).
numeric_limits::has_denorm
static
const float_denorm_style has_denorm
=
denorm_absent;
The
member stores denorm_present
(page 115)
for a floating-point type that
has
denormalized
values (effectively a variable
number of exponent
bits).
numeric_limits::has_denorm_loss
static
const bool has_denorm_loss
=
false;
The
member stores true for a
type that determines whether
a value has lost
accuracy
because it is delivered as a denormalized
result (too small to
represent as
a
normalized value) or because it is
inexact (not the same as a
result not subject to
limitations
of exponent range and precision), an
option with IEC 559 (page 117)
floating-point
representations that can
affect some results.
116
Standard
C++ Library
numeric_limits::has_infinity
static
const bool has_infinity
=
false;
The
member stores true for a
type that has a
representation for positive
infinity.
True
if is_iec559 (page 117)
is true.
numeric_limits::has_quiet_NaN
static
const bool has_quiet_NaN
=
false;
The
member stores true for a
type that has a
representation for a quiet
NaN,
an
encoding
that is ``Not a Number'' which
does not signal its
presence in an
expression.
True if is_iec559 (page 117)
is true.
numeric_limits::has_signaling_NaN
static
const bool has_signaling_NaN
=
false;
The
member stores true for a
type that has a
representation for a signaling
NaN,
an
encoding that is ``Not a Number''
which signals its presence
in an expression
by
reporting an exception. True if
is_iec559 (page 117)
is true.
numeric_limits::infinity
static
T infinity()
throw();
The
function returns the
representation of positive infinity for
the type. The
return
value
is meaningful only if has_infinity
(page 117)
is true.
numeric_limits::is_bounded
static
const bool is_bounded
=
false;
The
member stores true for a
type that has a bounded
set of representable
values
(which
is the case for all
predefined types).
numeric_limits::is_exact
static
const bool is_exact
=
false;
The
member stores true for a
type that has exact
representations for all its
values
(which
is the case for all
predefined integer types). A
fixed-point or rational
representation
is also considered exact,
but not a floating-point
representation.
numeric_limits::is_iec559
static
const bool is_iec559
=
false;
The
member stores true for a
type that has a
representation conforming to IEC
559,
an
international standard for representing
floating-point values (also known
as
IEEE
754 in the
USA).
numeric_limits::is_integer
static
const bool is_integer
=
false;
The
member stores true for a
type that has an integer
representation (which is
the
case
for all predefined integer
types).
numeric_limits::is_modulo
static
const bool is_modulo
=
false;
117
Chapter
12. Standard C++ Library
Header Files
The
member stores true for a
type that has a modulo
representation, where
all
results
are reduced modulo some
value (which is the case for
all predefined
unsigned
integer types).
numeric_limits::is_signed
static
const bool is_signed
=
false;
The
member stores true for a
type that has a signed
representation (which is
the
case
for all predefined floating-point and
signed integer
types).
numeric_limits::is_specialized
static
const bool is_specialized
=
false;
The
member stores true for a
type that has an explicit
specialization defined for
template
class numeric_limits (page 115)
(which is the case for
all scalar types
other
than pointers).
numeric_limits::max
static
T max()
throw();
The
function returns the maximum
finite value for the type
(which is INT_MAX
for
type int
and
FLT_MAX for type float).
The return value is
meaningful if
is_bounded
(page 117)
is true.
numeric_limits::max_exponent
static
const int max_exponent
=
0;
The
member stores the maximum
positive integer such that
the type can
represent
as
a finite value radix (page
119)
raised to that power (which is
the value
FLT_MAX_EXP
for type float).
Meaningful only for floating-point
types.
numeric_limits::max_exponent10
static
const int max_exponent10
=
0;
The
member stores the maximum
positive integer such that
the type can
represent
as
a finite value 10 raised to
that power (which is the
value FLT_MAX_10_EXP for
type
float).
Meaningful only for floating-point
types.
numeric_limits::min
static
T min()
throw();
The
function returns the minimum
normalized value for the
type (which is
INT_MIN
for type int
and
FLT_MIN for type float).
The return value is
meaningful
false.
numeric_limits::min_exponent
static
const int min_exponent
=
0;
The
member stores the minimum
negative integer such that
the type can
represent
as
a normalized value radix
(page 119)
raised to that power (which is
the value
FLT_MIN_EXP
for type float).
Meaningful only for floating-point
types.
numeric_limits::min_exponent10
static
const int min_exponent10
=
0;
118
Standard
C++ Library
The
member stores the minimum
negative integer such that
the type can
represent
as
a normalized value 10 raised to
that power (which is the
value
FLT_MIN_10_EXP
for type float).
Meaningful only for floating-point
types.
numeric_limits::quiet_NaN
static
T quiet_NaN()
throw();
The
function returns a representation of a
quiet NaN (page 117)
for the type. The
return
value is meaningful only if
has_quiet_NaN (page 117)
is true.
numeric_limits::radix
static
const int radix
=
0;
The
member stores the base of
the representation for the
type (which is 2 for
the
predefined
integer types, and the base
to which the exponent is
raised, or
FLT_RADIX,
for the predefined floating-point
types).
numeric_limits::round_error
static
T round_error()
throw();
The
function returns the maximum
rounding error for the
type.
numeric_limits::round_style
static
const float_round_style round_style
=
round_toward_zero;
The
member stores a value that
describes the vaious methods
that an
implementation
can choose for rounding a
floating-point value to an integer
value.
numeric_limits::signaling_NaN
static
T signaling_NaN()
throw();
The
function returns a representation of a
signaling NaN (page 117)
for the type.
The
return value is meaningful
only if has_signaling_NaN (page 117)
is true.
numeric_limits::tinyness_before
static
const bool tinyness_before
=
false;
The
member stores true for a
type that determines whether
a value is ``tiny''
(too
small
to represent as a normalized value)
before rounding, an option with
IEC 559
(page
117)
floating-point representations that
can affect some
results.
numeric_limits::traps
static
const bool traps
=
false;
The
member stores true for a
type that generates some
kind of signal to report
certain
arithmetic exceptions.
<locale>
119
Chapter
12. Standard C++ Library
Header Files
toupper
(page 164)
namespace
std {
class
locale;
class
ctype_base;
template<class
E>
class
ctype;
template<>
class
ctype<char>;
template<class
E>
class
ctype_byname;
class
codect_base;
template<class
From, class To, class
State>
class
codecvt;
template<class
From, class To, class
State>
class
codecvt_byname;
template<class
E, class InIt>
class
num_get;
template<class
E, class OutIt>
class
num_put;
template<class
E>
class
numpunct;
template<class
E>
class
numpunct_byname;
template<class
E>
class
collate;
template<class
E>
class
collate_byname;
class
time_base;
template<class
E, class InIt>
class
time_get;
template<class
E, class InIt>
class
time_get_byname;
template<class
E, class OutIt>
class
time_put;
template<class
E, class OutIt>
class
time_put_byname;
class
money_base;
template<class
E, bool Intl, class InIt>
class
money_get;
template<class
E, bool Intl, class
OutIt>
class
money_put;
template<class
E, bool Intl>
class
moneypunct;
template<class
E, bool Intl>
class
moneypunct_byname;
class
messages_base;
template<class
E>
class
messages;
template<class
E>
class
messages_byname;
//
TEMPLATE FUNCTIONS
template<class
Facet>
bool
has_facet(const
locale& loc);
template<class
Facet>
const
Facet& use_facet(const
locale& loc);
template<class
E>
bool
isspace(E c,
const locale& loc) const;
template<class
E>
120
Standard
C++ Library
bool
isprint(E c,
const locale& loc) const;
template<class
E>
bool
iscntrl(E c,
const locale& loc) const;
template<class
E>
bool
isupper(E c,
const locale& loc) const;
template<class
E>
bool
islower(E c,
const locale& loc) const;
template<class
E>
bool
isalpha(E c,
const locale& loc) const;
template<class
E>
bool
isdigit(E c,
const locale& loc) const;
template<class
E>
bool
ispunct(E c,
const locale& loc) const;
template<class
E>
bool
isxdigit(E c,
const locale& loc) const;
template<class
E>
bool
isalnum(E c,
const locale& loc) const;
template<class
E>
bool
isgraph(E c,
const locale& loc) const;
template<class
E>
E
toupper(E c,
const locale& loc) const;
template<class
E>
E
tolower(E c,
const locale& loc) const;
};
Include
the standard header
<locale>
to
define a host of template classes
and
functions
that encapsulate and manipulate
locales.
codecvt
template<class
From, class To, class
State>
class
codecvt
:
public locale::facet, codecvt_base
{
public:
typedef
From intern_type;
typedef
To extern_type;
typedef
State state_type;
explicit
codecvt(size_t
refs = 0);
result
in(State&
state,
const
To *first1, const To *last1,
const
To *next1,
From
*first2, From *last2, From
*next2);
result
out(State&
state,
const
From *first1, const From
*last1,
const
From *next1,
To
*first2, To *last2, To *next2);
result
unshift(State&
state,
To
*first2, To *last2, To *next2);
bool
always_noconv()
const throw();
int
max_length()
const throw();
int
length(State&
state,
const
To *first1, const To *last1,
size_t
_N2) const throw();
int
encoding()
const throw();
static
locale::id id;
protected:
~codecvt();
virtual
result do_in(State&
state,
const
To *first1, const To *last1,
const
To *next1,
From
*first2, From *last2, From
*next2);
virtual
result do_out(State&
state,
const
From *first1, const From
*last1,
const
From *next1,
To
*first2, To *last2, To *next2);
virtual
result do_unshift(State&
state,
121
Chapter
12. Standard C++ Library
Header Files
To
*first2, To *last2, To *next2);
virtual
bool do_always_noconv()
const throw();
virtual
int do_max_length()
const throw();
virtual
int do_encoding()
const throw();
virtual
int do_length(State&
state,
const
To *first1, const To *last1,
size_t
len2) const throw();
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions between a sequence of
values of type From
and a
sequence of
values
of type To. The
class State
characterizes
the transformation -- and an
object
of
class State
stores
any necessary state
information during a
conversion.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
The
template versions of do_in
and
do_out
always
return codecvt_base::noconv.
The
Standard C++ library defines
an explicit specialization, however,
that is more
useful:
template<>
codecvt<wchar_t,
char, mbstate_t>
which
converts between wchar_t
and
char
sequences.
codecvt::always_noconv
bool
always_noconv()
const throw();
The
member function returns do_always_noconv().
codecvt::codecvt
explicit
codecvt(size_t
refs = 0);
The
constructor initializes its locale::facet
base
object with locale::facet(refs).
codecvt::do_always_noconv
virtual
bool do_always_noconv()
const throw();
The
protected virtual member
function returns true only
if every call to
do_in
always
returns true.
codecvt::do_encoding
virtual
int do_encoding()
const throw();
The
protected virtual member
function returns:
v
-1, if
the encoding of sequences of
type extern_type
is
state dependent
v
0, if
the encoding involves
sequences of varying
lengths
v
n, if the
encoding involves only
sequences of length n
codecvt::do_in
virtual
result do_in(State
state&,
const
To *first1, const To *last1, const To
*next1,
From
*first2, From *last2, From
*next2);
The
protected virtual member
function endeavors to convert
the source sequence
at
[first1,
last1) to a
destination sequence that it
stores within [first2,
last2).
It
122
Standard
C++ Library
always
stores in next1
a
pointer to the first
unconverted element in the
source
sequence,
and it always stores in next2
a
pointer to the first
unaltered element in
the
destination sequence.
state
must
represent the initial
conversion state (page 12)
at the beginning of a
new
source sequence. The
function alters its stored
value, as needed, to reflect
the
current
state of a successful conversion.
Its stored value is
otherwise unspecified.
The
function returns:
v
codecvt_base::error
if the source sequence is
ill formed
v
codecvt_base::noconv
if the function performs no
conversion
v
codecvt_base::ok
if the conversion
succeeds
v
codecvt_base::partial
if the source is insufficient, or if
the destination is not
large
enough,
for the conversion to
succeed
The
template version always
returns noconv.
codecvt::do_length
virtual
int do_length(State
state&,
const
To *first1, const To *last1,
size_t
len2) const throw();
The
protected virtual member
function effectively calls do_in(state,
first1,
last1,
next1, buf, buf + len2, next2) for
some buffer buf
and
pointers next1
and
next2, then
returns next2
- buf.
(Thus, it counts the maximum
number of
conversions,
not greater than len2,
defined by the source
sequence at [first1,
last1).)
The
template version always
returns the lesser of last1
- first1 and len2.
codecvt::do_max_length
virtual
int do_max_length()
const throw();
The
protected virtual member
function returns the largest
permissible value
that
can
be returned by do_length(first1,
last1, 1), for
arbitrary valid values of
first1
and
last1. (Thus,
it is roughly analogous to the
macro MB_CUR_MAX, at
least
when To is type
char.)
The
template version always
returns 1.
codecvt::do_out
virtual
result do_out(State
state&,
const
From *first1, const From
*last1,
const
From *next1,
To
*first2, To *last2, To *next2);
The
protected virtual member
function endeavors to convert
the source sequence
at
[first1,
last1) to a
destination sequence that it
stores within [first2,
last2).
It
always
stores in next1
a
pointer to the first
unconverted element in the
source
sequence,
and it always stores in next2
a
pointer to the first
unaltered element in
the
destination sequence.
state
must
represent the initial
conversion state (page 12)
at the beginning of a
new
source sequence. The
function alters its stored
value, as needed, to reflect
the
current
state of a successful conversion.
Its stored value is
otherwise unspecified.
123
Chapter
12. Standard C++ Library
Header Files
The
function returns:
v
codecvt_base::error
if the source sequence is
ill formed
v
codecvt_base::noconv
if the function performs no
conversion
v
codecvt_base::ok
if the conversion
succeeds
v
codecvt_base::partial
if the source is insufficient, or if
the destination is not
large
enough,
for the conversion to
succeed
The
template version always
returns noconv.
codecvt::do_unshift
virtual
result do_unshift(State
state&,
To
*first2, To *last2, To *next2);
The
protected virtual member
function endeavors to convert
the source element
From(0)
to a
destination sequence that it
stores within [first2,
last2),
except for
the
terminating element To(0). It
always stores in next2
a
pointer to the first
unaltered
element in the destination
sequence.
state
must
represent the initial
conversion state (page 12)
at the beginning of a
new
source sequence. The
function alters its stored
value, as needed, to reflect
the
current
state of a successful conversion.
Typically, converting the
source element
From(0)
leaves
the current state in the
initial conversion
state.
The
function returns:
v
codecvt_base::error
if state
represents
an invalid state
v
codecvt_base::noconv
if the function performs no
conversion
v
codecvt_base::ok
if the conversion
succeeds
v
codecvt_base::partial
if the destination is not
large enough for the
conversion to
succeed
The
template version always
returns noconv.
codecvt::extern_type
typedef
To extern_type;
The
type is a synonym for the
template parameter To.
codecvt::in
result
in(State
state&,
const
To *first1, const To *last1, const To
*next1,
From
*first2, From *last2, From
*next2);
The
member function returns do_in(state,
first1, last1, next1, first2,
last2,
next2).
codecvt::intern_type
typedef
From intern_type;
The
type is a synonym for the
template parameter From.
codecvt::length
int
length(State
state&,
const
To *first1, const To *last1,
size_t
len2) const throw();
124
Standard
C++ Library
The
member function returns do_length(first1,
last1, len2).
codecvt::encoding
int
encoding()
const throw();
The
member function returns do_encoding().
codecvt::max_length
int
max_length()
const throw();
The
member function returns do_max_length().
codecvt::out
result
out(State
state&,
const
From *first1, const From
*last1,
const
From *next1,
To
*first2, To *last2, To *next2);
The
member function returns do_out(state,
first1, last1, next1, first2,
last2,
next2).
codecvt::state_type
typedef
State state_type;
The
type is a synonym for the
template parameter State.
codecvt::unshift
result
unshift(State
state&,
To
*first2, To *last2, To *next2);
The
member function returns do_unshift(state,
first2, last2, next2).
codecvt_base
class
codecvt_base
{
public:
enum
result
{ok,
partial,
error,
noconv};
};
The
class describes an enumeration common to
all specializations of template
class
codecvt
(page 121).
The enumeration result
describes
the possible return
values
v
error
if
the source sequence is ill
formed
v
noconv
if
the function performs no
conversion
v
ok if
the conversion
succeeds
v
partial
if
the destination is not large
enough for the conversion to
succeed
codecvt_byname
template<class
From, class To, class
State>
class
codecvt_byname
:
public codecvt<From, To, State>
{
public:
explicit
codecvt_byname(const
char *s,
size_t
refs = 0);
protected:
~codecvt_byname();
};
125
Chapter
12. Standard C++ Library
Header Files
The
template class describes an object
that can serve as a locale
facet (page 135)
of
type
codecvt<From,
To, State>.
Its behavior is determined by
the named (page
136)
locale s. The
constructor initializes its
base object with codecvt<From,
To,
State>(refs).
collate
template<class
E>
class
collate
:
public locale::facet {
public:
typedef
E char_type;
typedef
basic_string<E> string_type;
explicit
collate(size_t
refs = 0);
int
compare(const
E *first1, const E *last1,
const
E *first2, const E *last2)
const;
string_type
transform(const
E *first,
const
E *last) const;
long
hash(const
E *first, const E *last) const;
static
locale::id id;
protected:
~collate();
virtual
int
do_compare(const
E *first1, const E *last1,
const
E *first2, const E *last2)
const;
virtual
string_type do_transform(const
E *first,
const
E *last) const;
virtual
long do_hash(const
E *first,
const
E *last) const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
comparisons of sequences of type
E.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
collate::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
collate::collate
explicit
collate(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
collate::compare
int
compare(const
E *first1, const E *last1,
const
E *first2, const E *last2)
const;
The
member function returns do_compare(first1,
last1, first2, last2).
collate::do_compare
virtual
int do_compare(const
E *first1, const E *last1,
const
E *first2, const E *last2)
const;
The
protected virtual member
function compares the
sequence at [first1,
last1)
with
the sequence at [first2,
last2).
It compares values by applying
operator<
between
pairs of corresponding elements of
type E. The
first sequence
compares
less
if it has the smaller
element in the earliest
unequal pair in the
sequences, or if
no
unequal pairs exist but
the first sequence is
shorter.
126
Standard
C++ Library
If
the first sequence compares
less than the second
sequence, the function
returns
-1.
If the second sequence
compares less, the function
returns +1. Otherwise,
the
function
returns zero.
collate::do_hash
virtual
long do_hash(const
E *first,
const
E *last) const;
The
protected virtual member
function returns an integer
derived from the
values
of
the elements in the sequence
[first,
last).
Such a hash
value
can be useful,
for
example, in distributing sequences
pseudo randomly across an
array of lists.
collate::do_transform
virtual
string_type do_transform(const
E *first,
const
E *last) const;
The
protected virtual member
function returns an object of class
string_type (page
127)
whose controlled sequence is a
copy of the sequence [first,
last).
If a class
derived
from collate<E>
overrides
do_compare (page 126),
it should also
override
do_transform
to
match. Put simply, two
transformed strings should
yield the same
result,
when passed to collate::compare, that
you would get from passing
the
untransformed
strings to compare
in
the derived class.
collate::hash
long
hash(const
E *first, const E *last) const;
The
member function returns do_hash(first,
last).
collate::string_type
typedef
basic_string<E> string_type;
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store copies of the
source sequence.
collate::transform
string_type
transform(const
E *first,
const
E *last) const;
The
member function returns do_transform(first,
last).
collate_byname
template<class
E>
class
collate_byname
:
public collate<E> {
public:
explicit
collate_byname(const
char *s,
size_t
refs = 0);
protected:
~collate_byname();
};
The
template class describes an object
that can serve as a locale
facet (page 135)
of
type
collate<E>. Its
behavior is determined by the
named (page 136)
locale s.
The
constructor
initializes its base object
with collate<E>(refs).
ctype
127
Chapter
12. Standard C++ Library
Header Files
widen
(page 131)
template<class
E>
class
ctype
:
public locale::facet, public
ctype_base {
public:
typedef
E char_type;
explicit
ctype(size_t
refs = 0);
bool
is(mask
msk, E ch) const;
const
E *is(const
E *first, const E *last,
mask
*dst) const;
const
E *scan_is(mask
msk, const E *first,
const
E *last) const;
const
E *scan_not(mask
msk, const E *first,
const
E *last) const;
E
toupper(E
ch) const;
const
E *toupper(E *first, E
*last) const;
E
tolower(E
ch) const;
const
E *tolower(E *first, E
*last) const;
E
widen(char
ch) const;
const
char *widen(char
*first, char *last,
E
*dst) const;
char
narrow(E ch,
char dflt) const;
const
E *narrow(const
E *first, const E *last,
char
dflt, char *dst)
const;
static
locale::id id;
protected:
~ctype();
virtual
bool do_is(mask
msk, E ch) const;
virtual
const E *do_is(const
E *first, const E *last,
mask
*dst) const;
virtual
const E *do_scan_is(mask
msk, const E *first,
const
E *last) const;
virtual
const E *do_scan_not(mask
msk, const E *first,
const
E *last) const;
virtual
E do_toupper(E
ch) const;
virtual
const E *do_toupper(E *first, E
*last) const;
virtual
E do_tolower(E
ch) const;
virtual
const E *do_tolower(E *first, E
*last) const;
virtual
E do_widen(char
ch) const;
virtual
const char *do_widen(char
*first, char *last,
E
*dst) const;
virtual
char do_narrow(E ch,
char dflt) const;
virtual
const E *do_narrow(const
E *first,
const
E *last, char dflt, char *dst)
const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
characterize
various properties of a ``character''
(element) of type E. Such a
facet
also
converts between sequences of
E
elements
and sequences of char.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
The
Standard C++ library defines
two explicit specializations of this
template class:
v
ctype<char>
(page 131),
an explicit specialization whose
differences are
described
separately
v
ctype<wchar_t>, which
treats elements as wide characters
(page 13)
In
this implementation (page 3),
other specializations of template
class ctype<E>:
v
convert
a value ch
of
type E
to a
value of type char
with
the expression (char)ch
128
Standard
C++ Library
v
convert
a value c
of
type char
to
a value of type E
with
the expression E(c)
All
other operations are
performed on char
values
the same as for the
explicit
specialization
ctype<char>.
ctype::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
ctype::ctype
explicit
ctype(size_t
refs = 0);
The
constructor initializes its locale::facet
base
object with locale::facet(refs).
ctype::do_is
virtual
bool do_is(mask
msk, E ch) const;
virtual
const E *do_is(const
E *first, const E *last,
mask
*dst) const;
The
first protected member
template function returns
true if MASK(ch)
& msk is
nonzero,
where MASK(ch)
designates
the mapping between an
element value ch
and
its classification mask, of
type mask (page 132).
The name MASK
is
purely
symbolic
here; it is not defined by
the template class. For an
object of class
ctype<char>
(page 131),
the mapping is tab[(unsigned
char)(char)ch],
where tab
is
the stored pointer to the
ctype mask table (page 132).
The
second protected member
template function stores in dst[I]
the
value
MASK(first[I])
& msk,
where I
ranges
over the interval [0,
last - first).
ctype::do_narrow
virtual
char do_narrow(E ch,
char dflt) const;
virtual
const E *do_narrow(const
E *first, const E *last,
char
dflt, char *dst)
const;
The
first protected member
template function returns (char)ch, or dflt if
that
expression
is undefined.
The
second protected member
template function stores in dst[I]
the
value
do_narrow(first[I],
dflt),
for I in the
interval [0,
last - first).
ctype::do_scan_is
virtual
const E *do_scan_is(mask
msk, const E *first,
const
E *last) const;
The
protected member function
returns the smallest pointer
p
in
the range [first,
last)
for
which do_is(msk,
*p) is
true. If no such value
exists, the function
returns
last.
ctype::do_scan_not
virtual
const E *do_scan_not(mask
msk, const E *first,
const
E *last) const;
The
protected member function
returns the smallest pointer
p
in
the range [first,
last)
for
which do_is(msk,
*p) is
false. If no such value
exists, the function
returns
last.
129
Chapter
12. Standard C++ Library
Header Files
ctype::do_tolower
virtual
E do_tolower(E
ch) const;
virtual
const E *do_tolower(E *first, E
*last) const;
The
first protected member
template function returns
the lowercase
character
corresponding
to ch, if
such a character exists.
Otherwise, it returns ch.
The
second protected member
template function replaces
each element first[I],
for
I
in
the interval [0,
last - first),
with do_tolower(first[I]).
ctype::do_toupper
virtual
E do_toupper(E
ch) const;
virtual
const E *do_toupper(E *first, E
*last) const;
The
first protected member
template function returns
the uppercase
character
corresponding
to ch, if
such a character exists.
Otherwise, it returns ch.
The
second protected member
template function replaces
each element first[I],
for
I
in
the interval [0,
last - first),
with do_toupper(first[I]).
ctype::do_widen
virtual
E do_widen(char
ch) const;
virtual
const char *do_widen(char
*first, char *last,
E
*dst) const;
The
first protected member
template function returns E(ch).
The
second protected member
template function stores in dst[I]
the
value
do_widen(first[I]), for I in the
interval [0,
last - first).
ctype::is
bool
is(mask
msk, E ch) const;
const
E *is(const
E *first, const E *last,
mask
*dst) const;
The
first member function
returns do_is(msk,
ch).
The second member
function
returns
do_is(first,
last, dst).
ctype::narrow
char
narrow(E ch,
char dflt) const;
const
E *narrow(const
E *first, const E *last,
char
dflt, char *dst)
const;
The
first member function
returns do_narrow(ch,
dflt).
The second member
function
returns do_narrow(first,
last, dflt, dst).
ctype::scan_is
const
E *scan_is(mask
msk, const E *first,
const
E *last) const;
The
member function returns do_scan_is(msk,
first, last).
ctype::scan_not
const
E *scan_not(mask
msk, const E *first,
const
E *last) const;
The
member function returns do_scan_not(msk,
first, last).
130
Standard
C++ Library
ctype::tolower
E
tolower(E
ch) const;
const
E *tolower(E *first, E
*last) const;
The
first member function
returns do_tolower(ch). The
second member
function
returns
do_tolower(first,
last).
ctype::toupper
E
toupper(E
ch) const;
const
E *toupper(E *first, E
*last) const;
The
first member function
returns do_toupper(ch). The
second member
function
returns
do_toupper(first,
last).
ctype::widen
E
widen(char
ch) const;
const
char *widen(char
*first, char *last, E *dst)
const;
The
first member function
returns do_widen(ch). The
second member
function
returns
do_widen(first,
last, dst).
ctype<char>
template<>
class
ctype<char>
:
public locale::facet, public
ctype_base {
public:
typedef
char char_type;
explicit
ctype(const
mask *tab = 0, bool del =
false,
size_t
refs = 0);
bool
is(mask
msk, char ch) const;
const
char *is(const
char *first, const char
*last,
mask
*dst) const;
const
char *scan_is(mask
msk,
const
char *first, const char *last)
const;
const
char *scan_not(mask
msk,
const
char *first, const char *last)
const;
char
toupper(char
ch) const;
const
char *toupper(char
*first, char *last) const;
char
tolower(char
ch) const;
const
char *tolower(char
*first, char *last) const;
char
widen(char
ch) const;
const
char *widen(char
*first, char *last,
char
*dst) const;
char
narrow(char
ch, char dflt) const;
const
char *narrow(const
char *first,
const
char *last, char dflt, char
*dst) const;
static
locale::id id;
protected:
~ctype();
virtual
char do_toupper(char
ch) const;
virtual
const char *do_toupper(char
*first,
char
*last) const;
virtual
char do_tolower(char
ch) const;
virtual
const char *do_tolower(char
*first,
char
*last) const;
virtual
char do_widen(char
ch) const;
virtual
const char *do_widen(char
*first, char *last,
char
*dst) const;
virtual
char do_narrow(char
ch, char dflt) const;
virtual
const char *do_narrow(const
char *first,
const
char *last, char dflt, char
*dst) const;
131
Chapter
12. Standard C++ Library
Header Files
const
mask *table()
const throw();
static
const mask *classic_table()
const throw();
static
const size_t table_size;
};
The
class is an explicit specialization of
template class ctype (page 127)
for type
char.
Hence,
it describes an object that
can serve as a locale facet
(page 135),
to
characterize
various properties of a ``character''
(element) of type char.
The
explicit
specialization
differs from the template class in
several ways:
v
An
object of class ctype<char>
stores a
pointer to the first element
of a ctype
mask
table, an
array of UCHAR_MAX
+ 1 elements
of type ctype_base::mask.
It
also
stores a boolean object that
indicates whether the array
should be deleted
when
the ctype<E>
object
is destroyed.
v
Its
sole public constructor lets
you specify tab, the
ctype mask table, and del,
the
boolean object that is true
if the array should be
deleted when the
ctype<char>
object
is destroyed -- as well as the usual
reference-count
parameter
refs.
v
The
protected member function table()
returns
the stored ctype mask
table.
v
The
static member object table_size
specifies
the minimum number of
elements
in
a ctype mask table.
v
The
protected static member
function classic_table()
returns
the ctype mask
table
appropriate to the "C"
locale.
v
There
are no protected virtual
member functions do_is (page
129),
do_scan_is
functions
perform the equivalent
operations themselves.
copy
elements unaltered.
ctype_base
class
ctype_base
{
public:
enum
mask;
static
const mask space,
print,
cntrl,
upper,
lower,
digit,
punct,
xdigit,
alpha,
alnum,
graph;
};
The
class serves as a base class for facets
of template class ctype (page 127).
It
defines
just the enumerated type
mask
and
several constants of this
type. Each of
the
constants characterizes a different way
to classify characters, as defined by
the
functions
with similar names declared in
the header <ctype.h>.
The constants are:
v
space
(function
isspace)
v
print
(function
isprint)
v
cntrl
(function
iscntrl)
v
upper
(function
isupper)
v
lower
(function
islower)
v
digit
(function
isdigit)
v
punct
(function
ispunct)
v
xdigit
(function
isxdigit)
v
alpha
(function
isalpha)
v
alnum
(function
isalnum)
v
graph
(function
isgraph)
132
Standard
C++ Library
You
can charaterize a combination of
classifications by ORing these
constants. In
particular,
it is always true that alnum
== (alpha | digit) and
graph
== (alnum |
punct).
ctype_byname
template<class
E>
class
ctype_byname
:
public ctype<E> {
public:
explicit
ctype_byname(const
char *s,
size_t
refs = 0);
protected:
~ctype_byname();
};
The
template class describes an object
that can serve as a locale
facet (page 135)
of
type
ctype<E>. Its
behavior is determined by the
named (page 136)
locale s.
The
constructor
initializes its base object
with ctype<E>(refs)
(or
the equivalent for
base
class ctype<char> (page 131)).
has_facet
template<class
Facet>
bool
has_facet(const
locale& loc);
The
template function returns
true if a locale facet (page
135)
of class Facet
is
listed
within the locale object
(page 135)
loc.
isalnum
template<class
E>
bool
isalnum(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
alnum,
c).
isalpha
template<class
E>
bool
isalpha(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
alpha,
c).
iscntrl
template<class
E>
bool
iscntrl(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
cntrl,
c).
isdigit
template<class
E>
bool
isdigit(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
digit,
c).
133
Chapter
12. Standard C++ Library
Header Files
isgraph
template<class
E>
bool
isgraph(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
graph,
c).
islower
template<class
E>
bool
islower(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
lower,
c).
isprint
template<class
E>
bool
isprint(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
print,
c).
ispunct
template<class
E>
bool
ispunct(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
punct,
c).
isspace
template<class
E>
bool
isspace(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
space,
c).
isupper
template<class
E>
bool
isupper(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). is(ctype<E>::
upper,
c).
isxdigit
template<class
E>
bool
isxdigit(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc).
is(ctype<E>::
xdigit,
c).
locale
134
Standard
C++ Library
class
locale
{
public:
class
facet;
class
id;
typedef
int category;
static
const category none,
collate,
ctype,
monetary,
numeric,
time,
messages,
all;
locale();
explicit
locale(const
char *s);
locale(const
locale& x, const locale& y,
category
cat);
locale(const
locale& x, const char *s, category
cat);
template<class
Facet>
locale(const
locale& x, Facet *fac);
template<class
Facet>
locale
combine(const
locale& x) const;
template<class
E, class T, class A>
bool
operator()(const
basic_string<E, T, A>& lhs,
const
basic_string<E, T, A>& rhs)
const;
string
name()
const;
bool
operator==(const
locale& x) const;
bool
operator!=(const
locale& x) const;
static
locale global(const
locale& x);
static
const locale& classic();
};
The
class describes a locale
object that
encapsulates a locale. It
represents
culture-specific
information as a list of facets.
A facet is a pointer to an object of
a
class
derived from class facet (page 137)
that has a public object
of the form:
static
locale::id id;
You
can define an open-ended set
of these facets. You can
also construct a
locale
object
that designates an arbitrary
number of facets.
Predefined
groups of these facets
represent the locale
categories traditionally
managed
in the Standard C library by
the function
setlocale.
Category
collate
(page 137)
(LC_COLLATE)
includes the facets:
collate<char>
collate<wchar_t>
Category
ctype
(page 137)
(LC_CTYPE)
includes the facets:
ctype<char>
ctype<wchar_t>
codecvt<char,
char, mbstate_t>
codecvt<wchar_t,
char, mbstate_t>
Category
monetary
(page 137)
(LC_MONETARY)
includes the facets:
moneypunct<char,
false>
moneypunct<wchar_t,
false>
moneypunct<char,
true>
moneypunct<wchar_t,
true>
money_get<char,
istreambuf_iterator<char> >
money_get<wchar_t,
istreambuf_iterator<wchar_t> >
money_put<char,
ostreambuf_iterator<char> >
money_put<wchar_t,
ostreambuf_iterator<wchar_t> >
Category
numeric
(page 137)
(LC_NUMERIC)
includes the facets:
135
Chapter
12. Standard C++ Library
Header Files
num_get<char,
istreambuf_iterator<char> >
num_get<wchar_t,
istreambuf_iterator<wchar_t> >
num_put<char,
ostreambuf_iterator<char> >
num_put<wchar_t,
ostreambuf_iterator<wchar_t> >
numpunct<char>
numpunct<wchar_t>
Category
time
(page 137)
(LC_TIME)
includes the facets:
time_get<char,
istreambuf_iterator<char> >
time_get<wchar_t,
istreambuf_iterator<wchar_t> >
time_put<char,
ostreambuf_iterator<char> >
time_put<wchar_t,
ostreambuf_iterator<wchar_t> >
Category
messages
(page 137)
[sic]
(LC_MESSAGE)
includes the facets:
messages<char>
messages<wchar_t>
(The
last category is required by
Posix, but not the C
Standard.)
Some
of these predefined facets
are used by the iostreams
(page 7)
classes, to
control
the conversion of numeric
values to and from text
sequences.
An
object of class locale
also
stores a locale
name as an
object of class string
locale
object throws an object of class
runtime_error (page 185).
The stored locale
name
is "*" if the
locale object cannot be
certain that a C-style
locale corresponds
exactly
to that represented by the
object. Otherwise, you can
establish a matching
locale
within the Standard C
library, for the locale
object x, by
calling setlocale(
LC_ALL,
x.name. c_str()).
In
this implementation (page 3),
you can also call the
static member
function:
static
locale empty();
to
construct a locale object
that has no facets. It is
also a transparent
locale --
if
the
requested facet in a transparent
locale, they consult first
the global locale
(page
write:
cout.imbue(locale::empty());
Subsequent
insertions to cout (page 104)
are mediated by the
current state of the
global
locale. You can even
write:
locale
loc(locale::empty(),
locale::classic(),
locale::numeric);
cout.imbue(loc);
Numeric
formatting rules for subsequent
insertions to cout
remain
the same as in
the
C locale, even as the global
locale supplies changing
rules for inserting
dates
and
monetary amounts.
locale::category
typedef
int category;
static
const category none,
collate,
ctype,
monetary,
numeric,
time,
messages,
all;
The
type is a synonym for int,
so that it can represent any
of the C locale
categories.
It can also represent a
group of constants local to class
locale:
136
Standard
C++ Library
none,
corresponding to none of the
the C categories
v
collate,
corresponding to the C category
LC_COLLATE
v
ctype,
corresponding to the C category
LC_CTYPE
v
monetary,
corresponding to the C category
LC_MONETARY
v
numeric,
corresponding to the C category
LC_NUMERIC
v
time,
corresponding to the C category
LC_TIME
v
messages,
corresponding to the Posix
category LC_MESSAGE
v
v
all,
corresponding to the C union of
all categories LC_ALL
You
can represent an arbitrary
group of categories by ORing
these constants, as in
monetary
| time.
locale::classic
static
const locale& classic();
The
static member function
returns a locale object that
represents the classic
locale,
which
behaves the same as the C
locale within the Standard C
library.
locale::combine
template<class
Facet>
locale
combine(const
locale& x) const;
The
member function returns a
locale object that replaces
in (or adds to) *this
the
facet
Facet
listed
in x.
locale::facet
class
facet
{
protected:
explicit
facet(size_t
refs = 0);
virtual
~facet();
private:
facet(const
facet&)
//
not defined
void
operator=(const
facet&) // not defined
};
The
member class serves as the
base class for all locale
facets (page 135).
Note that
you
can neither copy nor assign
an object of class facet. You
can construct and
destroy
objects derived from class locale::facet, but
not objects of the base
class
proper.
Typically, you construct an object
myfac
derived
from facet
when
you
construct
a locale, as in:
locale
loc(locale::classic(), new
myfac);
In
such cases, the constructor
for the base class facet
should
have a zero refs
argument.
When the object is no longer
needed, it is deleted. Thus, you
supply a
nonzero
refs
argument
only in those rare cases
where you take responsibility
for
the
lifetime of the
object.
locale::global
static
locale global(const
locale& x);
The
static member function
stores a copy of x
as
the global
locale. It
also calls
setlocale(
LC_ALL, x.name. c_str()),
to establishing a matching locale
within the
Standard
C library. The function then
returns the previous global
locale. At
program
startup, the global locale
is the same as the classic
locale (page 137).
137
Chapter
12. Standard C++ Library
Header Files
locale::id
class
id
{
protected:
id();
private:
id(const
id&)
//
not defined
void
operator=(const
id&) // not defined
};
The
member class describes the
static member object
required by each
unique
locale
facet (page 135).
Note that you can
neither copy nor assign an
object of class
id.
locale::locale
locale();
explicit
locale(const
char *s);
locale(const
locale& x, const locale& y,
category
cat);
locale(const
locale& x, const char *s, category
cat);
template<class
Facet>
locale(const
locale& x, Facet *fac);
The
first constructor initializes
the object to match the
global locale (page 137).
The
second
constructor initializes all
the locale categories to
have behavior
consistent
with
the locale name (page 136)
s. The
remaining constructors copy x, with
the
exceptions
noted:
locale(const
locale& x, const locale& y,
category
cat);
replaces
from y those
facets corresponding to a category
c
for
which c
& cat is
nonzero.
locale(const
locale& x, const char *s, category
cat);
replaces
from locale(s, all)
those
facets corresponding to a category
c
for
which
c
& cat is
nonzero.
template<class
Facet>
locale(const
locale& x, Facet *fac);
replaces
in (or adds to) x
the
facet fac, if fac is not a
null pointer.
If
a locale name s
is a
null pointer or otherwise invalid,
the function throws
runtime_error
(page 185).
locale::name
string
name()
const;
The
member function returns the
stored locale name (page 136).
locale::operator!=
bool
operator!=(const
locale& x) const;
The
member function returns !(*this ==
x).
locale::operator()
template<class
E, class T, class A>
bool
operator()(const
basic_string<E, T, A>& lhs,
const
basic_string<E, T, A>& rhs);
138
Standard
C++ Library
The
member function effectively
executes:
const
collate<E>& fac =
use_fac<collate<E> >(*this);
return
(fac.compare(lhs.begin(),
lhs.end(),
rhs.begin(),
rhs.end()) < 0);
Thus,
you can use a locale object
as a function object (page 285).
locale::operator==
bool
operator==(const
locale& x) const;
The
member function returns true
only if *this
and
x
are
copies of the same
locale
or
have the same name
(other than "*").
messages
template<class
E>
class
messages
:
public locale::facet, public
messages_base {
public:
typedef
E char_type;
typedef
basic_string<E> string_type;
explicit
messages(size_t
refs = 0);
catalog
open(const
string& name,
const
locale& loc) const;
string_type
get(catalog
cat, int set, int msg,
const
string_type& dflt) const;
void
close(catalog
cat) const;
static
locale::id id;
protected:
~messages();
virtual
catalog do_open(const
string& name,
const
locale& loc) const;
virtual
string_type do_get(catalog
cat, int set,
int
msg, const string_type& dflt)
const;
virtual
void do_close(catalog
cat) const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
characterize
various properties of a message
catalog that
can supply messages
represented
as sequences of elements of type
E.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
messages::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
messages::close
void
close(catalog
cat) const;
The
member function calls do_close(cat);.
messages::do_close
virtual
void do_close(catalog
cat) const;
The
protected member function
closes the message catalog
(page 139)
cat,
which
must
have been opened by an
earlier call to do_open
(page 140).
139
Chapter
12. Standard C++ Library
Header Files
messages::do_get
virtual
string_type do_get(catalog
cat, int set, int msg,
const
string_type& dflt) const;
The
protected member function
endeavors to obtain a message
sequence from the
message
catalog (page 139)
cat. It may
make use of set, msg, and dflt in doing
so.
It
returns a copy of dflt
on
failure. Otherwise, it returns a
copy of the specified
message
sequence.
messages::do_open
virtual
catalog do_open(const
string& name,
const
locale& loc) const;
The
protected member function
endeavors to open a message
catalog (page 139)
whose
name is name. It may
make use of the locale
loc
in
doing so. It returns
a
value
that compares less than zero
on failure. Otherwise, the
returned value can be
used
as the first argument on a
later call to get (page 140).
It should in any case
be
used
as the argument on a later
call to close (page 139).
messages::get
string_type
get(catalog
cat, int set, int msg,
const
string_type& dflt) const;
The
member function returns do_get(cat,
set, msg, dflt);.
messages::messages
explicit
messages(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
messages::open
catalog
open(const
string& name,
const
locale& loc) const;
The
member function returns do_open(name,
loc);.
messages::string_type
typedef
basic_string<E> string_type;
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store copies of the
message sequences.
messages_base
class
messages_base
{
typedef
int catalog;
};
The
class describes a type common to
all specializations of template class
messages
(page
139).
The type catalog
is a
synonym for type int
that
describes the
possible
return
values from messages::do_open.
messages_byname
template<class
E>
class
messages_byname
:
public messages<E> {
public:
explicit
messages_byname(const
char *s,
140
Standard
C++ Library
size_t
refs = 0);
protected:
~messages_byname();
};
The
template class describes an object
that can serve as a locale
facet of
type
messages<E>. Its
behavior is determined by the
named locale s. The
constructor
initializes
its base object with messages<E>(refs).
money_base
class
money_base
{
enum
part
{none,
sign,
space,
symbol,
value};
struct
pattern
{
char
field[4];
};
};
The
class describes an enumeration and a
structure common to all
specializations
of
template class moneypunct (page 145).
The enumeration part
describes
the
possible
values in elements of the
array field
in
the structure pattern.
The values
of
part
are:
none
to
match zero or more spaces or
generate nothing
v
sign
to
match or generate a positive or
negative sign
v
space
to
match zero or more spaces or
generate a space
v
symbol
to
match or generate a currency
symbol
v
value
to
match or generate a monetary
value
v
money_get
template<class
E,
class
InIt = istreambuf_iterator<E> >
class
money_get
:
public locale::facet {
public:
typedef
E char_type;
typedef
InIt iter_type;
typedef
basic_string<E> string_type;
explicit
money_get(size_t
refs = 0);
iter_type
get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
long
double& val) const;
iter_type
get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
string_type&
val) const;
static
locale::id id;
protected:
~money_get();
virtual
iter_type do_get(iter_type
first,
iter_type
last, bool intl, ios_base& x,
ios_base::iostate&
st, string_type& val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last, bool intl, ios_base& x,
ios_base::iostate&
st, long double& val)
const;
};
The
template class describes an object
that can serve as a locale
facet, to control
conversions
of sequences of type E
to
monetary values.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
141
Chapter
12. Standard C++ Library
Header Files
money_get::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
money_get::do_get
virtual
iter_type do_get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
string_type&
val) const;
virtual
iter_type do_get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
long
double& val) const;
The
first virtual protected
member function endeavors to
match sequential
elements
beginning at first
in
the sequence [first,
last) until it
has recognized
a
complete, nonempty monetary
input field. If
successful, it converts this
field to a
sequence
of one or more decimal
digits, optionally preceded by a
minus sign (-),
to
represent the amount and
stores the result in the
string_type (page 143)
object
val. It
returns an iterator designating
the first element beyond
the monetary input
field.
Otherwise, the function
stores an empty sequence in val and
sets
ios_base::failbit
in
st. It
returns an iterator designating
the first element
beyond
any
prefix of a valid monetary input
field. In either case, if
the return value
equals
last, the
function sets ios_base::eofbit
in
st.
The
second virtual protected
member function behaves the
same as the first,
except
that
if successful it converts the
optionally-signed digit sequence to a
value of type
long
double and
stores that value in val.
The
format of a monetary input
field is determined by the
locale facet (page 135)
fac
returned
by the (effective) call use_facet
<moneypunct<E, intl> >(x.
getloc()).
Specifically:
v
fac.neg_format()
determines
the order in which
components of the field
occur.
v
fac.curr_symbol()
determines
the sequence of elements
that constitutes a
currency
symbol.
v
fac.positive_sign()
determines
the sequence of elements
that constitutes a
positive
sign.
v
fac.negative_sign()
determines
the sequence of elements
that constitutes a
negative
sign.
v
fac.grouping()
determines
how digits are grouped to
the left of any
decimal
point.
v
fac.thousands_sep()
determines
the element that separates
groups of digits to
the
left of any decimal
point.
v
fac.decimal_point()
determines
the element that separates
the integer digits
from
the fraction digits.
v
fac.frac_digits()
determines
the number of significant
fraction digits to
the
right
of any decimal point.
If
the sign string (fac.negative_sign
or
fac.positive_sign) has
more than one
element,
only the first element is
matched where the element
equal to
money_base::sign
(page 141)
appears
in the format pattern (fac.neg_format).
Any
remaining
elements are matched at the
end of the monetary input
field. If neither
string
has a first element that
matches the next element in
the monetary input
field,
the sign string is taken as
empty and the sign is
positive.
142
Standard
C++ Library
If
x.flags() &
showbase is
nonzero, the string fac.curr_symbol
must
match
where
the
element equal to money_base::symbol
appears
in the format pattern.
Otherwise,
if
money_base::symbol
occurs
at the end of the format
pattern, and if no elements
of
the sign string remain to be
matched, the currency symbol
is not
matched.
Otherwise,
the currency symbol is
optionally
matched.
If
no instances of fac.thousands_sep()
occur in
the value portion of the
monetary
input
field (where the element
equal to money_base::value
appears
in the format
pattern),
no grouping constraint is imposed.
Otherwise, any grouping
constraints
imposed
by fac.grouping()
is
enforced. Note that the
resulting digit
sequence
represents
an integer whose low-order fac.frac_digits()
decimal
digits are
considered
to the right of the decimal
point.
Arbitrary
white space (page 31)
is matched where the
element equal to
money_base::space
appears
in the format pattern, if it
appears other than at
the
end
of the format pattern.
Otherwise, no internal white
space is matched. An
element
c
is
considered white space if use_facet
<ctype<E> >(x. getloc()).
is(ctype_base::
space, c) is
true.
money_get::get
iter_type
get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
long
double& val) const;
iter_type
get(iter_type
first, iter_type last,
bool
intl, ios_base& x, ios_base::iostate&
st,
string_type&
val) const;
Both
member functions return do_get(first,
last, intl, x, st, val).
money_get::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter InIt.
money_get::money_get
explicit
money_get(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
money_get::string_type
typedef
basic_string<E> string_type;
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store sequences of
elements from the source
sequence.
money_put
template<class
E,
class
OutIt = ostreambuf_iterator<E> >
class
money_put
:
public locale::facet {
public:
typedef
E char_type;
typedef
OutIt iter_type;
typedef
basic_string<E> string_type;
explicit
money_put(size_t
refs = 0);
iter_type
put(iter_type
next, bool intl, ios_base& x,
E
fill, long double& val)
const;
iter_type
put(iter_type
next, bool intl, ios_base& x,
E
fill, string_type& val) const;
static
locale::id id;
143
Chapter
12. Standard C++ Library
Header Files
protected:
~money_put();
virtual
iter_type do_put(iter_type
next, bool intl,
ios_base&
x, E fill, string_type& val)
const;
virtual
iter_type do_put(iter_type
next, bool intl,
ios_base&
x, E fill, long double& val)
const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions of monetary values to
sequences of type E.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
money_put::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
money_put::do_put
virtual
iter_type do_put(iter_type
next, bool intl,
ios_base&
x, E fill, string_type& val)
const;
virtual
iter_type do_put(iter_type
next, bool intl,
ios_base&
x, E fill, long double& val)
const;
The
first virtual protected
member function generates
sequential elements
beginning
at next
to
produce a monetary
output field from the
string_type (page
145)
object val. The
sequence controlled by val
must
begin with one or
more
decimal
digits, optionally preceded by a
minus sign (-), which
represents the
amount.
The function returns an
iterator designating the
first element beyond
the
generated
monetary output
field.
The
second virtual protected
member function behaves the
same as the first,
except
that
it effectively first converts
val
to a
sequence of decimal digits,
optionally
preceded
by a minus sign, then
converts that sequence as
above.
The
format of a monetary output
field is determined by the
locale facet (page 135)
fac
returned
by the (effective) call use_facet
<moneypunct<E, intl> >(x.
getloc()).
Specifically:
v
fac.pos_format()
determines
the order in which
components of the field
are
generated
for a non-negative value.
v
fac.neg_format()
determines
the order in which
components of the field
are
generated
for a negative value.
v
fac.curr_symbol()
determines
the sequence of elements to
generate for a
currency
symbol.
v
fac.positive_sign()
determines
the sequence of elements to
generate for a
positive
sign.
v
fac.negative_sign()
determines
the sequence of elements to
generate for a
negative
sign.
v
fac.grouping()
determines
how digits are grouped to
the left of any
decimal
point.
v
fac.thousands_sep()
determines
the element that separates
groups of digits to
the
left of any decimal
point.
v
fac.decimal_point()
determines
the element that separates
the integer digits
from
any fraction digits.
144
Standard
C++ Library
v
fac.frac_digits()
determines
the number of significant
fraction digits to
the
right
of any decimal point.
If
the sign string (fac.negative_sign
or
fac.positive_sign) has
more than one
element,
only the first element is
generated where the element
equal to
money_base::sign
appears
in the format pattern (fac.neg_format
or
fac.pos_format). Any
remaining elements are
generated at the end of the
monetary
output
field.
If
x.flags() &
showbase is
nonzero, the string fac.curr_symbol
is
generated where
the
element equal to money_base::symbol
appears
in the format pattern.
Otherwise,
no
currency symbol is
generated.
If
no grouping constraints are
imposed by fac.grouping()
(its
first element has
the
value
CHAR_MAX) then no instances of fac.thousands_sep()
are
generated in the
value
portion of the monetary
output field (where the
element equal to
money_base::value
appears
in the format pattern). If fac.frac_digits()
is
zero,
then
no instance of fac.decimal_point()
is
generated after the decimal
digits.
Otherwise,
the resulting monetary
output field places the
low-order
fac.frac_digits()
decimal
digits to the right of the
decimal point.
Padding
(page 154)
occurs as for any numeric
output field, except that if
x.flags()
&
x.internal is
nonzero, any internal
padding is generated where
the element
equal
to money_base::space
appears
in the format pattern, if it
does appear.
Otherwise,
internal padding occurs
before the generated
sequence. The padding
character
is fill.
The
function calls x.width(0)
to
reset the field width to
zero.
money_put::put
iter_type
put(iter_type
next,
bool
intl, ios_base& x,
E
fill, long double& val)
const;
iter_type
put(iter_type
next,
bool
intl, ios_base& x,
E
fill, string_type& val)
const;
Both
member functions return do_put(next,
intl, x, fill, val).
money_put::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter OutIt.
money_put::money_put
explicit
money_put(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
money_put::string_type
typedef
basic_string<E> string_type;
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store sequences of
elements from the source
sequence.
moneypunct
145
Chapter
12. Standard C++ Library
Header Files
thousands_sep
(page 149)
template<class
E, bool Intl>
class
moneypunct
:
public locale::facet, public
money_base {
public:
typedef
E char_type;
typedef
basic_string<E> string_type;
explicit
moneypunct(size_t
refs = 0);
E
decimal_point()
const;
E
thousands_sep()
const;
string
grouping()
const;
string_type
curr_symbol()
const;
string_type
positive_sign()
const;
string_type
negative_sign()
const;
int
frac_digits()
const;
pattern
pos_format(
oonst;
pattern
neg_format()
const;
static
const bool intl
=
Intl;
static
locale::id id;
protected:
~moneypunct();
virtual
E do_decimal_point()
const;
virtual
E do_thousands_sep()
const;
virtual
string do_grouping()
const;
virtual
string_type do_curr_symbol()
const;
virtual
string_type do_positive_sign()
const;
virtual
string_type do_negative_sign()
const;
virtual
int do_frac_digits()
const;
virtual
pattern do_pos_format()
const;
virtual
pattern do_neg_format()
const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
desceibe
the sequences of type E
used to
represent a monetary
input field (page
international
conventions are
observed.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
The
const static object
intl
stores
the value of the template
parameter Intl.
moneypunct::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
moneypunct::curr_symbol
string_type
curr_symbol()
const;
The
member function returns do_curr_symbol().
moneypunct::decimal_point
E
decimal_point()
const;
The
member function returns do_decimal_point().
146
Standard
C++ Library
moneypunct::do_curr_symbol
string_type
do_curr_symbol()
const;
The
protected virtual member
function returns a locale-specific
sequence of
elements
to use as a currency
symbol.
moneypunct::do_decimal_point
E
do_decimal_point()
const;
The
protected virtual member
function returns a locale-specific
element to use as a
decimal-point.
moneypunct::do_frac_digits
int
do_frac_digits()
const;
The
protected virtual member
function returns a locale-specific
count of the
number
of digits to display to the
right of any decimal
point.
moneypunct::do_grouping
string
do_grouping()
const;
The
protected virtual member
function returns a locale-specific
rule for
determining
how digits are grouped to
the left of any decimal
point. The encoding
is
the same as for lconv::grouping.
moneypunct::do_neg_format
pattern
do_neg_format()
const;
The
protected virtual member
function returns a locale-specific
rule for
determining
how to generate a monetary output
field (page 144)
for a negative
amount.
Each of the four elements of pattern::field
can
have the values:
v
none
(page 141)
to
match zero or more spaces or
generate nothing
v
sign
(page 141)
to
match or generate a positive or
negative sign
v
space
(page 141)
to
match zero or more spaces or
generate a space
v
symbol
(page 141)
to
match or generate a currency
symbol
v
value
(page 141)
to
match or generate a monetary
value
Components
of a monetary output field
are generated (and
components of a
monetary
input field (page 142)
are matched) in the
order in which these
elements
appear
in pattern::field. Each
of the values sign, symbol, value, and
either none
or
space
must
appear exactly once. The
value none
must
not appear first.
The
value
space
must
not appear first or last. If
Intl
is
true, the order is symbol, sign,
none, then
value.
The
template version of moneypunct<E,
Intl> returns
{money_base::symbol,
money_base::sign,
money_base::value, money_base::none}.
moneypunct::do_negative_sign
string_type
do_negative_sign()
const;
The
protected virtual member
function returns a locale-specific
sequence of
elements
to use as a negative
sign.
moneypunct::do_pos_format
pattern
do_pos_format()
const;
147
Chapter
12. Standard C++ Library
Header Files
The
protected virtual member
function returns a locale-specific
rule for
determining
how to generate a monetary output
field (page 144)
for a positive
amount.
(It also determines how to
match the components of a
monetary input
The
template version of moneypunct<E,
Intl> returns
{money_base::symbol,
money_base::sign,
money_base::value, money_base::none}.
moneypunct::do_positive_sign
string_type
do_positive_sign()
const;
The
protected virtual member
function returns a locale-specific
sequence of
elements
to use as a positive
sign.
moneypunct::do_thousands_sep
E
do_thousands_sep()
const;
The
protected virtual member
function returns a locale-specific
element to use as a
group
separator to the left of any
decimal point.
moneypunct::frac_digits
int
frac_digits()
const;
The
member function returns do_frac_digits().
moneypunct::grouping
string
grouping()
const;
The
member function returns do_grouping().
moneypunct::moneypunct
explicit
moneypunct(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
moneypunct::neg_format
pattern
neg_format()
const;
The
member function returns do_neg_format().
moneypunct::negative_sign
string_type
negative_sign()
const;
The
member function returns do_negative_sign().
moneypunct::pos_format
pattern
pos_format()
const;
The
member function returns do_pos_format().
moneypunct::positive_sign
string_type
positive_sign()
const;
The
member function returns do_positive_sign().
moneypunct::string_type
typedef
basic_string<E> string_type;
148
Standard
C++ Library
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store copies of the
punctuation sequences.
moneypunct::thousands_sep
E
thousands_sep()
const;
The
member function returns do_thousands_sep().
moneypunct_byname
template<class
E, bool Intl>
class
moneypunct_byname
:
public moneypunct<E, Intl> {
public:
explicit
moneypunct_byname(const
char *s,
size_t
refs = 0);
protected:
~moneypunct_byname();
};
The
template class describes an object
that can serve as a locale
facet of
type
moneypunct<E,
Intl>. Its
behavior is determined by the
named (page 136)
locale s.
The
constructor initializes its
base object with moneypunct<E,
Intl>(refs).
num_get
template<class
E, class InIt = istreambuf_iterator<E>
>
class
num_get
:
public locale::facet {
public:
typedef
E char_type;
typedef
InIt iter_type;
explicit
num_get(size_t
refs = 0);
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
long&
val) const;
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
unsigned
long& val) const;
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
double&
val) const;
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
long
double& val) const;
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
void
*& val) const;
iter_type
get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
bool&
val) const;
static
locale::id id;
protected:
~num_get();
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
long&
val) const;
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
unsigned
long& val) const;
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
double&
val) const;
149
Chapter
12. Standard C++ Library
Header Files
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
long
double& val) const;
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
void
*& val) const;
virtual
iter_type
do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
bool&
val) const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions of sequences of type
E
to
numeric values.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
num_get::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
num_get::do_get
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
long&
val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
unsigned
long& val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
double&
val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
long
double& val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
void
*& val) const;
virtual
iter_type do_get(iter_type
first,
iter_type
last,
ios_base&
x, ios_base::iostate& st,
bool&
val) const;
The
first virtual protected
member function endeavors to
match sequential
elements
beginning at first
in
the sequence [first,
last) until it
has recognized
a
complete, nonempty integer
input field. If
successful, it converts this
field to its
equivalent
value as type long,
and
stores the result in val. It
returns an iterator
designating
the first element beyond
the numeric input field.
Otherwise, the
function
stores nothing in val
and sets
ios_base::failbit
in
st. It
returns an
iterator
designating the first
element beyond any prefix of
a valid integer input
field.
In either case, if the
return value equals last, the
function sets
ios_base::eofbit
in
st.
The
integer input field is
converted by the same rules
used by the scan
functions
(page
25)
for matching and converting a series
of char
elements
from a file. (Each
such
char
element
is assumed to map to an equivalent
element of type E
by
a
simple,
one-to-one, mapping.) The
equivalent scan conversion
specification (page
25)
is determined as follows:
150
Standard
C++ Library
v If x.flags()
& ios_base::basefield == ios_base::oct, the
conversion
specification
is lo.
v
If
x.flags() &
ios_base::basefield == ios_base::hex,
the conversion
specification
is lx.
v
If
x.flags() &
ios_base::basefield == 0,
the conversion specification is
li.
v
Otherwise,
the conversion specification is
ld.
The
format of an integer input
field is further determined by
the locale facet
(page
135)
fac returned
by the call use_facet
<numpunct<E>(x. getloc()).
Specifically:
v
fac.grouping()
determines
how digits are grouped to
the left of any
decimal
point
v
fac.thousands_sep()
determines
the sequence that separates
groups of digits to
the
left of any decimal
point
If
no instances of fac.thousands_sep()
occur in
the numeric input field,
no
grouping
constraint is imposed. Otherwise,
any grouping constraints
imposed by
fac.grouping()
is
enforced and separators are
removed before the scan
conversion
occurs.
The
second virtual protected
member function:
virtual
iter_type do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
unsigned
long& val) const;
behaves
the same as the first,
except that it replaces a
conversion specification of
ld
with
lu. If
successful it converts the
numeric input field to a
value of type
unsigned
long and
stores that value in val.
The
third virtual protected
member function:
virtual
iter_type do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
double&
val) const;
behaves
the same as the first,
except that it endeavors to
match a complete,
nonempty
floating-point
input field. fac.decimal_point()
determines
the
sequence
that separates the integer
digits from the fraction
digits. The
equivalent
scan
conversion specifier is lf.
The
fourth virtual protected
member function:
virtual
iter_type do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
long
double& val) const;
behaves
the same the third,
except that the equivalent
scan conversion specifier
is
Lf.
The
fifth virtual protected
member function:
virtual
iter_type do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
void
*& val) const;
behaves
the same the first,
except that the equivalent
scan conversion specifier is p.
The
sixth virtual protected
member function:
151
Chapter
12. Standard C++ Library
Header Files
virtual
iter_type do_get(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st,
bool&
val) const;
behaves
the same as the first,
except that it endeavors to
match a complete,
nonempty
boolean
input field. If
successful it converts the
boolean input field to
a
value
of type bool
and
stores that value in val.
A
boolean input field takes
one of two forms. If x.flags()
& ios_base::boolalpha
is
false, it is the same as an
integer input field, except
that the converted
value
must
be either 0 (for false) or 1
(for true). Otherwise, the
sequence must match
either
fac.falsename()
(for
false), or fac.truename()
(for
true).
num_get::get
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
long&
val) const;
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
unsigned
long& val) const;
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
double&
val) const;
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
long
double& val) const;
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
void
*& val) const;
iter_type
get(iter_type
first, iter_type
last,
ios_base&
x, ios_base::iostate& st,
bool&
val) const;
All
member functions return do_get(first,
last, x, st, val).
num_get::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter InIt.
num_get::num_get
explicit
num_get(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
num_put
template<class
E, class OutIt = ostreambuf_iterator<E>
>
class
num_put
:
public locale::facet {
public:
typedef
E char_type;
typedef
OutIt iter_type;
explicit
num_put(size_t
refs = 0);
iter_type
put(iter_type
next, ios_base& x,
E
fill, long val) const;
iter_type
put(iter_type
next, ios_base& x,
E
fill, unsigned long val)
const;
iter_type
put(iter_type
next, ios_base& x,
E
fill, double val) const;
iter_type
put(iter_type
next, ios_base& x,
E
fill, long double val)
const;
iter_type
put(iter_type
next, ios_base& x,
152
Standard
C++ Library
E fill,
const void *val)
const;
iter_type
put(iter_type
next, ios_base& x,
E
fill, bool val) const;
static
locale::id id;
protected:
~num_put();
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, long val) const;
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, unsigned long val)
const;
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, double val) const;
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, long double val)
const;
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, const void *val)
const;
virtual
iter_type do_put(iter_type
next, ios_base&
x,
E
fill, bool val) const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions of numeric values to
sequences of type E.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
num_put::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
num_put::do_put
virtual
iter_type do_put(iter_type
next,
ios_base&
x,
E
fill, long val) const;
virtual
iter_type do_put(iter_type
next,
ios_base&
x,
E
fill, unsigned long val)
const;
virtual
iter_type do_put(iter_type
next,
ios_base&
x,
E
fill, double val) const;
virtual
iter_type do_put(iter_type
nextp
ios_base&
x,
E
fill, long double val)
const;
virtual
iter_type do_put(iter_type
nextp
ios_base&
x,
E
fill, const void *val)
const;
virtual
iter_type do_put(iter_type
next,
ios_base&
x,
E
fill, bool val) const;
The
first virtual protected
member function generates
sequential elements
beginning
at next
to
produce an integer
output field from the
value of val.
The
function
returns an iterator designating
the next place to insert an
element beyond
the
generated integer output
field.
The
integer output field is
generated by the same rules
used by the print
functions
(page
32)
for generating a series of char
elements
to a file. (Each such
char
element
is
assumed to map to an equivalent element
of type E
by a
simple, one-to-one,
mapping.)
Where a print function pads
a field with either spaces or
the digit 0,
however,
do_put
instead
uses fill. The
equivalent print conversion
specification
(page
32)
is determined as follows:
v
If
x.flags() &
ios_base::basefield == ios_base::oct,
the conversion
specification
is lo.
v
If
x.flags() &
ios_base::basefield == ios_base::hex,
the conversion
specification
is lx.
153
Chapter
12. Standard C++ Library
Header Files
v Otherwise,
the conversion specification is
ld.
If
x.width()
is
nonzero, a field width of this
value is prepended. The
function then
calls
x.width(0)
to
reset the field width to
zero.
Padding
occurs
only if the minimum number of
elements N
required
to specify the
output
field is less than x.width(). Such
padding consists of a sequence of
N
-
width()
copies
of fill.
Padding then occurs as
follows:
v
If
x.flags() &
ios_base::adjustfield == ios_base::left,
the flag -
is
prepended.
(Padding occurs after the
generated text.)
v
If
x.flags() &
ios_base::adjustfield ==
ios_base::internal,
the flag 0
is
prepended.
(For a numeric output field,
padding occurs where the
print
functions
pad with 0.)
v
Otherwise,
no additional flag is prepended.
(Padding occurs before
the
generated
sequence.)
Finally:
v
If
x.flags() &
ios_base::showpos is
nonzero, the flag +
is
prepended to the
conversion
specification.
v
If
x.flags() &
ios_base::showbase is
nonzero, the flag #
is
prepended to the
conversion
specification.
The
format of an integer output
field is further determined by
the locale facet
(page
135)
fac returned
by the call use_facet
<numpunct<E>(x. getloc()).
Specifically:
v
fac.grouping()
determines
how digits are grouped to
the left of any
decimal
point
v
fac.thousands_sep()
determines
the sequence that separates
groups of digits to
the
left of any decimal
point
If
no grouping constraints are
imposed by fac.grouping()
(its
first element has
the
value
CHAR_MAX) then no instances of fac.thousands_sep()
are
generated in the
output
field. Otherwise, separators
are inserted after the
print conversion
occurs.
The
second virtual protected
member function:
virtual
iter_type do_put(iter_type
next, ios_base& x,
E
fill, unsigned long val)
const;
behaves
the same as the first,
except that it replaces a
conversion specification of
ld
with
lu.
The
third virtual protected
member function:
virtual
iter_type do_put(iter_type
next, ios_base& x,
E
fill, double val) const;
behaves
the same as the first,
except that it produces a
floating-point
output field
from
the value of val. fac.decimal_point()
determines
the sequence that
separates
the
integer digits from the
fraction digits. The
equivalent print
conversion
specification
is determined as follows:
v
If
x.flags()
&
ios_base::floatfield
== ios_base::fixed,
the conversion
specification
is
lf.
v
If
x.flags()
&
ios_base::floatfield
== ios_base::scientific,
the conversion
specification
is
le. If x.flags() &
ios_base::uppercase is
nonzero, e
is
replaced
with
E.
154
Standard
C++ Library
v Otherwise,
the conversion specification is
lg. If x.flags()
&
ios_base::uppercase
is
nonzero, g
is
replaced with G.
If
x.flags() &
ios_base::fixed is
nonzero, or if x.precision()
is
greater than
zero,
a precision with the value x.precision()
is
prepended to the
conversion
specification.
Any padding (page 154)
behaves the same as for an
integer output
field.
The padding character is fill.
Finally:
v
If
x.flags() &
ios_base::showpos is
nonzero, the flag +
is
prepended to the
conversion
specification.
v
If
x.flags() &
ios_base::showpoint is
nonzero, the flag #
is
prepended to the
conversion
specification.
The
fourth virtual protected
member function:
virtual
iter_type do_put(iter_type
next, ios_base& x,
E
fill, long double val)
const;
behaves
the same the third,
except that the qualifier
l
in
the conversion
specification
is replaced with L.
The
fifth virtual protected
member function:
virtual
iter_type do_put(iter_type
next, ios_base& x,
E
fill, const void *val)
const;
behaves
the same the first,
except that the conversion
specification is p, plus
any
qualifier
needed to specify
padding.
The
sixth virtual protected
member function:
virtual
iter_type do_put(iter_type
next, ios_base& x,
E
fill, bool val) const;
behaves
the same as the first,
except that it generates a
boolean
output field from
val.
A
boolean output field takes
one of two forms. If x.flags()
&
ios_base::boolalpha
is
false, the generated
sequence is either 0
(for
false) or 1
(for
true).
Otherwise, the generated
sequence is either fac.falsename()
(for
false), or
fac.truename()
(for
true).
num_put::put
iter_type
put(iter_type
next, ios_base&
x,
E
fill, long val) const;
iter_type
put(iter_type
next, ios_base&
x,
E
fill, unsigned long val)
const;
iter_type
put(iter_type
iter_type next,
ios_base&
x,
E
fill, double val) const;
iter_type
put(iter_type
next, ios_base&
x,
E
fill, long double val)
const;
iter_type
put(iter_type
next, ios_base&
x,
E
fill, const void *val)
const;
iter_type
put(iter_type
next, ios_base&
x,
E
fill, bool val) const;
All
member functions return do_put(next,
x, fill, val).
155
Chapter
12. Standard C++ Library
Header Files
num_put::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter OutIt.
num_put::num_put
explicit
num_put(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
numpunct
truename
(page 157)
template<class
E, class numpunct
:
public locale::facet {
public:
typedef
E char_type;
typedef
basic_string<E> string_type;
explicit
numpunct(size_t
refs = 0);
E
decimal_point()
const;
E
thousands_sep()
const;
string
grouping()
const;
string_type
truename()
const;
string_type
falsename()
const;
static
locale::id id;
protected:
~numpunct();
virtual
E do_decimal_point()
const;
virtual
E do_thousands_sep()
const;
virtual
string do_grouping()
const;
virtual
string_type do_truename()
const;
virtual
string_type do_falsename()
const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
desceibe
the sequences of type E
used to
represent the input fields
matched by
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
numpunct::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
numpunct::decimal_point
E
decimal_point()
const;
The
member function returns do_decimal_point().
numpunct::do_decimal_point
E
do_decimal_point()
const;
The
protected virtual member
function returns a locale-specific
element to use as a
decimal-point.
156
Standard
C++ Library
numpunct::do_falsename
string_type
do_falsename()
const;
The
protected virtual member
function returns a locale-specific
sequence to use as
a
text representation of the
value false.
numpunct::do_grouping
string
do_grouping()
const;
The
protected virtual member
function returns a locale-specific
rule for
determining
how digits are grouped to
the left of any decimal
point. The encoding
is
the same as for lconv::grouping.
numpunct::do_thousands_sep
E
do_thousands_sep()
const;
The
protected virtual member
function returns a locale-specific
element to use as a
group
separator to the left of any
decimal point.
numpunct::do_truename
string_type
do_truename()
const;
The
protected virtual member
function returns a locale-specific
sequence to use as
a
text representation of the
value true.
numpunct::falsename
string_type
falsename()
const;
The
member function returns do_falsename().
numpunct::grouping
string
grouping()
const;
The
member function returns do_grouping().
numpunct::numpunct
explicit
numpunct(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
numpunct::string_type
typedef
basic_string<E> string_type;
The
type describes a specialization of
template class basic_string (page 197)
whose
objects
can store copies of the
punctuation sequences.
numpunct::thousands_sep
E
thousands_sep()
const;
The
mmmber function returns do_thousands_sep().
numpunct::truename
string_type
falsename()
const;
The
member function returns do_truename().
157
Chapter
12. Standard C++ Library
Header Files
numpunct_byname
template<class
E>
class
numpunct_byname
:
public numpunct<E> {
public:
explicit
numpunct_byname(const
char *s,
size_t
refs = 0);
protected:
~numpunct_byname();
};
The
template class describes an object
that can serve as a locale
facet of
type
numpunct<E>. Its
behavior is determined by the
named (page 136)
locale s.
The
constructor
initializes its base object
with numpunct<E>(refs).
time_base
class
time_base
{
public:
enum
dateorder
{no_order,
dmy,
mdy,
ymd,
ydm};
};
The
class serves as a base class for facets
of template class time_get (page 158).
It
defines
just the enumerated type
dateorder
and
several constants of this
type. Each
of
the constants characterizes a
different way to order the
components of a date.
The
constants are:
v
no_order
specifies
no particular order.
v
dmy
specifies
the order day, month,
then year, as in 2
December 1979.
v
mdy
specifies
the order month, day,
then year, as in December
2, 1979.
v
ymd
specifies
the order year, month,
then day, as in 1979/12/2.
v
ydm
specifies
the order year, day,
then month, as in 1979:
2 Dec.
time_get
template<class
E, class InIt = istreambuf_iterator<E>
>
class
time_get
:
public locale::facet {
public:
typedef
E char_type;
typedef
InIt iter_type;
explicit
time_get(size_t
refs = 0);
dateorder
date_order()
const;
iter_type
get_time(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
iter_type
get_date(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
iter_type
get_weekday(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
iter_type
get_month(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
iter_type
get_year(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
static
locale::id id;
protected:
~time_get();
virtual
dateorder do_date_order()
const;
virtual
iter_type
do_get_time(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
virtual
iter_type
do_get_date(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
virtual
iter_type
do_get_weekday(iter_type
first, iter_type last,
158
Standard
C++ Library
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
virtual
iter_type
do_get_month(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
virtual
iter_type
do_get_year(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions of sequences of type
E
to
time values.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
time_get::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
time_get::date_order
dateorder
date_order()
const;
The
member function returns date_order().
time_get::do_date_order
virtual
dateorder do_date_order()
const;
The
virtual protected member
function returns a value of
type
time_base::dateorder, which
describes the order in which
date components are
time_base::mdy,
corresponding to dates of the form
December
2, 1979.
time_get::do_get_date
virtual
iter_type
do_get_date(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
virtual protected member
function endeavors to match
sequential elements
beginning
at first
in
the sequence [first,
last) until it
has recognized a
complete,
nonempty date
input field. If
successful, it converts this
field to its
equivalent
value as the components tm::tm_mon, tm::tm_day, and tm::tm_year,
and
stores
the results in pt->tm_mon, pt->tm_day
and
pt->tm_year,
respectively. It
returns
an iterator designating the
first element beyond the
date input field.
Otherwise,
the function sets ios_base::failbit
in
st. It
returns an iterator
designating
the first element beyond
any prefix of a valid date
input field. In
either
case,
if the return value equals
last, the
function sets ios_base::eofbit
in
st.
In
this implementation (page 3),
the date input field
has the form MMM
DD, YYYY,
where:
v
MMM
is
matched by calling get_month
(page 161),
giving the month.
v
DD
is a
sequence of decimal digits
whose corresponding numeric
value must be
in
the range [1, 31], giving
the day of the
month.
v
YYYY
is
matched by calling get_year
(page 161),
giving the year.
v
The
literal spaces and commas
must match corresponding
elements in the input
sequence.
159
Chapter
12. Standard C++ Library
Header Files
time_get::do_get_month
virtual
iter_type
do_get_month(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
virtual protected member
function endeavors to match
sequential elements
beginning
at first
in
the sequence [first,
last) until it
has recognized a
complete,
nonempty month
input field. If
successful, it converts this
field to its
equivalent
value as the component tm::tm_mon, and
stores the result in pt->tm_mon.
It
returns an iterator designating
the first element beyond
the month input
field.
Otherwise,
the function sets ios_base::failbit
in
st. It
returns an iterator
designating
the first element beyond
any prefix of a valid month
input field. In
either
case, if the return value
equals last, the
function sets ios_base::eofbit
in
st.
The
month input field is a
sequence that matches the
longest of a set of
locale-specific
sequences, such as: Jan, January, Feb, February, etc.
The converted
value
is the number of months
since January.
time_get::do_get_time
virtual
iter_type
do_get_time(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
virtual protected member
function endeavors to match
sequential elements
beginning
at first
in
the sequence [first,
last) until it
has recognized a
complete,
nonempty time
input field. If
successful, it converts this
field to its
equivalent
value as the components tm::tm_hour, tm::tm_min, and tm::tm_sec,
and
stores
the results in pt->tm_hour, pt->tm_min
and
pt->tm_sec,
respectively. It
returns
an iterator designating the
first element beyond the
time input field.
Otherwise,
the function sets ios_base::failbit
in
st. It
returns an iterator
designating
the first element beyond
any prefix of a valid time
input field. In
either
case, if the return value
equals last, the
function sets ios_base::eofbit
in
st.
In
this implementation (page 3),
the time input field
has the form HH:MM:SS,
where:
v
HH
is a
sequence of decimal digits
whose corresponding numeric
value must be
in
the range [0, 24), giving
the hour of the day.
v
MM
is a
sequence of decimal digits
whose corresponding numeric
value must be
in
the range [0, 60), giving
the minutes past the
hour.
v
SS
is a
sequence of decimal digits
whose corresponding numeric
value must be
in
the range [0, 60), giving
the seconds past the
minute.
v
The
literal colons must match
corresponding elements in the
input sequence.
time_get::do_get_weekday
virtual
iter_type
do_get_weekday(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
virtual protected member
function endeavors to match
sequential elements
beginning
at first
in
the sequence [first,
last) until it
has recognized a
complete,
nonempty weekday
input field. If
successful, it converts this
field to its
equivalent
value as the component tm::tm_wday, and
stores the result in
pt->tm_wday. It
returns an iterator designating
the first element beyond
the
weekday
input field. Otherwise, the
function sets ios_base::failbit
in
st.
It
160
Standard
C++ Library
returns
an iterator designating the
first element beyond any
prefix of a valid
weekday
input field. In either case,
if the return value equals
last, the
function
sets
ios_base::eofbit
in
st.
The
weekday input field is a
sequence that matches the
longest of a set of
locale-specific
sequences, such as: Sun, Sunday, Mon, Monday, etc.
The converted
value
is the number of days since
Sunday.
time_get::do_get_year
virtual
iter_type
do_get_year(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
virtual protected member
function endeavors to match
sequential elements
beginning
at first
in
the sequence [first,
last) until it
has recognized a
complete,
nonempty year
input field. If
successful, it converts this
field to its
equivalent
value as the component tm::tm_year, and
stores the result in
pt->tm_year. It
returns an iterator designating
the first element beyond
the year
input
field. Otherwise, the
function sets ios_base::failbit
in
st. It
returns an
iterator
designating the first
element beyond any prefix of
a valid year input
field.
In
either case, if the return
value equals last, the
function sets ios_base::eofbit
in
st.
The
year input field is a
sequence of decimal digits
whose corresponding
numeric
value
must be in the range [1900,
2036). The stored value is
this value minus
1900.
In
this implementation (page 3),
a numeric value in the
range [0, 136) is
also
permissible.
It is stored unchanged.
time_get::get_date
iter_type
get_date(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
member function returns do_get_date(first,
last, x, st, pt).
time_get::get_month
iter_type
get_month(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
member function returns do_get_month(first,
last, x, st, pt).
time_get::get_time
iter_type
get_time(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
member function returns do_get_time(first,
last, x, st, pt).
time_get::get_weekday
iter_type
get_weekday(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
member function returns do_get_weekday(first,
last, x, st, pt).
time_get::get_year
iter_type
get_year(iter_type
first, iter_type last,
ios_base&
x, ios_base::iostate& st, tm *pt)
const;
The
member function returns do_get_year(first,
last, x, st, pt).
161
Chapter
12. Standard C++ Library
Header Files
time_get::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter InIt.
time_get::time_get
explicit
time_get(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
time_get_byname
template<class
E, class InIt>
class
time_get_byname
:
public time_get<E, InIt> {
public:
explicit
time_get_byname(const
char *s,
size_t
refs = 0);
protected:
~time_get_byname();
};
The
template class describes an object
that can serve as a locale
facet (page 135)
of
type
time_get<E,
InIt>. Its
behavior is determined by the
named (page 136)
locale
s. The
constructor initializes its
base object with time_get<E,
InIt>(refs).
time_put
template<class
E, class OutIt = ostreambuf_iterator<E>
>
class
time_put
:
public locale::facet {
public:
typedef
E char_type;
typedef
OutIt iter_type;
explicit
time_put(size_t
refs = 0);
iter_type
put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, char fmt, char mod =
0) const;
iter_type
put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, const E *first, const
E *last) const;
static
locale::id id;
protected:
~time_put();
virtual
iter_type do_put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, char fmt, char mod =
0) const;
};
The
template class describes an object
that can serve as a locale
facet (page 135),
to
control
conversions of time values to
sequences of type E.
As
with any locale facet, the
static object id
has an
initial stored value of
zero. The
first
attempt to access its stored
value stores a unique
positive value in id.
time_put::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
time_put::do_put
virtual
iter_type do_put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, char fmt, char mod =
0) const;
162
Standard
C++ Library
The
virtual protected member
function generates sequential
elements beginning at
next
from
time values stored in the
object *pt, of
type tm. The function
returns an
iterator
designating the next place
to insert an element beyond
the generated
output.
The
output is generated by the
same rules used by strftime,
with a last argument
of
pt, for
generating a series of char
elements
into an array. (Each such
char
element
is
assumed to map to an equivalent element
of type E
by a
simple, one-to-one,
mapping.)
If mod
equals
zero, the effective format
is "%F", where
F
equals
fmt.
Otherwise,
the effective format is "%MF", where
M
equals
mod.
The
parameter fill
is
not used.
time_put::put
iter_type
put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, char fmt, char mod =
0) const;
iter_type
put(iter_type
next, ios_base& x,
char_type
fill, const tm *pt, const E *first, const
E *last) const;
The
first member function
returns do_put(next,
x, fill, pt, fmt, mod).
The
second
member function copies to *next++
any
element in the interval [first,
last)
other
than a percent (%). For a
percent followed by a character
C
in
the
interval
[first,
last),
the function instead
evaluates next
= do_put(next, x,
fill,
pt, C, 0) and
skips past C. If,
however, C
is a
qualifier character from
the
set
EOQ#,
followed by a character C2
in
the interval [first,
last),
the function
instead
evaluates next
= do_put(next, x, fill, pt, C2, C) and
skips past C2.
time_put::iter_type
typedef
InIt iter_type;
The
type is a synonym for the
template parameter OutIt.
time_put::time_put
explicit
time_put(size_t
refs = 0);
The
constructor initializes its
base object with locale::facet(refs).
time_put_byname
template<class
E, class OutIt>
class
time_put_byname
:
public time_put<E, OutIt>
{
public:
explicit
time_put_byname(const
char *s,
size_t
refs = 0);
protected:
~time_put_byname();
};
The
template class describes an object
that can serve as a locale
facet of
type
time_put<E,
OutIt>.
Its behavior is determined by
the named (page 136)
locale s.
The
constructor initializes its
base object with time_put<E,
OutIt>(refs).
tolower
template<class
E>
E
tolower(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). tolower(c).
163
Chapter
12. Standard C++ Library
Header Files
toupper
template<class
E>
E
toupper(E c,
const locale& loc) const;
The
template function returns use_facet<
ctype<E> >(loc). toupper(c).
use_facet
template<class
Facet>
const
Facet& use_facet(const
locale& loc);
The
template function returns a
reference to the locale
facet of
class Facet
listed
within
the locale object (page 135)
loc. If no
such object is listed, the
function
throws
an object of class bad_cast (page 224).
<new>
namespace
std {
typedef
void (*new_handler)();
class
bad_alloc;
class
nothrow_t;
extern
const nothrow_t nothrow;
//
FUNCTIONS
new_handler
set_new_handler(new_handler
ph) throw();
};
//
OPERATORS -- NOT IN NAMESPACE
std
void
operator
delete(void
*p) throw();
void
operator
delete(void
*, void *) throw();
void
operator
delete(void
*p,
const
std::nothrow_t&) throw();
void
operator
delete[](void
*p) throw();
void
operator
delete[](void
*, void *) throw();
void
operator
delete[](void
*p,
const
std::nothrow_t&) throw();
void
*operator
new(std::size_t
n)
throw(std::bad_alloc);
void
*operator
new(std::size_t
n,
const
std::nothrow_t&) throw();
void
*operator
new(std::size_t
n, void *p) throw();
void
*operator
new[](std::size_t
n)
throw(std::bad_alloc);
void
*operator
new[](std::size_t
n,
const
std::nothrow_t&) throw();
void
*operator
new[](std::size_t
n, void *p) throw();
Include
the standard header
<new>
to
define several types and
functions that
control
allocation and freeing of storage
under program
control.
Some
of the functions declared in
this header are replaceable.
The implementation
supplies
a default version, whose
behavior is described in this
document. A
program
can, however, define a
function with the same
signature to replace
the
default
version at link time. The
replacement version must
satisfy the
requirements
described
in this document.
bad_alloc
class
bad_alloc
:
public exception {
};
164
Standard
C++ Library
The
class describes an exception thrown to
indicate that an allocation
request did
not
succeed. The value returned
by what()
is an
implementation-defined C string.
None
of the member functions throw
any exceptions.
new_handler
typedef
void (*new_handler)();
The
type points to a function
suitable for use as a new handler
(page 166).
nothrow
extern
const nothrow_t nothrow;
The
object is used as a function
argument to match the
parameter type
nothrow_t
(page
165).
nothrow_t
class
nothrow_t
{};
The
class is used as a function parameter to
operator
new to
indicate that the
function
should return a null pointer to
report an allocation failure,
rather than
throw
an exception.
operator
delete
void
operator
delete(void
*p) throw();
void
operator
delete(void
*, void *) throw();
void
operator
delete(void
*p,
const
std::nothrow_t&) throw();
The
first function is called by a
delete
expression to
render the value of p
invalid.
The
program can define a
function with this function
signature that replaces
(page
164)
the default version
defined by the Standard C++
library. The required
behavior
is to accept a value of p
that is
null or that was returned by an
earlier call
to
operator
new(size_t).
The
default behavior for a null value of
p
is to do
nothing. Any other value of p
must
be a value returned earlier by a
call as described above. The
default behavior
for
such a non-null value of p is to
reclaim storage allocated by
the earlier call. It
is
unspecified
under what conditions part or
all of such reclaimed
storage is allocated
by
a subsequent call to operator
new(size_t),
or to any of calloc(size_t),
malloc(size_t), or realloc(void*,
size_t).
The
second function is called by a
placement
delete expression corresponding
to
a
new
expression of
the form new(std::size_t). It
does nothing.
The
third function is called by a
placement delete
expression
corresponding to a
new
expression
of the form new(std::size_t,
const std::nothrow_t&).
It calls
delete(p).
operator
delete[]
void
operator
delete[](void
*p) throw();
void
operator
delete[](void
*, void *) throw();
void
operator
delete[](void
*p,
const
std::nothrow_t&) throw();
165
Chapter
12. Standard C++ Library
Header Files
The
first function is called by a
delete[]
expression
to
render the value of p
invalid.
The program can define a
function with this function
signature that
replaces
(page 164)
the default version
defined by the Standard C++
library.
The
required behavior is to accept a
value of p
that is
null or that was returned
by
an
earlier call to operator
new[](size_t).
The
default behavior for a null value of
p
is to do
nothing. Any other value of ptr
must
be a value returned earlier by a
call as described above. The
default behavior
for
such a non-null value of p is to
reclaim storage allocated by
the earlier call. It
is
unspecified
under what conditions part or
all of such reclaimed
storage is allocated
by
a subsequent call to operator
new(size_t),
or to any of calloc(size_t),
malloc(size_t), or realloc(void*,
size_t).
The
second function is called by a
placement
delete[] expression corresponding
to
a new[]
expression of
the form new[](std::size_t). It
does nothing.
The
third function is called by a
placement delete
expression
corresponding to a
new[]
expression
of the form new[](std::size_t,
const std::nothrow_t&).
It calls
delete[](p).
operator
new
void
*operator
new(std::size_t
n) throw(bad_alloc);
void
*operator
new(std::size_t
n,
const
std::nothrow_t&) throw();
void
*operator
new(std::size_t
n, void *p) throw();
The
first function is called by a
new
expression to
allocate n
bytes of
storage
suitably
aligned to represent any
object of that size. The
program can define a
function
with this function signature
that replaces (page 164)
the default
version
defined
by the Standard C++
library.
The
required behavior is to return a
non-null pointer only if
storage can be
allocated
as requested. Each such
allocation yields a pointer to
storage disjoint
from
any other allocated storage.
The order and contiguity of
storage allocated by
successive
calls is unspecified. The
initial stored value is
unspecified. The
returned
pointer
points to the start (lowest
byte address) of the
allocated storage. If n
is
zero,
the value returned does
not compare equal to any
other value returned
by
the
function.
The
default behavior is to execute a
loop. Within the loop,
the function first
attempts
to allocate the requested
storage. Whether the attempt
involves a call to
malloc(size_t)
is
unspecified. If the attempt is
successful, the function
returns a
pointer
to the allocated storage.
Otherwise, the function
calls the designated new
handler. If the
called function returns, the
loop repeats. The loop
terminates when
an
attempt to allocate the
requested storage is successful or when a
called function
does
not return.
The
required behavior of a new
handler is to
perform one of the
following
operations:
v
make
more storage available for
allocation and then
return
v
call
either abort()
or
exit(int)
v
throw an
object of type bad_alloc
166
Standard
C++ Library
The
default behavior of a new
handler is
to throw an object of type bad_alloc.
A
null
pointer designates the
default new handler.
The
order and contiguity of storage
allocated by successive calls to
operator
new(size_t)
is
unspecified, as are the
initial values stored
there.
The
second function:
void
*operator
new(std::size_t
n,
const
std::nothrow_t&) throw();
is
called by a placement
new expression
to allocate n
bytes of
storage suitably
aligned
to represent any object of
that size. The program
can define a function
with
this function signature that
replaces (page 164)
the default version
defined by
the
Standard C++ library.
The
default behavior is to return
operator
new(n) if
that function
succeeds.
Otherwise,
it returns a null pointer.
The
third function:
void
*operator
new(std::size_t
n, void *p) throw();
is
called by a placement
new
expression,
of the form new
(args) T. Here,
args
consists
of a single object pointer.
The function returns p.
operator
new[]
void
*operator
new[](std::size_t
n)
throw(std::bad_alloc);
void
*operator
new[](std::size_t
n,
const
std::nothrow_t&) throw();
void
*operator
new[](std::size_t
n, void *p) throw();
The
first function is called by a
new[]
expression to
allocate n
bytes of
storage
suitably
aligned to represent any
array object of that size or
smaller. The program
can
define a function with this
function signature that
replaces (page 164)
the
default
version defined by the
Standard C++ library.
The
required behavior is the
same as for operator
new(size_t).
The default
behavior
is to return operator
new(n).
The
second function is called by a
placement
new[] expression to
allocate n
bytes
of
storage suitably aligned to
represent any array object
of that size. The
program
can
define a function with this
function signature that
replaces (page 164)
the
default
version defined by the
Standard C++ library.
The
default behavior is to return
operator
new(n) if
that function
succeeds.
Otherwise,
it returns a null pointer.
The
third function is called by a
placement
new[]
expression,
of the form new
(args)
T[N].
Here, args
consists
of a single object pointer.
The function returns p.
set_new_handler
new_handler
set_new_handler(new_handler
ph) throw();
167
Chapter
12. Standard C++ Library
Header Files
The
function stores ph
in a
static new handler (page 166)
pointer that it
maintains,
then
returns the value previously
stored in the pointer. The
new handler is used by
operator
new(size_t).
<ostream>
namespace
std {
template<class
E, class T = char_traits<E>
>
class
basic_ostream;
typedef
basic_ostream<char, char_traits<char>
>
ostream;
typedef
basic_ostream<wchar_t, char_traits<wchar_t>
>
wostream;
//
INSERTERS
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
E *s);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
E
c);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
char *s);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
char
c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
char *s);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
char
c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
signed char *s);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
signed
char c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
unsigned char *s);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
unsigned
char c);
//
MANIPULATORS
template
class<E, T>
basic_ostream<E,
T>&
endl(basic_ostream<E,
T>& os);
template
class<E, T>
basic_ostream<E,
T>&
ends(basic_ostream<E,
T>& os);
168
Standard
C++ Library
template
class<E, T>
basic_ostream<E,
T>&
flush(basic_ostream<E,
T>& os);
};
Include
the iostreams (page 7)
standard header <ostream>
to
define template class
basic_ostream
(page 169),
which mediates insertions for
the iostreams. The
header
also
defines several related
manipulators (page 87).
(This header is
typically
included
for you by another of the iostreams
headers. You seldom have
occasion to
include
it directly.)
basic_ostream
template
<class E, class T =
char_traits<E> >
class
basic_ostream
:
virtual public basic_ios<E, T>
{
public:
typedef
typename basic_ios<E, T>::char_type
char_type;
typedef
typename basic_ios<E, T>::traits_type
traits_type;
typedef
typename basic_ios<E, T>::int_type
int_type;
typedef
typename basic_ios<E, T>::pos_type
pos_type;
typedef
typename basic_ios<E, T>::off_type
off_type;
explicit
basic_ostream(basic_streambuf<E,
T> *sb);
class
sentry;
virtual
~ostream();
bool
opfx();
void
osfx();
basic_ostream&
operator<<(
basic_ostream&
(*pf)(basic_ostream&));
basic_ostream&
operator<<(
ios_base;&
(*pf)(ios_base&));
basic_ostream&
operator<<(
basic_ios<E,
T>& (*pf)(basic_ios<E, T>&));
basic_ostream&
operator<<(
basic_streambuf<E,
T> *sb);
basic_ostream&
operator<<(bool
n);
basic_ostream&
operator<<(short
n);
basic_ostream&
operator<<(unsigned
short n);
basic_ostream&
operator<<(int
n);
basic_ostream&
operator<<(unsigned
int n);
basic_ostream&
operator<<(long
n);
basic_ostream&
operator<<(unsigned
long n);
basic_ostream&
operator<<(float
n);
basic_ostream&
operator<<(double
n);
basic_ostream&
operator<<(long
double n);
basic_ostream&
operator<<(const
void *n);
basic_ostream&
put(char_type
c);
basic_ostream&
write(char_type
*s, streamsize n);
basic_ostream&
flush();
pos_type
tellp();
basic_ostream&
seekp(pos_type
pos);
basic_ostream&
seekp(off_type
off,
ios_base::seek_dir
way);
};
The
template class describes an object
that controls insertion of
elements and
encoded
objects into a stream buffer
(page 187)
with elements of type E,
also
the
class T, also
known as traits_type (page 91).
169
Chapter
12. Standard C++ Library
Header Files
Most of
the member functions that
overload operator<< (page 170)
are formatted
output
functions. They
follow the pattern:
iostate
state = goodbit;
const
sentry ok(*this);
if
(ok)
{try
{<convert
and insert elements
accumulate
flags in state>}
catch
(...)
{try
{setstate(badbit);
}
catch
(...)
{}
if
((exceptions() & badbit) != 0)
throw;
}}
width(0);
//
except for operator<<(E)
setstate(state);
return
(*this);
Two
other member functions are
unformatted
output functions. They
follow the
pattern:
iostate
state = goodbit;
const
sentry ok(*this);
if
(!ok)
state
|= badbit;
else
{try
{<obtain
and insert elements
accumulate
flags in state>}
catch
(...)
{try
{setstate(badbit);
}
catch
(...)
{}
if
((exceptions() & badbit) != 0)
throw;
}}
setstate(state);
return
(*this);
Both
groups of functions call setstate(badbit)
if
they encounter a failure
while
inserting
elements.
An
object of class basic_istream<E,
T> stores
only a virtual public base
object of
class
basic_ios<E,
T> (page 88)
basic_ostream::basic_ostream
explicit
basic_ostream(basic_streambuf<E,
T> *sb);
The
constructor initializes the
base class by calling init(sb).
basic_ostream::flush
basic_ostream&
flush();
If
rdbuf()
is
not a null pointer, the
function calls rdbuf()->pubsync(). If
that
returns
-1, the function calls
setstate(badbit). It
returns *this.
basic_ostream::operator<<
basic_ostream&
operator<<(
basic_ostream&
(*pf)(basic_ostream&));
basic_ostream&
operator<<(
ios_base&
(*pf)(ios_base&));
basic_ostream&
operator<<(
170
Standard
C++ Library
basic_ios<E,
T>& (*pf)(basic_ios<E, T>&));
basic_ostream&
operator<<(
basic_streambuf<E,
T> *sb);
basic_ostream&
operator<<(bool
n);
basic_ostream&
operator<<(short
n);
basic_ostream&
operator<<(unsigned
short n);
basic_ostream&
operator<<(int
n);
basic_ostream&
operator<<(unsigned
int n);
basic_ostream&
operator<<(long
n);
basic_ostream&
operator<<(unsigned
long n);
basic_ostream&
operator<<(float
n);
basic_ostream&
operator<<(double
n);
basic_ostream&
operator<<(long
double n);
basic_ostream&
operator<<(const
void *n);
The
first member function
ensures that an expression of
the form ostr
<< endl
calls
endl(ostr), then
returns *this. The
second and third functions
ensure that
remaining
functions are all formatted
output functions (page 170).
The
function:
basic_ostream&
operator<<(
basic_streambuf<E,
T> *sb);
extracts
elements from sb, if sb is not a
null pointer, and inserts them.
Extraction
stops
on end-of-file, or if an extraction
throws an exception (which is
rethrown). It
also
stops, without extracting
the element in question, if an
insertion fails. If
the
function
inserts no elements, or if an extraction
throws an exception, the
function
calls
setstate(failbit). In any
case, the function returns
*this.
The
function:
basic_ostream&
operator<<(bool
n);
converts
n
to a
boolean field and inserts it by
calling use_facet<num_put<E,
OutIt>(getloc()).
put(OutIt( rdbuf()), *this, getloc(), n).
Here, OutIt
is
defined
as ostreambuf_iterator<E,
T>.
The function returns *this.
The
functions:
basic_ostream&
operator<<(short
n);
basic_ostream&
operator<<(unsigned
short n);
basic_ostream&
operator<<(int
n);
basic_ostream&
operator<<(unsigned
int n);
basic_ostream&
operator<<(long
n);
basic_ostream&
operator<<(unsigned
long n);
basic_ostream&
operator<<(const
void *n);
each
convert n
to a
numeric field and insert it by
calling use_facet<num_put<E,
OutIt>(getloc()).
put(OutIt( rdbuf()), *this, getloc(), n).
Here, OutIt
is
defined
as ostreambuf_iterator<E,
T>.
The
function returns *this.
The
functions:
basic_ostream&
operator<<(float
n);
basic_ostream&
operator<<(double
n);
basic_ostream&
operator<<(long
double n);
171
Chapter
12. Standard C++ Library
Header Files
each
convert n
to a
numeric field and insert it by
calling use_facet<num_put<E,
OutIt>(getloc()).
put(OutIt( rdbuf()), *this, getloc(), n).
Here, OutIt
is
defined
as ostreambuf_iterator<E,
T>.
The function returns *this.
basic_ostream::opfx
bool
opfx();
If
good()
is
true, and tie()
is
not a null pointer, the
member function calls
tie->flush(). It
returns good().
You
should not call opfx
directly.
It is called as needed by an object of
class sentry
(page
172).
basic_ostream::osfx
void
osfx();
If
flags() &
unitbuf is
nonzero, the member function
calls flush(). You
should
not
call osfx
directly.
It is called as needed by an object of
class sentry.
basic_ostream::put
basic_ostream&
put(char_type
c);
The
unformatted output function
(page 170)
inserts the element c. It
returns *this.
basic_ostream::seekp
basic_ostream&
seekp(pos_type
pos);
basic_ostream&
seekp(off_type
off,
ios_base::seek_dir
way);
If
fail()
is
false, the first member
function calls rdbuf()->
pubseekpos(pos).
If
fail()
is
false, the second function
calls rdbuf()->
pubseekoff(off, way).
Both
functions
return *this.
basic_ostream::sentry
class
sentry
{
public:
explicit
sentry(basic_ostream<E,
T>& os);
operator
bool()
const;
private:
sentry(const
sentry&); // not defined
sentry&
operator=(const
sentry&); // not defined
};
The
nested class describes an object
whose declaration structures
the formatted
constructor
effectively calls os.opfx()
and
stores the return value.
operator
bool()
delivers
this return value. The
destructor effectively calls os.osfx(), but
only if
uncaught_exception()
returns
false.
basic_ostream::tellp
pos_type
tellp();
If
fail()
is
false, the member function
returns rdbuf()->
pubseekoff(0, cur, in).
Otherwise,
it returns pos_type(-1).
basic_ostream::write
basic_ostream&
write(const
char_type *s, streamsize n);
172
Standard
C++ Library
The
unformatted output function
(page 170)
inserts the sequence of n elements
beginning
at s.
endl
template
class<E, T>
basic_ostream<E,
T>& endl(basic_ostream<E,
T>& os);
The
manipulator calls os.put(os.
widen('\n')), then
calls os.flush(). It
returns
os.
ends
template
class<E, T>
basic_ostream<E,
T>& ends(basic_ostream<E,
T>& os);
The
manipulator calls os.put(E('\0')). It
returns os.
flush
template
class<E, T>
basic_ostream<E,
T>& flush(basic_ostream<E,
T>& os);
The
manipulator calls os.flush(). It
returns os.
operator<<
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
E *s);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
E
c);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
char *s);
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
char
c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
char *s);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
char
c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
signed char *s);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
signed
char c);
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
unsigned char *s);
173
Chapter
12. Standard C++ Library
Header Files
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
unsigned
char c);
The
template function:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
E *s);
is
a formatted output functions
(page 170)
that determines the
length n
=
traits_type::length(s)
of
the sequence beginning at s, and
inserts the sequence.
If
n
< os.width(),
then the function also
inserts a repetition of os.width()
- n fill
characters
(page 89).
The repetition precedes
the sequence if (os.flags()
&
adjustfield
!= left.
Otherwise, the repetition
follows the sequence. The
function
returns
os.
The
template function:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
E
c);
inserts
the element c. If 1 <
os.width(),
then the function also
inserts a repetition
of
os.width()
- 1 fill
characters (page 89).
The repetition precedes
the sequence if
(os.flags()
& adjustfield != left.
Otherwise, the repetition
follows the
sequence.
It returns os.
The
template function:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
char *s);
behaves
the same as:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
E *s);
except
that each element c
of
the sequence beginning at s is
converted to an object
of
type E
by
calling os.put(os.
widen(c)).
The
template function:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
char
c);
behaves
the same as:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
E
c);
except
that c
is
converted to an object of type
E
by
calling os.put(os.
widen(c)).
The
template function:
174
Standard
C++ Library
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
char *s);
behaves
the same as:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
const
E *s);
(It
does not have to widen the
elements before inserting
them.)
The
template function:
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
char
c);
behaves
the same as:
template<class
E, class T>
basic_ostream<E,
T>&
operator<<(basic_ostream<E,
T>& os,
E
c);
(It
does not have to widen c
before
inserting it.)
The
template function:
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
signed char *s);
returns
os
<< (const char *)s.
The
template function:
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
signed
char c);
returns
os
<< (char)c.
The
template function:
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
const
unsigned char *s);
returns
os
<< (const char *)s.
The
template function:
template<class
T>
basic_ostream<char,
T>&
operator<<(basic_ostream<char,
T>& os,
unsigned
char c);
returns
os
<< (char)c.
175
Chapter
12. Standard C++ Library
Header Files
ostream
typedef
basic_ostream<char, char_traits<char> >
ostream;
The
type is a synonym for template class
basic_ostream (page 169),
specialized for
elements
of type char
with
default character traits
(page 211).
wostream
typedef
basic_ostream<wchar_t, char_traits<wchar_t>
>
wostream;
The
type is a synonym for template class
basic_ostream (page 169),
specialized for
elements
of type wchar_t
with
default character traits
(page 211).
<sstream>
namespace
std {
template<class
E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_stringbuf;
typedef
basic_stringbuf<char> stringbuf;
typedef
basic_stringbuf<wchar_t> wstringbuf;
template<class
E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_istringstream;
typedef
basic_istringstream<char> istringstream;
typedef
basic_istringstream<wchar_t> wistringstream;
template<class
E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_ostringstream;
typedef
basic_ostringstream<char> ostringstream;
typedef
basic_ostringstream<wchar_t> wostringstream;
template<class
E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_stringstream;
typedef
basic_stringstream<char> stringstream;
typedef
basic_stringstream<wchar_t> wstringstream;
};
Include
the iostreams (page 7)
standard header <sstream>
to
define several
template
classes that support iostreams
operations on sequences stored in
an
allocated
array object. Such sequences
are easily converted to and from
objects of
template
class basic_string (page 197).
basic_stringbuf
template
<class E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_stringbuf
:
public basic_streambuf<E, T>
{
public:
typedef
typename basic_streambuf<E,
T>::char_type
char_type;
typedef
typename basic_streambuf<E,
T>::traits_type
traits_type;
typedef
typename basic_streambuf<E,
T>::int_type
int_type;
typedef
typename basic_streambuf<E,
T>::pos_type
176
Standard
C++ Library
pos_type;
typedef
typename basic_streambuf<E,
T>::off_type
off_type;
basic_stringbuf(ios_base::openmode
mode =
ios_base::in
| ios_base::out);
basic_stringbuf(basic_string<E,
T, A>& x,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
basic_string<E,
T, A> str()
const;
void
str(basic_string<E,
T, A>& x);
protected:
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
virtual
pos_type seekpos(pos_type
sp,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
virtual
int_type underflow();
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
virtual
int_type overflow(int_type
c =
traits_type::eof());
};
The
template class describes a stream
buffer (page 187)
that
controls the
transmission
of elements of type E, whose
character traits (page 211)
are
determined
by the class T, to and from a
sequence of elements stored in an
array
object.
The object is allocated,
extended, and freed as necessary to
accommodate
changes
in the sequence.
An
object of class basic_stringbuf<E,
T, A> stores a
copy of the
ios_base::openmode
argument
from its constructor as its
stringbuf
mode mode:
v
If
mode
& ios_base::in is
nonzero, the input buffer
(page 187)
is accessible.
v
If
mode
& ios_base::out is
nonzero, the output buffer
(page 187)
is accessible.
basic_stringbuf::basic_stringbuf
basic_stringbuf(ios_base::openmode
mode =
ios_base::in
| ios_base::out);
basic_stringbuf(basic_string<E,
T, A>& x,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
The
first constructor stores a null
pointer in all the pointers
controlling the input
stringbuf
mode (page 177).
The
second constructor allocates a
copy of the sequence
controlled by the
string
object
x. If mode
& ios_base::in is
nonzero, it sets the input
buffer to begin
reading
at the start of the
sequence. If mode
& ios_base::out is
nonzero, it sets the
output
buffer to begin writing at
the start of the sequence.
It also stores mode
as
the
stringbuf
mode (page 177).
basic_stringbuf::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
177
Chapter
12. Standard C++ Library
Header Files
basic_stringbuf::int_type
typedef
typename traits_type::int_type int_type;
The
type is a synonym for traits_type::int_type.
basic_stringbuf::off_type
typedef
typename traits_type::off_type off_type;
The
type is a synonym for traits_type::off_type.
basic_stringbuf::overflow
virtual
int_type overflow(int_type
c =
traits_type::eof());
If
c
does
not compare equal to traits_type::eof(), the
protected virtual
member
function
endeavors to insert the
element traits_type::to_char_type(c)
into
the
output
buffer (page 187).
It can do so in various
ways:
v
If a
write position (page 188)
is available, it can store
the element into the
write
position
and increment the next
pointer for the output
buffer.
v
It
can make a write position
available by allocating new or additional
storage for
the
output buffer. (Extending
the output buffer this way
also extends any
associated
input buffer (page 187).)
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(c).
basic_stringbuf::pbackfail
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
The
protected virtual member
function endeavors to put back an
element into the
input
buffer (page 187),
then make it the current
element (pointed to by the
next
pointer).
If c
compares
equal to traits_type::eof(), the
element to push back
is
effectively
the one already in the
stream before the current
element. Otherwise,
that
element is replaced by x
= traits_type::to_char_type(c).
The function can
put
back an element in various
ways:
v
If a
putback position (page 188)
is available, and the element
stored there
compares
equal to x, it can
simply decrement the next
pointer for the input
buffer.
v
If a
putback position is available, and if
the stringbuf mode (page 177)
permits
the
sequence to be altered (mode
& ios_base::out is
nonzero), it can store x
into
the
putback position and decrement
the next pointer for the
input buffer.
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(c).
basic_stringbuf::pos_type
typedef
typename traits_type::pos_type pos_type;
The
type is a synonym for traits_type::pos_type.
basic_stringbuf::seekoff
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
178
Standard
C++ Library
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class basic_stringbuf<E,
T, A>, a
stream
position
consists purely of a stream
offset. Offset zero
designates the first
element
of
the controlled
sequence.
The
new position is determined as
follows:
v
If
way
== ios_base::beg,
the new position is the
beginning of the stream
plus
off.
v
If
way
== ios_base::cur,
the new position is the
current stream position
plus
off.
v
If
way
== ios_base::end,
the new position is the end
of the stream plus off.
If
mode
& ios_base::in is
nonzero, the function alters
the next position to read
in
the
input buffer. If mode
& ios_base::out is
nonzero, the function alters
the next
position
to write in the output
buffer. For a stream to be
affected, its buffer
must
exist.
For a positioning operation to
succeed, the resulting
stream position must
lie
within
the controlled sequence. If
the function affects both
stream positions, way
must
be ios_base::beg
or
ios_base::end
and
both streams are positioned
at the
same
element. Otherwise (or if
neither position is affected)
the positioning
operation
fails.
If
the function succeeds in
altering the stream
position(s), it returns the
resultant
stream
position. Otherwise, it fails and
returns an invalid stream
position.
basic_stringbuf::seekpos
virtual
pos_type seekpos(pos_type
sp,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class basic_stringbuf<E,
T, A>, a
stream
position
consists purely of a stream
offset. Offset zero
designates the first
element
of
the controlled sequence. The
new position is determined by sp.
If
mode
& ios_base::in is
nonzero, the function alters
the next position to read
in
the
input buffer. If mode
& ios_base::out is
nonzero, the function alters
the next
position
to write in the output
buffer. For a stream to be
affected, its buffer
must
exist.
For a positioning operation to
succeed, the resulting
stream position must
lie
within
the controlled sequence.
Otherwise (or if neither
position is affected)
the
positioning
operation fails.
If
the function succeeds in
altering the stream
position(s), it returns the
resultant
stream
position. Otherwise, it fails and
returns an invalid stream
position.
basic_stringbuf::str
basic_string<E,
T, A> str()
const;
void
str(basic_string<E,
T, A>& x);
The
first member function
returns an object of class basic_string<E,
T, A>,
whose
controlled
sequence is a copy of the
sequence controlled by *this. The
sequence
copied
depends on the stored
stringbuf mode (page 177)
mode:
v
If
mode
& ios_base::out is
nonzero and an output buffer
exists, the sequence
is
the
entire output buffer (epptr()
- pbase() elements
beginning with pbase()).
179
Chapter
12. Standard C++ Library
Header Files
v Otherwise,
if mode
& ios_base::in is
nonzero and an input buffer
exists, the
sequence
is the entire input buffer
(egptr() -
eback() elements
beginning with
eback()).
v
Otherwise,
the copied sequence is
empty.
The
second member function
deallocates any sequence
currently controlled by
*this. It
then allocates a copy of the
sequence controlled by x. If mode
&
ios_base::in
is
nonzero, it sets the input
buffer to begin reading at
the beginning
of
the sequence. If mode
& ios_base::out is
nonzero, it sets the output
buffer to
begin
writing at the beginning of
the sequence.
basic_stringbuf::traits_type
typedef
T traits_type;
The
type is a synonym for the
template parameter T.
basic_stringbuf::underflow
virtual
int_type underflow();
The
protected virtual member
function endeavors to extract
the current element c
from
the input buffer, then
advance the current stream
position, and return
the
element
as traits_type::to_int_type(c). It can
do so in only one way: If a
read
position
(page 188)
is available, it takes c
as
the element stored in the
read position
and
advances the next pointer
for the input buffer.
If
the function cannot succeed,
it returns traits_type::eof().
Otherwise, it returns
the
current element in the input
stream, converted as described
above.
basic_istringstream
template
<class E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_istringstream
:
public basic_istream<E, T> {
public:
explicit
basic_istringstream(
ios_base::openmode
mode = ios_base::in);
explicit
basic_istringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode = ios_base::in);
basic_stringbuf<E,
T, A> *rdbuf()
const;
basic_string<E,
T, A>& str();
void
str(const
basic_string<E, T, A>& x);
};
The
template class describes an object
that controls extraction of
elements and
encoded
objects from a stream buffer of class
basic_stringbuf<E,
T, A>,
with
elements
of type E, whose
character traits (page 211)
are determined by the class
T,
and
whose elements are allocated
by an allocator of class A. The
object stores an
object
of class basic_stringbuf<E,
T, A>.
basic_istringstream::basic_istringstream
explicit
basic_istringstream(
ios_base::openmode
mode = ios_base::in);
explicit
basic_istringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode = ios_base::in);
180
Standard
C++ Library
The
first constructor initializes
the base class by calling basic_istream(sb),
where
sb
is
the stored object of class basic_stringbuf<E,
T, A>. It
also initializes sb
by
calling
basic_stringbuf<E,
T, A>(mode | ios_base::in).
The
second constructor initializes
the base class by calling basic_istream(sb).
It
also
initializes sb
by
calling basic_stringbuf<E,
T, A>(x, mode |
ios_base::in).
basic_istringstream::rdbuf
basic_stringbuf<E,
T, A> *rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to basic_stringbuf<E,
T, A>.
basic_istringstream::str
basic_string<E,
T, A> str()
const;
void
str(basic_string<E,
T, A>& x);
The
first member function
returns rdbuf()->
str().
The second member
function
calls
rdbuf()->
str(x).
basic_ostringstream
template
<class E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_ostringstream
:
public basic_ostream<E, T> {
public:
explicit
basic_ostringstream(
ios_base::openmode
mode = ios_base::out);
explicit
basic_ostringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode = ios_base::out);
basic_stringbuf<E,
T, A> *rdbuf()
const;
basic_string<E,
T, A>& str();
void
str(const
basic_string<E, T, A>& x);
};
The
template class describes an object
that controls insertion of
elements and
encoded
objects into a stream buffer
of class basic_stringbuf<E,
T, A>,
with
elements
of type E, whose
character traits (page 211)
are determined by the class
T,
and
whose elements are allocated
by an allocator of class A. The
object stores an
object
of class basic_stringbuf<E,
T, A>.
basic_ostringstream::basic_ostringstream
explicit
basic_ostringstream(
ios_base::openmode
mode = ios_base::out);
explicit
basic_ostringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode = ios_base::out);
The
first constructor initializes
the base class by calling basic_ostream(sb),
where
sb
is
the stored object of class basic_stringbuf<E,
T, A>. It
also initializes sb
by
calling
basic_stringbuf<E,
T, A>(mode | ios_base::out).
The
second constructor initializes
the base class by calling basic_ostream(sb).
It
also
initializes sb
by
calling basic_stringbuf<E,
T, A>(x, mode |
ios_base::out).
basic_ostringstream::rdbuf
basic_stringbuf<E,
T, A> *rdbuf()
const
181
Chapter
12. Standard C++ Library
Header Files
The
member function returns the
address of the stored stream
buffer, of type
pointer
to basic_stringbuf<E,
T, A>.
basic_ostringstream::str
basic_string<E,
T, A> str()
const;
void
str(basic_string<E,
T, A>& x);
The
first member function
returns rdbuf()->
str().
The second member
function
calls
rdbuf()->
str(x).
basic_stringstream
template
<class E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_stringstream
:
public basic_iostream<E, T>
{
public:
explicit
basic_stringstream(
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
explicit
basic_stringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
basic_stringbuf<E,
T, A> *rdbuf()
const;
basic_string<E,
T, A>& str();
void
str(const
basic_string<E, T, A>& x);
};
The
template class describes an object
that controls insertion and
extraction of
elements
and encoded objects using a
stream buffer of class basic_stringbuf<E,
T,
A>,
with elements of type E, whose
character traits (page 211)
are determined by
the
class T, and
whose elements are allocated
by an allocator of class A. The
object
stores
an object of class basic_stringbuf<E,
T, A>.
basic_stringstream::basic_stringstream
explicit
basic_stringstream(
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
explicit
basic_stringstream(
const
basic_string<E, T, A>& x,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
The
first constructor initializes
the base class by calling basic_iostream(sb),
where
sb
is
the stored object of class basic_stringbuf<E,
T, A>. It
also initializes sb
by
calling
basic_stringbuf<E,
T, A>(mode).
The
second constructor initializes
the base class by calling basic_ostream(sb).
It
also
initializes sb
by
calling basic_stringbuf<E,
T, A>(x, mode).
basic_stringstream::rdbuf
basic_stringbuf<E,
T, A> *rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to basic_stringbuf<E,
T, A>.
basic_stringstream::str
basic_string<E,
T, A> str()
const;
void
str(basic_string<E,
T, A>& x);
182
Standard
C++ Library
The
first member function
returns rdbuf()->
str().
The second member
function
calls
rdbuf()->
str(x).
istringstream
typedef
basic_istringstream<char> istringstream;
The
type is a synonym for template class
basic_istringstream (page 180),
specialized
for elements of type char.
ostringstream
typedef
basic_ostringstream<char> ostringstream;
The
type is a synonym for template class
basic_ostringstream (page 181),
specialized
for elements of type char.
stringbuf
typedef
basic_stringbuf<char> stringbuf;
The
type is a synonym for template class
basic_stringbuf (page 176),
specialized for
elements
of type char.
stringstream
typedef
basic_stringstream<char> stringstream;
The
type is a synonym for template class
basic_stringstream,
specialized for
elements
of type char.
wistringstream
typedef
basic_istringstream<wchar_t> wistringstream;
The
type is a synonym for template class
basic_istringstream,
specialized for
elements
of type wchar_t.
wostringstream
typedef
basic_ostringstream<wchar_t> wostringstream;
The
type is a synonym for template class
basic_ostringstream,
specialized for
elements
of type wchar_t.
wstringbuf
typedef
basic_stringbuf<wchar_t> wstringbuf;
The
type is a synonym for template class
basic_stringbuf,
specialized for elements
of
type wchar_t.
wstringstream
typedef
basic_stringstream<wchar_t> wstringstream;
The
type is a synonym for template class
basic_stringstream,
specialized for
elements
of type wchar_t.
183
Chapter
12. Standard C++ Library
Header Files
<stdexcept>
namespace
std {
class
logic_error;
class
domain_error;
class
invalid_argument;
class
length_error;
class
out_of_range;
class
runtime_error;
class
range_error;
class
overflow_error;
class
underflow_error;
};
Include
the standard header
<stdexcept>
to
define several classes used
for
reporting
exceptions. The classes form a derivation
hierarchy, as indicated by
the
indenting
above, all derived from class
exception (page 75).
domain_error
class
domain_error
:
public logic_error {
public:
domain_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report a
domain
error.
The value returned by what()
is a
copy of what_arg.data().
invalid_argument
class
invalid_argument
:
public logic_error {
public:
invalid_argument(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report an
invalid
argument.
The value returned by what()
is a
copy of what_arg.data().
length_error
class
length_error
:
public logic_error {
public:
length_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report an
attempt to
generate
an object too long to be
specified. The value
returned by what()
is a
copy
of
what_arg.data().
logic_error
class
logic_error
:
public exception {
public:
logic_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report
errors
presumably
detectable before the
program executes, such as
violations of logical
preconditions.
The value returned by what()
is a
copy of what_arg.data().
184
Standard
C++ Library
out_of_range
class
out_of_range
:
public logic_error {
public:
out_of_range(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report an
argument
that
is out of its valid range.
The value returned by what()
is a
copy of
what_arg.data().
overflow_error
class
overflow_error
:
public runtime_error {
public:
overflow_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report an
arithmetic
overflow.
The value returned by what()
is a
copy of what_arg.data().
range_error
class
range_error
:
public runtime_error {
public:
range_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report a
range
error.
The
value returned by what()
is a
copy of what_arg.data().
runtime_error
class
runtime_error
:
public exception {
public:
runtime_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report
errors
presumably
detectable only when the
program executes. The value
returned by
what()
is a
copy of what_arg.data().
underflow_error
class
underflow_error
:
public runtime_error {
public:
underflow_error(const
string& what_arg);
};
The
class serves as the base class for
all exceptions thrown to report an
arithmetic
underflow.
The value returned by what()
is a
copy of what_arg.data().
<streambuf>
namespace
std {
template<class
E, class T = char_traits<E>
>
class
basic_streambuf;
typedef
basic_streambuf<char, char_traits<char>
>
streambuf;
typedef
basic_streambuf<wchar_t,
char_traits<wchar_t>
> wstreambuf;
};
185
Chapter
12. Standard C++ Library
Header Files
Include
the iostreams (page 7)
standard header <streambuf>
to
define template
class
basic_streambuf (page 186),
which is basic to the
operation of the
iostreams
classes.
(This header is typically
included for you by another of the
iostreams
headers.
You seldom have occasion to
include it directly.)
basic_streambuf
(page
194)
template
<class E, class T =
char_traits<E> >
class
basic_streambuf
{
public:
typedef
E char_type;
typedef
T traits_type;
typedef
typename traits_type::int_type int_type;
typedef
typename traits_type::pos_type pos_type;
typedef
typename traits_type::off_type off_type;
virtual
~streambuf();
locale
pubimbue(const
locale& loc);
locale
getloc()
const;
basic_streambuf
*pubsetbuf(char_type
*s,
streamsize
n);
pos_type
pubseekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
pos_type
pubseekpos(pos_type
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
int
pubsync();
streamsize
in_avail();
int_type
snextc();
int_type
sbumpc();
int_type
sgetc();
void
stossc(); //
OPTIONAL
streamsize
sgetn(char_type
*s, streamsize n);
int_type
sputbackc(char_type
c);
int_type
sungetc();
int_type
sputc(char_type
c);
streamsize
sputn(const
char_type *s, streamsize n);
protected:
basic_streambuf();
char_type
*eback()
const;
char_type
*gptr()
const;
char_type
*egptr()
const;
void
gbump(int
n);
void
setg(char_type
*gbeg,
char_type
*gnext, char_type
*gend);
char_type
*pbase()
const;
char_type
*pptr()
const;
char_type
*epptr()
const;
void
pbump(int
n);
void
setp(char_type
*pbeg, char_type
*pend);
virtual
void imbue(const
locale &loc);
186
Standard
C++ Library
virtual
basic_streambuf *setbuf(char_type
*s,
streamsize
n);
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
pos_type seekpos(pos_type
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
int sync();
virtual
streamsize showmanyc();
virtual
streamsize xsgetn(char_type
*s,
streamsize
n);
virtual
int_type underflow();
virtual
int_type uflow();
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
virtual
streamsize xsputn(const
char_type *s,
streamsize
n);
virtual
int_type overflow(int_type
c =
traits_type::eof());
};
The
template class describes an abstract
base class for deriving a stream
buffer,
which
controls the transmission of
elements to and from a specific
representation
of
a stream. An object of class basic_streambuf
helps
control a stream with
elements
of type T, also
known as char_type (page 188),
whose character
traits
traits_type
(page 193).
Every
stream buffer conceptually
controls two independent streams, in
fact, one for
extractions
(input) and one for insertions
(output). A specific representation
may,
however,
make either or both of these
streams inaccessible. It typically
maintains
some
relationship between the two
streams. What you insert
into the output
stream
of a basic_stringbuf<E,
T> object,
for example, is what you later
extract
from
its input stream. And when you
position one stream of a basic_filebuf<E,
T>
(page 77)
object,
you position the other
stream in tandem.
The
public interface to template class
basic_streambuf (page 186)
supplies the
operations
common to all stream
buffers, however specialized.
The protected
interface
supplies the operations
needed for a specific representation of a
stream to
do
its work. The protected
virtual member functions let
you tailor the behavior
of
a
derived stream buffer for a
specific representation of a stream.
Each of the
derived
stream buffers in this
library describes how it specializes
the behavior of
its
protected virtual member
functions. Documented here is
the default
behavior
for
the base class, which is
often to do nothing.
The
remaining protected member
functions control copying to and from
any
storage
supplied to buffer transmissions to and
from streams. An input
buffer,
for
example,
is characterized by:
v
eback()
(page 188), a
pointer to the beginning of
the buffer
v
gptr()
(page 189), a
pointer to the next element
to read
v
egptr()
(page 188), a
pointer just past the
end of the buffer
Similarly,
an output
buffer is
characterized by:
v
pbase()
(page 190), a
pointer to the beginning of
the buffer
v
pptr()
(page 190), a
pointer to the next element
to write
v
epptr()
(page 188), a
pointer just past the
end of the buffer
187
Chapter
12. Standard C++ Library
Header Files
For
any buffer, the protocol
is:
v
If
the next pointer is null, no
buffer exists. Otherwise,
all three pointers
point
into
the same sequence. (They
can be safely compared for
order.)
v
For an
output buffer, if the next
pointer compares less than
the end pointer, you
can
store an element at the
write
position designated
by the next pointer.
v
For an
input buffer, if the next
pointer compares less than
the end pointer, you
can
read an element at the
read
position designated
by the next pointer.
v
For an
input buffer, if the
beginning pointer compares less
than the next
pointer,
you
can put back an element at
the putback
position designated
by the
decremented
next pointer.
Any
protected virtual member
functions you write for a class derived
from
basic_streambuf<E,
T> must
cooperate in maintaining this
protocol.
An
object of class basic_streambuf<E,
T> stores
the six pointers described
above. It
potential
use by a derived stream
buffer.
basic_streambuf::basic_streambuf
basic_streambuf();
The
protected constructor stores a null
pointer in all the pointers
controlling the
locale::classic()
in
the locale object (page 135).
basic_streambuf::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
basic_streambuf::eback
char_type
*eback()
const;
The
member function returns a
pointer to the beginning of
the input buffer
(page
basic_streambuf::egptr
char_type
*egptr()
const;
The
member function returns a
pointer just past the
end of the input buffer
(page
basic_streambuf::epptr
char_type
*epptr()
const;
The
member function returns a
pointer just past the
end of the output buffer
(page
basic_streambuf::gbump
void
gbump(int
n);
The
member function adds n
to
the next pointer for the
input buffer (page 187).
188
Standard
C++ Library
basic_streambuf::getloc
locale
getloc()
const;
The
member function returns the
stored locale object.
basic_streambuf::gptr
char_type
*gptr()
const;
The
member function returns a
pointer to the next element
of the input buffer
(page
187).
basic_streambuf::imbue
virtual
void imbue(const
locale &loc);
The
default behavior is to do
nothing.
basic_streambuf::in_avail
streamsize
in_avail();
If
a read position (page 188)
is available, the member
function returns egptr()
-
gptr().
Otherwise, it returns showmanyc().
basic_streambuf::int_type
typedef
typename traits_type::int_type int_type;
The
type is a synonym for traits_type::int_type.
basic_streambuf::off_type
typedef
typename traits_type::off_type off_type;
The
type is a synonym for traits_type::off_type.
basic_streambuf::overflow
virtual
int_type overflow(int_type
c =
traits_type::eof());
If
c
does
not compare equal to traits_type::eof(), the
protected virtual
member
function
endeavors to insert the
element traits_type::
to_char_type(c) into
the
output
stream. It can do so in various
ways:
v
If a
write position (page 188)
is available, it can store
the element into the
write
position
and increment the next
pointer for the output
buffer (page 187).
v
It
can make a write position
available by allocating new or additional
storage for
the
output buffer.
v
It
can make a write position
available by writing out, to
some external
destination,
some or all of the elements
between the beginning and
next pointers
for
the output buffer.
If
the function cannot succeed,
it returns traits_type::eof()
or
throws an
exception.
Otherwise, it returns traits_type::not_eof(c). The
default behavior is
to
return traits_type::eof().
basic_streambuf::pbackfail
virtual
int_type pbackfail(int_type
c =
traits_type::eof());
189
Chapter
12. Standard C++ Library
Header Files
The
protected virtual member
function endeavors to put back an
element into the
input
stream, then make it the
current element (pointed to by
the next pointer). If c
compares
equal to traits_type::eof(), the
element to push back is
effectively the
one
already in the stream before
the current element.
Otherwise, that element
is
replaced
by traits_type::to_char_type(c). The
function can put back an
element
in
various ways:
v
If a
putback position (page 188)
is available, it can store
the element into
the
putback
position and decrement the
next pointer for the input
buffer (page 187).
v
It
can make a putback position
available by allocating new or additional
storage
for
the input buffer.
v
For a
stream buffer with common
input and output streams, it
can make a
putback
position available by writing
out, to some external
destination, some or
all
of the elements between the
beginning and next pointers for
the output
buffer.
If
the function cannot succeed,
it returns traits_type::eof()
or
throws an
exception.
Otherwise, it returns some
other value. The default
behavior is to return
traits_type::eof().
basic_streambuf::pbase
char_type
*pbase()
const;
The
member function returns a
pointer to the beginning of
the output buffer
(page
basic_streambuf::pbump
void
pbump(int
n);
The
member function adds n
to
the next pointer for the
output buffer (page 187).
basic_streambuf::pos_type
typedef
typename traits_type::pos_type pos_type;
The
type is a synonym for traits_type::pos_type.
basic_streambuf::pptr
char_type
*pptr()
const;
The
member function returns a
pointer to the next element
of the output buffer.
basic_streambuf::pubimbue
locale
pubimbue(const
locale& loc);
The
member function stores loc
in
the locale object, calls
imbue(), then
returns the
previous
value stored in the locale
object.
basic_streambuf::pubseekoff
pos_type
pubseekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
member function returns seekoff(off,
way, which).
190
Standard
C++ Library
basic_streambuf::pubseekpos
pos_type
pubseekpos(pos_type
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
member function returns seekpos(sp,
which).
basic_streambuf::pubsetbuf
basic_streambuf
*pubsetbuf(char_type
*s, streamsize n);
The
member function returns stbuf(s,
n).
basic_streambuf::pubsync
int
pubsync();
The
member function returns sync().
basic_streambuf::sbumpc
int_type
sbumpc();
If
a read position (page 188)
is available, the member
function returns
traits_type::to_int_type(
*gptr()) and
increments the next pointer
for the input
buffer.
Otherwise, it returns uflow().
basic_streambuf::seekoff
virtual
pos_type seekoff(off_type
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. The new
position is determined as
follows:
v
If
way
== ios_base::beg,
the new position is the
beginning of the stream
plus
off.
v
If
way
== ios_base::cur,
the new position is the
current stream position
plus
off.
v
If
way
== ios_base::end,
the new position is the end
of the stream plus off.
Typically,
if which
& ios_base::in is
nonzero, the input stream is
affected, and if
which
& ios_base::out is
nonzero, the output stream
is affected. Actual use of
this
parameter
varies among derived stream
buffers, however.
If
the function succeeds in
altering the stream
position(s), it returns the
resultant
stream
position (or one of them).
Otherwise, it returns an invalid
stream position.
The
default behavior is to return an
invalid stream
position.
basic_streambuf::seekpos
virtual
pos_type seekpos(pos_type
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. The new
position is sp.
Typically,
if which
& ios_base::in is
nonzero, the input stream is
affected, and if
which
& ios_base::out is
nonzero, the output stream
is affected. Actual use of
this
parameter
varies among derived stream
buffers, however.
191
Chapter
12. Standard C++ Library
Header Files
If the
function succeeds in altering
the stream position(s), it
returns the resultant
stream
position (or one of them).
Otherwise, it returns an invalid
stream position.
The
default behavior is to return an
invalid stream
position.
basic_streambuf::setbuf
virtual
basic_streambuf *setbuf(char_type
*s,
streamsize
n);
The
protected virtual member
function performs an operation
peculiar to each
derived
stream buffer. (See, for example,
basic_filebuf (page 77).)
The default
behavior
is to return this.
basic_streambuf::setg
void
setg(char_type
*gbeg, char_type
*gnext,
char_type
*gend);
The
member function stores gbeg
in
the beginning pointer, gnext
in
the next
pointer,
and gend
in
the end pointer for the
input buffer (page 187).
basic_streambuf::setp
void
setp(char_type
*pbeg, char_type
*pend);
The
member function stores pbeg
in
the beginning pointer, pbeg
in
the next pointer,
and
pend
in
the end pointer for the
output buffer (page 187).
basic_streambuf::sgetc
int_type
sgetc();
If
a read position (page 188)
is available, the member
function returns
traits_type::to_int_type(
*gptr()) Otherwise,
it returns underflow().
basic_streambuf::sgetn
streamsize
sgetn(char_type
*s, streamsize n);
The
member function returns xsgetn(s,
n).
basic_streambuf::showmanyc
virtual
streamsize showmanyc();
The
protected virtual member
function returns a count of
the number of
characters
that
can be extracted from the
input stream with no fear
that the program will
suffer
an indefinite wait. The
default behavior is to return
zero.
basic_streambuf::snextc
int_type
snextc();
The
member function calls sbumpc()
and, if
that function returns
traits_type::eof(),
returns traits_type::eof().
Otherwise, it returns sgetc().
basic_streambuf::sputbackc
int_type
sputbackc(char_type
c);
If
a putback position (page 188)
is available and c
compares
equal to the
character
stored
in that position, the member
function decrements the next
pointer for the
input
buffer and returns ch, which
is the value traits_type::to_int_type(c).
Otherwise,
it returns pbackfail(ch).
192
Standard
C++ Library
basic_streambuf::sputc
int_type
sputc(char_type
c);
If
a write position (page 188)
is available, the member
function stores c
in
the write
position,
increments the next pointer
for the output buffer, and
returns ch, which
is
the
value traits_type::to_int_type(c).
Otherwise, it returns overflow(ch).
basic_streambuf::sputn
streamsize
sputn(const
char_type *s, streamsize n);
The
member function returns xsputn(s,
n).
basic_streambuf::stossc
void
stossc();
//
OPTIONAL
The
member function calls sbumpc(). Note
that an implementation is not
required
to
supply this member
function.
basic_streambuf::sungetc
int_type
sungetc();
If
a putback position (page 188)
is available, the member
function decrements
the
next
pointer for the input buffer
and returns traits_type::to_int_type(
*gptr()).
Otherwise
it returns pbackfail().
basic_streambuf::sync
virtual
int sync();
The
protected virtual member
function endeavors to synchronize
the controlled
streams
with any associated external
streams. Typically, this
involves writing out
any
elements between the
beginning and next pointers for
the output buffer. It
does
not
involve
putting back any elements
between the next and end
pointers for
the
input buffer. If the
function cannot succeed, it
returns -1. The default
behavior
is
to return zero.
basic_streambuf::traits_type
typedef
T traits_type;
The
type is a synonym for the
template parameter T.
basic_streambuf::uflow
virtual
int_type uflow();
The
protected virtual member
function endeavors to extract
the current element c
from
the input stream, then
advance the current stream
position, and return
the
element
as traits_type::to_int_type(c). It can
do so in various ways:
v
If a
read position (page 188)
is available, it takes c
as
the element stored in
the
read
position and advances the
next pointer for the input
buffer.
v
It
can read an element
directly, from some external
source, and deliver it as
the
value
c.
v
For a
stream buffer with common
input and output streams, it
can make a read
position
available by writing out, to
some external destination,
some or all of the
elements
between the beginning and
next pointers for the output
buffer. Or it
can
allocate new or additional storage for
the input buffer. The
function then
reads
in, from some external
source, one or more
elements.
193
Chapter
12. Standard C++ Library
Header Files
If the
function cannot succeed, it
returns traits_type::eof(), or
throws an
exception.
Otherwise, it returns the
current element c
in
the input stream,
converted
as described above, and advances
the next pointer for the
input buffer.
The
default behavior is to call underflow()
and, if
that function returns
traits_type::eof(), to
return traits_type::eof().
Otherwise, the function
returns
the
current element c
in
the input stream, converted
as described above, and
advances
the next pointer for the
input buffer.
basic_streambuf::underflow
virtual
int_type underflow();
The
protected virtual member
function endeavors to extract
the current element c
from
the input stream, without
advancing the current stream
position, and return
it
as traits_type::to_int_type(c). It can
do so in various ways:
v
If a
read position (page 188)
is available, c
is
the element stored in the
read
position.
v
It
can make a read position
available by allocating new or additional
storage for
the
input buffer, then reading
in, from some external
source, one or more
elements.
If
the function cannot succeed,
it returns traits_type::eof(), or
throws an
exception.
Otherwise, it returns the
current element in the input
stream, converted
as
described above. The default
behavior is to return traits_type::eof().
basic_streambuf::xsgetn
virtual
streamsize xsgetn(char_type
*s, streamsize n);
The
protected virtual member
function extracts up to n
elements
from the input
stream,
as if by repeated calls to sbumpc
(page 191),
and stores them in the
array
beginning
at s. It
returns the number of
elements actually
extracted.
basic_streambuf::xsputn
virtual
streamsize xsputn(const
char_type *s,
streamsize
n);
The
protected virtual member
function inserts up to n
elements
into the output
stream,
as if by repeated calls to sputc
(page 193),
from the array beginning at
s.
It
returns
the number of elements
actually inserted.
streambuf
typedef
basic_streambuf<char, char_traits<char>
>
streambuf;
The
type is a synonym for template class
basic_streambuf,
specialized for elements
of
type char
with
default character traits
(page 211).
wstreambuf
typedef
basic_streambuf<wchar_t, char_traits<wchar_t>
>
wstreambuf;
The
type is a synonym for template class
basic_streambuf,
specialized for elements
of
type wchar_t
with
default character traits
(page 211).
194
Standard
C++ Library
<string>
namespace
std {
template<class
E>
class
char_traits;
template<>
class
char_traits<char>;
template<>
class
char_traits<wchar_t>;
template<class
E,
class
T = char_traits<E>,
class
A = allocator<E> >
class
basic_string;
typedef
basic_string<char> string;
typedef
basic_string>wchar_t> wstring;
//
TEMPLATE FUNCTIONS
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
E
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
E
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator==(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator==(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator==(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator!=(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator!=(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator!=(
const
E *lhs,
195
Chapter
12. Standard C++ Library
Header Files
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator<(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator<(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator<(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator>(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator>(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator>(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator<=(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator<=(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator<=(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator>=(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
bool
operator>=(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
bool
operator>=(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
void
swap(
basic_string<E,
T, A>& lhs,
basic_string<E,
T, A>& rhs);
template<class
E, class T, class A>
basic_ostream<E>&
operator<<(
basic_ostream<E>&
os,
const
basic_string<E, T, A>&
str);
template<class
E, class T, class A>
basic_istream<E>&
operator>>(
basic_istream<E>&
is,
basic_string<E,
T, A>& str);
template<class
E, class T, class A>
basic_istream<E,
T>& getline(
basic_istream<E,
T>& is,
basic_string<E,
T, A>& str);
template<class
E, class T, class A>
basic_istream<E,
T>& getline(
196
Standard
C++ Library
basic_istream<E,
T>& is,
basic_string<E,
T, A>& str,
E
delim);
};
Include
the standard header
<string>
to
define the container (page
41)
template
class
basic_string (page 197)
and various supporting
templates.
basic_string
template<class
E,
class
T = char_traits<E>,
class
A = allocator<T> >
class
basic_string
{
public:
typedef
T traits_type;
typedef
A allocator_type;
typedef
T0 iterator;
typedef
T1 const_iterator;
typedef
T2 size_type;
typedef
T3 difference_type;
typedef
reverse_iterator<const_iterator>
const_reverse_iterator;
typedef
reverse_iterator<iterator>
reverse_iterator;
typedef
typename allocator_type::pointer
pointer;
typedef
typename allocator_type::const_pointer
const_pointer;
typedef
typename allocator_type::reference
reference;
typedef
typename allocator_type::const_reference
const_reference;
typedef
typename allocator_type::value_type
value_type;
static
const size_type npos
=
-1;
basic_string();
explicit
basic_string(const
allocator_type& al);
basic_string(const
basic_string& rhs);
basic_string(const
basic_string& rhs, size_type
pos,
size_type
n = npos);
basic_string(const
basic_string& rhs, size_type
pos,
size_type
n, const allocator_type& al);
basic_string(const
value_type *s, size_type n);
basic_string(const
value_type *s, size_type n,
const
allocator_type& al);
basic_string(const
value_type *s);
basic_string(const
value_type *s,
const
allocator_type& al);
197
Chapter
12. Standard C++ Library
Header Files
basic_string(size_type
n, value_type c);
basic_string(size_type
n, value_type c,
const
allocator_type& al);
template
<class InIt>
basic_string(InIt first, InIt
last);
template
<class InIt>
basic_string(InIt first, InIt
last,
const
allocator_type& al);
basic_string&
operator=(const
basic_string& rhs);
basic_string&
operator=(const
value_type *s);
basic_string&
operator=(value_type
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;
const_reference
at(size_type
pos) const;
reference
at(size_type
pos);
const_reference
operator[](size_type
pos) const;
reference
operator[](size_type
pos);
void
push_back(value_type
c);
const
value_type *c_str()
const;
const
value_type *data()
const;
size_type
length()
const;
size_type
size()
const;
size_type
max_size()
const;
void
resize(size_type
n, value_type c = value_type());
size_type
capacity()
const;
void
reserve(size_type
n = 0);
bool
empty()
const;
basic_string&
operator+=(const
basic_string& rhs);
basic_string&
operator+=(const
value_type *s);
basic_string&
operator+=(value_type
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
value_type *s,
size_type
n);
basic_string&
append(const
value_type *s);
basic_string&
append(size_type
n, value_type c);
template<class
InIt>
basic_string&
append(InIt first, InIt
last);
basic_string&
assign(const
basic_string& str);
basic_string&
assign(const
basic_string& str,
size_type
pos, size_type n);
basic_string&
assign(const
value_type *s,
size_type
n);
basic_string&
assign(const
value_type *s);
basic_string&
assign(size_type
n, value_type c);
template<class
InIt>
basic_string&
assign(InIt first, InIt
last);
basic_string&
insert(size_type
p0,
const
basic_string& str);
basic_string&
insert(size_type
p0,
const
basic_string& str, size_type
pos,
size_type
n);
basic_string&
insert(size_type
p0,
const
value_type *s, size_type n);
basic_string&
insert(size_type
p0,
const
value_type *s);
basic_string&
insert(size_type
p0,
size_type
n, value_type c);
iterator
insert(iterator
it,
value_type
c = value_type());
198
Standard
C++ Library
void
insert(iterator it,
size_type n, value_type c);
template<class
InIt>
void
insert(iterator
it,
InIt
first, InIt last);
basic_string&
erase(size_type
p0 = 0,
size_type
n = npos);
iterator
erase(iterator
it);
iterator
erase(iterator first,
iterator last);
void
clear();
basic_string&
replace(size_type
p0, size_type n0,
const
basic_string& str);
basic_string&
replace(size_type
p0, size_type n0,
const
basic_string& str, size_type
pos,
size_type
n);
basic_string&
replace(size_type
p0, size_type n0,
const
value_type *s, size_type n);
basic_string&
replace(size_type
p0, size_type n0,
const
value_type *s);
basic_string&
replace(size_type
p0, size_type n0,
size_type
n, value_type c);
basic_string&
replace(iterator first0,
iterator last0,
const
basic_string& str);
basic_string&
replace(iterator first0,
iterator last0,
const
value_type *s, size_type n);
basic_string&
replace(iterator first0,
iterator last0,
const
value_type *s);
basic_string&
replace(iterator first0,
iterator last0,
size_type
n, value_type c);
template<class
InIt>
basic_string&
replace(iterator first0,
iterator last0,
InIt
first, InIt last);
size_type
copy(value_type
*s, size_type n,
size_type
pos = 0) const;
void
swap(basic_string&
str);
size_type
find(const
basic_string& str,
size_type
pos = 0) const;
size_type
find(const
value_type *s, size_type
pos,
size_type
n) const;
size_type
find(const
value_type *s,
size_type
pos = 0) const;
size_type
find(value_type
c, size_type pos = 0)
const;
size_type
rfind(const
basic_string& str,
size_type
pos = npos) const;
size_type
rfind(const
value_type *s, size_type
pos,
size_type
n = npos) const;
size_type
rfind(const
value_type *s,
size_type
pos = npos) const;
size_type
rfind(value_type
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
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_first_of(const
value_type *s,
size_type
pos = 0) const;
size_type
find_first_of(value_type
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
value_type *s,
size_type
pos, size_type n = npos)
const;
size_type
find_last_of(const
value_type *s,
size_type
pos = npos) const;
size_type
find_last_of(value_type
c,
size_type
pos = npos) const;
size_type
find_first_not_of(const
basic_string& str,
199
Chapter
12. Standard C++ Library
Header Files
size_type
pos = 0) const;
size_type
find_first_not_of(const
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_first_not_of(const
value_type *s,
size_type
pos = 0) const;
size_type
find_first_not_of(value_type
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
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_last_not_of(const
value_type *s,
size_type
pos = npos) const;
size_type
find_last_not_of(value_type
c,
size_type
pos = npos) const;
basic_string
substr(size_type
pos = 0,
size_type
n = npos) const;
int
compare(const
basic_string& str) const;
int
compare(size_type
p0, size_type n0,
const
basic_string& str);
int
compare(size_type
p0, size_type n0,
const
basic_string& str, size_type
pos,
size_type
n);
int
compare(const
value_type *s) const;
int
compare(size_type
p0, size_type n0,
const
value_type *s) const;
int
compare(size_type
p0, size_type n0,
const
value_type *s, size_type pos)
const;
allocator_type
get_allocator()
const;
};
The
template class describes an object
that controls a varying-length
sequence of
elements
of type E, also
known as value_type (page 210).
Such an element
type
must
not require explicit
construction or destruction, and it must
be suitable for
``plain
old data structure,'' or POD,
from C generally meets this
criterion.) The
Standard
C++ library provides two
specializations of this template class,
with the
for
elements of type wchar_t.
Various
important properties of the
elements in a basic_string
specialization
are
described
by the class T, also
known as traits_type (page 210).
A class that specifies
these
character traits (page 211)
must have the same
external interface as an
object
of
template class char_traits (page 210).
The
object allocates and frees
storage for the sequence it
controls through a
stored
an
allocator object must have
the same external interface
as an object of template
alternate
addressing schemes, such as
might be required to implement a far
heap
(page
338).)
Note that the stored
allocator object is not
copied
when the container
object
is assigned.
The
sequences controlled by an object of
template class basic_string
are
usually
called
strings.
These objects should not be
confused, however, with
the
null-terminated
C strings used throughout
the Standard C++
library.
Many
member functions require an
operand
sequence of
elements. You can
specify
such
an operand sequence several
ways:
v
c
--
one element with value c
200
Standard
C++ Library
v n, c -- a
repetition of n
elements
each with value c
v
s
-- a
null-terminated sequence (such as a C
string, for E
of
type char)
beginning
at
s
(which
must not be a null pointer),
where the terminating
element is the
value
value_type()
and is
not part of the operand
sequence
v
s, n
-- a
sequence of n
elements
beginning at s
(which
must not be a null
pointer)
v
str
--
the sequence specified by
the basic_string
object
str
v
str,
pos, n --
the substring of the basic_string
object
str
with up
to n
elements
(or through the end of
the string, whichever comes
first) beginning at
position
pos
v
first, last
-- a
sequence of elements delimited by
the iterators first
and
last, in the
range [first,
last),
which must not
overlap
the sequence
controlled
by the string object whose
member function is being
called
If
a position
argument (such as
pos
above)
is beyond the end of the
string on a
call
to a basic_string
member
function, the function
reports an out-of-range
error
by
throwing an object of class out_of_range
(page 185).
If
a function is asked to generate a
sequence longer than max_size()
elements,
the
function
reports a length
error by
throwing an object of class length_error
(page
References,
pointers, and iterators that
designate elements of the
controlled
sequence
can become invalid after
any call to a function that
alters the controlled
sequence,
or after the first call to
the non-const member
functions at (page 202),
(page
208).
(The idea is to permit
multiple strings to share
the same
representation
until
one string becomes a
candidate for change, at which
point that string
makes
a
private copy of the
representation, using a discipline
called copy
on write.)
basic_string::allocator_type
typedef
A allocator_type;
The
type is a synonym for the
template parameter A.
basic_string::append
basic_string&
append(const
value_type *s);
basic_string&
append(const
value_type *s,
size_type
n);
basic_string&
append(const
basic_string& str,
size_type
pos, size_type n);
basic_string&
append(const
basic_string& str);
basic_string&
append(size_type
n, value_type c);
template<class
InIt>
basic_string&
append(InIt first, InIt
last);
If
InIt
is an
integer type, the template
member function behaves the
same as
append((size_type)first,
(value_type)last).
Otherwise, the member
functions
each
append the operand sequence
(page 200)
to the end of the
sequence
controlled
by *this, then
return *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
InIt>
basic_string&
append(InIt first, InIt
last);
201
Chapter
12. Standard C++ Library
Header Files
is
replaced by:
basic_string&
append(const_pointer
first,
const_pointer
last);
basic_string::assign
basic_string&
assign(const
value_type *s);
basic_string&
assign(const
value_type *s,
size_type
n);
basic_string&
assign(const
basic_string& str,
size_type
pos, size_type n);
basic_string&
assign(const
basic_string& str);
basic_string&
assign(size_type
n, value_type c);
template<class
InIt>
basic_string&
assign(InIt first, InIt
last);
If
InIt
is an
integer type, the template
member function behaves the
same as
assign((size_type)first,
(value_type)last).
Otherwise, the member
functions
each
replace the sequence
controlled by *this
with
the operand sequence
(page
200),
then return *this.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
InIt>
basic_string&
assign(InIt first, InIt
last);
is
replaced by:
basic_string&
assign(const_pointer
first,
const_pointer
last);
basic_string::at
const_reference
at(size_type
pos) const;
reference
at(size_type
pos);
The
member functions each return
a reference to the element of
the controlled
sequence
at position pos, or
report an out-of-range error
(page 201).
basic_string::basic_string
basic_string(const
value_type *s);
basic_string(const
value_type *s,
const
allocator_type& al);
basic_string(const
value_type *s, size_type n);
basic_string(const
value_type *s, size_type n,
const
allocator_type& al);
basic_string(const
basic_string& rhs);
basic_string(const
basic_string& rhs, size_type
pos,
size_type
n = npos);
basic_string(const
basic_string& rhs, size_type
pos,
size_type
n, const allocator_type& al);
basic_string(size_type
n, value_type c);
basic_string(size_type
n, value_type c,
const
allocator_type& al);
basic_string();
explicit
basic_string(const
allocator_type& al);
template
<class InIt>
basic_string(InIt first, InIt
last);
template
<class InIt>
basic_string(InIt first, InIt
last, const allocator_type&
al);
All
constructors store an allocator
object (page 337)
and initialize the
controlled
sequence.
The allocator object is the
argument al, if
present. For the
copy
constructor,
it is x.get_allocator().
Otherwise, it is A().
202
Standard
C++ Library
The
controlled sequence is initialized to a
copy of the operand sequence
(page 200)
specified
by the remaining operands. A
constructor with no operand
sequence
specifies
an empty initial controlled
sequence. If InIt
is an
integer type in a
template
constructor, the operand
sequence first,
last behaves
the same as
(size_type)first,
(value_type)last.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the templates:
template
<class InIt>
basic_string(InIt first, InIt
last);
template
<class InIt>
basic_string(InIt first, InIt
last,
const
allocator_type& al);
are
replaced by:
basic_string(const_pointer
first, const_pointer last);
basic_string(const_pointer
first, const_pointer last,
const
allocator_type& al);
basic_string::begin
const_iterator
begin()
const;
iterator
begin();
The
member functions each return
a random-access iterator that
points at the first
element
of the sequence (or just
beyond the end of an empty
sequence).
basic_string::c_str
const
value_type *c_str()
const;
The
member function returns a
pointer to a non-modifiable C string
constructed by
adding
a terminating null element (value_type()) to the
controlled sequence.
Calling
any non-const member
function for *this
can
invalidate the
pointer.
basic_string::capacity
size_type
capacity()
const;
The
member function returns the
storage currently allocated to hold
the controlled
sequence,
a value at least as large as size().
basic_string::clear
void
clear();
The
member function calls erase(
begin(), end()).
basic_string::compare
int
compare(const
basic_string& str) const;
int
compare(size_type
p0, size_type n0,
const
basic_string& str);
int
compare(size_type
p0, size_type n0,
const
basic_string& str, size_type pos,
size_type n);
int
compare(const
value_type *s) const;
int
compare(size_type
p0, size_type n0,
const
value_type *s) const;
int
compare(size_type
p0, size_type n0,
const
value_type *s, size_type pos)
const;
The
member functions each
compare up to n0
elements
of the controlled
sequence
beginning
with position p0, or the
entire controlled sequence if
these arguments are
not
supplied, to the operand
sequence (page 200).
Each function
returns:
203
Chapter
12. Standard C++ Library
Header Files
v a
negative value if the first
differing element in the
controlled sequence
compares
less than the corresponding
element in the operand
sequence (as
determined
by traits_type::compare), or if
the two have a common prefix
but
the
operand sequence is
longer
v
zero if
the two compare equal
element by element and are
the same length
v
a
positive value
otherwise
basic_string::const_iterator
typedef
T1 const_iterator;
The
type describes an object
that can serve as a constant
random-access iterator for
the
controlled sequence. It is described
here as a synonym for
the
implementation-defined
type T1.
basic_string::const_pointer
typedef
typename allocator_type::const_pointer
const_pointer;
The
type is a synonym for allocator_type::const_pointer.
basic_string::const_reference
typedef
typename allocator_type::const_reference
const_reference;
The
type is a synonym for allocator_type::const_reference.
basic_string::const_reverse_iterator
typedef
reverse_iterator<const_iterator>
const_reverse_iterator;
The
type describes an object
that can serve as a constant
reverse iterator for
the
controlled
sequence.
basic_string::copy
size_type
copy(value_type
*s, size_type n,
size_type
pos = 0) const;
The
member function copies up to n elements
from the controlled
sequence,
beginning
at position pos, to the
array of value_type
beginning
at s. It
returns the
number
of elements actually
copied.
basic_string::data
const
value_type *data()
const;
The
member function returns a
pointer to the first element
of the sequence (or,
for
an
empty sequence, a non-null
pointer that cannot be
dereferenced).
basic_string::difference_type
typedef
T3 difference_type;
The
signed integer type
describes an object that can
represent the
difference
between
the addresses of any two
elements in the controlled
sequence. It is
described
here as a synonym for the
implementation-defined type T3.
204
Standard
C++ Library
basic_string::empty
bool
empty()
const;
The
member function returns true
for an empty controlled
sequence.
basic_string::end
const_iterator
end()
const;
iterator
end();
The
member functions each return
a random-access iterator that
points just beyond
the
end of the sequence.
basic_string::erase
iterator
erase(iterator first,
iterator last);
iterator
erase(iterator
it);
basic_string&
erase(size_type
p0 = 0,
size_type
n = npos);
The
first member function
removes the elements of the
controlled sequence in
the
range
[first,
last).
The second member function
removes the element of
the
controlled
sequence pointed to by it. Both
return an iterator that
designates the
first
element remaining beyond any
elements removed, or end()
if no
such element
exists.
The
third member function
removes up to n
elements
of the controlled
sequence
beginning
at position p0, then
returns *this.
basic_string::find
size_type
find(value_type
c, size_type pos = 0)
const;
size_type
find(const
value_type *s,
size_type
pos = 0) const;
size_type
find(const
value_type *s, size_type
pos,
size_type
n) const;
size_type
find(const
basic_string& str,
size_type
pos = 0) const;
The
member functions each find
the first (lowest beginning
position) subsequence
in
the controlled sequence,
beginning on or after position
pos, that
matches the
operand
sequence (page 200)
specified by the remaining
operands. If it succeeds, it
returns
the position where the
matching subsequence begins.
Otherwise, the
function
returns npos (page 207).
basic_string::find_first_not_of
size_type
find_first_not_of(value_type
c,
size_type
pos = 0) const;
size_type
find_first_not_of(const
value_type *s,
size_type
pos = 0) const;
size_type
find_first_not_of(const
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_first_not_of(const
basic_string& str,
size_type
pos = 0) const;
The
member functions each find
the first (lowest position)
element of the
controlled
sequence, at or after position
pos, that
matches none
of
the elements in
the
operand sequence (page 200)
specified by the remaining
operands. If it
succeeds,
it returns the position.
Otherwise, the function
returns npos (page 207).
205
Chapter
12. Standard C++ Library
Header Files
basic_string::find_first_of
size_type
find_first_of(value_type
c,
size_type
pos = 0) const;
size_type
find_first_of(const
value_type *s,
size_type
pos = 0) const;
size_type
find_first_of(const
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_first_of(const
basic_string& str,
size_type
pos = 0) const;
The
member functions each find
the first (lowest position)
element of the
controlled
sequence, at or after position
pos, that
matches any
of
the elements in
the
operand sequence (page 200)
specified by the remaining
operands. If it
succeeds,
it returns the position.
Otherwise, the function
returns npos (page 207).
basic_string::find_last_not_of
size_type
find_last_not_of(value_type
c,
size_type
pos = npos) const;
size_type
find_last_not_of(const
value_type *s,
size_type
pos = npos) const;
size_type
find_last_not_of(const
value_type *s,
size_type
pos, size_type n)
const;
size_type
find_last_not_of(const
basic_string& str,
size_type
pos = npos) const;
The
member functions each find
the last (highest position)
element of the
controlled
sequence, at or before position
pos, that
matches none
of
the elements in
the
operand sequence (page 200)
specified by the remaining
operands. If it
succeeds,
it returns the position.
Otherwise, the function
returns npos (page 207).
basic_string::find_last_of
size_type
find_last_of(value_type
c,
size_type
pos = npos) const;
size_type
find_last_of(const
value_type *s,
size_type
pos = npos) const;
size_type
find_last_of(const
value_type *s,
size_type
pos, size_type n = npos)
const;
size_type
find_last_of(const
basic_string& str,
size_type
pos = npos) const;
The
member functions each find
the last (highest position)
element of the
controlled
sequence, at or before position
pos, that
matches any
of
the elements in
the
operand sequence (page 200)
specified by the remaining
operands. If it
succeeds,
it returns the position.
Otherwise, the function
returns npos (page 207).
basic_string::get_allocator
allocator_type
get_allocator()
const;
The
member function returns the
stored allocator object
(page 337).
basic_string::insert
basic_string&
insert(size_type
p0, const value_type
*s);
basic_string&
insert(size_type
p0, const value_type
*s,
size_type
n);
basic_string&
insert(size_type
p0,
const
basic_string& str);
basic_string&
insert(size_type
p0,
const
basic_string& str, size_type pos,
size_type n);
basic_string&
insert(size_type
p0,
size_type
n, value_type c);
iterator
insert(iterator
it,
206
Standard
C++ Library
value_type
c = value_type());
template<class
InIt>
void
insert(iterator it,
InIt first, InIt last);
void
insert(iterator it,
size_type n, value_type c);
The
member functions each
insert, before position p0 or
before the element
pointed
to
by it in the
controlled sequence, the
operand sequence (page 200)
specified by
the
remaining operands. A function
that returns a value returns
*this. If InIt is
an
integer
type in the template member
function, the operand
sequence first,
last
behaves
the same as (size_type)first,
(value_type)last.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
InIt>
void
insert(iterator it,
InIt first, InIt last);
is
replaced by:
void
insert(iterator
it,
const_pointer
first, const_pointer last);
basic_string::iterator
typedef
T0 iterator;
The
type describes an object
that can serve as a
random-access iterator for
the
controlled
sequence. It is described here as a
synonym for the
implementation-defined
type T0.
basic_string::length
size_type
length()
const;
The
member function returns the
length of the controlled
sequence (same as
size()).
basic_string::max_size
size_type
max_size()
const;
The
member function returns the
length of the longest
sequence that the object
can
control.
basic_string::npos
static
const size_type npos
=
-1;
The
constant is the largest
representable value of type size_type. It is
assuredly
larger
than max_size(), hence
it serves as either a very large
value or as a special
code.
basic_string::operator+=
basic_string&
operator+=(value_type
c);
basic_string&
operator+=(const
value_type *s);
basic_string&
operator+=(const
basic_string& rhs);
The
operators each append the
operand sequence (page 200)
to the end of the
sequence
controlled by *this, then
return *this.
basic_string::operator=
basic_string&
operator=(value_type
c);
basic_string&
operator=(const
value_type *s);
basic_string&
operator=(const
basic_string& rhs);
207
Chapter
12. Standard C++ Library
Header Files
The
operators each replace the
sequence controlled by *this
with
the operand
sequence
(page 200),
then return *this.
basic_string::operator[]
const_reference
operator[](size_type
pos) const;
reference
operator[](size_type
pos);
The
member functions each return
a reference to the element of
the controlled
sequence
at position pos. If
that position is invalid,
the behavior is
undefined.
basic_string::pointer
typedef
typename allocator_type::pointer
pointer;
The
type is a synonym for allocator_type::pointer.
basic_string::push_back
void
push_back(value_type
c);
The
member function effectively
calls insert(
end(), c).
basic_string::rbegin
const_reverse_iterator
rbegin()
const;
reverse_iterator
rbegin();
The
member function returns a
reverse iterator that points
just beyond the end
of
the
controlled sequence. Hence, it
designates the beginning of
the reverse
sequence.
basic_string::reference
typedef
typename allocator_type::reference
reference;
The
type is a synonym for allocator_type::reference.
basic_string::rend
const_reverse_iterator
rend()
const;
reverse_iterator
rend();
The
member functions each return
a reverse iterator that
points at the first
element
of
the sequence (or just
beyond the end of an empty
sequence). Hence, the
function
designates the end of the
reverse sequence.
basic_string::replace
basic_string&
replace(size_type
p0, size_type n0,
const
value_type *s);
basic_string&
replace(size_type
p0, size_type n0,
const
value_type *s, size_type n);
basic_string&
replace(size_type
p0, size_type n0,
const
basic_string& str);
basic_string&
replace(size_type
p0, size_type n0,
const
basic_string& str, size_type pos,
size_type n);
basic_string&
replace(size_type
p0, size_type n0,
size_type
n, value_type c);
basic_string&
replace(iterator first0,
iterator last0,
const
value_type *s);
basic_string&
replace(iterator first0,
iterator last0,
const
value_type *s, size_type n);
basic_string&
replace(iterator first0,
iterator last0,
const
basic_string& str);
208
Standard
C++ Library
basic_string&
replace(iterator first0,
iterator last0,
size_type
n, value_type c);
template<class
InIt>
basic_string&
replace(iterator first0,
iterator last0,
InIt
first, InIt last);
The
member functions each
replace up to n0
elements
of the controlled
sequence
beginning
with position p0, or the
elements of the controlled
sequence beginning
with
the one pointed to by first, up to
but not including last. The
replacement is
the
operand sequence (page 200)
specified by the remaining
operands. The
function
then returns *this. If InIt is an
integer type in the template
member
function,
the operand sequence first,
last behaves
the same as
(size_type)first,
(value_type)last.
In
this implementation (page 3),
if a translator does not
support member
template
functions,
the template:
template<class
InIt>
basic_string&
replace(iterator first0,
iterator last0,
InIt
first, InIt last);
is
replaced by:
basic_string&
replace(iterator first0,
iterator last0,
const_pointer
first, const_pointer last);
basic_string::reserve
void
reserve(size_type
n = 0);
The
member function ensures that
capacity()
henceforth
returns at least n.
basic_string::resize
void
resize(size_type
n, value_type c = value_type());
The
member function ensures that
size()
henceforth
returns n. If it
must make the
controlled
sequence longer, it appends
elements with value c. To
make the
controlled
sequence shorter, the member
function effectively calls erase(begin()
+
n,
end()).
basic_string::reverse_iterator
typedef
reverse_iterator<iterator>
reverse_iterator;
The
type describes an object
that can serve as a reverse
iterator for the
controlled
sequence.
basic_string::rfind
size_type
rfind(value_type
c, size_type pos = npos)
const;
size_type
rfind(const
value_type *s,
size_type
pos = npos) const;
size_type
rfind(const
value_type *s,
size_type
pos, size_type n = npos)
const;
size_type
rfind(const
basic_string& str,
size_type
pos = npos) const;
The
member functions each find
the last (highest beginning
position) subsequence
in
the controlled sequence,
beginning on or before position
pos, that
matches the
operand
sequence (page 200)
specified by the remaining
operands. If it succeeds,
the
function returns the
position where the matching
subsequence begins.
Otherwise,
it returns npos (page 207).
209
Chapter
12. Standard C++ Library
Header Files
basic_string::size
size_type
size()
const;
The
member function returns the
length of the controlled
sequence.
basic_string::size_type
typedef
T2 size_type;
The
unsigned integer type
describes an object that can
represent the length of
any
controlled
sequence. It is described here as a
synonym for the
implementation-defined
type T2.
basic_string::substr
basic_string
substr(size_type
pos = 0,
size_type
n = npos) const;
The
member function returns an
object whose controlled
sequence is a copy of up
to
n
elements
of the controlled sequence
beginning at position pos.
basic_string::swap
void
swap(basic_string&
str);
The
member function swaps the
controlled sequences between *this
and
str.
If
get_allocator()
== str.get_allocator(),
it does so in constant time, it
throws no
exceptions,
and it invalidates no references,
pointers, or iterators that
designate
elements
in the two controlled sequences.
Otherwise, it performs a number
of
element
assignments and constructor calls
proportional to the number of
elements
in
the two controlled
sequences.
basic_string::traits_type
typedef
T traits_type;
The
type is a synonym for the
template parameter T.
basic_string::value_type
typedef
typename allocator_type::value_type
value_type;
The
type is a synonym for allocator_type::value_type.
char_traits
template<class
E>
class
char_traits
{
public:
typedef
E char_type;
typedef
T1 int_type;
typedef
T2 pos_type;
typedef
T3 off_type;
typedef
T4 state_type;
static
void assign(char_type&
x, const char_type& y);
static
char_type *assign(char_type
*x, size_t n,
char_type
y);
static
bool eq(const
char_type& x,
const
char_type& y);
static
bool lt(const
char_type& x,
const
char_type& y);
static
int compare(const
char_type *x,
const
char_type *y, size_t n);
static
size_t length(const
char_type *x);
210
Standard
C++ Library
static
char_type *copy(char_type
*x,
const
char_type *y, size_t n);
static
char_type *move(char_type
*x,
const
char_type *y, size_t n);
static
const char_type *find(const
char_type *x,
size_t
n, const char_type& y);
static
char_type to_char_type(const
int_type& ch);
static
int_type to_int_type(const
char_type& c);
static
bool eq_int_type(const
int_type& ch1,
const
int_type& ch2);
static
int_type eof();
static
int_type not_eof(const
int_type& ch);
};
The
template class describes various
character
traits for type
E. The
template class
basic_string
(page 197)
as well as several iostreams template
classes, including
basic_ios
(page 88),
use this information to
manipulate elements of type E. Such
an
element
type must not require
explicit construction or destruction. It
must supply a
default
constructor, a copy constructor, and an
assignment operator, with
the
expected
semantics. A bitwise copy
must have the same
effect as an assignment.
Not
all parts of the Standard
C++ Library rely completely
upon the member
functions
of char_traits<E>
to
manipulate an element. Specifically,
formatted input
following
additional operations, also with
the expected
semantics:
v
operator==(E)
and
operator!=(E)
to
compare elements
v
(char)ch
to
convert an element ch
to
its corresponding single-byte
character
code,
or '\0' if
no such code exists
v
(E)c
to
convert a char
value
c
to
its correponding character
code of type E
None
of the member functions of class
char_traits
may
throw exceptions.
char_traits::assign
static
void assign(char_type&
x, const char_type& y);
static
char_type *assign(char_type
*x, size_t n,
char_type
y);
The
first static member function
assigns y
to
x. The
second static member
function
assigns
y
to
each element X[N]
for
N
in
the range [0,
N).
char_traits::char_type
typedef
E char_type;
The
type is a synonym for the
template parameter E.
char_traits::compare
static
int compare(const
char_type *x,
const
char_type *y, size_t n);
The
static member function
compares the sequence of
length n
beginning
at xto
the
sequence
of the same length beginning
at y. The
function returns:
v
a
negative value if the first
differing element in x
(as
determined by eq (page
212))
compares less than the
corresponding element in y
(as
determined by lt
(page
212))
v
zero if
the two compare equal
element by element
v
a
positive value
otherwise
211
Chapter
12. Standard C++ Library
Header Files
char_traits::copy
static
char_type *copy(char_type
*x, const char_type *y,
size_t
n);
The
static member function
copies the sequence of n
elements
beginning at y
to
the
array
beginning at x, then
returns x. The
source and destination must
not overlap.
char_traits::eof
static
int_type eof();
The
static member function
returns a value that
represents end-of-file (such as
EOF
or
WEOF). If the value is also
representable as type E, it
must correspond to no
valid
value
of that type.
char_traits::eq
static
bool eq(const
char_type& x, const char_type&
y);
The
static member function
returns true if x
compares
equal to y.
char_traits::eq_int_type
static
bool eq_int_type(const
int_type& ch1,
const
int_type& ch2);
The
static member function
returns true if ch1
== ch2.
char_traits::find
static
const char_type *find(const
char_type *x,
size_t
n, const char_type& y);
The
static member function
determines the lowest N
in
the range [0,
n) for
which
eq(x[N],
y) is
true. If successful, it returns
x +
N.
Otherwise, it returns a null
pointer.
char_traits::int_type
typedef
T1 int_type;
The
type is (typically) an integer
type T1
that
describes an object that can
represent
any
element of the controlled
sequence as well as the value
returned by eof().
It
must
be possible to type cast a
value of type E
to
int_type
then
back to E
without
altering
the original value.
char_traits::length
static
size_t length(const
char_type *x);
The
static member function
returns the number of
elements N
in
the sequence
beginning
at x
up to
but not including the
element x[N]
which
compares equal to
char_type().
char_traits::lt
static
bool lt(const
char_type& x, const char_type&
y);
The
static member function
returns true if x
compares
less than y.
char_traits::move
static
char_type *move(char_type
*x, const char_type *y,
size_t
n);
212
Standard
C++ Library
The
static member function
copies the sequence of n
elements
beginning at y
to
the
array
beginning at x, then
returns x. The
source and destination may
overlap.
char_traits::not_eof
static
int_type not_eof(const
int_type& ch);
If
!eq_int_type
(page 212)(
eof (page 212)(), ch),
the static member
function
returns
ch.
Otherwise, it returns a value
other than eof().
char_traits::off_type
typedef
T3 off_type;
The
type is a signed integer
type T3
that
describes an object that can
store a byte
offset
involved in various stream positioning
operations. It is typically a
synonym
for
streamoff (page 101),
but in any case it has
essentially the same
properties as
that
type.
char_traits::pos_type
typedef
T2 pos_type;
The
type is an opaque type T2
that
describes an object that can
store all the
information
needed to restore an arbitrary
file-position indicator (page 19)
within a
stream.
It is typically a synonym for streampos
(page 101),
but in any case it
has
essentially
the same properties as that
type.
char_traits::state_type
typedef
T4 state_type;
The
type is an opaque type T4
that
describes an object that can
represent a
conversion
state (page 12).
It is typically a synonym for
mbstate_t, but in any
case
it
has essentially the same
properties as that
type.
char_traits::to_char_type
static
char_type to_char_type(const
int_type& ch);
The
static member function
returns ch,
represented as type E. A
value of ch
that
cannot
be so represented yields an unspecified
result.
char_traits::to_int_type
static
int_type to_int_type(const
char_type& c);
The
static member function
returns ch,
represented as type int_type. It
should
always
be true that to_char_type(to_int_type(c)
== c for
any value of c.
char_traits<char>
template<>
class
char_traits<char>;
The
class is an explicit specialization of
template class char_traits (page 210)
for
elements
of type char,
(so
that it can take advantage
of library functions
that
manipulate
objects of this
type).
char_traits<wchar_t>
template<>
class
char_traits<wchar_t>;
213
Chapter
12. Standard C++ Library
Header Files
The
class is an explicit specialization of
template class char_traits (page 210)
for
elements
of type wchar_t
(so
that it can take advantage
of library functions
that
manipulate
objects of this
type).
getline
template<class
E, class T, class A>
basic_istream<E,
T>& getline(
basic_istream<E,
T>& is,
basic_string<E,
T, A>& str);
template<class
E, class T, class A>
basic_istream<E,
T>& getline(
basic_istream<E,
T>& is,
basic_string<E,
T, A>& str,
E
delim);
The
first function returns getline(is,
str, is.widen('\n')).
The
second function replaces the
sequence controlled by str
with a
sequence of
elements
extracted from the stream is. In
order of testing, extraction
stops:
1.
at
end of file
2.
after
the function extracts an
element that compares equal
to delim, in
which
case
the element is neither put
back nor appended to the
controlled sequence
3.
after
the function extracts str.max_size()
elements,
in which case the
function
calls
setstate(ios_base::failbit).
If
the function extracts no
elements, it calls setstate(failbit). In any
case, it
returns
*this.
operator+
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
const
E *rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
basic_string<E, T, A>&
lhs,
E
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
const
E *lhs,
const
basic_string<E, T, A>&
rhs);
template<class
E, class T, class A>
basic_string<E,
T, A> operator+(
E
lhs,
const
basic_string<E, T, A>&
rhs);
The
functions each overload operator+
to
concatenate two objects of template
class
basic_string
(page 197).
All effectively return basic_string<E,
T,
A>(lhs).append(rhs).
operator!=
template<class
E, class T, class A>
bool
operator!=(
const
basic_string<E, T, A>& lhs,
const
basic_string<E, T, A>& rhs);
214
Standard
C++ Library
template<class
E, class T, class
A>
bool
operator!=(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator!=(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator!=
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
!= 0.
operator==
template<class
E, class T, class
A>
bool
operator==(
const
basic_string<E, T,
A>&
lhs,
const
basic_string<E, T,
A>&
rhs);
template<class
E, class T, class
A>
bool
operator==(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator==(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator==
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
== 0.
operator<
template<class
E, class T, class
A>
bool
operator<(
const
basic_string<E, T,
A>&
lhs,
const
basic_string<E, T,
A>&
rhs);
template<class
E, class T, class
A>
bool
operator<(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator<(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator<
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
< 0.
operator<<
template<class
E, class T, class A>
basic_ostream<E,
T>& operator<<(
basic_ostream<E,
T>& os,
const
basic_string<E, T, A>& str);
The
template function overloads operator<<
to
insert an object str
of
template
class
basic_string (page 197)
into the stream os
The
function effectively
returns
os.write(
str.c_str(), str.size()).
215
Chapter
12. Standard C++ Library
Header Files
operator<=
template<class
E, class T, class
A>
bool
operator<=(
const
basic_string<E, T,
A>&
lhs,
const
basic_string<E, T,
A>&
rhs);
template<class
E, class T, class
A>
bool
operator<=(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator<=(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator<=
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
<= 0.
operator>
template<class
E, class T, class
A>
bool
operator>(
const
basic_string<E, T,
A>&
lhs,
const
basic_string<E, T,
A>&
rhs);
template<class
E, class T, class
A>
bool
operator>(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator>(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator>
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
> 0.
operator>=
template<class
E, class T, class
A>
bool
operator>=(
const
basic_string<E, T,
A>&
lhs,
const
basic_string<E, T,
A>&
rhs);
template<class
E, class T, class
A>
bool
operator>=(
const
basic_string<E, T,
A>&
lhs,
const
E *rhs);
template<class
E, class T, class
A>
bool
operator>=(
const
E *lhs,
const
basic_string<E, T,
A>&
rhs);
The
template functions each
overload operator>=
to
compare two objects of
template
class basic_string (page 197).
All effectively return basic_string<E,
T,
A>(lhs).compare(rhs)
>= 0.
operator>>
template<class
E, class T, class A>
basic_istream<E,
T>& operator>>(
basic_istream<E,
T>& is,
const
basic_string<E, T, A>& str);
216
Standard
C++ Library
The
template function overloads operator>>
to
replace the sequence
controlled by
str
with a
sequence of elements extracted from
the stream is.
Extraction stops:
v
at
end of file
v
after
the function extracts is.width()
elements,
if that value is
nonzero
v
after
the function extracts is.max_size()
elements
v
after
the function extracts an
element c
for
which use_facet<
ctype<E> >(
getloc()).
is( ctype<E>::space, c) is
true, in which case the
character is put
back
If
the function extracts no
elements, it calls setstate(ios_base::failbit). In
any
case,
it calls is.width(0)
and
returns *this.
string
typedef
basic_string<char> string;
The
type describes a specialization of
template class basic_string
specialized
for
elements
of type char.
swap
template<class
T, class A>
void
swap(
basic_string<E,
T, A>& lhs,
basic_string<E,
T, A>& rhs);
The
template function executes lhs.swap(rhs).
wstring
typedef
basic_string<wchar_t> wstring;
The
type describes a specialization of
template class basic_string
for
elements of
type
wchar_t.
<strstream>
namespace
std {
class
strstreambuf;
class
istrstream;
class
ostrstream;
class
strstream;
};
Include
the iostreams (page 7)
standard header <strstream>
to
define several
classes
that support iostreams
operations on sequences stored in an
allocated array
of
char
object.
Such sequences are easily
converted to and from C strings.
strstreambuf
class
strstreambuf
:
public streambuf {
public:
explicit
strstreambuf(streamsize
n = 0);
strstreambuf(void
(*palloc)(size_t),
void
(*pfree)(void *));
strstreambuf(char
*gp, streamsize n,
char
*pp = 0);
strstreambuf(signed
char *gp, streamsize
n,
signed
char *pp = 0);
strstreambuf(unsigned
char *gp, streamsize
n,
217
Chapter
12. Standard C++ Library
Header Files
unsigned
char *pp = 0);
strstreambuf(const
char *gp, streamsize
n);
strstreambuf(const
signed char *gp, streamsize
n);
strstreambuf(const
unsigned char *gp,
streamsize n);
void
freeze(bool
frz = true);
char
*str();
streamsize
pcount();
protected:
virtual
streampos seekoff(streamoff
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
streampos seekpos(streampos
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
virtual
int underflow();
virtual
int pbackfail(int c =
EOF);
virtual
int overflow(int c =
EOF);
};
The
class describes a stream
buffer (page 187)
that
controls the transmission
of
elements
to and from a sequence of elements stored
in a char
array
object.
Depending
on how it is constructed, the object
can be allocated, extended,
and
freed
as necessary to accommodate changes in
the sequence.
An
object of class strstreambuf
stores
several bits of mode
information as its
strstreambuf
mode. These
bits indicate whether the
controlled sequence:
v
has
been allocated,
and hence needs to be freed
eventually
v
is
modifiable
v
is
extendable
by
reallocating storage
v
has
been frozen
and
hence needs to be unfrozen
before the object is
destroyed,
or
freed (if allocated) by an agency
other than the
object
A
controlled sequence that is
frozen cannot be modified or
extended, regardless of
the
state of these separate mode
bits.
The
object also stores pointers
to two functions that control
strstreambuf
allocation.
If these are null pointers,
the object devises its own
method of
allocating
and freeing storage for the
controlled sequence.
strstreambuf::freeze
void
freeze(bool
frz = true);
If
frz
is
true, the function alters
the stored strstreambuf mode
(page 218)
to make
the
controlled sequence frozen.
Otherwise, it makes the
controlled sequence
not
frozen.
strstreambuf::pcount
streamsize
pcount();
The
member function returns a
count of the number of
elements written to
the
controlled
sequence. Specifically, if pptr()
is a
null pointer, the function
returns
zero.
Otherwise, it returns pptr()
-
pbase().
strstreambuf::overflow
virtual
int overflow(int c =
EOF);
218
Standard
C++ Library
If c
!= EOF,
the protected virtual member
function endeavors to insert
the element
(char)c
into
the output buffer (page 187).
It can do so in various
ways:
v
If a
write position (page 188)
is available, it can store
the element into the
write
position
and increment the next
pointer for the output
buffer.
v
If
the stored strstreambuf mode
(page 218)
says the controlled
sequence is
modifiable,
extendable, and not frozen,
the function can make a
write position
available
by allocating new for the output
buffer. (Extending the
output buffer
this
way also extends any
associated input buffer
(page 187).)
If
the function cannot succeed,
it returns EOF.
Otherwise, if c
== EOF it
returns
some
value other than EOF.
Otherwise, it returns c.
strstreambuf::pbackfail
virtual
int pbackfail(int c =
EOF);
The
protected virtual member
function endeavors to put back an
element into the
input
buffer (page 187),
then make it the current
element (pointed to by the
next
pointer).
If
c =
EOF,
the element to push back is
effectively the one already
in the stream
before
the current element.
Otherwise, that element is
replaced by x
= (char)c.
The
function can put back an
element in various
ways:
v
If a
putback position (page 188)
is available, and the element
stored there
compares
equal to x, it can
simply decrement the next
pointer for the input
buffer.
v
If a
putback position is available, and if
the strstreambuf mode (page
218)
says
the
controlled sequence is modifiable,
the function can store
x
into
the putback
position
and decrement the next
pointer for the input
buffer.
If
the function cannot succeed,
it returns EOF.
Otherwise, if c
== EOF it
returns
some
value other than EOF.
Otherwise, it returns c.
strstreambuf::seekoff
virtual
streampos seekoff(streamoff
off,
ios_base::seekdir
way,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class strstreambuf, a
stream position
consists
purely of a stream offset.
Offset zero designates the
first element of the
controlled
sequence.
The
new position is determined as
follows:
v
If
way
== ios_base::beg,
the new position is the
beginning of the stream
plus
off.
v
If
way
== ios_base::cur,
the new position is the
current stream position
plus
off.
v
If
way
== ios_base::end,
the new position is the end
of the stream plus off.
If
which
& ios_base::in is
nonzero and the input buffer
exist, the function
alters
the
next position to read in the
input buffer (page 187).
If which
& ios_base::out
is
also nonzero, way
!= ios_base::cur,
and the output buffer
exists, the function
also
sets the next position to
write to match the next
position to read.
219
Chapter
12. Standard C++ Library
Header Files
Otherwise,
if which
& ios_base::out is
nonzero and the output
buffer exists, the
function
alters the next position to
write in the output buffer
(page 187).
Otherwise,
the positioning operation
fails. For a positioning
operation to succeed,
the
resulting stream position
must lie within the
controlled sequence.
If
the function succeeds in
altering the stream
position(s), it returns the
resultant
stream
position. Otherwise, it fails and
returns an invalid stream
position.
strstreambuf::seekpos
virtual
streampos seekpos(streampos
sp,
ios_base::openmode
which =
ios_base::in
| ios_base::out);
The
protected virtual member
function endeavors to alter
the current positions
for
the
controlled streams. For an
object of class strstreambuf, a
stream position
consists
purely of a stream offset.
Offset zero designates the
first element of the
controlled
sequence. The new position is
determined by sp.
If
which
& ios_base::in is
nonzero and the input buffer
exists, the function
alters
the
next position to read in the
input buffer (page 187).
(If which
& ios_base::out
is
nonzero and the output
buffer exists, the function
also sets the next position
to
write
to match the next position
to read.) Otherwise, if which
& ios_base::out is
nonzero
and the output buffer
exists, the function alters
the next position to
write
in
the output buffer (page 187).
Otherwise, the positioning
operation fails. For
a
positioning
operation to succeed, the
resulting stream position
must lie within
the
controlled
sequence.
If
the function succeeds in
altering the stream
position(s), it returns the
resultant
stream
position. Otherwise, it fails and
returns an invalid stream
position.
strstreambuf::str
char
*str();
The
member function callsfreeze(),
then returns a pointer to
the beginning of the
controlled
sequence. (Note that no
terminating null element exists,
unless you
insert
one explicitly.)
strstreambuf::strstreambuf
explicit
strstreambuf(streamsize
n = 0);
strstreambuf(void
(*palloc)(size_t),
void
(*pfree)(void *));
strstreambuf(char
*gp, streamsize n,
char
*pp = 0);
strstreambuf(signed
char *gp, streamsize
n,
signed
char *pp = 0);
strstreambuf(unsigned
char *gp, streamsize
n,
unsigned
char *pp = 0);
strstreambuf(const
char *gp, streamsize
n);
strstreambuf(const
signed char *gp, streamsize
n);
strstreambuf(const
unsigned char *gp,
streamsize n);
The
first constructor stores a null
pointer in all the pointers
controlling the input
sequence
modifiable and extendable.
220
Standard
C++ Library
The
second constructor behaves
much as the first, except
that it stores palloc
as
the
pointer to the function to
call to allocate storage, and
pfree
as
the pointer to
the
function to call to free
that storage.
The
three constructors:
strstreambuf(char
*gp, streamsize n,
char
*pp = 0);
strstreambuf(signed
char *gp, streamsize
n,
signed
char *pp = 0);
strstreambuf(unsigned
char *gp, streamsize
n,
unsigned
char *pp = 0);
also
behave much as the first,
except that gp
designates
the array object used
to
hold
the controlled sequence.
(Hence, it must not be a null
pointer.) The number
of
elements
N
in
the array is determined as
follows:
v
If
(n
> 0),
then N
is
n.
v
If
(n
== 0),
then N
is
strlen((const
char *)gp).
v
If
(n
< 0),
then N
is
INT_MAX.
If
pp
is a
null pointer, the function
establishes just an input
buffer, by executing:
setg(gp,
gp, gp + N);
Otherwise,
it establishes both input and
output buffers, by
executing:
setg(gp,
gp, pp);
setp(pp,
gp + N);
In
this case, pp
must be
in the interval [gp,
gp + N].
Finally,
the three
constructors:
strstreambuf(const
char *gp, streamsize
n);
strstreambuf(const
signed char *gp, streamsize
n);
strstreambuf(const
unsigned char *gp,
streamsize n);
all
behave the same
as:
streambuf((char
*)gp, n);
except
that the stored mode
makes the controlled
sequence neither modifiable
not
extendable.
strstreambuf::underflow
virtual
int underflow();
The
protected virtual member
function endeavors to extract
the current element c
from
the input buffer (page 187),
then advance the current
stream position, and
return
the element as (int)(unsigned
char)c.
It can do so in only one
way: If a
read
position (page 188)
is available, it takes c
as
the element stored in the
read
position
and advances the next
pointer for the input
buffer.
If
the function cannot succeed,
it returns EOF. Otherwise, it
returns the current
element
in the input stream,
converted as described
above.
istrstream
class
istrstream
:
public istream {
public:
explicit
istrstream(const
char *s);
explicit
istrstream(char
*s);
221
Chapter
12. Standard C++ Library
Header Files
istrstream(const
char *s, streamsize n);
istrstream(char
*s, streamsize n);
strstreambuf
*rdbuf()
const;
char
*str();
};
The
class describes an object that
controls extraction of elements and
encoded
stores
an ojbect of class strstreambuf.
istrstream::istrstream
explicit
istrstream(const
char *s);
explicit
istrstream(char
*s);
istrstream(const
char *s, streamsize n);
istrstream(char
*s, streamsize n);
All
the constructors initialize
the base class by calling istream(sb), where
sb
is
the
stored
object of class strstreambuf. The
first two constructors also
initialize sb
by
calling
strstreambuf((const
char *)s, 0).
The remaining two constructors
instead
call
strstreambuf((const
char *)s, n).
istrstream::rdbuf
strstreambuf
*rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to strstreambuf (page 217).
istrstream::str
char
*str();
The
member function returns rdbuf()->
str().
ostrstream
class
ostrstream
:
public ostream {
public:
ostrstream();
ostrstream(char
*s, streamsize n,
ios_base::openmode
mode = ios_base::out);
strstreambuf
*rdbuf()
const;
void
freeze(bool
frz = true);
char
*str();
streamsize
pcount()
const;
};
The
class describes an object that
controls insertion of elements and
encoded
objects
into a stream buffer of class
strstreambuf. The
object stores an ojbect
of
class
strstreambuf.
ostrstream::freeze
void
freeze(bool
frz = true)
The
member function calls rdbuf()->
freeze(frz).
ostrstream::ostrstream
ostrstream();
ostrstream(char
*s, streamsize n,
ios_base::openmode
mode = ios_base::out);
222
Standard
C++ Library
Both
constructors initialize the
base class by calling ostream(sb), where
sb
is
the
stored
object of class strstreambuf. The
first constructor also
initializes sb
by
calling
strstreambuf(). The
second constructor initializes
the base class one of
two
ways:
v
If
mode
& ios_base::app == 0,
then s
must
designate the first element
of an
array
of n
elements,
and the constructor calls strstreambuf(s,
n, s).
v
Otherwise,
s
must
designate the first element
of an array of n
elements
that
contains
a C string whose first
element is designated by s, and
the constructor
calls
strstreambuf(s,
n, s + strlen(s).
ostrstream::pcount
streamsize
pcount()
const;
The
member function returns rdbuf()->
pcount().
ostrstream::rdbuf
strstreambuf
*rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to strstreambuf (page 217).
ostrstream::str
char
*str();
The
member function returns rdbuf()->
str().
strstream
class
strstream
:
public iostream {
public:
strstream();
strstream(char
*s, streamsize n,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
strstreambuf
*rdbuf()
const;
void
freeze(bool
frz = true);
char
*str();
streamsize
pcount()
const;
};
The
class describes an object that
controls insertion and extraction of
elements and
The
object stores an ojbect of class
strstreambuf.
strstream::freeze
void
freeze(bool
frz = true)
The
member function calls rdbuf()->
freeze(zfrz).
strstream::pcount
streamsize
pcount()
const;
The
member function returns rdbuf()->
pcount().
strstream::strstream
strstream();
strstream(char
*s, streamsize n,
ios_base::openmode
mode =
ios_base::in
| ios_base::out);
223
Chapter
12. Standard C++ Library
Header Files
Both
constructors initialize the
base class by calling streambuf(sb), where
sb
is
the
stored
object of class strstreambuf (page 217).
The first constructor
also initializes
sb
by
calling strstreambuf(). The
second constructor initializes
the base class one
of
two ways:
v
If
mode
& ios_base::app == 0,
then s
must
designate the first element
of an
array
of n
elements,
and the constructor calls strstreambuf(s,
n, s).
v
Otherwise,
s
must
designate the first element
of an array of n
elements
that
contains
a C string whose first
element is designated by s, and
the constructor
calls
strstreambuf(s,
n, s + strlen(s).
strstream::rdbuf
strstreambuf
*rdbuf()
const
The
member function returns the
address of the stored stream
buffer, of type
pointer
to strstreambuf (page 217).
strstream::str
char
*str();
The
member function returns rdbuf()->
str().
<typeinfo>
namespace
std {
class
type_info;
class
bad_cast;
class
bad_typeid;
};
Include
the standard header
<typeinfo>
to
define several types
associated with the
type-identification
operator typeid,
which yields information
about both static and
dynamic
types.
bad_cast
class
bad_cast
:
public exception {
};
The
class describes an exception thrown to
indicate that a dynamic
cast expression,
of
the form:
dynamic_cast<type>(expression)
generated
a null pointer to initialize a reference.
The value returned by what()
is
an
implementation-defined C string. None of
the member functions throw
any
exceptions.
bad_typeid
class
bad_typeid
:
public exception {
};
The
class describes an exception thrown to
indicate that a typeid (page
224)
operator
encountered a null pointer. The
value returned by what()
is
an
implementation-defined
C string. None of the member
functions throw any
exceptions.
224
Standard
C++ Library
type_info
class
type_info
{
public:
virtual
~type_info();
bool
operator==(const
type_info& rhs)
const;
bool
operator!=(const
type_info& rhs)
const;
bool
before(const
type_info& rhs)
const;
const
char *name()
const;
private:
type_info(const
type_info& rhs);
type_info&
operator=(const
type_info& rhs);
};
The
class describes type information
generated within the program
by the
implementation.
Objects of this class effectively
store a pointer to a name
for
the
type,
and an encoded value suitable for
comparing two types for equality
or
collating
order. The
names, encoded values, and
collating order for types
are all
unspecified
and may differ between
program executions.
An
expression of the form typeid
x is
the only
way
to construct a (temporary)
typeinfo
object.
The class has only a private
copy constructor. Since
the
assignment
operator is also private, you
cannot copy or assign
objects of class
typeinfo
either.
type_info::operator!=
bool
operator!=(const
type_info& rhs)
const;
The
function returns !(*this
== rhs).
type_info::operator==
bool
operator==(const
type_info& rhs)
const;
The
function returns a nonzero
value if *this
and
rhs
represent
the same type.
type_info::before
bool
before(const
type_info& rhs)
const;
The
function returns a nonzero
value if *this
precedes
rhs
in
the collating
order
for
types.
type_info::name
const
char *name()
const;
The
function returns a C string
which specifies the name
of
the type.
<valarray>
valarray<bool>
(page 247)
225
Chapter
12. Standard C++ Library
Header Files
namespace
std {
class
slice;
class
gslice;
//
TEMPLATE CLASSES
template<class
T>
class
valarray;
template<class
T>
class
slice_array;
template<class
T>
class
gslice_array;
template<class
T>
class
mask_array;
template<class
T>
class
indirect_array;
//
TEMPLATE FUNCTIONS
template<class
T>
valarray<T>
operator*(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator*(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator*(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator/(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator/(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator/(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator%(const
valarray<T>&
x,
const
vararray<T>& y);
template<class
T>
valarray<T>
operator%(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator%(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator+(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator+(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator+(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator-(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator-(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator-(const
T&
x,
const
valarray<T>& y);
template<class
T>
226
Standard
C++ Library
valarray<T>
operator^(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator^(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator^(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator&(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator&(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator&(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator|(const
valarray<T>&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator|(const
valarray<T>
x,
const
T& y);
template<class
T>
valarray<T>
operator|(const
T&
x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator<<(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator<<(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator<<(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator>>(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator>>(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator>>(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator&&(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator&&(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator&&(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator||(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator||(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator||(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator==(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
227
Chapter
12. Standard C++ Library
Header Files
valarray<bool>
operator==(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator==(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator!=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator!=(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator!=(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator<(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator<(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator<(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>=(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator>=(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator>(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator<=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator<=(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator<=(const
T& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
abs(const
valarray<T>& x);
template<class
T>
valarray<T>
acos(const
valarray<T>& x);
template<class
T>
valarray<T>
asin(const
valarray<T>& x);
template<class
T>
valarray<T>
atan(const
valarray<T>& x);
template<class
T>
valarray<T>
atan2(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
atan2(const
valarray<T> x, const T&
y);
template<class
T>
valarray<T>
atan2(const
T& x, const valarray<T>&
y);
template<class
T>
valarray<T>
cos(const
valarray<T>& x);
228
Standard
C++ Library
template<class
T>
valarray<T>
cosh(const
valarray<T>& x);
template<class
T>
valarray<T>
exp(const
valarray<T>& x);
template<class
T>
valarray<T>
log(const
valarray<T>& x);
template<class
T>
valarray&tt;T>
log10(const
valarray<T>& x);
template<class
T>
valarray<T>
pow(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
pow(const
valarray<T> x, const T&
y);
template<class
T>
valarray<T>
pow(const
T& x, const valarray<T>&
y);
template<class
T>
valarray<T>
sin(const
valarray<T>& x);
template<class
T>
valarray<T>
sinh(const
valarray<T>& x);
template<class
T>
valarray<T>
sqrt(const
valarray<T>& x);
template<class
T>
valarray<T>
tan(const
valarray<T>& x);
template<class
T>
valarray<T>
tanh(const
valarray<T>& x);
};
Include
the standard header
<valarray>
to
define the template class
valarray (page
240)
and numerous supporting template
classes and functions. These
template
classes
and functions are permitted
unusual latitude, in the
interest of improved
performance.
Specifically, any function
returning valarray<T>
may
return an object
of
some other type T'.
In that case, any function
that accepts one or
more
arguments
of type valarray<T>
must
have overloads that accept
arbitrary
combinations
of those arguments, each
replaced with an argument of type
T'.
(Put
simply,
the only way you can detect
such a substitution is to go looking for
it.)
abs
template<class
T>
valarray<T>
abs(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the absolute value of x[I].
acos
template<class
T>
valarray<T>
acos(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the arccosine of x[I].
asin
template<class
T>
valarray<T>
asin(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the arcsine of x[I].
229
Chapter
12. Standard C++ Library
Header Files
atan
template<class
T>
valarray<T>
atan(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the arctangent of x[I].
atan2
template<class
T>
valarray<T>
atan2(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
atan2(const
valarray<T> x, const T&
y);
template<class
T>
valarray<T>
atan2(const
T& x, const valarray<T>&
y);
The
first template function
returns an object of class valarray<T>, each
of whose
elements
I
is
the arctangent of x[I]
/ y[I].
The second template function
stores in
element
I
the
arctangent of x[I]
/ y.
The third template function
stores in element
I
the
arctangent of x
/ y[I].
cos
template<class
T>
valarray<T>
cos(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the cosine of x[I].
cosh
template<class
T>
valarray<T>
cosh(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the hyperbolic cosine of x[I].
exp
template<class
T>
valarray<T>
exp(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the exponential of x[I].
gslice
class
gslice
{
public:
gslice();
gslice(size_t
st,
const
valarray<size_t> len,
const
valarray<size_t> str);
size_t
start()
const;
const
valarray<size_t> size()
const;
const
valarray<size_t> stride()
const;
};
230
Standard
C++ Library
The
class stores the parameters
that characterize a gslice_array
(page 231)
when an
object
of class gslice
appears
as a subscript for an object of class valarray<T>.
The
stored
values include:
v
a
starting
index
v
a
length
vector of class valarray<size_t>
v
a
stride
vector of class valarray<size_t>
The
two vectors must have the
same length.
gslice::gslice
gslice();
gslice(size_t
st,
const
valarray<size_t> len,
const
valarray<size_t> str);
The
default constructor stores
zero for the starting index,
and zero-length vectors
for
the length and stride
vectors. The second
constructor stores st
for
the starting
index,
len
for
the length vector, and str
for
the stride vector.
gslice::size
const
valarray<size_t> size()
const;
The
member function returns the
stored length vector.
gslice::start
size_t
start()
const;
The
member function returns the
stored starting
index.
gslice::stride
const
valarray<size_t> stride()
const;
The
member function returns the
stored stride vector.
gslice_array
template<class
T>
class
gslice_array
{
public:
typedef
T value_type;
void
operator=(const
valarray<T> x) const;
void
operator=(const
T& x);
void
operator*=(const
valarray<T> x) const;
void
operator/=(const
valarray<T> x) const;
void
operator%=(const
valarray<T> x) const;
void
operator+=(const
valarray<T> x) const;
void
operator-=(const
valarray<T> x) const;
void
operator^=(const
valarray<T> x) const;
void
operator&=(const
valarray<T> x) const;
void
operator|=(const
valarray<T> x) const;
void
operator<<=(const
valarray<T> x) const;
void
operator>>=(const
valarray<T> x) const;
private:
void
gslice_array(); //
not defined
void
gslice_array(
const
gslice_array&); // not
defined
gslice_array&
operator=(
const
gslice_array&); // not
defined
};
231
Chapter
12. Standard C++ Library
Header Files
The
class describes an object that
stores a reference to an object
x
of
class
valarray<T>, along
with an object gs
of class
gslice
which
describes the
sequence
of
elements to select from the valarray<T>
object.
You
construct a gslice_array<T>
object
only by writing an expression of
the form
x[gs]. The
member functions of class gslice_array
then
behave like the
corresponding
function signatures defined for
valarray<T>, except
that only the
sequence
of selected elements is
affected.
The
sequence is determined as follows.
For a length vector gs.size()
of
length N,
construct
the index vector valarray<size_t>
idx(0, N). This
designates the
initial
element
of the sequence, whose index
k
within
x
is
given by the mapping:
k
= start;
for
(size_t i = 0; i < gs.size()[i];
++i)
k
+= idx[i] * gs.stride()[i];
The
successor to an index vector
value is given by:
for
(size_t i = N; 0 < i--; )
if
(++idx[i] < gs.size()[i])
break;
else
idx[i]
= 0;
For
example:
const
size_t lv[] = {2, 3};
const
size_t dv[] = {7, 2};
const
valarray<size_t> len(lv, 2), str(dv, 2);
//
x[gslice(3, len, str)] selects elements
with
//
indices
3, 5, 7, 10, 12, 14
indirect_array
template<class
T>
class
indirect_array
{
public:
typedef
T value_type;
void
operator=(const
valarray<T> x) const;
void
operator=(const
T& x);
void
operator*=(const
valarray<T> x) const;
void
operator/=(const
valarray<T> x) const;
void
operator%=(const
valarray<T> x) const;
void
operator+=(const
valarray<T> x) const;
void
operator-=(const
valarray<T> x) const;
void
operator^=(const
valarray<T> x) const;
void
operator&=(const
valarray<T> x) const;
void
operator|=(const
valarray<T> x) const;
void
operator<<=(const
valarray<T> x) const;
void
operator>>=(const
valarray<T> x) const;
private:
private:
void
indirect_array(); //
not defined
void
indirect_array(
const
indirect_array&); // not
defined
indirect_array&
operator=(
const
indirect_array&); // not
defined
};
The
class describes an object that
stores a reference to an object
x
of
class
valarray<T>, along
with an object xa
of class
valarray<size_t>
which
describes the
sequence
of elements to select from the
valarray<T>
object.
232
Standard
C++ Library
You
construct an indirect_array<T>
object
only by writing an expression of
the
form
x[xa]. The
member functions of class indirect_array
then
behave like the
corresponding
function signatures defined for
valarray<T>, except
that only the
sequence
of selected elements is
affected.
The
sequence consists of xa.size()
elements,
where element i
becomes
the index
xa[i]
within
x. For
example:
const
size_t vi[] = {7, 5, 2, 3, 8};
//
x[valarray<size_t>(vi, 5)] selects
elements with
//
indices
7, 5, 2, 3, 8
log
template<class
T>
valarray<T>
log(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the natural logarithm of x[I].
log10
template<class
T>
valarray<T>
log10(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the base-10 logarithm of x[I].
mask_array
template<class
T>
class
mask_array
{
public:
typedef
T value_type;
void
operator=(const
valarray<T> x) const;
void
operator=(const
T& x);
void
operator*=(const
valarray<T> x) const;
void
operator/=(const
valarray<T> x) const;
void
operator%=(const
valarray<T> x) const;
void
operator+=(const
valarray<T> x) const;
void
operator-=(const
valarray<T> x) const;
void
operator^=(const
valarray<T> x) const;
void
operator&=(const
valarray<T> x) const;
void
operator|=(const
valarray<T> x) const;
void
operator<<=(const
valarray<T> x) const;
void
operator>>=(const
valarray<T> x) const;
private:
void
mask_array(); //
not defined
void
mask_array(
const
mask_array&); // not
defined
gslice_array&
operator=(
const
mask_array&); // not
defined
};
The
class describes an object that
stores a reference to an object
x
of
class
valarray<T>, along
with an object ba
of class
valarray<bool>
which
describes the
sequence
of elements to select from the
valarray<T>
object.
You
construct a mask_array<T>
object
only by writing an expression of
the form
x[xa]. The
member functions of class mask_array
then
behave like the
corresponding
function signatures defined for
valarray<T>, except
that only the
sequence
of selected elements is
affected.
233
Chapter
12. Standard C++ Library
Header Files
The
sequence consists of at most ba.size()
elements.
An element j
is
included
only
if ba[j]
is
true. Thus, there are as
many elements in the
sequence as there are
true
elements in ba. If i is the
index of the lowest true
element in ba, then
x[i]
is
element
zero in the selected
sequence. For
example:
const
bool vb[] = {false, false, true, true,
false, true};
//
x[valarray<bool>(vb, 56] selects
elements with
//
indices
2, 3, 5
operator!=
template<class
T>
valarray<bool>
operator!=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator!=(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator!=(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
!= y[I].
The second template operator
stores in
element
I
x[I] != y. The
third template operator
stores in element I
x != y[I].
operator%
template<class
T>
valarray<T>
operator%(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator%(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator%(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
% y[I].
The second template operator
stores in element I
x[I] %
y. The
third template operator
stores in element I
x % y[I].
operator&
template<class
T>
valarray<T>
operator&(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator&(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator&(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
& y[I].
The second template operator
stores in element I
x[I] &
y. The
third template operator
stores in element I
x & y[I].
operator&&
template<class
T>
valarray<bool>
operator&&(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator&&(const
valarray<T> x,
234
Standard
C++ Library
const
T& y);
template<class
T>
valarray<bool>
operator&&(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<bool>, each
of
whose
elements I
is
x[I]
&& y[I].
The second template operator
stores in element
I
x[I] && y.
The third template operator
stores in element I
x && y[I].
operator>
template<class
T>
valarray<bool>
operator>(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator>(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
> y[I]. The
second template operator
stores in
element
I
x[I] > y.
The third template operator
stores in element I
x > y[I].
operator>>
template<class
T>
valarray<T>
operator>>(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator>>(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator>>(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
>> y[I].
The second template operator
stores in element I
x[I]
>>
y.
The third template operator
stores in element I
x >> y[I].
operator>=
template<class
T>
valarray<bool>
operator>=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator>=(const
valarray<T> x, const T&
y);
template<class
T>
valarray<bool>
operator>=(const
T& x, const valarray<T>&
y);
The
first template operator
returns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
>= y[I].
The second template operator
stores in
element
I
x[I] >= y.
The third template operator
stores in element I
x >= y[I].
operator<
template<class
T>
valarray<bool>
operator<(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
235
Chapter
12. Standard C++ Library
Header Files
valarray<bool>
operator<(const
valarray<T> x, const T&
y);
template<class
T>
valarray<bool>
operator<(const
T& x, const valarray<T>&
y);
The
first template operator
returns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
< y[I]. The
second template operator
stores in
element
I
x[I] < y.
The third template operator
stores in element I
x < y[I].
operator<<
template<class
T>
valarray<T>
operator<<(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator<<(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator<<(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
<< y[I].
The second template operator
stores in element I
x[I]
<<
y.
The third template operator
stores in element I
x << y[I].
operator<=
template<class
T>
valarray<bool>
operator<=(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator<=(const
valarray<T> x, const T&
y);
template<class
T>
valarray<bool>
operator<=(const
T& x, const valarray<T>&
y);
The
first template operator
retrrns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
<= y[I].
The second template operator
stores in
element
I
x[I] <= y.
The third template operator
stores in element I
x <= y[I].
operator*
template<class
T>
valarray<T>
operator*(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator*(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator*(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
* y[I].
The second template operator
stores in element I
x[I] *
y. The
third template operator
stores in element I
x * y[I].
operator+
template<class
T>
valarray<T>
operator+(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator+(const
valarray<T> x,
236
Standard
C++ Library
const
T& y);
template<class
T>
valarray<T>
operator+(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
+ y[I].
The second template operator
stores in element I
x[I] +
y. The
third template operator
stores in element I
x + y[I].
operator-
template<class
T>
valarray<T>
operator-(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator-(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator-(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
- y[I].
The second template operator
stores in element I
x[I] -
y. The
third template operator
stores in element I
x - y[I].
operator/
template<class
T>
valarray<T>
operator/(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator/(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator/(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
/ y[I].
The second template operator
stores in element I
x[I] /
y. The
third template operator
stores in element I
x / y[I].
operator==
template<class
T>
valarray<bool>
operator==(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator==(const
valarray<T> x, const T&
y);
template<class
T>
valarray<bool>
operator==(const
T& x const valarray<T>&
y);
The
first template operator
returns an object of class
valarray<bool> (page 247),
each
of whose elements I
is
x[I]
== y[I].
The second template operator
stores in
element
I
x[I] == y. The
third template operator
stores in element I
x == y[I].
operator^
template<class
T>
valarray<T>
operator^(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator^(const
valarray<T> x,
237
Chapter
12. Standard C++ Library
Header Files
const
T& y);
template<class
T>
valarray<T>
operator^(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
^ y[I].
The second template operator
stores in element I
x[I] ^
y. The
third template operator
stores in element I
x ^ y[I].
operator|
template<class
T>
valarray<T>
operator|(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
operator|(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<T>
operator|(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
| y[I].
The second template operator
stores in element I
x[I] |
y. The
third template operator
stores in element I
x | y[I].
operator||
template<class
T>
valarray<bool>
operator||(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<bool>
operator||(const
valarray<T> x,
const
T& y);
template<class
T>
valarray<bool>
operator||(const
T& x,
const
valarray<T>& y);
The
first template operator
returns an object of class valarray<bool>, each
of
whose
elements I
is
x[I]
|| y[I].
The second template operator
stores in element
I
x[I] || y. The
third template operator
stores in element I
x || y[I].
pow
template<class
T>
valarray<T>
pow(const
valarray<T>& x,
const
valarray<T>& y);
template<class
T>
valarray<T>
pow(const
valarray<T> x, const T&
y);
template<class
T>
valarray<T>
pow(const
T& x, const valarray<T>&
y);
The
first template function
returns an object of class valarray<T>, each
of whose
elements
I
is
x[I]
raised
to the y[I]
power.
The second template function
stores in
element
I
x[I] raised
to the y
power.
The third template function
stores in element
I
x raised
to the y[I]
power.
sin
template<class
T>
valarray<T>
sin(const
valarray<T>& x);
238
Standard
C++ Library
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the sine of x[I].
sinh
template<class
T>
valarray<T>
sinh(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the hyperbolic sine of x[I].
slice
class
slice
{
public:
slice();
slice(size_t
st, size_t len, size_t str);
size_t
start()
const;
size_t
size()
const;
size_t
stride()
const;
};
The
class stores the parameters
that characterize a slice_array
(page 239)
when an
object
of class slice
appears
as a subscript for an object of class valarray<T>.
The
stored
values include:
v
a
starting
index
v
a
total
length
v
a
stride,
or distance between subsequent
indices
slice::slice
slice();
slice(size_t
st,
const
valarray<size_t> len, const
valarray<size_t> str);
The
default constructor stores
zeros for the starting
index, total length, and
stride.
The
second constructor stores st for the
starting index, len
for
the total length, and
str
for
the stride.
slice::size
size_t
size()
const;
The
member function returns the
stored total length.
slice::start
size_t
start()
const;
The
member function returns the
stored starting
index.
slice::stride
size_t
stride()
const;
The
member function returns the
stored stride.
slice_array
template<class
T>
class
slice_array
{
public:
typedef
T value_type;
239
Chapter
12. Standard C++ Library
Header Files
void
operator=(const
valarray<T> x) const;
void
operator=(const
T& x);
void
operator*=(const
valarray<T> x) const;
void
operator/=(const
valarray<T> x) const;
void
operator%=(const
valarray<T> x) const;
void
operator+=(const
valarray<T> x) const;
void
operator-=(const
valarray<T> x) const;
void
operator^=(const
valarray<T> x) const;
void
operator&=(const
valarray<T> x) const;
void
operator|=(const
valarray<T> x) const;
void
operator<<=(const
valarray<T> x) const;
void
operator>>=(const
valarray<T> x) const;
private:
void
slice_array(); //
not defined
void
slice_array(
const
slice_array&); // not
defined
slice_array&
operator=(
const
slice_array&); // not
defined
};
The
class describes an object that
stores a reference to an object
x
of
class
valarray<T>, along
with an object sl
of class
slice (page 239)
which describes
the
sequence
of elements to select from the
valarray<T>
object.
You
construct a slice_array<T>
object
only by writing an expression of
the form
x[sl]
(page 244).
The member functions of class
slice_array
then
behave like the
corresponding
function signatures defined for
valarray<T>, except
that only the
sequence
of selected elements is
affected.
The
sequence consists of sl.size()
elements,
where element i
becomes
the index
sl.start()
+ i * sl.stride() within
x. For
example:
//
x[slice(2, 5, 3)] selects elements
with
//
indices
2, 5, 8, 11, 14
sqrt
template<class
T>
valarray<T>
sqrt(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the square root of x[I].
tan
template<class
T>
valarray<T>
tan(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the tangent of x[I].
tanh
template<class
T>
valarray<T>
tanh(const
valarray<T>& x);
The
template function returns an
object of class valarray<T>, each
of whose
elements
I
is
the hyperbolic tangent of x[I].
valarray
240
Standard
C++ Library
value_type
(page 247)
template<class
T>
class
valarray
{
public:
typedef
T value_type;
valarray();
explicit
valarray(size_t
n);
valarray(const
T& val, size_t n));
valarray(const
T *p, size_t n);
valarray(const
slice_array<T>& sa);
valarray(const
gslice_array<T>& ga);
valarray(const
mask_array<T>& ma);
valarray(const
indirect_array<T>& ia);
valarray<T>&
operator=(const
valarray<T>& va);
valarray<T>&
operator=(const
T& x);
valarray<T>&
operator=(const
slice_array<T>& sa);
valarray<T>&
operator=(const
gslice_array<T>& ga);
valarray<T>&
operator=(const
mask_array<T>& ma);
valarray<T>&
operator=(const
indirect_array<T>& ia);
T
operator[](size_t
n) const;
T&
operator[](size_t
n);
valarray<T>
operator[](slice
sa) const;
slice_array<T>
operator[](slice
sa);
valarray<T>
operator[](const
gslice& ga) const;
gslice_array<T>
operator[](const
gslice& ga);
valarray<T>
operator[](const
valarray<bool>& ba)
const;
mask_array<T>
operator[](const
valarray<bool>& ba);
valarray<T>
operator[](const
valarray<size_t>& xa)
const;
indirect_array<T>
operator[](const
valarray<size_t>& xa);
valarray<T>
operator+();
valarray<T>
operator-();
valarray<T>
operator~();
valarray<bool>
operator!();
valarray<T>&
operator*=(const
valarray<T>& x);
valarray<T>&
operator*=(const
T& x);
valarray<T>&
operator/=(const
valarray<T>& x);
valarray<T>&
operator/=(const
T& x);
valarray<T>&
operator%=(const
valarray<T>& x);
valarray<T>&
operator%=(const
T& x);
valarray<T>&
operator+=(const
valarray<T>& x);
valarray<T>&
operator+=(const
T& x);
valarray<T>&
operator-=(const
valarray<T>& x);
valarray<T>&
operator-=(const
T& x);
valarray<T>&
operator^=(const
valarray<T>& x);
valarray<T>&
operator^=(const
T& x);
valarray<T>&
operator&=(const
valarray<T>& x);
valarray<T>&
operator&=(const
T& x);
valarray<T>&
operator|=(const
valarray<T>& x);
valarray<T>&
operator|=(const
T& x);
valarray<T>&
operator<<=(const
valarray<T>& x);
valarray<T>&
operator<<=(const
T& x);
valarray<T>&
operator>>=(const
valarray<T>& x);
valarray<T>&
operator>>=(const
T& x);
operator
T *();
operator
const T *()
const;
size_t
size()
const;
T
sum()
const;
T
max()
const;
241
Chapter
12. Standard C++ Library
Header Files
T
min()
const;
valarray<T>
shift(int n)
const;
valarray<T>
cshift(int n)
const;
valarray<T>
apply(T fn(T))
const;
valarray<T>
apply(T
fn(const T&)) const;
void
resize(size_t
n);
void
resize(size_t
n, const T& c);
};
The
template class describes an object
that controls a varying-length
sequence of
elements
of type T. The
sequence is stored as an array of
T. It
differs from template
class
vector (page 404)
in two important ways:
v
It
defines numerous arithmetic
operations between corresponding
elements of
valarray<T>
objects
of the same type and length,
such as x
= cos(y) + sin(z).
v
It
defines a variety of interesting
ways to subscript a valarray<T>
object,
by
overloading
operator[] (page 244).
An
object of class T:
v
has a
public default constructor,
destructor, copy constructor, and
assignment
operator
-- with conventional behavior
v
defines
the arithmetic operators and
math functions, as needed,
that are defined
for
the floating-point types -- with
conventional behavior
In
particular, no subtle differences
may exist between copy
construction and
default
construction followed by assignment. And
none of the operations
on
objects
of class T
may
throw exceptions.
valarray::apply
valarray<T>
apply(T fn(T))
const;
valarray<T>
apply(T
fn(const T&)) const;
The
member function returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
fn((*this)[I]).
valarray::cshift
valarray<T>
cshift(int n)
const;
The
member function returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
(*this)[(I + n) %
size()].
Thus, if element zero is
taken
as
the leftmost element, a
positive value of n
shifts
the elements circularly left
n
places.
valarray::max
T
max()
const;
The
member function returns the
value of the largest element
of *this, which
must
have
nonzero length. If the
length is greater than one,
it compares values by
applying
operator<
between
pairs of corresponding elements of class
T.
valarray::min
T
min()
const;
The
member function returns the
value of the smallest
element of *this,
which
must
have nonzero length. If the
length is greater than one,
it compares values by
applying
operator<
between
pairs of elements of class T.
242
Standard
C++ Library
valarray::operator
T *
operator
T *();
operator
const T *()
const;
Both
member functions return a
pointer to the first element
of the controlled
array,
which
must have at least one
element.
valarray::operator!
valarray<bool>
operator!();
The
member operator returns an
object of class valarray<bool>, of
length size(),
each
of whose elements I
is
!(*this).
valarray::operator%=
valarray<T>&
operator%=(const
valarray<T>& x);
valarray<T>&
operator%=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] %
x[I].
It
returns
*this.
valarray::operator&=
valarray<T>&
operator&=(const
valarray<T>& x);
valarray<T>&
operator&=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] &
x[I].
It
returns
*this.
valarray::operator>>=
valarray<T>&
operator>>=(const
valarray<T>& x);
valarray<T>&
operator>>=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I]
>> x[I].
It
returns
*this.
valarray::operator<<=
valarray<T>&
operator<<=(const
valarray<T>& x);
valarray<T>&
operator<<=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I]
<< x[I].
It
returns
*this.
valarray::operator*=
valarray<T>&
operator*=(const
valarray<T>& x);
valarray<T>&
operator*=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] *
x[I].
It
returns
*this.
valarray::operator+
valarray<T>
operator+();
The
member operator returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
(*this)[I].
valarray::operator+=
valarray<T>&
operator+=(const
valarray<T>& x);
valarray<T>&
operator+=(const
T& x);
243
Chapter
12. Standard C++ Library
Header Files
The
member operator replaces
each element I
of
*this
with
(*this)[I] +
x[I].
It
returns
*this.
valarray::operator-
valarray<T>
operator-();
The
member operator returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
-(*this)[I].
valarray::operator-=
valarray<T>&
operator-=(const
valarray<T>& x);
valarray<T>&
operator-=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] -
x[I].
It
returns
*this.
valarray::operator/=
valarray<T>&
operator/=(const
valarray<T>& x);
valarray<T>&
operator/=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] /
x[I].
It
returns
*this.
valarray::operator=
valarray<T>&
operator=(const
valarray<T>& va);
valarray<T>&
operator=(const
T& x);
valarray<T>&
operator=(const
slice_array<T>& sa);
valarray<T>&
operator=(const
gslice_array<T>& ga);
valarray<T>&
operator=(const
mask_array<T>& ma);
valarray<T>&
operator=(const
indirect_array<T>& ia);
The
first member operator
replaces the controlled
sequence with a copy of
the
sequence
controlled by va. The
second member operator
replaces each element
of
the
controlled sequence with a copy of
x. The
remaining member operators
replace
those
elements of the controlled
sequence selected by their
arguments, which are
generated
only by operator[] (page 244).
If the value of a member in
the
replacement
controlled sequence depends on a
member in the initial
controlled
sequence,
the result is
undefined.
If
the length of the controlled
sequence changes, the result
is generally undefined.
In
this implementation (page 3),
however, the effect is
merely to invalidate
any
pointers
or references to elements in the
controlled sequence.
valarray::operator[]
T&
operator[](size_t
n);
slice_array<T>
operator[](slice
sa);
gslice_array<T>
operator[](const
gslice& ga);
mask_array<T>
operator[](const
valarray<bool>& ba);
indirect_array<T>
operator[](const
valarray<size_t>& xa);
T
operator[](size_t
n) const;
valarray<T>
operator[](slice
sa) const;
valarray<T>
operator[](const
gslice& ga) const;
valarray<T>
operator[](const
valarray<bool>& ba)
const;
valarray<T>
operator[](const
valarray<size_t>& xa)
const;
The
member operator is overloaded to
provide several ways to
select sequences of
elements
from among those controlled by
*this. The
first group of five
member
operators
work in conjunction with various
overloads of operator= (page 244)
(and
244
Standard
C++ Library
other
assigning operators) to allow
selective replacement (slicing) of
the controlled
sequence.
The selected elements must
exist.
The
first member operator
selects element n. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
v0[3]
= 'A';
//
v0 == valarray<char>("abcAefghijklmnop",
16)
The
second member operator
selects those elements of
the controlled
sequence
designated
by sa. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
valarray<char>
v1("ABCDE", 5);
v0[slice(2,
5, 3)] = v1;
//
v0 == valarray<char>("abAdeBghCjkDmnEp",
16)
The
third member operator
selects those elements of
the controlled
sequence
designated
by ga. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
valarray<char>
v1("ABCDEF", 6);
const
size_t lv[] = {2, 3};
const
size_t dv[] = {7, 2};
const
valarray<size_t> len(lv, 2), str(dv, 2);
v0[gslice(3,
len, str)] = v1;
//
v0 == valarray<char>("abcAeBgCijDlEnFp",
16)
The
fourth member operator
selects those elements of
the controlled
sequence
designated
by ba. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
valarray<char>
v1("ABC", 3);
const
bool vb[] = {false, false, true, true,
false, true};
v0[valarray<bool>(vb,
6)] = v1;
//
v0 == valarray<char>("abABeCghijklmnop",
16)
The
fifth member operator
selects those elements of
the controlled
sequence
designated
by ia. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
valarray<char>
v1("ABCDE", 5);
const
size_t vi[] = {7, 5, 2, 3, 8};
v0[valarray<size_t>(vi,
5)] = v1;
//
v0 == valarray<char>("abCDeBgAEjklmnop",
16)
The
second group of five member
operators each construct an
object that
represents
the value(s) selected. The
selected elements must
exist.
The
sixth member operator
returns the value of element
n. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
//
v0[3] returns 'd'
The
seventh member operator
returns an object of class valarray<T>
containing
those
elements of the controlled
sequence designated by sa. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
//
v0[slice(2, 5, 3)] returns
valarray<char>("cfilo", 5)
The
eighth member operator
selects those elements of
the controlled
sequence
designated
by ga. For
example:
245
Chapter
12. Standard C++ Library
Header Files
valarray<char>
v0("abcdefghijklmnop", 16);
const
size_t lv[] = {2, 3};
const
size_t dv[] = {7, 2};
const
valarray<size_t> len(lv, 2), str(dv, 2);
//
v0[gslice(3, len, str)] returns
//
valarray<char>("dfhkmo",
6)
The
ninth member operator
selects those elements of
the controlled
sequence
designated
by ba. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
const
bool vb[] = {false, false, true, true,
false, true};
//
v0[valarray<bool>(vb, 6)]
returns
//
valarray<char>("cdf",
3)
The
last member operator selects
those elements of the
controlled sequence
designated
by ia. For
example:
valarray<char>
v0("abcdefghijklmnop", 16);
const
size_t vi[] = {7, 5, 2, 3, 8};
//
v0[valarray<size_t>(vi, 5)]
returns
//
valarray<char>("hfcdi",
5)
valarray::operator^=
valarray<T>&
operator^=(const
valarray<T>& x);
valarray<T>&
operator^=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] ^
x[I].
It
returns
*this.
valarray::operator|=
valarray<T>&
operator|=(const
valarray<T>& x);
valarray<T>&
operator|=(const
T& x);
The
member operator replaces
each element I
of
*this
with
(*this)[I] |
x[I].
It
returns
*this.
valarray::operator~
valarray<T>
operator~();
The
member operator returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
~(*this)[I].
valarray::resize
void
resize(size_t
n);
void
resize(size_t
n, const T& c);
The
member functions both ensure
that size()
henceforth
returns n. If it
must
make
the controlled sequence
longer, the first member
function appends
elements
with
value T(), while
the second member function
appends elements with value c.
To
make the controlled sequence
shorter, both member
functions remove and
delete
elements with subscripts in the
range [n,
size()).
Any pointers or
references
to elements in the controlled
sequence are
invalidated.
valarray::shift
valarray<T>
shift(int n)
const;
246
Standard
C++ Library
The
member function returns an
object of class valarray<T>, of
length size(),
each
of
whose elements I
is
either (*this)[I
+ n], if
I +
n is a
valid subscript, or T().
Thus,
if element zero is taken as
the leftmost element, a
positive value of n
shifts
the
elements left n
places,
with zero fill.
valarray::size
size_t
size()
const;
The
member function returns the
number of elements in the
array.
valarray::sum
T
sum()
const;
The
member function returns the
sum of all elements of *this, which
must have
nonzero
length. If the length is
greater than one, it adds
values to the sum by
applying
operator+=
between
pairs of elements of class T.
valarray::valarray
valarray();
explicit
valarray(size_t
n);
valarray(const
T& val, size_t n));
valarray(const
T *p, size_t n);
valarray(const
slice_array<T>& sa);
valarray(const
gslice_array<T>& ga);
valarray(const
mask_array<T>& ma);
valarray(const
indirect_array<T>& ia);
The
first (default) constructor
initializes the object to an
empty array. The
next
three
constructors each initialize
the object to an array of n elements
as follows:
v
For
explicit
valarray(size_t n),
each element is initialized with
the default
constructor.
v
For
valarray(const
T& val, size_t n)),
each element is initialized with
val.
v
For
valarray(const
T *p, size_t n),
the element at position I is
initialized
with
p[I].
Each
of the remaining constructors
initializes the object to a valarray<T>
object
determined
by the argument.
valarray::value_type
typedef
T value_type;
The
type is a synonym for the
template parameter T.
valarray<bool>
class
valarray<bool>
The
type is a specialization of template
class valarray (page 240),
for elements of
type
bool.
247
Chapter
12. Standard C++ Library
Header Files
248
Standard
C++ Library
Table of Contents:
- C++ Library
- C++ Library Overview:Using C++ Library Headers, Iostreams Conventions
- Characters:Escape Sequences, Multibyte Characters, Wide-Character Encoding
- Expressions
- Files and Streams:Text and Binary Streams, Controlling Streams, Stream States
- Indefinite Integrals of Logarithmic Functions:Combinations of Logarithms and Polynomials, The Logarithm
- Formatted Input:Scan Formats, Scan Functions, Scan Conversion Specifiers
- Formatted Output:Print Formats, Print Functions, Print Conversion Specifiers
- STL Conventions:Iterator Conventions, Algorithm Conventions
- Containers:Cont::const_reference, difference_type, reverse_iterator
- Preprocessing
- Standard C++ Library Header Files:bitset, conj, cos, showpoint, streampos
- Standard Template Library C++:adjacent_find, copy_backward, lexicographical_compare
- Appendix. Type Traits:Helper Class, Primary Type Categories, Binary Type Traits
- Notices:References, Bug Reports