DEC C++
Class Library Reference Manual


Previous Contents Index

Failure occurs if the ofstream 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's error state. The members of open_mode are bits that may be joined together by or (and 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 ofstream 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.

OMANIP(TYPE) class

For an ostream 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 ostream object. It must be an identifier.

DECLARATION


class OMANIP(TYPE) 
{ 
public: 
    OMANIP(TYPE)(ostream &(*f)(ostream &, TYPE), T a ); 
    friend ostream &operator<<(ostream & s, OMANIP(TYPE) &m); 
}; 


DESCRIPTION

These manipulators serve the ostream 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 ostream class.

In its simplest form, a manipulator takes an ostream& argument, operates on it in some way, and returns it.


CONSTRUCTOR

OMANIP(TYPE)(ostream &(*f)(ostream &, TYPE), T a )

Creates a manipulator.

OPERATOR

ostream &operator << (ostream & s, OMANIP(TYPE) &m)

Sends data to an ostream object.

ostream class

Supports insertion into streambuf objects.

HEADER FILE

#include <iostream.hxx>

Alternative Header

#include <iostream.h>


DECLARATION


class ostream : virtual public ios 
{ 
public: 
                        ostream(streambuf *); 
    virtual             ~ostream(); 
 
    ostream             &flush(); 
    int                 opfx(); 
    void                osfx(); 
    ostream             &put(char c); 
    ostream             &seekp(streampos); 
    ostream             &seekp(streamoff, seek_dir); 
    streampos           tellp(); 
    ostream             &write(const char *ptr, int n); 
    inline ostream      &write(const unsigned char *ptr, int n); 
    ostream             &operator<<(const char *); 
    ostream             &operator<<(char); 
    inline ostream      &operator<<(short); 
    ostream             &operator<<(int); 
    ostream             &operator<<(long); 
    ostream             &operator<<(float); 
    ostream             &operator<<(double); 
    ostream             &operator<<(const unsigned char *); 
    inline ostream      &operator<<(unsigned char); 
    inline ostream      &operator<<(unsigned short); 
    ostream             &operator<<(unsigned int); 
    ostream             &operator<<(unsigned long); 
    ostream             &operator<<(void *); 
    ostream             &operator<<(streambuf *); 
    inline ostream      &operator<<(ostream &(*f)(ostream &)); 
    ostream             &operator<<(ios &(*f)(ios &)); 
 
protected: 
                        ostream(); 
}; 


DESCRIPTION

Objects of this class perform formatted and unformatted insertions into streambuf objects.

CONSTRUCTORS AND DESTRUCTORS

ostream(streambuf *b)

Constructs an istream object. It initializes ios state variables and associates the buffer b with the ostream object.

virtual ~ostream()

Deletes an ostream object.

OVERLOADED OPERATORS

The following operators are all formatted output inserters. Given the expression outs << x, these operators insert into outs.rdbuf() a sequence of characters representing x. The argument to the operator determines the type of x. Insertions are performed after a call to outs.opfx() only if that call returns nonzero. Errors are indicated by setting the error state of the ostream object. The ostream object is always returned.

Conversion of x to a sequence of characters depends on the type of x and on the values of the ostream object's format state flags and variables. Padding occurs after this representation is determined. If width() is greater than 0, and the representation contains fewer than width() characters, then the function adds enough fill() characters to bring the total number of characters to ios::width(). If ios::left() is set, the sequence is left-adjusted; that is, the function puts the padding after the sequence of characters. If ios::right() is set, the padding is added before the character sequence. If ios::internal() is set, the padding is added after any leading sign or base indication and before the characters that represent the value. ios::width() is reset to 0 but all other format variables are unchanged. The full sequence (padding plus representation) is inserted into the ostream object rdbuf() function.

ostream &operator << (char x)

ostream &operator << (unsigned char x)

Inserts a character x. No special conversion is needed.

ostream &operator << (const char *x)

ostream &operator << (const unsigned char *x)

Inserts a sequence of characters up to (but not including) the terminating null of the string that x points at.

ostream &operator << (short x)

ostream &operator << (int x)

ostream &operator << (long x)

ostream &operator << (unsigned short x)

ostream &operator << (unsigned int x)

ostream &operator << (unsigned long x)

Inserts characters as follows:

ostream &operator << (float x)

ostream &operator << (double x)

Converts the arguments according to the current values of the ostream object's precision() function, the ostream object's width() function, and the ostream object's format flags: ios::scientific, ios::fixed, and ios::uppercase. The default value for the ostream object's precision() function is 6. If neither ios::scientific nor ios::fixed is set, the value of x determines whether the representation uses scientific or fixed notation.

