istream(3C++)
istream --
formatted and unformatted input
Synopsis
#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(3C++) ...
} ;
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>>(long 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*);
istream_withassign& operator=(istream_withassign&);
};
extern istream_withassign cin;
istream& ws(istream&) ;
ios& dec(ios&) ;
ios& hex(ios&) ;
ios& oct(ios&) ;
Description
istreams support interpretation of characters
fetched from an associated streambuf.
These are commonly referred to as input or extraction operations.
The istream member functions and related functions
are described below.
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(3C++)).
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(3C++))
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&, long double&-
Converts the characters according to C++ syntax for a floating point type,
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:
These functions call ipfx(1) and proceed only
if it returns non-zero:
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 are:
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
streambuf_pub(3C++)
for a discussion of positioning.
insp=&ins.seekg(pos)-
Repositions ins.rdbuf()'s get pointer.
See
streambuf_pub(3C++)
for a discussion of positioning.
pos=ins.tellg()-
The current position of ios.rdbuf()'s get pointer.
See
streambuf_pub(3C++)
for a discussion of positioning.
Manipulator:
ins 0>>ws-
Extracts whitespace characters.
ins>>dec-
Sets the conversion base format flag to 10.
See
ios(3C++).
ins>>hex-
Sets the conversion base format flag to 16.
See
ios(3C++).
ins>>oct-
Sets the conversion base format flag to 8.
See
ios(3C++).
Notices
There is no overflow detection on conversion of integers. There should
be, and overflow should cause the error state to be set.
References
ios(3C++),
manip(3C++),
streambuf_pub(3C++)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004