Top: Streams: instm

#include <pstreams.h>

bool instm::get_eof();
bool instm::get_eol();
char instm::preview();
char instm::get();

string instm::token(const cset& chars [, int limit ] );
int    instm::token(const cset& chars, char* buf, int size);
string instm::line();
string instm::line( [ int limit ] );
int    instm::line(char* buf, int size);
void   instm::skipline();
void   instm::skiptoken(const cset& chars);
int    instm::skip(int numbytes);

int instm::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 different 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).

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. This method does not require buffering.

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