DEC C++
Class Library Reference Manual


Previous Contents Index

#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.


Previous Next Contents Index