This section describes the istream member functions and related functions for formatted and unformatted input. #include <iostream.h> typedef long streamoff, streampos; class ios enum bin, tabexp}; /* Format control flags */ skipws=01, }; // see ios for other class members ... }; class istream : virtual public ios { public: istream(streambuf*);
}; class istream_withassign : public istream { public:
}; extern istream_withassign cin;
| |||||||||||||
istreams support interpretation of characters fetched from an associated streambuf. These are commonly referred to as input or extraction operations. In the following descriptions assume that:
Constructors and assignmentistream(streambuf* sb) Initializes ios state variables and associates buffer sb with the istream. istream_withassign() Does no initialization. istream_withassign inswa; Associates sb with inswa and initializes the entire state of inswa. istream_withassign inswa; Associates ins.rdbuf() with inswa and initializes the entire state of inswa. Input prefix functionint i = ins.ipfx(int need) If ins’s error state is non-zero, returns zero immediately. If necessary (even if it isnon-null), any ios tied to ins is flushed (see the description ios::tie() in section ios. Flushing is considered necessary if either need==0 or if there are fewer thanneed characters immediately available. If ios::skipws is set in ins.flags() and need iszero, then leading whitespace characters are extracted from ins. ipfx() returns zero if an error occurs while skipping whitespace; otherwise it returnsnon-zero. Formatted input functions call ipfx(0), while unformatted input functions call ipfx(1);see below. Formatted input functions (extractors)istream ins; 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 did not match 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 and the type of x. Extractors are defined for thefollowing types, with conversion rules as described below. x might have one of the following types: 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 char&, unsigned char& A character is extracted and stored in x. short&, unsigned short&, Characters are extracted and converted to an integral value according to theconversion 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 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. Note skipws should not be unset during the extraction of numerical values. Otherwise an error can occur. The type and name 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 functionsThese functions call ipfx(1) and proceed only if it returns non-zero: istream * insp=&ins.get(char * ptr, int len, char 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. istream * insp=&ins.get(char & c) Extracts a single character and stores it in c. istream * insp=&ins.get(streambuf & sb, char delim) Extracts characters from ins.rdbuf() and stores them into sb. It stops if it encounters end of file, or a store into sb fails, or it encounters delim (which it leaves in ins). ios::failbit is set if it stops because the store into sb fails. int i=ins.get(). Extracts a character and returns it. i is EOF if extraction encounters end of file.ios::failbit is never set. istream * insp=&ins.getline(char * ptr, int len, int delim) Does the same thing as ins.get(char* ptr, int len, char 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. istream * insp=&ins.ignore(int n, char 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. istream * insp=&ins.read(char * ptr, int 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 membersint 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. int 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. istream* insp=&ins.putback(char c) Attempts to back up ins.rdbuf() so that the character c can be read later. 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(). However, it returns without doing anything if the error state is non-zero. int 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 positioningistream& insp=ins.seekg(streamoff off, ios::seek_dir dir) Repositions ins.rdbuf()’s get pointer. See sbufpub for a discussion of positioning. istream& insp=ins.seekg(streampos pos) Repositions ins.rdbuf()’s get pointer. See sbufpub for a discussion of positioning. streampos pos=ins.tellg() The current position of ios.rdbuf()’s get pointer. See sbufpub for a discussion of positioning. Manipulatorsins>>ws Extracts whitespace characters. ins>>dec Sets the conversion base format flag to 10. See ios. ins>>hex Sets the conversion base format flag to 16. See ios. ins>>oct Sets the conversion base format flag to 8. See ios. | |||||||||||||
EXAMPLE | The following program reads one line of text, and then prints it in the reverse order. #include <iostream.h>
const int N = 80;
char a[ N]; /* text buffer */
int main()
{
int i;
cout << " Please enter text :\n";
cin.unsetf(ios::skipws);
cin.getline(text, N); /* get at most N characters */
i = cin.gcount() - 1;
while (i)
{
cout << text [--i]; /* prints line in the reverse */
/* order */
}
return 0; /* successful return */
}
The result of executing the program is: Please enter text : TOM MOT % CCM0998 CPU time used: 0.0024 seconds | ||||||||||||
BUGS | There is no overflow detection on conversion of integers. | ||||||||||||
SEE ALSO | |||||||||||||