ISTREAM(3CC4)ISTREAM(3CC4)NAMEistream - formatted and unformatted input
SYNOPSIS
#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&) ;
DESCRIPTION
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".
ENVIRONMENT
Constructors and Assignment
istream(sbufp)
Associates the streambuf pointed to by sbufp with the stream and
initializes the ios state.
istream_withassign()
Performs no initialization.
istream_withassign isw = sbufp
Associates the streambuf pointed to by sbufp with isw and com‐
pletely initializes isw.
istream_withassign isw = istr
The streambuf associated with istr becomes associated with isw
and the constructor completely initializes isw.
About wide character operations
Input functions that produce wide character results set failbit if they
encounter an illegal sequence of bytes. A sequence of bytes is consid‐
ered 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.
Input prefix function
int i = istr.ipfx(noform)
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 imme‐
diately. 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 encoun‐
tered, non-zero otherwise.
int i = istr.wipfx(noform)
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 pro‐
posed ANSI iostreams interface, so avoid calling it directly
from application code.
Formatted input (extraction) functions
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.
istr >> sbufp
Extracts characters from istr and inserts them into the stream‐
buf pointed to by sbufp. This function always returns a refer‐
ence to istr. You can use this function to copy a stream effi‐
ciently, 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;
}
istr >> x
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 white‐
space 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 extrac‐
tion. The predefined formatted extractors are as follows:
char&, unsigned char&
Extracts one character and stores it in x.
wchar_t&
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.
short&, unsigned short&
int&, unsigned int&
long&, unsigned long&
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 encoun‐
tered. A ``0x'' followed by a non-digit is an error. In the
case of an error, the value of x is not changed.
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 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.
char*, unsigned char*
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.
wchar_t*
Behaves like the extractor for char* except it decodes charac‐
ters in multibyte representation into an array of wide charac‐
ters until it encounters a multibyte whitespace character. In
addition sets ios::failbit if it encounters an illegal sequence
of bytes.
Unformatted input (extraction) functions
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).
int c = istr.get()
Extracts the next character from istr and returns it. Returns
EOF if no more characters are available; never sets ios::fail‐
bit.
istr.get(ch)
Extracts the next character from istr and stores it in ch.
Stores EOF if no more characters are available; sets ios::fail‐
bit when attempting to extract beyond EOF. This function always
returns a reference to istr.
istr.get(ptr, count, delim)
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.
istr.get(sbuf, delim)
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 hap‐
pens 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.
istr.get(wc)
Extracts the next character from istr and stores it in wc in its
wide character representation. Stores WEOF if no more charac‐
ters 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.
istr.get(wptr, count, wdelim)
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.
istr.getline(ptr, count, delim)
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.
istr.getline(wptr, count, wdelim)
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.
istr.ignore(count, delim)
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.
istr.wignore(count=1, wdelim=WEOF)
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.
istr.read(ptr, count)
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 ref‐
erence to istr. The number of characters extracted can be found
by calling istr.gcount(). (See below.)
Positioning functions
These deal with the get pointer of the streambuf associated with an
istream. See .BR 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.
istr.seekg(pos)
Sets the position of the get pointer; returns istr.
istr.seekg(offset, dir)
Sets the position of the get pointer; returns istr.
streampos pos = istr.tellg()
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 cor‐
rectly with all operations on the istream.
Miscellaneous functions
int i = istr.gcount()
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.
int i = istr.peek()
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.
int i = istr.peekw()
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.
istr.putback(ch)
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.
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 istr.rdbuf()->sync(),
which of course will depend on the actual type of the buffer
class. It returns EOF on error.
Predefined Manipulators
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 prede‐
fined for use with istreams.
istr >> manip
This is equivalent to the call manip(istr).
istr >> dec
This sets the conversion base of istr to 10.
istr >> oct
This sets the conversion base of istr to 8.
istr >> hex
This sets the conversion base of istr to 16.
istr >> ws
This extracts and discards consecutive whitespace characters
from istr.
SEE ALSOios.intro(3CC4), ctype(3C), ios(3CC4), manip(3CC4), sbufpub(3CC4),
stdiobuf(3CC4), C++ Library Reference, Chapter 3, "The Classic iostream
Library", and Chapter 4, "Using Classic iostream in a Multithreaded
Environment"
08 August 2000 ISTREAM(3CC4)