|
Compaq C++
Compaq C++ Class Library Reference Manual
ifstream class
Supports formatted and unformatted input from files.
Header File
#include <fstream.hxx>
Alternative Header
#include <fstream.h>
Declaration
class ifstream: public istream
{
public:
ifstream();
ifstream(const char *name, int mode = ios::in,
int prot = filebuf::openprot);
ifstream(int fd);
ifstream(int fd, char *p, int len);
~ifstream();
void attach(int fd);
void close();
void open(const char *name, int mode = ios::in,
int prot = filebuf::openprot);
filebuf *rdbuf();
void setbuf(char *p, int len);
};
|
Description
This class specializes the
istream
class to files by using a
filebuf
object to do the input. Your program can perform common operations,
such as opening and closing files, without explicitly mentioning
filebuf
objects.
Constructors and Destructors
ifstream()
Constructs an unopened
ifstream
object.
ifstream(int fd)
Constructs an
ifstream
object connected to a file whose descriptor is passed through the
fd argument. The file must already be open.
ifstream(int fd, char *p, int len)
Constructs an
ifstream
object connected to a file whose descriptor is passed through the
fd argument, and also initializes the associated
filebuf
object to use the len bytes starting at p as the
reserve area. If p is null or len is 0, the
filebuf
object is unbuffered.
ifstream(const char *name, int mode, int prot)
Constructs an
ifstream
object and opens the file with the file name specified by
name. The mode and prot arguments specify
the file open mode and protection. By default, prot is
filebuf::openprot
. If the open fails, the error state (
io_state
) of the constructed
ifstream
object indicates failure.
~ifstream()
Deletes an
ifstream
object.
Member Functions
void attach(int fd)
Connects an
ifstream
object to a file whose descriptor is passed through the fd
argument. A failure occurs when the
ifstream
object is connected to a file, in which case
ios::failbit
is set in the
ifstream
object error state.
void close()
Closes any associated
filebuf
object and consequently breaks the connection of the
ifstream
object to the file. The error state of the
fstream
object is cleared except on failure. A failure occurs when the call to
the
filebuf
object's
close()
function fails.
void open(const char *name, int mode, int prot)
Opens a file specified by the name argument and connects the
ifstream
object to it. If the file does not exist, the function tries to create
it with the protection specified by the prot argument unless
ios::nocreate
is set. By default, prot is
filebuf::openprot
.
Failure occurs if the
ifstream
object is open or when the call to the
filebuf
object
open()
function fails, in which case
ios::failbit
is set in the
filebuf
object error state. The members of
open_mode
are bits that may be joined together by
or
(because this joining takes an
int
,
open()
takes an
int
rather than an
open_mode
argument). For an explanation of the meanings of these bits in
open_mode
, see the Enumerated Types section for the
ios
class.
filebuf *rdbuf()
Returns a pointer to the
filebuf
object associated with the
ifstream
object. This function has the same meaning as
ios::rdbuf()
but has a different type.
void setbuf(char *p, int len)
Calls the associated
filebuf
object
setbuf()
function to request space for a reserve area. A failure occurs if the
filebuf
object is open or if the call to
rdbuf()->setbuf
fails for any other reason.
IMANIP(TYPE) class
For an
istream
object, declares the predefined parameterized manipulators and provides
macros for user-defined parameterized manipulators.
Header File
#include <iomanip.hxx>
Alternative Header
#include <iomanip.h>
Compile-Time Parameter
TYPE---The type of the
istream
object. It must be an identifier.
Declaration
class IMANIP(TYPE)
{
public:
IMANIP(TYPE)(istream &(*f)(istream &, TYPE), TYPE a);
friend istream &operator>>(istream &s, IMANIP(TYPE) &m);
};
|
Description
These manipulators serve the
istream
class by producing some useful effect, such as embedding a function
call in an expression containing a series of insertions and
extractions. You also can use manipulators to shorten the long names
and sequences of operations required by the
iostream
class.
In its simplest form, a manipulator takes an
istream&
argument, operates on it in some way, and returns it.
Constructor
IMANIP(TYPE)(istream &(*f)(istream &, TYPE), TYPE a)
Creates a manipulator; *f is the left operand of the extractor
operator.
Operator
istream &operator >> (istream &s, IMANIP(TYPE)
&m)
Takes data from an
istream
object.
IOAPP(TYPE) class
For an
iostream
object, declares predefined parameterized applicators.
Header File
#include <iomanip.hxx>
Alternative Header
#include <iomanip.h>
Compile-Time Parameter
TYPE---The type of the
iostream
object. It must be an identifier.
Declaration
class IOAPP(TYPE)
{
public:
IOAPP(TYPE)(iostream &(*f)(iostream &, TYPE));
IOMANIP(TYPE) operator()(TYPE a);
};
|
Constructor
IOAPP(TYPE)(iostream &(*f)(iostream &, TYPE))
Creates an applicator.
Operator
IOMANIP(TYPE) operator () (TYPE a)
Casts an object of type a into a manipulator function for an
iostream
object.
See Also
IOMANIP(TYPE)
class
IOMANIP(TYPE) class
For an
iostream
object, declares predefined parameterized manipulators and provides
macros for user-defined parameterized manipulators.
Header File
#include <iomanip.hxx>
Alternative Header
#include <iomanip.h>
Compile-Time Parameter
TYPE---The type of the
iostream
object. It must be an identifier.
Declaration
class IOMANIP(TYPE)
{
public:
IOMANIP(TYPE)(iostream &(*f)(iostream &, TYPE), TYPE a);
friend istream &operator>>(iostream &s, IOMANIP(TYPE) &m);
friend ostream &operator<<(iostream &s, IOMANIP(TYPE) &m);
};
IOMANIPdeclare(int);
IOMANIPdeclare(long);
|
Description
These manipulators serve the
iostream
class by producing some useful effect, such as embedding a function
call in an expression containing a series of insertions and
extractions. You can also use manipulators to shorten the long names
and sequences of operations required by the
iostream
class.
In its simplest form, a manipulator takes an
iostream&
argument, operates on it in some way, and returns it.
Two
ios
manipulators for using
Mutex
objects,
lock
and
unlock
, come in both parameterized and unparameterized forms. The
parameterized manipulators let users synchronize
iostream
objects, the parameter being a user-defined
Mutex
object. To use parameterized manipulators, you must include
iomanip.hxx
. Unparameterized manipulators let users synchronize the predefined
stream objects:
cerr
,
cin
,
clog
, and
cout
.
For examples of using the
lock
and
unlock
manipulators, see Chapter 6 and the section on Global Declarations in this
chapter.
Constructor
IOMANIP(TYPE)(iostream &(*f)(iostream &, TYPE), TYPE a)
Creates a manipulator.
Macro
IOMANIPdeclare(TYPE)
Declares the manipulators (and the manipulator classes) that have an
operator()
member function for type TYPE.
Operators
ostream &operator << (iostream &s, IOMANIP(TYPE)
&m)
Sends data to an
iostream
object.
istream &operator >> (iostream &s, IOMANIP(TYPE)
&m)
Takes data from an
iostream
object.
ios class
Contains state variables common to most of the other classes in the
iostream package.
Header
#include <iostream.hxx>
Alternative Header
#include <iostream.h>
Declaration
class ios
{
public:
enum io_state { goodbit = 0, eofbit = 01,
failbit = 02, badbit = 04 };
enum open_mode { in = 01, out = 02, ate = 04,
app = 010, trunc = 020,
nocreate = 040, noreplace = 0100 };
enum seek_dir { beg = 0, cur = 01, end = 02 };
enum { skipws = 01,
left = 02, right = 04, internal = 010,
dec = 020, oct = 040, hex = 0100,
showbase = 0200, showpoint = 0400,
uppercase = 01000,
showpos = 02000,
scientific = 04000, fixed = 010000,
unitbuf = 020000, stdio = 040000 };
static const long basefield;
static const long adjustfield;
static const long floatfield;
ios(streambuf *);
virtual ~ios();
inline int bad() const;
static long bitalloc();
inline void clear(int state = 0);
inline int eof() const;
inline int fail() const;
inline char fill() const;
char fill(char);
inline long flags() const;
long flags(long);
inline int good() const;
long &iword(int);
inline int operator!();
inline operator void *();
inline int precision() const;
int precision(int);
void *&pword(int);
inline streambuf *rdbuf();
inline int rdstate() const;
long setf(long setbits, long field);
long setf(long);
static void sync_with_stdio();
inline ostream *tie() const;
ostream *tie(ostream *);
long unsetf(long);
inline int width() const;
int width(int n);
static int xalloc();
protected:
ios();
void init(streambuf *);
inline void setstate(int state);
};
|
Description
Classes derived from the
ios
class provide an interface for transferring formatted and unformatted
information into and out of
streambuf
objects.
Enumerated Types
io_state
Represents a collection of bits (flags) that describe the internal
error states of an object. The values are as follows:
goodbit
|
No errors occurred.
|
eofbit
|
End-of-file encountered during an extraction operation.
|
failbit
|
Extraction or conversion failed but the stream is still usable.
|
badbit
|
A severe error, usually in an operation on the associated
streambuf
object, from which recovery is unlikely.
|
open_mode
Represents a collection of bits (flags) for specifying the mode of the
open()
function. Use this data type with objects of the
fstream
,
ifstream
, and
ofstream
classes. The values are as follows:
app
|
Performs a seek to the end-of-file. This appends to the end of the file
any subsequent data written to the file.
ios::app
implies
ios::out
.
|
ate
|
Performs a seek to the end-of-file during an
open()
operation.
ios::ate
does not imply
ios::out
.
|
in
|
Opens the file for input. Constructions and open operations of
ifstream
objects imply
ios::in
. For
fstream
objects,
ios::in
signifies that input operations should be allowed if possible. Including
ios::in
in the modes of an
ofstream
object is legal, implying that the original file (if it exists) should
not be truncated.
|
out
|
Opens the file for output. Constructions and open operations of
ofstream
objects imply
ios::out
. For
fstream
objects,
ios::out
indicates that output operations are allowed.
|
trunc
|
Truncates (discards) the contents of the file (if it exists).
ios::trunc
is implied if
ios::out
is specified (including implicit specification for
ofstream
objects), and neither
ios::app
nor
ios::ate
is specified.
|
nocreate
|
Causes an
open()
operation to fail if the file does not exist.
|
noreplace
|
Causes an
open()
operation to fail if the file exists.
|
seek_dir
Represents a collection of bits for positioning get and put pointers.
Use this data type with functions of the
filebuf
,
istream
,
ostream
, and
streambuf
classes. The values are as follows:
beg
|
Indicates the beginning of the stream
|
cur
|
Indicates the current position
|
end
|
Indicates the end of the stream (end-of-file)
|
Data Members
const long adjustfield
Collectively specifies the flags (bits) that control padding (
left
,
right
, and
internal
).
const long basefield
Collectively specifies the flags that control base conversion (
dec
,
hex
, and
oct
).
const long floatfield
Collectively specifies the flags that control floating-point value
conversion (
fixed
and
scientific
).
Note
When you set a flag that is part of
adjustfield
,
basefield
, or
floatfield
, you must ensure that the other flags within the collection are
cleared. Only one flag within the collection should be set at any one
time.
Be aware that the
setiosflags(flag)
manipulator and the
setf(flag)
member function set only the flag or flags that you specify. If the
flag you specify is part of a collection, these do not clear the other
flags in the collection.
The
setf(flag, field)
member function is useful for setting fields within a collection. Also,
the
hex
,
oct
, and
dec
manipulators do ensure that the other flags within the
basefield
collection are cleared.
|
Constructors and Destructors
ios()
Constructs an
ios
object with the effect undefined. It lets derived classes inherit the
ios
class as a virtual base class. The object is initialized with the
following default values:
Element |
Default Value |
fill()
|
The space character
|
flags()
|
ios::dec
|
ios::skipws
|
precision()
|
6
|
rdstate()
|
ios::goodbit
|
width()
|
0
|
ios(streambuf *b)
Constructs an
ios
object, associating the constructed
ios
object with the
streambuf
object pointed to by b. The object is initialized with the
same default values as the
ios()
constructor.
virtual ~ios()
Deletes an
ios
object.
Overloaded Operators
When defined, the following operators allow convenient checking of the
error state of an
ios
.
int operator !()
Returns nonzero if
failbit
or
badbit
is set in the error state, which allows the use of such expressions as
if (!cin)
....
int operator void *()
Converts an
ios
object to a pointer so that it can be compared to 0. The conversion
returns a nonzero value (not meant for further use) if neither
failbit
nor
badbit
is set in the error state. This allows the use of such expressions as
if (cin)
... and
if (cin >> x)
....
Other Member Functions
int bad() const
Returns a nonzero value if
badbit
is set in the error state; otherwise, it returns 0. This usually
indicates that some operation on
rdbuf()
has failed, and that continued operations on the associated
streambuf
object may not be possible.
long bitalloc()
Returns a long integer with a single, previously unallocated bit set.
This gives you an additional flag should you need one (to pass to
ios::set()
, for example).
void clear(int state)
Stores an integer value as the error state. A 0 value clears all bits.
int eof() const
Returns a nonzero value if
eofbit
is set in the error state; otherwise, it returns 0. This bit is usually
set during an extraction and when an end-of-file has been encountered.
int fail() const
Returns a nonzero value if either
badbit
or
failbit
is set in the error state; otherwise, it returns 0. This usually
indicates that some extraction or conversion operation has failed, but
that the stream remains usable; once
failbit
clears, operations on the stream can usually continue.
char fill() const
Returns the variable currently used as the fill (padding) character.
char fill(char c)
Sets c as the fill (padding) character if one is needed (see
width ()
) and returns the previous value. The default fill character is a
space. The
right
,
left
, and
internal
flags determine positioning of the fill character. A parameterized
manipulator,
setfill
, is also available for setting the fill character.
long flags() const
Returns the current format flags.
long flags(long f)
Resets all the format flags to those specified in f and
returns the previous settings. The flags are as follows:
skipws
|
For scalar operations, instructs the arithmetical extractor to skip
white space before beginning conversion. As a precaution against
looping, arithmetical extractors signal an error if the next character
is white space and the skip variable is not set.
|
left
right
internal
|
Control padding of values. The
left
flag adds a fill character after a value,
right
adds a fill character before a value, and
internal
adds a fill character after any leading sign or base indication, but
before the value. Right-adjustment is the default if none of these
flags are set. The fields are collectively identified by the static
member
ios::adjustfield
. The fill character is controlled by the
fill()
function and the width after the padding is controlled by the
width()
function.
|
dec
oct
hex
|
Control the conversion base of a value. Insertions are in decimal if
none of these flags are set. Extractions follow C++ lexical conventions
for integral constants. The flags are collectively identified by the
static member
ios::basefield
. The manipulators
hex
,
dec
, and
oct
are also available for setting the conversion base.
|
showbase
|
Converts insertions to an external form that can be read according to
the C++ lexical conventions for integral constants. By default,
showbase
is not set.
|
showpos
|
Inserts a plus sign (+) into a decimal conversion of a positive
integral value.
|
uppercase
|
Uses an uppercase X for hexadecimal conversion when
showbase
is set, or uses uppercase E to print floating-point numbers in
scientific notation. By default,
uppercase
is not set.
|
showpoint
|
Specifies that trailing zeros and decimal points appear in the result
of a floating-point conversion.
|
scientific
fixed
|
Control the format to which a floating-point value is converted for
insertion into a stream. These two flags are collectively identified by
the static member
ios::floatfield
. The
scientific
flag converts the value using scientific notation, with one digit
before the decimal point. Depending on the
uppercase
flag, an E or an e introduces the exponent. The
fixed
flag converts the value to decimal notation. For both flags, the
precision
function determines the number of digits following the decimal point (6
is the default). If neither flag is set, then scientific notation is
used only if the exponent from the conversion is less than --4 or
greater than the precision. If
showpoint
is not set, trailing zeros are removed from the result and a decimal
point appears only if followed by a digit.
|
unitbuf
|
Causes
ostream::osfx()
to perform a flush after each insertion. Unit buffering constitutes a
performance compromise between buffered and unbuffered output.
|
stdio
|
Causes
ostream::osfx()
to flush
stdout
and
stderr
after each insertion.
|
int good() const
Returns a nonzero value if the error state has no bits set; otherwise,
it returns 0.
void init(streambuf *b)
Initializes the
ios
object; intended for use by classes derived from
ios
.
long& iword(int i)
Returns a reference to the ith user-defined word, where
i is an index into an array of words allocated by
ios::xalloc
. 1
int precision() const
Returns the precision format state variable.
int precision(int i)
Sets the precision format state variable to i and returns the
previous value. The variable controls the number of significant digits
inserted by the floating-point inserter. The default is 6. A
parameterized manipulator,
setprecision
, is also available for setting the precision.
void *&ios::pword(int i)
Returns a reference to the ith user-defined word, where
i is an index into an array of words allocated by
ios::xalloc
. This function differs from
iword()
only in type.
streambuf *ios::rdbuf()
Returns a pointer to the
streambuf
object that was associated with an
ios
object when the
ios
object was constructed.
int rdstate() const
Returns the current error state.
long setf(long setbits)
Makes available to the
streambuf
object associated with an
ios
object the format flags marked in setbits and returns the
previous settings. A parameterized manipulator,
setiosflags
, performs the same function. If you are setting a flag that is part of
a collection (for example,
basefield
), note that this manipulator does not clear the other flags
in the collection.
long setf(long setbits, long field)
Clears, in the
streambuf
object associated with an
ios
object, the format flags specified by field, then resets these
flags to the settings marked in setbits. It returns the
previous settings. Specifying 0 in setbits clears all the bits
specified in field, as does the parameterized manipulator,
resetioflags
.
void setstate(int state)
Changes only the bits specified in the state argument.
void sync_with_stdio()
Solves problems that arise with mixing
stdio
and
iostream
objects. When first called, the
sync_with_stdio()
function resets the standard iostream functions (
cin
,
cout
,
cerr
, and
clog
) to be streams using
stdiobuf
objects. Subsequently, input and output using these streams may be
mixed with input and output using the corresponding
FILE
parameters (
stdin
,
stdout
, and
stderr
), and properly synchronized. The
sync_with_stdio()
function makes
cout
and
cerr
unit buffered (see
ios::unitbuf
and
ios::stdio
). Invoking
sync_with_stdio()
degrades performance variably; the shorter the strings being inserted,
the greater the degradation.
ostream *ios::tie() const
Returns the tie variable (see the following member function
description).
ostream *ios::tie(ostream *osp)
Sets the tie variable to osp and returns its previous value.
The tie variable supports automatic flushing of
ios
objects. The
ios
object that the tie variable points at is flushed if the variable is
not null, and an
ios
object either needs more characters or has characters to be consumed.
By default,
cin
is initially tied to
cout
so that attempts to get more characters from standard input result in
flushing standard output. Additionally,
cerr
and
clog
are tied to
cout
by default. By default, the tie variable is set to 0 for other
ios
objects.
long unsetf(long setbits)
Unsets, in the
streambuf
object associated with an
ios
object, the bits set in setbits; it returns the previous
settings.
int width() const
Returns the field-width format variable (see the following member
function description). The field width setting within the
ios
class is ignored during single character output: operator<<(char)
and operator<<(unsigned char).
int width(int n)
Sets the field-width format variable to n and returns the
previous value. The field width specifies a minimum number of
characters for inserters. When the variable is 0 (the default),
inserters insert only as many characters as needed to represent the
value being inserted. When the variable is nonzero, and the value being
inserted needs fewer than field-width characters to be represented,
inserters insert at least that many characters using the fill character
to pad the value. Numeric inserters do not truncate values even if the
value being inserted is more than field-width characters. After each
insertion or extraction, the field-width format variable resets to 0. A
parameterized manipulator,
setw
, is also available for setting the field width.
int xalloc()
Returns a previously unused index into an array of words available for
use by derived classes as format state variables. 1
Examples
#1 |
cout.width(6);
cout << x << " " << y;
|
Note
1 This function references the array
that is specific to the ios instance. This differs from the OpenVMS
operating system, where this function references a single array that is
shared among all instances of ios objects.
1 This function references the array
that is specific to the ios instance. This differs from the OpenVMS
operating system, where this function references a single array that is
shared among all instances of ios objects.
|
|
|
|