basic_ios , fpos , ios , ios_base , streamoff , streampos , streamsize , wios , wstreampos , Manipulators: boolalpha , dec , fixed , hex , internal , left , noboolalpha , noshowbase , noshowpoint , noshowpos , noskipws , nounitbuf , nouppercase , oct , right , scientific , showbase , showpoint , showpos , skipws , unitbuf , uppercase - defines the template class that serves as the base for many iostreams classes
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
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
. 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
or
basic_ostream
.
For example, noskipws(str)
clears the 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;
calls noskipws(istr)
.
bad , basic_ios , char_type , clear , copyfmt , eof , exceptions , init , fail , good , imbue , init , int_type , narrow , off_type , operator! , operator void * , pos_type , rdbuf , rdstate , setstate , tie , traits_type , widen
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
)
and output streams (of template class
basic_ostream
)
that depend on the template parameters. (The class
ios_base
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 are determined by the
class T
.
An object of class basic_ios<E, T>
stores:
basic_ostream<E,
T>
basic_streambuf<E,
T>
ios_base
bool bad() const;
The member function returns true if
rdstate() & badbit
is nonzero.
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.
typedef E char_type;
The type is a synonym for the template parameter E
.
void clear(iostate state = goodbit);
The member function replaces the stored
stream state information with
state |
(rdbuf() != 0 ? goodbit : badbit)
.
If state &
exceptions()
is nonzero, it
then throws an object of class
failure
.
basic_ios& copyfmt(const basic_ios& rhs);
The member function reports the
callback event
erase_event
.
It then copies from rhs
into *this
the fill character,
the tie pointer, and the
formatting information.
Before altering the
exception mask, it reports the
callback event
copyfmt_event
.
If, after the copy is complete, state &
exceptions()
is nonzero,
the function effectively calls
clear
with the argument
rdstate()
.
It returns *this
.
bool eof() const;
The member function returns true if
rdstate() & eofbit
is nonzero.
iostate exceptions() const; iostate exceptions(iostate except);
The first member function returns the stored
exception mask. 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())
.
bool fail() const;
The member function returns true if
rdstate() & failbit
is nonzero.
char_type fill() const; char_type fill(char_type ch);
The first member function returns the stored
fill character. The second member
function stores ch
in the fill character and returns its
previous stored value.
bool good() const;
The member function returns true if
rdstate() == goodbit
(no state flags are set).
locale imbue(const locale& loc);
If rdbuf
is not a
null pointer, the member function calls
rdbuf()->pubimbue(loc)
.
In any case, it returns
ios_base::imbue(loc)
.
void init(basic_streambuf<E, T> *sb);
The member function stores values in all member objects, so that:
rdbuf()
returns
sb
tie()
returns a null
pointerrdstate()
returns
goodbit
if
sb
is nonzero; otherwise, it returns
badbit
exceptions()
returns
goodbit
flags()
returns
skipws |
dec
width()
returns zeroprecision()
returns 6fill()
returns the
space charactergetloc()
returns
locale::classic()
iword
returns zero and
pword
returns a null
pointer for all argument valuetypedef typename T::int_type int_type;
The type is a synonym for
T::int_type
.
char narrow(char_type ch, char dflt);
The member function returns
use_facet<
ctype<E> >(
getloc()).
narrow(ch, dflt)
.
typedef typename T::off_type off_type;
The type is a synonym for
T::off_type
.
operator void *() const;
The operator returns a null pointer only if
fail()
.
bool operator!() const;
The operator returns
fail()
.
typedef typename T::pos_type pos_type;
The type is a synonym for
T::pos_type
.
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.
iostate rdstate() const;
The member function returns the stored stream state information.
void setstate(iostate state);
The member function effectively calls
clear(state |
rdstate())
.
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. The second member function
stores str
in the tie pointer and returns its previous
stored value.
typedef T traits_type;
The type is a synonym for the template parameter T
.
char_type widen(char ch);
The member function returns
use_facet<
ctype<E> >(
getloc()).
widen(ch)
.
ios_base& boolalpha(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
boolalpha)
, then returns
str
.
ios_base& dec(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
dec, ios_base::
basefield)
, then returns
str
.
ios_base& fixed(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
fixed, ios_base::
floatfield)
, then returns
str
.
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
within any stream. An object of class fpos<St>
effectively
stores at least two member objects:
streamoff
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
,
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,
mbstate_t
may actually be unused. So the number of
member objects stored may vary.
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
(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
.
bool operator!=(const fpos& rhs) const;
The member function returns !(*this == rhs)
.
fpos operator+(streamoff off) const;
The member function returns fpos(*this) += off
.
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 streams that do not have a
state-dependent encoding.
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-=(streamoff off);
The member function returns fpos(*this) -= off
.
For positioning within a file, the result is generally valid only for
binary streams that do not have a
state-dependent encoding.
bool operator==(const fpos& rhs) const;
The member function returns (streamoff)*this == (streamoff)rhs
.
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.
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.
ios_base& hex(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
hex, ios_base::
basefield)
, then returns
str
.
ios_base& internal(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
internal, ios_base::
adjustfield)
, then returns
str
.
typedef basic_ios<char, char_traits<char> > ios;
The type is a synonym for template class
basic_ios
, specialized for
elements of type char with default
character traits.
event , event_callback , failure , flags , fmtflags , getloc , imbue , Init , ios_base , iostate , iword , openmode , operator= , precision , pword , register_callback , seekdir , setf , sync_with_stdio , unsetf , width , xalloc
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; enum event { copyfmt_event, erase_event, imbue_event}; static const event copyfmt_event, erase_event, copyfmt_event; class Init; ios_base& operator=(const ios_base& rhs); 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(); };
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
describes what is
common and is dependent on template parameters.
An object of class ios_base
stores
formatting information,
which consists of:
fmtflags
iostate
locale
An object of class ios_base
also stores
stream state information,
in an object of type
iostate
, and a
callback stack.
enum event { copyfmt_event, erase_event, imbue_event};
The type is an enumeration that describes an
object that can store the
callback event used as an argument to
a function registered with
register_callback
.
The distinct event values are:
copyfmt_event
,
to identify a callback that occurs near the end of a call to
copyfmt
, just before the
exception mask is copied.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
.imbue_event
,
to identify a callback that occurs at the end of a call to
imbue
, 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
.
Such a function must not throw an exception.
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 function
clear
in template class
basic_ios
. The value returned by
what()
is
what_arg.data()
.
fmtflags flags() const; fmtflags flags(fmtflags fmtfl);
The first member function returns the stored
format flags. The second member function
stores fmtfl
in the format flags and returns its previous
stored value.
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
T1
that describes an object that can store
format flags. The distinct flag values (elements) are:
boolalpha
, to insert or
extract objects of type bool as names (such as true
and false
) rather than as numeric valuesdec
, to insert or extract
integer values in decimal formatfixed
, to insert
floating-point values in fixed-point format (with no exponent field)hex
, to insert or extract
integer values in hexadecimal formatinternal
,
to pad to a field width
as needed by inserting fill
characters at a point internal to a generated numeric fieldleft
,
to pad to a field width as needed
by inserting fill characters
at the end of a generated field (left justification)oct
, to insert or extract
integer values in octal formatright
,
to pad to a field width
as needed by inserting fill characters
at the beginning of a generated field (right justification)scientific
, to insert
floating-point values in scientific format (with an exponent field)showbase
, to insert a
prefix that reveals the base of a generated integer fieldshowpoint
, to insert a
decimal point unconditionally in a generated floating-point fieldshowpos
, to insert a plus
sign in a non-negative generated numeric fieldskipws
, to skip leading
white space before certain
extractionsunitbuf
, to flush output
after each insertionuppercase
, to insert
uppercase equivalents of lowercase letters in certain insertionsIn addition, several useful values are:
adjustfield
,
internal | left | right
basefield
,
dec | hex | oct
floatfield
,
fixed | scientific
locale getloc() const;
The member function returns the stored locale object.
locale imbue(const locale& loc);
The member function stores loc
in the
locale object, then reports the
callback event
imbue_event
.
It returns the previous stored value.
class Init { };
The nested class describes an object whose construction ensures that the standard iostreams objects are properly constructed, even before the execution of a constructor for an arbitrary static object.
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
.
typedef T2 iostate; static const iostate badbit, eofbit, failbit, goodbit;
The type is a bitmask type
T2
that describes an object that can store
stream state information. The
distinct flag values (elements) are:
badbit
, to record a loss of
integrity of the stream buffereofbit
, to record
end-of-file while extracting from a streamfailbit
, to record a
failure to extract a valid field from a streamIn addition, a useful value is:
goodbit
, no bits setlong& iword(int idx);
The member function returns a reference to element
idx
of the
extensible array 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
.
typedef T3 openmode; static const openmode app, ate, binary, in, out, trunc;
The type is a bitmask type
T3
that describes an object that can store the
opening mode for several iostreams
objects. The distinct flag values (elements) are:
app
, to seek to the end of a
stream before each insertionate
, to seek to the end of a
stream when its controlling object is first createdbinary
, to read a file as a
binary stream,
rather than as a
text streamin
,
to permit extraction from a streamout
,
to permit insertion to a streamtrunc
, to truncate an
existing file when its controlling object is first createdios_base& operator=(const ios_base& rhs);
The operator copies the stored
formatting information,
making a new copy of any
extensible arrays.
It then returns *this
. Note that the
callback stack is not copied.
streamsize precision() const; streamsize precision(streamsize prec);
The first member function returns the stored
display precision. The second member
function stores prec
in the display precision and returns
its previous stored value.
void *& pword(int idx);
The member function returns a reference to element idx
of the
extensible array 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
.
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. When a
callback event ev
is reported,
the functions are called, in reverse order of registry, by the
expression (*pfn)(ev, *this, idx)
.
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:
beg
, to seek (alter the
current read or write position) relative to the beginning oc a sequence
(array, stream, or file)cur
, to seek relative to the
current position within a sequenceend
, to seek relative to the
end of a sequencevoid 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. The second member function
effectively calls
flags(mask & fmtfl, flags() & ~mask)
(replace selected
bits under a mask), then returns the previous format flags.
static bool sync_with_stdio(bool sync = true);
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 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.
void unsetf(fmtflags mask);
The member function effectively calls
flags(~mask & flags())
(clear selected bits).
streamsize width() const; streamsize width(streamsize wide);
The first member function returns the stored
field width. The second member function
stores wide
in the field width and returns its previous
stored value.
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 the member functions
iword
or
pword
.
ios_base& left(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
left, ios_base::
adjustfield)
, then returns
str
.
ios_base& noboolalpha(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
boolalpha)
, then returns
str
.
ios_base& noshowbase(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
showbase)
,
then returns str
.
ios_base& noshowpoint(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
showpoint)
, then returns
str
.
ios_base& noshowpos(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
showpos")
,
then returns str
.
ios_base& noskipws(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
skipws)
,
then returns str
.
ios_base& nounitbuf(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
unitbuf)
,
then returns str
.
ios_base& nouppercase(ios_base& str);
The manipulator effectively calls
str.unsetf(ios_base::
uppercase)
, then returns
str
.
ios_base& oct(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
oct, ios_base::
basefield)
, then returns
str
.
ios_base& right(ios_base& str);
The maiipulator effectively calls
str.setf(ios_base::
right, ios_base::
adjustfield)
, then returns
str
.
ios_base& scientific(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
scientific, ios_base::
floatfield)
, then returns
str
.
ios_base& showbase(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
showbase)
,
then returns str
.
ios_base& showpoint(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
showpoint)
, then returns
str
.
ios_base& showpos(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
showpos)
,
then returns str
.
ios_base& skipws(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
skipws)
,
then returns str
.
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.
typedef fpos<mbstate_t> streampos;
The type is a synonym for fpos<
mbstate_t>
.
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.
ios_base& unitbuf(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
unitbuf)
,
then returns str
.
ios_base& uppercase(ios_base& str);
The manipulator effectively calls
str.setf(ios_base::
uppercase)
, then returns
str
.
typedef basic_ios<wchar_t, char_traits<wchar_t> > wios;
The type is a synonym for template class
basic_ios
, specialized for
elements of type wchar_t
with default
character traits.
typedef fpos<mbstate_t> wstreampos;
The type is a synonym for fpos<
mbstate_t>
.
Copyright © 1992-1996 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.