istream(C++)

Syntax

#include <iostream.h>

typedef long streamoff, streampos;
class ios {
public:
	enum	seek_dir { beg, cur, end };
	enum	open_mode { in, out, ate, app, trunc, nocreate, noreplace };
	/* flags for controlling format */
	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 };
	// and lots of other stuff, see ios(C++) ...
} ;

class istream : public ios {
public:
		istream(streambuf*);
	int	gcount();
	istream&	get(char* ptr, int len, char delim='\n');
	istream&	get(unsigned char* ptr, int len, char delim='\n');

	istream&	get(unsigned char&);
	istream&	get(char&);
	istream&	get(streambuf& sb, char delim ='\n');
	int	get();
	istream&	getline(char* ptr, int len, char delim='\n');
	istream&	getline(unsigned char* ptr, int len,
				char delim='\n');
	istream&	ignore(int len=1,int delim=EOF);
	int	ipfx(int need=0);
	int	peek();
	istream&	putback(char);
	istream&	read(char* s, int n);
	istream&	read(unsigned char* s, int n);
	istream&	seekg(streampos);
	istream&	seekg(streamoff, seek_dir);
	int	sync();
	streampos	tellg();

	istream&	operator>>(char*);
	istream&	operator>>(char&);
	istream&	operator>>(short&);
	istream&	operator>>(int&);
	istream&	operator>>(long&);
	istream&	operator>>(float&);
	istream&	operator>>(double&);
	istream&	operator>>(unsigned char*);
	istream&	operator>>(unsigned char&);
	istream&	operator>>(unsigned short&);
	istream&	operator>>(unsigned int&);
	istream&	operator>>(unsigned long&);
	istream&	operator>>(streambuf*);
	istream&	operator>>(istream& (*)(istream&));
	istream&	operator>>(ios& (*)(ios&));
};

class istream_withassign : public istream {
		istream_withassign();
	istream&	operator=(istream&);
	istream&	operator=(streambuf*);
};

extern istream_withassign cin;

istream&	ws(istream&)	;
ios&	dec(ios&) ;
ios&	hex(ios&) ;
ios&	oct(ios&) ;

Description

In the following descriptions assume that

• ins is an istream

• inwa is an istream_withassign

• insp is an istream*

• c is a char&

• delim is a char

• ptr is a char* or unsigned char*

• sb is a streambuf&

• i, n, len, d, and need are ints

• pos is a streampos

• off is a streamoff

• dir is a seek_dir

• manip is a function with type istream& (*)(istream&)

Constructors and assignment

istream(sb)

Initializes ios state variables and associates buffer sb with the istream.

istream_withassign()

Does no initialization.

inswa=sb

Associates sb with inswa and initializes the entire state of inswa.

inswa=ins

Associates ins->rdbuf() with inswa and initializes the entire state of inswa.

Input prefix function

i=ins.ipfx(need)

If ins's error state is non-zero, returns zero immediately. If necessary (and if it is non-null), any ios tied to ins is flushed (see the description ios::tie() in ios(C++)). Flushing is considered necessary if either need==0 or if there are fewer than need characters immediately available. If ios::skipws is set in ins.flags() and need is zero, then leading whitespace characters are extracted from ins. ipfx() returns zero if an error occurs while skipping whitespace; otherwise it returns non-zero.

Formatted input functions call ipfx(0), while unformatted input functions call ipfx(1); see below.

Formatted input functions (extractors)

ins>>x

Calls ipfx(0) and if that returns non-zero, extracts characters from ins and converts them according to the type of x. It stores the converted value in x. Errors are indicated by setting the error state of ins. ios::failbit means that characters in ins were not a representation of the required type. ios::badbit indicates that attempts to extract characters failed. ins is always returned.

The details of conversion depend on the values of ins's format state flags and variables (see ios(C++)) and the type of x. Except that extractions that use width reset it to 0, the extraction operators do not change the value of ostream's format state. Extractors are defined for the following types, with conversion rules as described below.

char*, unsigned char*

