istream(3C++) istream(3C++)
NAME
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*);
Copyright 1994 Novell, Inc. Page 1
istream(3C++) istream(3C++)
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*);
};
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.
Copyright 1994 Novell, Inc. Page 2
istream(3C++) istream(3C++)
- 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.
Copyright 1994 Novell, Inc. Page 3
istream(3C++) istream(3C++)
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.
Copyright 1994 Novell, Inc. Page 4
istream(3C++) istream(3C++)
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.
Copyright 1994 Novell, Inc. Page 5
istream(3C++) istream(3C++)
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
Copyright 1994 Novell, Inc. Page 6
istream(3C++) istream(3C++)
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++).
Copyright 1994 Novell, Inc. Page 7
istream(3C++) istream(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++), streambuf_pub(3C++), manip(3C++)
Copyright 1994 Novell, Inc. Page 8