ios_base(3C++) - ios_base(3C++)
Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.
NAMEios_base
- Defines member types and maintains data for classes that inherit
from it.
SYNOPSIS
#include <ios>
class ios_base;
DESCRIPTION
The class_ios_base defines several member types:
· A class failure derived from exception.
· A class Init.
· Three bitmask types: fmtflags, iostate, and openmode.
· Two enumerated types: seekdir and event.
It maintains several kinds of data:
· Control information that influences how to interpret (format)
input sequences and how to generate (format) output sequences.
· Locale object used within the stream classes.
· Additional information that is stored by the program for its pri‐
vate use.
INTERFACE
class ios_base {
public:
class failure : public exception {
public:
explicit failure(const string& msg);
virtual ~failure()throw();
virtual const char* what() const throw();
};
typedef int fmtflags;
enum fmt_flags {
boolalpha = 0x0001,
dec = 0x0002,
fixed = 0x0004,
hex = 0x0008,
internal = 0x0010,
left = 0x0020,
oct = 0x0040,
right = 0x0080,
scientific = 0x0100,
showbase = 0x0200,
showpoint = 0x0400,
showpos = 0x0800,
skipws = 0x1000,
unitbuf = 0x2000,
uppercase = 0x4000,
adjustfield = left | right | internal,
basefield = dec | oct | hex,
floatfield = scientific | fixed
};
typedef int iostate;
enum io_state {
goodbit = 0x00,
badbit = 0x01,
eofbit = 0x02,
failbit = 0x04
};
typedef int openmode;
enum open_mode {
app = 0x01,
binary = 0x02,
in = 0x04,
out = 0x08,
trunc = 0x10,
ate = 0x20
};
typedef int seekdir;
enum seek_dir {
beg = 0x0,
cur = 0x1,
end = 0x2
};
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;
streamsize width(streamsize wide);
locale imbue(const locale& loc);
locale getloc() const
static int xalloc();
long& iword(int index);
void*& pword(int index);
ios_base& copyfmt(const ios_base& rhs);
enum event {
erase_event = 0x0001,
imbue_event = 0x0002,
copyfmt_event = 0x004
};
typedef void (*event_callback) (event, ios_base&,
int index);
void register_callback(event_callback fn, int index);
bool synch_with_stdio(bool sync = true);
bool is_synch();
protected:
ios_base();
virtual ~ios_base();
private:
union ios_user_union {
long lword;
void* pword;
};
union ios_user_union *userwords_;
};
ios_base& boolalpha(ios_base&);
ios_base& noboolalpha(ios_base&);
ios_base& showbase(ios_base&);
ios_base& noshowbase(ios_base&);
ios_base& showpoint(ios_base&);
ios_base& noshowpoint(ios_base&);
ios_base& showpos(ios_base&);
ios_base& noshowpos(ios_base&);
ios_base& skipws(ios_base&);
ios_base& noskipws(ios_base&);
ios_base& uppercase(ios_base&);
ios_base& nouppercase(ios_base&);
ios_base& internal(ios_base&);
ios_base& left(ios_base&);
ios_base& right(ios_base&);
ios_base& dec(ios_base&);
ios_base& hex(ios_base&);
ios_base& oct(ios_base&);
ios_base& fixed(ios_base&);
ios_base& scientific(ios_base&);
ios_base& unitbuf(ios_base&);
ios_base& nounitbuf(ios_base&);
TYPES
fmtflags
The type fmtflags is a bitmask type. Setting its elements has the following
effects:
showpos Generates a + sign in non-negative generated numeric output.
showbase Generates a prefix indicating the numeric base of generated
integer output
uppercase Replaces certain lowercase letters with their uppercase equiva‐
lents in generated output
showpoint Generates a decimal-point character unconditionally in gener‐
ated floating-point output
boolalpha Inserts and extracts bool type in alphabetic format
unitbuf Flushes output after each output operation
internal Adds fill characters at a designated internal point in certain
generated output. If no such point is designated, it's identical
to right.
left Adds fill characters on the right (final positions) of certain gen‐
erated output
right Adds fill characters on the left (initial positions) of certain
generated output
dec Converts integer input or generates integer output in decimal base
hex Converts integer input or generates integer output in hexadecimal
base
oct Converts integer input or generates integer output in octal base
fixed Generates floating-point output in fixed-point notation
scientific Generates floating-point output in scientific notation
skipws Skips leading white space before certain input operation.
iostate
The type iostate is a bitmask type. Setting its elements has the following
effects:
badbit Indicates a loss of integrity in an input or output sequence.
eofbit Indicates that an input operation reached the end of an input
sequence.
failbit Indicates that an input operation failed to read the expected
characters, or that an output operation failed to generate the
desired characters.
openmode
The type openmode is a bitmask type. Setting its elements has the following
effects:
app Seeks to the end before writing.
ate Opens and seeks to the end immediately after opening.
binary Performs input and output in binary mode.
in Opens for input.
out Opens for output.
trunc Truncates an existing stream when opening.
seekdir
The type seekdir is a bitmask type. Setting its elements has the following
effects:
beg Requests a seek relative to the beginning of the stream.
cur Requests a seek relative to the current position within the sequence.
end Requests a seek relative to the current end of the sequence.
event_callback
The type event_callback is the type of the callback function used as a
parameter in the function register_callback. These functions allow you to
use the iword, pword mechanism in an exception-safe environment.
PUBLIC CONSTRUCTORSios_base();
The ios_base members have an indeterminate value after construction.
PUBLIC DESTRUCTORS
virtual
~ios_base();
Destroys an object of class ios_base. Calls each registered callback pair
(fn, index) as (*fn)(erase_event,*this, index) at such a time that any
ios_base member function called from within fn has well-defined results.
PUBLIC MEMBER FUNCTIONS
ios_base&
copyfmt(const ios_base& rhs);
Assigns to the member objects of *this the corresponding member objects of
rhs. The contents of the union pointed to by pword and iword are copied,
not the pointers themselves. Before copying any part of rhs, calls each
registered callback pair (fn,index) as (*fn)(erase_even,*this, index).
After all parts have been replaced, calls each callback pair that was
copied from rhs as (*fn)(copy_event,*this,index).
fmtflagsflags() const;
Returns the format control information for both input and output.
fmtflagsflags(fmtflags fmtfl);
Saves the format control information, then sets it to fmtfl and returns the
previously saved value.
localegetloc() const;
Returns the imbued locale, which is used to perform locale-dependent input
and output operations. The default locale, locale::locale(), is used if no
other locale object has been imbued in the stream by a call to the imbue
function.
localeimbue(const locale& loc);
Saves the value returned by getloc(), then assigns loc to a private vari‐
able and calls each registered callback pair (fn, index) as
(*fn)(imbue_event,*this, index). It then returns the previously saved
value.
boolis_sync();
Returns true if the C++ standard streams and the standard C streams are
synchronized. Otherwise returns false. This function is not part of the C++
standard.
long&iword(int idx);
Returns userwords_[idx].iword. If userwords_ is a null pointer, allocates a
union of long and void* of unspecified size and stores a pointer to its
first element in userwords_. The function then extends the union pointed to
by userwords_ to include the element userwords_[idx]. Each newly allocated
element of the union is initialized to zero. The reference returned may
become invalid after another call to the object's iword or pword member
with a different index, after a call to its copyfmt member, or when the
object is destroyed.
streamsizeprecision() const;
Returns the precision (number of digits after the decimal point) to gener‐
ate on certain output conversions.
streamsizeprecision(streamsize prec);
Saves the precision, then sets it to prec and returns the previously saved
value.
void*&pword(int idx);
Returns userword_[idx].pword. If userwords_ is a null pointer, allocates a
union of long and void* of unspecified size and stores a pointer to its
first element in userwords_. The function then extends the union pointed to
by userwords_ to include the element userwords_[idx]. Each newly allocated
element of the array is initialized to zero. The reference returned may
become invalid after another call to the object's pword or iword member
with a different index, after a call to its copyfmt member, or when the
object is destroyed.
voidregister_callback(event_callback fn, int index);
Registers the pair (fn, index) such that during calls to imbue(), copy‐
fmt(), or ~ios_base(), the function fn is called with argument index. Func‐
tions registered are called when an event occurs, in opposite order of reg‐
istration. Functions registered while a callback function is active are not
called until the next event. Identical pairs are not merged; a function
registered twice is called twice per event.
fmtflagssetf(fmtflags fmtfl);
Saves the format control information, then sets it to fmtfl and returns the
previously saved value.
fmtflagssetf(fmtflags fmtfl, fmtflags mask);
Saves the format control information, then clears mask in flags(), sets
fmtfl & mask in flags() and returns the previously saved value.
boolsync_with_stdio(bool sync = true);
When called with a false argument, allows the C++ standard streams to oper‐
ate independently of the standard C streams, which greatly improves perfor‐
mance. When called with a true argument, restores the default synchroniza‐
tion. The return value of the function is the status of the synchronization
at the time of the call.
voidunsetf(fmtflags mask);
Clears mask in flags().
streamsizewidth() const;
Returns the field width (number of characters) to generate on certain out‐
put conversions.
streamsizewidth(streamsize wide);
Saves the field width, then sets it to wide and returns the previously
saved value.
static intxalloc();
Returns the next static index that can be used with pword and iword. This
is useful if you want to share data between several stream objects.
CLASS FAILURE
The class failure defines the base class for the types of all objects
thrown as exceptions by functions in the iostreams library. It reports
errors detected during stream buffer operations.
explicit failure(const string& msg);
Constructs an object of class failure, initializing the base class with
exception(msg).
const char*what() const;
Returns the message msg with which the exception was created.
CLASS INIT
The class Init describes an object whose construction ensures the con‐
struction of the eight objects declared in <iostream>, which associate
file stream buffers with the standard C streams.
NON-MEMBER FUNCTIONS
ios_base&
boolalpha(ios_base& str);
Calls str.setf(ios_base::boolalpha) and returns str.
ios_base&dec(ios_base& str);
Calls str.setf(ios_base::dec, ios_base::basefield) and returns str.
ios_base&fixed(ios_base& str);
Calls str.setf(ios_base::fixed, ios_base::floatfield) and returns str.
ios_base&hex(ios_base& str);
Calls str.setf(ios_base::hex, ios_base::basefield) and returns str.
ios_base&internal(ios_base& str);
Calls str.setf(ios_base::internal, ios_base::adjustfield) and returns str.
ios_base&left(ios_base& str);
Calls str.setf(ios_base::left, ios_base::adjustfield) and returns str.
ios_base&noboolalpha(ios_base& str);
Calls str.unsetf(ios_base::boolalpha) and returns str.
ios_base&noshowbase(ios_base& str);
Calls str.unsetf(ios_base::showbase) and returns str.
ios_base&noshowpoint(ios_base& str);
Calls str.unsetf(ios_base::showpoint) and returns str.
ios_base&noshowpos(ios_base& str);
Calls str.unsetf(ios_base::showpos) and returns str.
ios_base&noskipws(ios_base& str);
Calls str.unsetf(ios_base::skipws) and returns str.
ios_base&nounitbuf(ios_base& str);
Calls str.unsetf(ios_base::unitbuf) and returns str.
ios_base&nouppercase(ios_base& str);
Calls str.unsetf(ios_base::uppercase) and returns str.
ios_base&oct(ios_base& str);
Calls str.setf(ios_base::oct, ios_base::basefield) and returns str.
ios_base&right(ios_base& str);
Calls str.setf(ios_base::right, ios_base::adjustfield) and returns str.
ios_base&scientific(ios_base& str);
Calls str.setf(ios_base::scientific, ios_base::floatfield) and returns str.
ios_base&showbase(ios_base& str);
Calls str.setf(ios_base::showbase) and returns str.
ios_base&showpoint(ios_base& str);
Calls str.setf(ios_base::showpoint) and returns str.
ios_base&showpos(ios_base& str);
Calls str.setf(ios_base::showpos) and returns str.
ios_base&skipws(ios_base& str);
Calls str.setf(ios_base::skipws) and returns str.
ios_base&unitbuf(ios_base& str);
Calls str.setf(ios_base::unitbuf) and returns str.
ios_base&uppercase(ios_base& str);
Calls str.setf(ios_base::uppercase) and returns str.
SEE ALSO
basic_ios(3C++), basic_istream(3C++), basic_ostream(3C++),
char_traits(3C++)
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.4.2
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
Rogue Wave Software 02 Apr 1998 ios_base(3C++)