United States

Compaq C++

# Compaq C++
Class Library Reference Manual

Previous | Contents | Index

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

> In most other existing implementations, the `stdiostream` class is derived directly from the `ios` class rather than from the `iostream` class. Deriving the `stdiostream` class from the `ios` class limits its usefulness and, therefore, can be considered a historical mistake. Nevertheless, for maximum portability, you should use only those `stdiostream` features that originate from the `ios` class and avoid the features supplied by the `iostream` class.

## Constructors and Destructors

> ### stdiostream(FILE *f)

> Constructs a `stdiostream` object whose `stdiobuf` object is associated with the `FILE` parameter that the f argument points to.

> ### ~stdiostream()

> Deletes a `stdiostream` object and closes the associated `stdiobuf` object.

## Member Function

> ### stdiobuf *rdbuf()

> Returns a pointer to the `stdiobuf` object associated with the `stdiostream` object.

# streambuf class

> Provides the buffer mechanism for streams.

## Header File

> `#include <iostream.hxx>`

> Alternative Header

> `#include <iostream.h>`

## Declaration

>     class streambuf
>     {
>     public:
>                             streambuf();
>                             streambuf(char *p, int len);
>         virtual             ~streambuf();
>         void                dbp();

>     protected:
>         int                 allocate();
>         char                *base();
>         int                 blen();

>         virtual int  doallocate();

>         char                *eback();
>         char                *ebuf();
>         char                *egptr();
>         char                *epptr();
>         void                gbump(int n);
>         char                *gptr();
>         char                *pbase();
>         void                pbump(int n);
>         char                *pptr();
>         void                setb(char *b, char *eb, int a = 0);
>         void                setg(char *eb, char *g, char *eg);
>         void                setp(char *p, char *ep);
>         int                 unbuffered();
>         void                unbuffered(int n);

>     public:
>         int                 fd();
>         void                fd(int);
>         FILE                *fp();
>         void                fp(FILE *);
>         int                 in_avail();
>         int                 out_waiting();

>         virtual int         overflow(int c = EOF);
>         virtual int         pbackfail(int c);

>         int                 sbumpc();

>         virtual streampos   seekpos(streampos, int = ios::in
>                             | ios::out);
>         virtual streampos   seekoff(streamoff, seek_dir,
>                             int = ios::in | ios::out);
>         virtual streambuf   *setbuf(char *ptr, int len);

>         streambuf           *setbuf(unsigned char *ptr, int len);
>         streambuf           *setbuf(char *ptr, int len, int i);
>         int                 sgetc();
>         int                 sgetn(char *ptr, int n);
>         int                 snextc();
>         int                 sputbackc(char c);
>         int                 sputc(int c = EOF);
>         int                 sputn(const char *s, int n);
>         void                stossc();

>         virtual int         sync();
>         virtual int         underflow();
>     };

## Description

> This class supports buffers into which you can insert (put) or extract (get) characters. It contains only the basic members for manipulating the characters. Also, several of its member functions are virtual; to implement virtual functions, you typically use a class derived from the `streambuf` class.

> The protected members of the `streambuf` class present an interface to derived classes organized around the get, put, and reserve areas (arrays of bytes), which are managed cooperatively by the base and derived classes.

> The reserve area is a sequence of characters with an associated get pointer, put pointer, or both. This area serves mainly as a resource in which to allocate space for the put and get areas. As characters enter and exit the reserve area, the put and get areas change but the reserve area remains fixed. A collection of character pointer values defines the three areas. These pointers infer a boundary condition; therefore, it may be helpful to consider such pointers as pointing just before the byte, even though they point directly at it.

> Classes derived from `streambuf` vary in their handling of the get and put pointers. The simplest are unidirectional buffers that permit only get and put operations. Such classes serve as producers and consumers of characters. Queue-like buffers (such as `strstream` and `strstreambuf` ) have a put and a get pointer that move independently of each other. In such buffers, stored characters are queued until later fetched. File-like buffers (such as `filebuf` ) allow both get and put operations but have their get and put pointers linked together, so that when one pointer moves so does the other.

> You can call virtual functions to manage the collections of characters in the get and put areas. Services supplied by virtual functions include fetching more characters from an ultimate producer and flushing a collection of characters to an ultimate consumer.

> If your program expects a buffer to be allocated when none was allocated, then the iostream package allocates a default buffer.

