ISTREAM(3C++) ISTREAM(3C++)
NAMEistream - 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&);
Page 1
ISTREAM(3C++) ISTREAM(3C++)
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*);
};
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.
- inswa is an istream_withassign.
- insp is a 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.
Page 2
ISTREAM(3C++) ISTREAM(3C++)
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.
Page 3
ISTREAM(3C++) ISTREAM(3C++)
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&
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.
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
Page 4
ISTREAM(3C++) ISTREAM(3C++)
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.
Page 5
ISTREAM(3C++) ISTREAM(3C++)
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 sbuf.pub(3C++) for
a discussion of positioning.
insp=&ins.seekg(pos)
Repositions ins.rdbuf()'s get pointer. See sbuf.pub(3C++) for
a discussion of positioning.
pos=ins.tellg()
The current position of ios.rdbuf()'s get pointer. See
sbuf.pub(3C++) for a discussion of positioning.
Manipulator:
ins>>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++).
Page 6
ISTREAM(3C++) ISTREAM(3C++)
CAVEATS
There is no overflow detection on conversion of integers. There should
be, and overflow should cause the error state to be set.
SEE ALSO
ios(3C++), sbuf.pub(3C++), manip(3C++)
Page 7
