.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)istream.3 1.3 93/06/08 SMI; .\" .TH ISTREAM 3CC4 "18 June 1998" .\" .SH NAME istream \- formatted and unformatted input .SH SYNOPSIS .LP .nf .ft B #include .sp .5v typedef long streampos; typedef long streamoff; .sp .5v class unsafe_ios { public: // exported types // stream operation mode enum open_mode { in = 0x01, // open for reading out = 0x02, // open for writing ate = 0x04, // seek to eof upon original open app = 0x08, // append mode: all additions at eof trunc = 0x10, // truncate file if already exists nocreate = 0x20, // open fails if file doesn't exist noreplace= 0x40 // open fails if file already exists }; // stream seek direction enum seek_dir { beg=0, cur=1, end=2 }; // formatting flags enum { skipws = 0x0001, // skip whitespace on input left = 0x0002, // left-adjust output right = 0x0004, // right-adjust output internal = 0x0008, // padding after sign or base indicator dec = 0x0010, // decimal conversion oct = 0x0020, // octal conversion hex = 0x0040, // hexidecimal conversion showbase = 0x0080, // use base indicator on output showpoint = 0x0100, // force decimal point (floating output) uppercase = 0x0200, // upper-case hex output showpos = 0x0400, // add '+' to positive integers scientific= 0x0800, // use 1.2345E2 floating notation fixed = 0x1000, // use 123.45 floating notation unitbuf = 0x2000, // flush all streams after insertion stdio = 0x4000 // flush stdout, stderr after insertion }; .sp .5v // \fIsee \fBios\fR(3CC4)\fI for remainder ...\fB }; .sp .5v class unsafe_istream : virtual public unsafe_ios { public: // exported functions .sp .5v // unformatted input functions unsafe_istream& read(char* ptr, int count); unsafe_istream& read(unsigned char* ptr, int count); unsafe_istream& get(char* ptr, int count, char delim='\\n'); unsafe_istream& get(streambuf& sbuf, char delim='\\n'); unsafe_istream& get(char& ch); unsafe_istream& get(unsigned char& ch); unsafe_istream& get_line (char *ptr, int count, char delim='\\n'); unsafe_istream& get_line (unsigned char *ptr, int count, char delim='\\n'); int get(); int peek(); unsafe_istream& ignore(int count=1, int delim=EOF); unsafe_istream& putback(char ch); // wide character unsafe_istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\\n'); unsafe_istream& get(wchar_t& wc); unsafe_istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\\n'); unsafe_istream& wignore(count=1, wdelim=WEOF); .sp .5v // other functions int ipfx(int noform=0); int wipfx(int noform=0); // wide character ipfx unsafe_istream& seekg(streampos pos); unsafe_istream& seekg(streamoff offset, unsafe_ios::seek_dir dir); streampos tellg(); int sync(); int gcount(); public: // exported operator functions unsafe_istream& operator>> (char* buf); unsafe_istream& operator>> (unsigned char* buf); unsafe_istream& operator>> (char&); unsafe_istream& operator>> (unsigned char&); unsafe_istream& operator>> (short&); unsafe_istream& operator>> (int&); unsafe_istream& operator>> (long&); unsafe_istream& operator>> (unsigned short&); unsafe_istream& operator>> (unsigned int&); unsafe_istream& operator>> (unsigned long&); unsafe_istream& operator>> (float&); unsafe_istream& operator>> (double&); unsafe_istream& operator>> (streambuf* sbufp); unsafe_istream& operator>> (unsafe_istream& (*manip)(unsafe_istream&)); unsafe_istream& operator>> (unsafe_ios& (*manip)(unsafe_ios&) ); public: // wide character unsafe_istream& operator>>(wchar_t&); unsafe_istream& operator>>(wchar_t*); public: // exported constructors unsafe_istream(streambuf* sbuf); }; .sp .5v class istream : virtual public ios, public unsafe_istream { public: //exported functions // unformatted input functions istream& read(char* ptr, int count); istream& read(unsigned char* ptr, int count); istream& get(char* ptr, int count, char delim='\en'); istream& get(unsigned char* ptr,int count, char delim='\en'); istream& get(unsigned char& ch); istream& get(char& ch); istream& get(streambuf& sb, char delim ='\en'); istream& getline(char* ptr, int count, char delim='\en'); istream& getline(unsigned char* ptr, int count, char delim='\en'); int get(); int peek(); istream& ignore(int len=1,int delim=EOF); istream& putback(char ch); // wide character istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\\n'); istream& get(wchar_t& wc); istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\\n'); istream& wignore(int count=1, wchar_t wdelim=WEOF); wint_t peekw(); // other functions int ipfx(int noform=0); istream& seekg(streampos pos); istream& seekg(streamoff offset, seek_dir dir); streampos tellg(); int sync(); int gcount(); public: // exported operator functions istream& operator>>(char*); istream& operator>>(unsigned char*); istream& operator>>(char&); istream& operator>>(unsigned char&); istream& operator>>(short&); istream& operator>>(int&); istream& operator>>(long&); istream& operator>>(unsigned short&); istream& operator>>(unsigned int&); istream& operator>>(unsigned long&); istream& operator>>(float&); istream& operator>>(double&); istream& operator>>(streambuf*); istream& operator>>(istream& (*)(istream&)); istream& operator>>(ios& (*)(ios&)); public: // wide character istream& operator>>(wchar_t&); istream& operator>>(wchar_t*); public: // exported constructors istream(streambuf*); }; .sp .5v class istream_withassign : public istream { public: istream_withassign(); istream_withassign& operator= (istream&); istream_withassign& operator= (streambuf*); }; .sp .5v extern istream_withassign cin; .sp .5v ios& dec(ios&); ios& hex(ios&); ios& oct(ios&); istream& ws(istream&); unsafe_ios& dec(unsafe_ios&) ; unsafe_ios& hex(unsafe_ios&) ; unsafe_ios& oct(unsafe_ios&) ; unsafe_istream& ws(unsafe_istream&) ; .ft R .fi .\" .SH DESCRIPTION Class .B istream supports formatted and unformatted extraction (input) of data from an associated \fBstreambuf\fR. .\" .PP The .BR istream object and its member functions are protected against access by multiple threads by mutex locks. The .BR unsafe_istream object and its member functions do not implement mutex locking. Aside from this difference, the functionality of .BR istream and .BR unsafe_istream and their respective member functions is identical. For more information on mt-safety, mutex locks and how these relate to iostreams objects, see the "MT-Safe libC Programmers Guide". .SS ENVIRONMENT .SS "Constructors and Assignment" .TP .B istream(sbufp) Associates the \fBstreambuf\fR pointed to by \fBsbufp\fR with the stream and initializes the \fBios\fR state. .TP .B istream_withassign() Performs no initialization. .TP .B "istream_withassign isw = sbufp" Associates the \fBstreambuf\fR pointed to by \fBsbufp\fR with \fBisw\fR and completely initializes \fBisw\fR. .TP .B "istream_withassign isw = istr" The \fBstreambuf\fR associated with \fBistr\fR becomes associated with \fBisw\fR and the constructor completely initializes \fBisw\fR. .\" .SS "About wide character operations" .LP Input functions that produce wide character results set \fBfailbit\fR if they encounter an illegal sequence of bytes. A sequence of bytes is considered illegal if the input function cannot interpret it as multibyte encoding of characters in the current locale. Do not directly follow a multibyte input operation that may peek ahead with a single-byte input operation. A single-byte input operation is allowable after a seek (\fBseekg\fR). \fBstreambufs\fR need only support peeking one byte ahead, so multibyte input operations that peek may buffer "peeked" bytes in the istream itself. \fBseekg\fR and \fBtellg\fR take account of any such internal buffering. .SS "Input prefix function" .TP .B "int i = istr.ipfx(noform)" Performs setup common to all extraction operations. Formatted extractors call \fBipfx(0)\fR; unformatted extractors call \fBipfx(1)\fR. If the error state of \fBistr\fR is non-zero, \fBipfx\fR returns zero immediately. If a stream is \fItied\fR to \fBistr\fR (see \fBtie\fR in \fBios\fR(3CC4)) and \fBnoform\fR is zero, the tied stream is flushed. If the \fBskipws\fR flag is set for the stream and \fBnoform\fR is zero, leading whitespace characters (as defined by \fBiswhite\fR, see .BR ctype (3V)), are skipped. Function \fBipfx\fR returns zero if any error condition is encountered, non-zero otherwise. .\" .TP .B "int i = istr.wipfx(noform)" Wide character extractors use \fBwipfx\fR in place of \fBipfx\fR. This is similar to \fBipfx()\fR, but wipfx() skips over any multibyte space as defined by \fBiswspace\fR where \fBipfx\fR skips over single-byte space characters. Furthermore \fBwipfx()\fR sets \fBios::failbit\fR if encounters an illegal sequence of bytes. This function is not in the proposed ANSI \fBiostreams\fR interface, so avoid calling it directly from application code. .SS "Formatted input (extraction) functions" .LP These call \fBipfx(0)\fR. If it returns zero, no further action takes place. Otherwise, leading whitespace will be stripped if \fBios::skipws\fR is set. If only whitespace is left in the \fBistream\fR, no characters will then remain and the \fBios::failbit\fR will be set. Wide character formatted input functions call \fBwipfx(0)\fR and return with no further action if it returns zero. .TP .B "istr >> sbufp" Extracts characters from \fBistr\fR and inserts them into the \fBstreambuf\fR pointed to by \fBsbufp\fR. This function always returns a reference to \fBistr\fR. You can use this function to copy a stream efficiently, but you should be sure that neither stream is tied. For example: .sp .5 .in +.5i .nf .ft B #include main() { // copy cin to cout cin.tie(0); cout.tie(0); cin >> cout.rdbuf(); // see \fIios(3CC4)\fB for rdbuf return 0; } .ft R .fi .in -5i .TP .BI "istr >> "x Extracts characters from \fBistr\fR and converts them according to the type of \fIx\fR. If \fBipfx\fR returns zero, no characters are extracted and \fIx\fR is unchanged. Any errors encountered are recorded in the error state of \fBistr\fR. In general, \fBios::failbit\fR means that the next available characters were not suitable for the type; for example, leading letters for a numeric type, or leading whitespace for any type. The offending characters are not extracted. In general, \fBios::badbit\fR means that no characters could be extracted; for example, attempting to extract past the end of file. These functions always return a reference to \fBistr\fR. User-written functions should be of the form .ti +.5i .B "istream& operator>> (istream&, SomeType)" .br and should conform to these principles. The type of \fBx\fR and the format state of the \fBistream\fR (see \fBios\fR(3CC4) determine the details of the extraction and conversion. These functions do not change the state of the \fBistream\fR, except that the \fBwidth\fR variable is reset to zero after each formatted extraction. The predefined formatted extractors are as follows: .in +.5i .TP .B "char&, unsigned char&" Extracts one character and stores it in \fBx\fR. .TP .B "wchar_t&" Extracts one multibyte character and stores it in \fBx\fR as a wide character if \fBwipfx(0)\fR succeeds and it does not encounter end-of- file. Sets \fBios::failbit\fR if it encounters an illegal sequence of bytes. .TP .B "short&, unsigned short&" .in -.5i .B "int&, unsigned int&" .br .B "long&, unsigned long&" .in +.5i Extracts characters and converts them to an integral value according to the conversion base in the \fBistream\fR's format flags, and stores the value in \fBx\fR. The first character may be a plus (`+') or minus (`\-') sign. The characters are then treated as decimal, octal, or hexadecimal, if the \fBios::basfield\fR flags are .BR dec ", " oct ", or " hex , respectively. If none of these flags is set, the number is interpreted in the same way as integer constants in C++. That is, if the first two characters are ``0x'' or ``0X'' the base is hex; otherwise, if the first character is `0' the base is octal; otherwise the base is decimal. Extraction (and thus conversion) stops with the first non-digit, which is not extracted. Valid digits are `0'\-`7' for octal, `0'\-`9' for decimal, and `0'\-`9', `a'\-`f', `A'\-`F' for hexadecimal. The error flag \fBios::failbit\fR is set if no valid digits are encountered. A ``0x'' followed by a non-digit is an error. In the case of an error, the value of \fBx\fR is not changed. .TP .B "float&, double&" Extracts characters and converts them to a floating-point value according to the C++ rules for floating-point constants, and stores the value in \fBx\fR. The error flag \fBios::failbit\fR is set if the characters extracted do not begin a well-formed floating-point number; some characters may be extracted in this case, depending on at what point the error is detected. In the case of an error, the value of \fBx\fR is not changed. .TP .B "char*, unsigned char*" Extracts characters and stores them in the array pointed to by \fBx\fR until a whitespace character is encountered. The whitespace is not extracted (but \fBipfx\fR may have discarded leading whitespace). If the \fBwidth\fR formatting variable (see \fBios\fR(3CC4)) is non-zero, at most \fBwidth\-1\fR characters are extracted. A terminating null (0) is always stored in \fBx\fR, even when nothing is extracted. The error flag \fBios::failbit\fR is set if no characters are available for extraction. .in -.5i .\" .TP .B "wchar_t*" Behaves like the extractor for \fBchar*\fR except it decodes characters in multibyte representation into an array of wide characters until it encounters a multibyte whitespace character. In addition sets \fBios::failbit\fR if it encounters an illegal sequence of bytes. .SS "Unformatted input (extraction) functions" .LP These call \fBipfx(1)\fR. If it returns zero, no further action takes place. Leading whitespace is not skipped, and no conversions take place. Wide character input functions call \fBwipfx(1)\fR in place of \fBipfx(1)\fR. .TP .B "int c = istr.get()" Extracts the next character from \fBistr\fR and returns it. Returns \fBEOF\fR if no more characters are available; never sets \fBios::failbit\fR. .TP .B "istr.get(ch)" Extracts the next character from \fBistr\fR and stores it in \fBch\fR. Stores \fBEOF\fR if no more characters are available; sets \fBios::failbit\fR when attempting to extract beyond \fBEOF\fR. This function always returns a reference to \fBistr\fR. .TP .B "istr.get(ptr, count, delim)" Extracts characters from \fBistr\fR and stores them in the \fBchar\fR array beginning at \fBptr\fR. Extraction stops after \fBcount\-1\fR characters have been extracted or when a character matching \fBdelim\fR is encountered, whichever happens first. If a \fBdelim\fR character is encountered, it is not extracted or stored. This function always stores a terminating null (0) even if nothing is extracted. It sets \fBios::failbit\fR only if \fBEOF\fR is encountered before any characters are stored. This function always returns a reference to \fBistr\fR. .TP .B "istr.get(sbuf, delim)" Extracts characters from \fBistr\fR and stores them in the \fBstreambuf sbuf\fR. Extraction stops when a character matching \fBdelim\fR (or \fBEOF\fR) is encountered, or when a store into \fBsbuf\fR fails, whichever happens first. If a \fBdelim\fR character is encountered, it is not extracted or stored. If \fBdelim\fR is \fBEOF\fR, extraction stops only when input is exhausted or when a store fails. This function sets \fBios::failbit\fR only if a store into \fBsbuf\fR fails; it always returns a reference to \fBistr\fR. .TP .B "istr.get(wc)" Extracts the next character from \fBistr\fR and stores it in \fBwc\fR in its wide character representation. Stores \fBWEOF\fR if no more characters are available; sets \fBios::failbit\fR when attempting to extract beyond end of file or if it encounters an illegal sequence of bytes. Returns a reference to \fBistr\fR. .TP .B "istr.get(wptr, count, wdelim)" Same as for single-byte characters, but \fBwptr\fR points to an array of \fBwchar_t\fR and \fBwdelim\fR is of type \fBwchar_t\fR. Sets \fBios::failbit\fR if it encounters an illegal sequence of bytes. Returns a reference to \fBistr\fR. .TP .B "istr.getline(ptr, count, delim)" This function does the same thing as .BR "istr.get(ptr, count, delim)" , except that \fBdelim\fR, if encountered, is extracted but not stored. Once \fBcount\-1\fR characters have been extracted, the next character is left in \fBistr\fR, even if it is \fBdelim\fR. This function always returns a reference to \fBistr\fR. .TP .B "istr.getline(wptr, count, wdelim)" As for single-byte characters, but wptr points to an array of \fBwchar_t\fR and \fBwdelim\fR is of type \fBwchar_t\fR. Sets \fBios::failbit\fR if it encounters an illegal sequence of bytes. Returns a reference to istr. .TP .B "istr.ignore(count, delim)" Extracts characters from \fBistr\fR and discards them. Extraction stops when a character matching \fBdelim\fR is encountered, when \fBcount\fR characters have been extracted, or when \fBEOF\fR is encountered, whichever happens first; the \fBdelim\fR character is extracted. If \fBdelim\fR is \fBEOF\fR, all of the input is discarded. This function always returns a reference to \fBistr\fR. .TP .B "istr.wignore(count=1, wdelim=WEOF)" As for \fBignore()\fR, but if \fBwdelim\fR is not \fBWEOF\fR, count indicates the number of multibyte characters to skip rather than the number of bytes to skip. Even if \fBwdelim\fR is \fBWEOF\fR, sets \fBios::failbit\fR and stops if it encounters an illegal sequence of bytes. Returns a reference to \fBistr\fR. .TP .B "istr.read(ptr, count)" Extracts characters from \fBistr\fR and stores them in the \fBchar\fR array beginning at \fBptr\fR. Extraction stops after \fBcount\fR characters have been extracted or when \fBEOF\fR is encountered, whichever happens first. This function sets \fBios::failbit\fR if \fBEOF\fR is encountered before \fBcount\fR characters are extracted; it always returns a reference to \fBistr\fR. The number of characters extracted can be found by calling .BR istr.gcount() . (See below.) .\" .SS "Positioning functions" .LP These deal with the \fIget\fR pointer of the \fBstreambuf\fR associated with an \fBistream\fR. See .BR sbufpub (3CC4) for a complete discussion. Multibyte input operations may cause the get pointer of the \fBstreambuf\fR to differ from the value reported by \fBtellg()\fR, but seeks done on the \fBistream\fR itself will still coordinate correctly with all operations on the istream. .TP .B "istr.seekg(pos)" Sets the position of the \fIget\fR pointer; returns \fBistr\fR. .TP .B "istr.seekg(offset, dir)" Sets the position of the \fIget\fR pointer; returns \fBistr\fR. .TP .B "streampos pos = istr.tellg()" Returns the current position of the \fIget\fR pointer. Multibyte input operations may cause the get pointer of the streambuf to differ from the value reported by \fBtellg()\fR, but seeks done on the istream rather than the streambuf will still coordinate correctly with all operations on the \fBistream\fR. .\" .SS "Miscellaneous functions" .TP .B "int i = istr.gcount()" Returns the number of characters extracted from \fBistr\fR by the last unformatted input function. Note: Formatted input functions might call unformatted functions, thus changing the count. After an unformatted wide character input function, \fBgcount()\fR returns the number of (multibyte) characters extracted. .TP .B "int i = istr.peek()" First calls \fBistr.ipfx(1)\fR. If \fBipfx\fR returns zero or if \fBistr\fR is at \fBEOF\fR, it returns \fBEOF\fR. Otherwise, it returns the next character without extracting it. .TP .B "int i = istr.peekw()" Calls \fBwipfx(1)\fR and returns \fB(wint_t)WEOF\fR if that fails. Sets \fBios::failbit\fR and returns \fBWEOF\fR if it encounters an illegal sequence of bytes. If successful, returns the next character in the \fBstream\fR as a wide character without moving past it. .TP .B "istr.putback(ch)" If \fBistr.fail()\fR returns non-zero, this function returns without doing anything. Otherwise, it attempts to back up the \fBstreambuf\fR associated with \fBistr\fR by pushing back character \fBch\fR. Because it does no extraction, it does not call \fBipfx\fR. It may fail, setting \fBios::failbit\fR. In general, \fBc\fR must match the character ahead of the \fBstreambuf\fR's \fIget\fR pointer (normally the last character extracted) \- input might be coming from a read-only in-memory buffer. .TP .B "int i = istr.sync()" Forces a correspondence between the internal data structures and the external source of characters in an implementation-defined manner. It calls the virtual function \fBistr.rdbuf()->sync()\fR, which of course will depend on the actual type of the buffer class. It returns \fBEOF\fR on error. .\" .SS "Predefined Manipulators" .LP A \fImanipulator\fR may be used apparently as an inserted or extracted object, but many only change the state of the stream. See .BR manip "(3CC4) and " ios (3CC4) for more information. Several manipulators are predefined for use with istreams. .TP .BI "istr >> " manip This is equivalent to the call \fImanip\fB(istr)\fR. .TP .B "istr >> dec" This sets the conversion base of \fBistr\fR to 10. .TP .B "istr >> oct" This sets the conversion base of \fBistr\fR to 8. .TP .B "istr >> hex" This sets the conversion base of \fBistr\fR to 16. .TP .B "istr >> ws" This extracts and discards consecutive whitespace characters from \fBistr\fR. .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR ctype (3V), .BR ios (3CC4), .BR manip (3CC4), .BR sbufpub (3CC4), .BR stdiobuf (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????