## Data Member

> ### void dbp()

> Writes directly on file descriptor 1 information in ASCII about the state of the buffer. It is intended for debugging and nothing is specified about the form of the output. What it prints out can be understood only in relation to the protected interface, but `dbp()` is a public domain function so that it can be called anywhere during debugging.

## Constructors and Destructors

> ### streambuf()

> Constructs an empty buffer corresponding to an empty sequence.

> ### streambuf(char* base, int length)

> Constructs an empty buffer and then sets up the reserve area to be length bytes long starting at base.

> ### virtual ~streambuf()

> Deletes the reserve area if one is allocated.

## Member Functions

> ### int allocate()

> Tries to set up a reserve area. If a reserve area already exists or is unbuffered, it returns 0 without doing anything. If the attempt to allocate space succeeds, `allocate()` returns 1; otherwise, it returns `EOF` . No nonvirtual member functions of `streambuf` call `allocate()` .

> ### char *base()

> Returns a pointer to the first byte of the reserve area. The space between `base()` and `ebuf()` is the reserve area.

> ### int blen()

> Returns the size, in type `char` , of the current reserve area.

> ### virtual int doallocate()

> In `streambuf` , it tries to allocate a reserve area using the `new` operator.

> In classes derived from `streambuf` , this function is called when `allocate()` determines that space is needed. `doallocate()` is required to call `setb()` , to provide a reserve area, or to return `EOF` if it cannot. It is called only if both `unbuffered()` and `base()` are 0.

> ### char *eback()

> Returns a pointer to a lower bound on `gptr()` . The space between `eback()` and `gptr()` is available for putback operations.

> ### char *ebuf()

> Returns a pointer to the byte after the last byte of the reserve area.

> ### char *egptr()

> Returns a pointer to the byte after the last byte of the get area.

> ### char *epptr()

> Returns a pointer to the byte after the last byte of the put area.

> ### int fd()

> Returns the file descriptor associated with the `streambuf` object, if any; otherwise, it returns --1.

> ### void fd(int f)

> Sets the file descriptor associated with the `streambuf` object to f.

> ### FILE *fp()

> Returns the file pointer associated with the `streambuf` object, if any; otherwise, it returns 0.

> ### void fp(FILE *f)

> Sets the file pointer associated with the `streambuf` object to f.

> ### void gbump(int n)

> Increments `gptr()` by n, which can be a positive or a negative number. No checks are made on whether the new value of `gptr()` is in bounds.

> ### char *gptr()

> Returns a pointer to the first byte of the get area. The characters available are those between `gptr()` and `egptr()` . The next character fetched will be `*gptr()` unless `egptr()` is less than or equal to `gptr()` .

> ### int in_avail()

> Returns the number of characters immediately available in the get area for fetching. This number is the number of characters that can be fetched with confidence that an error will not be reported.

> ### int out_waiting()

> Returns the number of characters in the put area that have not been consumed (by the ultimate consumer).

> ### virtual int overflow(int c)

> In `streambuf` , this function should be treated as if its behavior is undefined; classes derived from `streambuf` should always define it.

