ios_base class — Root class for I/O declarations
class ios_base{ public: class failure; typedef . . . fmtflags; typedef . . . iostate; typedef . . . io_state; typedef . . . openmode; typedef . . . open_mode; typedef . . . seekdir; typedef . . . seek_dir; typedef . . . streamoff; typedef . . . streampos; class Init; // Destructor virtual ~ios_base( ); // Formatting 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; streamsize width(streamsize wide); // Locales locale imbue(const locale& loc); locale getloc( ) const; // Storage static int xalloc( ); long& iword(int index); void*& pword(int index); // Callbacks enum event { erase_event, imbue_event, copyfmt_event }; typedef void (*event_callback)(event, ios_base&, int index); void register_callback(event_callback fn, int index); static bool sync_with_stdio(bool sync = true); protected: ios_base( ); private: ios_base(const ios_base&); ios_base& operator=(const ios_base&); };
The ios_base
class is the
root class for all the I/O stream classes. It declares fundamental
types that are used throughout the I/O library. It also has members
to keep track of formatting for input and output, storing arbitrary
information for derived classes, and registering functions to be
called when something interesting happens to the stream
object.
The io_state
, open_mode
, seek_dir
, streamoff
, and streampos
types are deprecated and might
not be included in a future revision of the C++ standard. The first
three are integer types that are equivalent to iostate
, openmode
, and seekdir
. (See their respective subsections
later in this section for details.) The streamoff
and streampos
types have equivalent types at
namespace scope. See streamoff
later in this section and streampos
in <iosfwd>
for details.
The following are the member functions of ios_base
:
ios_base
The default constructor is protected so you cannot
accidentally declare an object of type ios_base
. It does not initialize its
members. That is left to the basic_ios::init
function.
ios_base
The copy constructor is private and not defined so you
cannot copy objects of type ios_base
or its derived
classes.
~ios_base
Calls every registered callback with the erase_event
if the ios_base
object has been properly
initialized. See basic_ios::init
.
ios_base&
operator=
(const
ios_base&)
The assignment operator is private and not defined to
prevent the assignment of ios_base
objects or its
derivatives.
fmtflags
flags
( )
const
, fmtflags
flags
(fmtflags
fmtfl)
Returns the current format flags or sets the flags. When setting the flags, the previous flags are returned.
locale
getloc
( )
const
Returns the stream's currently imbued locale.
locale
imbue
(const locale&
loc)
Saves loc
as the new
locale and calls all registered callbacks with imbue_event
. The new locale is
stored before calling any callbacks, so if a callback function
calls getloc
, it gets the
new locale.
long&
iword
(int
index)
Returns a reference to a long integer that is stored in
a private array, at index index
. If iword
has been called before with
the same index, a reference to the array element is returned.
Otherwise, the array is extended as needed so that index
is a valid index, and the new
entry is initialized to 0
.
A reference to the new element is returned.
The structure of the internal array is implementation-defined, and it might be a sparse array. The internal array grows as needed, and all prior values stored in the array are preserved, although the references might become invalid in any of the following situations:
After a call to iword
with a different
index
After calling basic_ios::copyfmt
for this
object
When the object is destroyed
If iword
fails
(perhaps because the internal array cannot grow), it returns a
reference to a valid long&
with a value that is
initially 0
. If the member
function is called for an object whose class derives from
basic_ios<>
, badbit
is set (which might throw
ios_base::failure
).
See the xalloc
member
function to learn how to obtain a suitable index.
streamsize
precision
( )
const
, streamsize
precision
(streamsize
prec)
Returns or sets the precision (places after the decimal point) used to format floating-point numbers for output. When setting a new precision, the previous precision is returned.
void*&
pword
(int
index)
Returns a reference to a void*
that is stored in a private
array, at index index
. If
pword
has been called
before with the same index, a reference to the array element
is returned. Otherwise, the array is extended as needed so
that index
is a valid
index, and the new entry is initialized to a null pointer. A
reference to the new element is returned.
The structure of the internal array is implementation-defined, and it might be a sparse array. The internal array grows as needed, and all prior values stored in the array are preserved, although the references might become invalid in any of the following situations:
After a call to pword
with a different
index
After calling basic_ios::copyfmt
for this
object
When the object is destroyed
If pword
fails
(perhaps because the internal array cannot grow), it returns a
reference to a valid void*&
with a value that is
initially 0
. If the object
derives from basic_ios<>
, badbit
is set (which might throw
ios_base::failure
).
See the xalloc
member
function to learn how to obtain a suitable index.
void
register_callback
(event_callback fn, int
index)
Registers a function fn
to be called when one of three
events occurs for the ios_base
object:
The object is destroyed (erase_event
)
copyfmt
is called
(erase_event
followed
by copyfmt_event
)
imbue
is called
(imbue_event
)
Each callback function is registered with an integer
index
. The index is passed
to the callback function. Functions are called in the opposite
order of registration. The callback function must not throw
exceptions.
For example, suppose a program stores some debugging
information with each stream. It allocates a struct
and stores a pointer to the
struct
in the stream's
pword
array. When copyfmt
is called, the debugging
information should also be copied. Example 13-14 shows how
to use callbacks to make sure the memory is managed
properly.
Example 13-14. Copying information associated with streams
void manage_info(std::ios_base::event event, std::ios_base& stream, int index) { infostruct* ip; switch(event) { case std::ios_base::erase_event: ip = static_cast<infostruct*>(stream.pword(index)); stream.pword(index) = 0; delete ip; break; case std::ios_base::copyfmt_event: stream.pword(index) = new infostruct; break; default: break; // imbue_event does not affect storage. } } void openread(std::ifstream& f, const char* name) { f.open(name); int index = f.xalloc( ); f.pword(index) = new infostruct; f.register_callback(manage_info, index); }
fmtflags
setf
(fmtflags
addflags)
Sets the addflags
bits of the formatting flags. It is equivalent to calling
flags(flags( )
|
addflags)
.
fmtflags
setf
(fmtflags newflags, fmtflags
mask)
Clears the mask
bits
from the formatting flags and then sets the newflags
&
mask
bits. It is equivalent to
calling flags((flags( )
&
~mask)
|
(newflags
&
mask))
. The two-argument version of
setf
is most often used
with multiple-choice flags (e.g., setf(ios_base::dec
, ios_base::basefield)
).
static bool
sync_with_stdio
(bool sync =
true)
Determines whether the standard C++ I/O objects are synchronized with the C I/O functions. Initially, they are synchronized.
If you call sync_with_stdio(false)
after any I/O
has been performed, the behavior is
implementation-defined.
void
unsetf
(fmtflags
mask)
Clears the mask bits from the formatting flags. It is
equivalent to calling flags(flags( )
&
~mask)
.
streamsize
width
( )
const
, streamsize
width
(streamsize
wide)
Returns or sets the minimum field width. When setting the width, the previous width is returned.
static int
xalloc
( )
Returns a unique integer, suitable for use as an index
to the iword
or pword
functions. You can think of
ios_base
as having a static
integer data member, xalloc_index
,
and xalloc
is implemented
so it returns xalloc_index
++
.