Characters are stored in the array pointed at by x until a whitespace character is found in ins. The terminating whitespace is left in ins. If ins.width() is non-zero it is taken to be the size of the array, and no more than ins.width()-1 characters are extracted. A terminating null character (0) is always stored (even when nothing else is done because of ins's error status). ins.width() is reset to 0.

char&, unsigned char&

A character is extracted and stored in x.

short&, unsigned short&,
int&, unsigned int&,
long&, unsigned long&

Characters are extracted and converted to an integral value according to the conversion specified in ins's format flags. Converted characters are stored in x. The first character may be a sign (+ or -). After that, if ios::oct, ios::dec, or ios::hex is set in ins.flags(), the conversion is octal, decimal, or hexadecimal, respectively. Conversion is terminated by the first ``non-digit,'' which is left in ins. Octal digits are the characters ``0'' to ``7''. Decimal digits are the octal digits plus ``8'' and ``9''. Hexadecimal digits are the decimal digits plus the letters ``a'' through ``f'' (in either upper or lower case). If none of the conversion base format flags is set, then the number is interpreted according to C++ lexical conventions. That is, if the first characters (after the optional sign) are ``0x'' or ``0X'' a hexadecimal conversion is performed on following hexadecimal digits. Otherwise, if the first character is a ``0'', an octal conversion is performed, and in all other cases a decimal conversion is performed. ios::failbit is set if there are no digits (not counting the ``0'' in ``0x'' or ``0X'' during hex conversion) available.

float&, double&

Converts the characters according to C++ syntax for a float or double, and stores the result in x. ios::failbit is set if there are no digits available in ins or if it does not begin with a well formed floating point number.

The type and name (operator>>) of the extraction operations are chosen to give a convenient syntax for sequences of input operations. The operator overloading of C++ permits extraction functions to be declared for user-defined classes. These operations can then be used with the same syntax as the member functions described here.

ins>>sb

If ios.ipfx(0) returns non-zero, extracts characters from ios and inserts them into sb. Extraction stops when EOF is reached. Always returns ins.

Unformatted input functions

insp=&ins.get(ptr,len,delim)

Extracts characters and stores them in the byte array beginning at ptr and extending for len bytes. Extraction stops when delim is encountered (delim is left in ins and not stored), when ins has no more characters, or when the array has only one byte left. get always stores a terminating null, even if it doesn't extract any characters from ins because of its error status. ios::failbit is set only if get encounters an end of file before it stores any characters.

insp=&ins.get(c)

Extracts a single character and stores it in c.

insp=&ins.get(sb,delim)

Extracts characters from ins.rdbuf() and stores them into sb. It stops if it encounters end of file or if a store into sb fails or if it encounters delim (which it leaves in ins). ios::failbit is set if it stops because the store into sb fails.

i=ins.get().

Extracts a character and returns it. i is EOF if extraction encounters end of file. ios::failbit is never set.

insp=&ins.getline(ptr,len,delim)

Does the same thing as ins.get(ptr,len,delim) with the exception that it extracts a terminating delim character from ins. In case delim occurs when exactly len characters have been extracted, termination is treated as being due to the array being filled, and this delim is left in ins.

insp=&ins.ignore(n,d)

Extracts and throws away up to n characters. Extraction stops prematurely if d is extracted or end of file is reached. If d is EOF it can never cause termination.

insp=&ins.read(ptr,n)

Extracts n characters and stores them in the array beginning at ptr. If end of file is reached before n characters have been extracted, read stores whatever it can extract and sets ios::failbit. The number of characters extracted can be determined via ins.gcount().

Other members

i=ins.gcount()

Returns the number of characters extracted by the last unformatted input function. Formatted input functions may call unformatted input functions and thereby reset this number.

i=ins.peek()

Begins by calling ins.ipfx(1). If that call returns zero or if ins is at end of file, it returns EOF. Otherwise it returns the next character without extracting it.

insp=&ins.putback(c)

Attempts to back up ins.rdbuf(). c must be the character before ins.rdbuf()'s get pointer. (Unless other activity is modifying ins.rdbuf() this is the last character extracted from ins.) If it is not, the effect is undefined. putback may fail (and set the error state). Although it is a member of istream, putback never extracts characters, so it does not call ipfx. It will, however, return without doing anything if the error state is non-zero.

i=&ins.sync()

Establishes consistency between internal data structures and the external source of characters. Calls ins.rdbuf()->sync(), which is a virtual function, so the details depend on the derived class. Returns EOF to indicate errors.

ins>>manip

Equivalent to manip(ins). Syntactically this looks like an extractor operation, but semantically it does an arbitrary operation rather than converting a sequence of characters and storing the result in manip. A predefined manipulator, ws, is described below.

Member functions related to positioning

insp=&ins.seekg(off,dir)

Repositions ins.rdbuf()'s get pointer. See sbuf.pub(C++) for a discussion of positioning.

insp=&ins.seekg(pos)

Repositions ins.rdbuf()'s get pointer. See sbuf.pub(C++) for a discussion of positioning.

pos=ins.tellg()

The current position of ios.rdbuf()'s get pointer. See sbuf.pub(C++) for a discussion of positioning.

Manipulator

ins>>ws

Extracts whitespace characters.

ins>>dec

Sets the conversion base format flag to 10. See ios(C++).

ins>>hex

Sets the conversion base format flag to 16. See ios(C++).

ins>>oct

Sets the conversion base format flag to 8. See ios(C++).

Caveats

See also