> In classes derived from `streambuf` , it is called to consume characters. If c is not `EOF` , `overflow(c)` also must 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()` . `overflow(c)` should return `EOF` to indicate an error; otherwise, it should return something else.

> ### virtual int pbackfail(int c)

> In `streambuf` , this function always returns `EOF` .

> In classes derived from `streambuf` , this function is called when `eback()` equals `gptr()` and an attempt has been made to put c back. If this situation can be managed (for example, by repositioning an external file), `pbackfail(c)` should return c; otherwise, it should return `EOF` .

> ### char *pbase()

> Returns a pointer to the put area base. Characters between `pbase()` and `pptr()` are stored into the buffer but are not yet consumed.

> ### void pbump(int n)

> Increments `pptr()` by n, which can be positive or negative. No checks are made on whether the new value of `pptr()` is in bounds.

> ### char *pptr()

> Returns a pointer to the first byte of the put area. The space between `pptr()` and `epptr()` is the put area.

> ### int sbumpc()

> Moves the get pointer forward one character and returns the character it moved past. The function returns `EOF` if the get pointer is currently at the end of the sequence.

> ### virtual streampos seekoff(streamoff off, (ios::)seek_dir dir, int mode)

> In `streambuf` , this function returns `EOF` .

> In classes derived from `streambuf` , it repositions the abstract get and put pointers (not `pptr()` and `gptr()` ). mode specifies whether to modify the put pointer ( `ios::out` bit set) or the get pointer ( `ios::in` bit set) or both pointers. off is interpreted as a byte offset (it is a signed value). 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.

> ### virtual streampos seekpos(streampos pos, int mode)

> In `streambuf` , this function returns `seekoff(streamoff(pos), ios::beg, mode)` . To define seeking in a derived class, you can often define `seekoff()` and use the inherited `streambuf::seekpos` .

> In classes derived from `streambuf` , this function repositions the `streambuf` get pointer, put pointer, or both, to pos. mode specifies the affected pointers. `seekpos()` returns the argument pos or `EOF` if the class does not support repositioning or if an error occurs. `streampos(0)` signifies the beginning of the file; `streampos(EOF)` indicates an error.

> ### void setb(char *b, char *eb, int a)

> Sets `base()` to b and `ebuf()` to eb. The a argument controls whether the reserve area will be subject to automatic deletion. If a is nonzero, then b will be deleted when `base()` is changed by another call to `setb()` , or when the destructor is called for the `streambuf` object. If b and eb are both null, then the reserve area effectively does not exist. If b is nonnull, a reserve area exists even if eb is less than b (in which case the reserve area has 0 length).

> ### virtual streambuf *setbuf(char *ptr, int len)

> ### streambuf *setbuf(unsigned char *ptr, int len)

> In `streambuf` , this function honors the request for a reserve area if there is none.

> In classes derived from `streambuf` , this function offers for use as a reserve area the array at ptr with len bytes. Normally, if ptr or len is 0, the action is interpreted as a request to make the `streambuf` object unbuffered. The derived class has the choice of using or not using this area by accepting or ignoring the request. `setbuf()` should return a reference to the `streambuf` object if the derived class honors the request; otherwise, it should return 0.

> ### streambuf *setbuf(char *ptr, int len, int i)

> Offers the len bytes starting at ptr as the reserve area. If ptr is null, or len is 0 or negative, then the function requests an unbuffered state. Whether the offered area is used or a request for an unbuffered state is honored depends on details of the derived class. `setbuf()` normally returns a reference to the `streambuf` object, but if the derived class does not accept the offer or honor the request, `setbuf()` returns 0.

> ### void setg(char *eb, char *g, char *eg)

> Sets `eback()` to eb, `gptr()` to g, and `egptr()` to eg.

> ### void setp(char *p, char *ep)

> Sets `base()` and `pptr()` to p and `epptr()` to ep.

> ### int sgetc()

> Returns the character after the get pointer; it does not move the get pointer. It returns `EOF` if no character is available.

> ### int sgetn(char *ptr, int n)

> Fetches n characters following the get pointer and copies them to the area starting at ptr. If fewer than n characters occur before the end of the sequence, `sgetn()` fetches the characters that remain. It repositions the get pointer after the fetched characters and returns the number of characters fetched.

> ### int snextc()

> Moves the get pointer forward one character and returns the character after the new position. If the pointer is at the end of the sequence, either before or after moving forward, the function returns `EOF` .

> ### int sputbackc(char c)

> Moves the get pointer back one character. c must be the current content of the sequence just before the get pointer. The underlying mechanism may back up the get pointer or may rearrange its internal data structures so that c is saved. The effect is undefined if c is not the character before the get pointer. The function returns `EOF` , by calling `pbackfail()` , when it fails. The conditions under which it can fail depend on the details of the derived class.

> ### int sputc(int c)

> Stores c after the put pointer and moves the put pointer past the stored character (usually this extends the sequence). The function returns `EOF` when an error occurs. Conditions that can cause errors depend on the derived class.

> ### int sputn(const char *s, int n)

> Stores after the put pointer the n characters starting at s, and moves the put pointer past them. It returns the number of characters successfully stored. Normally n characters are successfully stored, but fewer characters may be stored when errors occur.

> ### void stossc()

> Moves the get pointer ahead one character. If the pointer started at the end of the sequence, `stossc()` has no effect.

> ### virtual int sync()

> In `streambuf` this function returns 0 if the get area is empty and no unconsumed characters are present; otherwise, it returns `EOF` .

> Previous | Next | Contents | Index

> privacy and legal statement