ostream &operator << (void *v)

Converts pointers to integral values and then converts them to hexadecimal numbers as if ios::showbase was set.

ostream &operator << (streambuf *sb)

Given the expression outs << sb, inserts into sb.rdbuf() the sequence of characters that can be fetched from sb. When no more characters can be fetched from sb, insertion stops. This function does no padding. It always returns the ostream object.

ostream &operator << (ios &(*f)(ios &))

Calls an ios object manipulator function f for an ostream object.

ostream &operator << (ostream &(*f)(ostream &))

Calls an ostream object manipulator function f for an ostream object.

OTHER MEMBER FUNCTIONS

ostream &flush()

Calls the ostream object's rdbuf()->sync() function to consume (that is, write to the external file) any characters that may have been stored into a streambuf object but are not yet consumed.

int opfx()

Performs output prefix actions. If the error state of the ostream object is nonzero, it returns immediately. If the value of the ostream object's tie() function is not null, it is flushed. The function returns nonzero except when the error state of the ostream object is nonzero.

void osfx()

Performs output suffix actions before returning from inserters. If ios::unitbuf is set, this function flushes the ostream object. If ios::stdio is set, the function flushes stdout and stderr. It is called by all predefined inserters, and should also be called by user-defined inserters after any direct manipulation of the streambuf object. It is not called by the binary output functions.

ostream &ostream::put(char c)

Inserts c into the ostream object's rdbuf() function. It sets the error state if the insertion fails.

ostream &seekp(streampos)

ostream &seekp(streamoff, seek_dir)

Repositions the put pointer of the ostream object's rdbuf() function.

streampos tellp()

Returns the current position of the put pointer belonging to the ostream object's rdbuf() function.

ostream &write(const char *ptr, int n)

ostream &write(const unsigned char *ptr, int n)

Inserts the n characters starting at ptr into the ostream object's rdbuf() function. These characters may include zeros; that is, ptr need not be a null-terminated string.

Example


char c = 'Z'; 
cout.put(c); 

Inserts a single character (Z) into cout.


SEE ALSO

ostream_withassign class
ostrstream class

ostream_withassign class

Adds an assignment operator and a constructor with no operands to the ostream class.

HEADER FILE

#include <iostream.hxx>

Alternative Header

#include <iostream.h>


DECLARATION


class ostream_withassign: public ostream 
{ 
public: 
                        ostream_withassign(); 
    virtual             ~ostream_withassign(); 
 
    ostream_withassign  &operator=(ostream &); 
    ostream_withassign  &operator=(streambuf *); 
}; 
 


DESCRIPTION

This class adds an assignment operator and a constructor with no operands to the ostream class.

CONSTRUCTORS AND DESTRUCTORS

ostream_withassign()

Constructs an ostream_withassign object; it does no initialization.

virtual ~ostream_withassign()

Deletes an ostream_withassign object; no user action is required.

OVERLOADED OPERATORS

ostream_withassign &operator = (ostream &s)

Associates s.rdbuf() with the ostream_withassign object and initializes the entire state of that object.

ostream_withassign &operator = (streambuf *sb)

Associates sb with an ostream_withassign object and initializes the entire state of that object.

ostrstream class

Supports the insertion of characters into arrays of bytes in memory.

HEADER FILE

#include <strstream.hxx>

Alternative Header

#include <strstream.h>


DECLARATION


class ostrstream: public ostream 
{ 
 
public: 
                      ostrstream(); 
                      ostrstream(char *, int, int = ios::out); 
                      ~ostrstream(); 
 
     int              pcount(); 
     strstreambuf     *rdbuf(); 
     char             *str(); 
}; 


DESCRIPTION

This class specializes the ostream class for in-core operations by providing members that insert characters into arrays of bytes in memory.

CONSTRUCTORS AND DESTRUCTORS

ostrstream()

Constructs an ostrstream object and dynamically allocates space to hold stored characters.

ostrstream::ostrstream(char *cp, int n, int mode)

Constructs an ostrstream object and stores characters into the array starting at cp and continuing for n bytes. If ios::ate or ios::app is set in mode, the function takes cp to be a null-terminated string and it begins storing at the null character; otherwise, it begins storing at cp. Seeks are allowed anywhere in the array.

~ostrstream()

Deletes an ostrstream object.

MEMBER FUNCTIONS

int pcount()

Returns the number of bytes that have been stored into the buffer. This function is useful when binary data has been stored and the ostrstream object str() function does not point to a null-terminated string.

strstreambuf *rdbuf()

Returns the strstreambuf associated with the ostrstream object.

char *str()

