PTypes: streams: instm

Top: Streams: instm

>     #include <pstreams.h>

>     class instm: iobase {
>         bool   get_eof();
>         bool   get_eol();
>         char   preview();
>         char   get();
>         void   putback();
>         string token(const cset& chars [, int limit ] );
>         int    token(const cset& chars, char* buf, int size);
>         string line();
>         string line( [ int limit ] );
>         int    line(char* buf, int size);
>         void   skipline();
>         void   skiptoken(const cset& chars);
>         int    skip(int numbytes);
>         int    read(char* buf, int count);
>     }

This class implements the basic functionality of input streams. Instm is derived from iobase and inherits all its public methods and properties. All methods of instm except read() and get_eof() require buffering.

bool instm::get_eof() returns true if the end of file is reached.

bool instm::get_eol() returns true if the file pointer is currently at the end of a line. Since operating systems use different end-of-line codes or combinations of codes, it is recommended to check the end-of-line status using this property and skip the end-of-line sequence by calling skipline() method.

char instm::preview() returns the next character from the stream but does not advance the file pointer. If the pointer is at the end of file, preview() returns eofchar (null character).

char instm::get() returns the next character from the stream. If an attempt is made to read beyond the file (i.e. if the property eof is set), this method returns eofchar (null character).

void instm::putback() puts the last retrieved character back to the stream; a faster equivalent to seek(-1, IO_CURRENT). This function can be called only after a call to get() if the latter did not return an eof character.

string instm::token(const cset& chars [, int limit ] ) reads the next token that only contains characters of the given set chars. The optional parameter limit specifies the maximum number of bytes to read. If the token exceeds the limit, an exception (estream*) is thrown with error number ERANGE.

int instm::token(const cset& chars, char* buf, int size) -- this version of token() reads the next token to the given buffer buf. The number of characters is limited to size. This method returns the actual number of characters read from the stream which can not be greater than size. Unlike the other version of token(), does not throw exceptions if the token exceeds the limit, but rather truncates it to size. Note: this function does not put a terminating null symbol in the buffer.

string instm::line( [ int limit ] ) reads the current line from the stream. The end-of-line code(s) are not included in the returning value, however, line() skips them and sets the file pointer at the beginning of the next line. The optional parameter limit specifies the maximum number of bytes to read. If the token exceeds the limit, an exception (estream*) is thrown with error number ERANGE.

int instm::line(char* buf, int size) -- this version of line() reads the next line from the stream to the buffer buf. The number of characters is limited to size. This method returns the actual number of characters read from the stream which can not be greater than size. Unlike the other version of line(), does not throw exceptions if the token exceeds the limit, but rather truncates it to size. Note: this function does not put a terminating null symbol in the buffer.

void instm::skiptoken(const cset& chars) works like previous versions of token() except that the token string is not returned. Can be safely used to skip very large tokens.

void instm::skipline() skips the current line and sets the file pointer at the beginning of the next line.

int instm::skip(int numbytes) skips the specified number of bytes from the input stream.

int instm::read(char* buf, int count) reads count bytes from the stream and stores them in the buffer buf. Returns the number of bytes actually read. This method does not require buffering.

See also: iobase, outstm, string, cset, Error handling

PTypes home