istream - formatted and unformatted input
#include <iostream.h>
typedef long streampos;
typedef long streamoff;
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
};
// see ios(3CC4) for remainder ...
};
class unsafe_istream : virtual public unsafe_ios {
public:
// exported functions
// 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);
// 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);
};
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='\n');
istream& get(unsigned char* ptr,int count, char delim='\n');
istream& get(unsigned char& ch);
istream& get(char& ch);
istream& get(streambuf& sb, char delim ='\n');
istream& getline(char* ptr, int count, char delim='\n');
istream& getline(unsigned char* ptr, int count, char delim='\n');
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*);
};
class istream_withassign : public istream {
public:
istream_withassign();
istream_withassign& operator= (istream&);
istream_withassign& operator= (streambuf*);
};
extern istream_withassign cin;
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&) ;
Class istream supports formatted and unformatted extraction (input) of data from an associated streambuf.
The istream object and its member functions are protected against access by multiple threads by mutex locks. The unsafe_istream object and its member functions do not implement mutex locking. Aside from this difference, the functionality of istream and 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".
.
Associates the streambuf pointed to by sbufp with the stream and initializes the ios state.
Performs no initialization.
Associates the streambuf pointed to by sbufp with isw and completely initializes isw.
The streambuf associated with istr becomes associated with isw and the constructor completely initializes isw.
Input functions that produce wide character results set failbit 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 (seekg). streambufs need only support peeking one byte ahead, so multibyte input operations that peek may buffer "peeked" bytes in the istream itself. seekg and tellg take account of any such internal buffering.
Performs setup common to all extraction operations. Formatted extractors call ipfx(0); unformatted extractors call ipfx(1). If the error state of istr is non-zero, ipfx returns zero immediately. If a stream is tied to istr (see tie in ios(3cc4)) and noform is zero, the tied stream is flushed. If the skipws flag is set for the stream and noform is zero, leading whitespace characters (as defined by iswhite, see ctype(3c)), are skipped. Function ipfx returns zero if any error condition is encountered, non-zero otherwise.
Wide character extractors use wipfx in place of ipfx. This is similar to ipfx(), but wipfx() skips over any multibyte space as defined by iswspace where ipfx skips over single-byte space characters. Furthermore wipfx() sets ios::failbit if encounters an illegal sequence of bytes. This function is not in the proposed ANSI iostreams interface, so avoid calling it directly from application code.
These call ipfx(0). If it returns zero, no further action takes place. Otherwise, leading whitespace will be stripped if ios::skipws is set. If only whitespace is left in the istream, no characters will then remain and the ios::failbit will be set. Wide character formatted input functions call wipfx(0) and return with no further action if it returns zero.
Extracts characters from istr and inserts them into the streambuf pointed to by sbufp. This function always returns a reference to istr. You can use this function to copy a stream efficiently, but you should be sure that neither stream is tied. For example:
#include <iostream.h>
main()
{ // copy cin to cout
cin.tie(0);
cout.tie(0);
cin >> cout.rdbuf(); // see ios(3CC4) for rdbuf
return 0;
}
Extracts characters from istr and converts them according to the type of x. If ipfx returns zero, no characters are extracted and x is unchanged. Any errors encountered are recorded in the error state of istr. In general, ios::failbit 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, ios::badbit means that no characters could be extracted; for example, attempting to extract past the end of file. These functions always return a reference to istr. User-written functions should be of the form
istream& operator>> (istream&, SomeType)
and should conform to these principles.
The type of x and the format state of the istream (see ios (3cc4) determine the details of the extraction and conversion. These functions do not change the state of the istream, except that the width variable is reset to zero after each formatted extraction. The predefined formatted extractors are as follows:
Extracts one character and stores it in x.
Extracts one multibyte character and stores it in x as a wide character if wipfx(0) succeeds and it does not encounter end-of- file. Sets ios::failbit if it encounters an illegal sequence of bytes.
Extracts characters and converts them to an integral value according to the conversion base in the istream's format flags, and stores the value in x. The first character may be a plus (`+') or minus (`-') sign. The characters are then treated as decimal, octal, or hexadecimal, if the ios::basfield flags are 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 ios::failbit 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 x is not changed.
Extracts characters and converts them to a floating-point value according to the C++ rules for floating-point constants, and stores the value in x. The error flag ios::failbit 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 x is not changed.
Extracts characters and stores them in the array pointed to by x until a whitespace character is encountered. The whitespace is not extracted (but ipfx may have discarded leading whitespace). If the width formatting variable (see ios (3cc4) ) is non-zero, at most width-1 characters are extracted. A terminating null (0) is always stored in x, even when nothing is extracted. The error flag ios::failbit is set if no characters are available for extraction.
Behaves like the extractor for char* except it decodes characters in multibyte representation into an array of wide characters until it encounters a multibyte whitespace character. In addition sets ios::failbit if it encounters an illegal sequence of bytes.
These call ipfx(1). If it returns zero, no further action takes place. Leading whitespace is not skipped, and no conversions take place. Wide character input functions call wipfx(1) in place of ipfx(1).
Extracts the next character from istr and returns it. Returns EOF if no more characters are available; never sets ios::failbit.
Extracts the next character from istr and stores it in ch. Stores EOF if no more characters are available; sets ios::failbit when attempting to extract beyond EOF. This function always returns a reference to istr.
Extracts characters from istr and stores them in the char array beginning at ptr. Extraction stops after count-1 characters have been extracted or when a character matching delim is encountered, whichever happens first. If a delim character is encountered, it is not extracted or stored. This function always stores a terminating null (0) even if nothing is extracted. It sets ios::failbit only if EOF is encountered before any characters are stored. This function always returns a reference to istr.
Extracts characters from istr and stores them in the streambuf sbuf. Extraction stops when a character matching delim (or EOF) is encountered, or when a store into sbuf fails, whichever happens first. If a delim character is encountered, it is not extracted or stored. If delim is EOF, extraction stops only when input is exhausted or when a store fails. This function sets ios::failbit only if a store into sbuf fails; it always returns a reference to istr.
Extracts the next character from istr and stores it in wc in its wide character representation. Stores WEOF if no more characters are available; sets ios::failbit when attempting to extract beyond end of file or if it encounters an illegal sequence of bytes. Returns a reference to istr.
Same as for single-byte characters, but wptr points to an array of wchar_t and wdelim is of type wchar_t. Sets ios::failbit if it encounters an illegal sequence of bytes. Returns a reference to istr.
This function does the same thing as istr.get(ptr, count, delim), except that delim, if encountered, is extracted but not stored. Once count-1 characters have been extracted, the next character is left in istr, even if it is delim. This function always returns a reference to istr.
As for single-byte characters, but wptr points to an array of wchar_t and wdelim is of type wchar_t. Sets ios::failbit if it encounters an illegal sequence of bytes. Returns a reference to istr.
Extracts characters from istr and discards them. Extraction stops when a character matching delim is encountered, when count characters have been extracted, or when EOF is encountered, whichever happens first; the delim character is extracted. If delim is EOF, all of the input is discarded. This function always returns a reference to istr.
As for ignore(), but if wdelim is not WEOF, count indicates the number of multibyte characters to skip rather than the number of bytes to skip. Even if wdelim is WEOF, sets ios::failbit and stops if it encounters an illegal sequence of bytes. Returns a reference to istr.
Extracts characters from istr and stores them in the char array beginning at ptr. Extraction stops after count characters have been extracted or when EOF is encountered, whichever happens first. This function sets ios::failbit if EOF is encountered before count characters are extracted; it always returns a reference to istr. The number of characters extracted can be found by calling istr.gcount(). (See below.)
These deal with the get pointer of the streambuf associated with an istream. See sbufpub (3CC4) for a complete discussion. Multibyte input operations may cause the get pointer of the streambuf to differ from the value reported by tellg(), but seeks done on the istream itself will still coordinate correctly with all operations on the istream.
Sets the position of the get pointer; returns istr.
Sets the position of the get pointer; returns istr.
Returns the current position of the get pointer. Multibyte input operations may cause the get pointer of the streambuf to differ from the value reported by tellg(), but seeks done on the istream rather than the streambuf will still coordinate correctly with all operations on the istream.
Returns the number of characters extracted from istr 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, gcount() returns the number of (multibyte) characters extracted.
First calls istr.ipfx(1). If ipfx returns zero or if istr is at EOF, it returns EOF. Otherwise, it returns the next character without extracting it.
Calls wipfx(1) and returns (wint_t)WEOF if that fails. Sets ios::failbit and returns WEOF if it encounters an illegal sequence of bytes. If successful, returns the next character in the stream as a wide character without moving past it.
If istr.fail() returns non-zero, this function returns without doing anything. Otherwise, it attempts to back up the streambuf associated with istr by pushing back character ch. Because it does no extraction, it does not call ipfx. It may fail, setting ios::failbit. In general, c must match the character ahead of the streambuf's get pointer (normally the last character extracted) - input might be coming from a read-only in-memory buffer.
Forces a correspondence between the internal data structures and the external source of characters in an implementation-defined manner. It calls the virtual function istr.rdbuf()->sync(), which of course will depend on the actual type of the buffer class. It returns EOF on error.
A manipulator may be used apparently as an inserted or extracted object, but many only change the state of the stream. See manip(3cc4) and ios(3cc4) for more information. Several manipulators are predefined for use with istreams.
This is equivalent to the call manip(istr).
This sets the conversion base of istr to 10.
This sets the conversion base of istr to 8.
This sets the conversion base of istr to 16.
This extracts and discards consecutive whitespace characters from istr.
ctype (3C) , ios (3CC4) , ios.intro (3CC4) , manip (3CC4) , sbufpub (3CC4) , stdiobuf (3CC4)
C++ Library Reference, Chapter 3, "The Classic iostream Library" and Chapter 4, "Using Classic iostreams in a Multithreaded Environment."