Returns a pointer to the array being used and freezes the array. After str() has been called, the effect of storing more characters into the strstream object is undefined. If the strstream object was constructed with an explicit array, the function returns a pointer to the array; otherwise, it returns a pointer to a dynamically allocated area. Until str() is called, deleting the dynamically allocated area is the responsibility of the strstream object. After str() returns, dynamic allocation becomes the responsibility of the user program.

Example


char *bptr = bf.str()                                    

Initializes the variable bptr with the address of the array associated with the ostrstream object bf. This lets you manipulate the array through bptr just as you would any character array.


SAPP(TYPE) class

Defines parameterized applicators for an ios object.

HEADER FILE

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>


COMPILE-TIME PARAMETER

TYPE---The type of the ios object. It must be an identifier.

DECLARATION


class SAPP(TYPE) 
 
{ 
public: 
    SAPP(TYPE)(ios &(*f)(ios &, TYPE)); 
    SMANIP(TYPE) operator()(TYPE a); 
}; 


CONSTRUCTOR

SAPP(TYPE)(ios &(*f)(ios &, TYPE))

Creates an applicator.

OPERATOR

SMANIP(TYPE) operator () (TYPE a)

Casts an object of type a into a manipulator function for an istream or ostream object.

SEE ALSO

SMANIP(TYPE) class

SMANIP(TYPE) class

Defines parameterized manipulators for an ios object.

HEADER FILE

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>


COMPILE-TIME PARAMETER

TYPE---The type of the ios object. It must be an identifier.

DECLARATION


class SMANIP(TYPE) 
{ 
public: 
    SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a); 
    friend istream &operator>>(istream &i, SMANIP(TYPE) &m); 
    friend ostream &operator<<(ostream &o, SMANIP(TYPE) &m); 
}; 


DESCRIPTION

These manipulators serve the ios 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 ios class.

In its simplest form, a manipulator takes an ios& argument, operates on it in some way, and returns it.


CONSTRUCTOR

SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a)

Creates a manipulator.

OPERATORS

ostream &operator << (ostream &o, SMANIP(TYPE) &m)

Sends data to an ostream object.

istream &operator >> (istream &i, SMANIP(TYPE) &m)

Takes data from an istream object.

stdiobuf class

Provides input/output facilities through stdio FILE.

HEADER FILE

#include <stdiostream.hxx>

Alternative Header

#include <stdiostream.h>


DECLARATION


class stdiobuf: public streambuf 
{ 
public: 
                        stdiobuf(FILE *f); 
 
    virtual int         overflow(int = ); 
    virtual streampos   seekoff(streamoff, seek_dir, int mode); 
    FILE                *stdiofile(); 
    virtual int         sync(); 
    virtual int         underflow(); 
}; 


DESCRIPTION

This class specializes the streambuf class for stdio FILE. It uses unbuffered mode causing all operations to be reflected immediately in the stdio FILE.

CONSTRUCTOR

stdiobuf(FILE *f)

Constructs an empty stdiobuf object and connects it to the stdio FILE that the argument f points to.


MEMBER FUNCTIONS

virtual int overflow(int c)

Called to consume characters. If c is not EOF, this function must also either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != EOF) store c using sputc(). The overflow(c) function should return EOF to indicate an error; otherwise, it should return something else.

virtual streampos seekoff(streamoff off, seek_dir dir, int mode)

Repositions the abstract get and put pointers (not pptr() and gptr()). mode specifies whether to modify the put pointer (ios::out bit set), the get pointer, or both (ios::in bit set). off is interpreted as a byte offset. For the meanings of dir, see the explanation of the enumerated type seek_dir in class ios.

A class derived from streambuf is not required to support repositioning. If the derived class does not, then seekoff() should return EOF. If the derived class does support repositioning, seekoff() should return the new position or EOF on error.

FILE *stdiofile()

Returns a pointer to the stdio FILE associated with the stdiobuf object.

virtual int sync()

Should consume any characters stored into the put area and, if possible, give back to the source any characters in the get area that have not been fetched. When sync() returns, there should be no unconsumed characters and the get area should be empty. If some kind of failure occurs, the function should return EOF.

virtual int underflow()

Called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

stdiostream class

Specializes the iostream class for stdio FILE.

HEADER FILE

#include <stdiostream.hxx>

Alternative Header

#include <stdiostream.h>


DECLARATION


class stdiostream: public iostream 
{ 
public: 
                stdiostream(FILE *f); 
                ~stdiostream(); 
 
    stdiobuf    *rdbuf(); 
}; 


DESCRIPTION

This class specializes the iostream class for stdio FILE, and causes that class to use a stdiobuf object as its associated streambuf object.


Previous Next Contents Index