path: root/static/v10/man3/istream.3

.  \"ident	"%W%"
.  \"Copyright (c) 1984 AT&T
.  \"All Rights Reserved
.  \"THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AT&T
.  \"The copyright notice above does not evidence any
.  \"actual or intended publication of such source code.
.TH ISTREAM  3I+ "C++ Stream Library" " "
.SH NAME
istream \- formatted and unformatted input
.SH SYNOPSIS
.nf
.ft B
.ta1i 2i
#include <iostream.h>

typedef long streamoff, streampos;
class ios {
public:
	enum	seek_dir { beg, cur, end };
	enum	open_mode { in, out, ate, app } ;
	// \fIand lots of other stuff ... \fP
	} ;

class istream : ios {
public:
	int	gcount();
	istream&	get(char* ptr, int len, char delim='\en');
	istream&	get(unsigned char* ptr,int len, char delim='\en');

	istream&	get(unsigned char& c);
	istream&	get(char& c);
	istream&	get(streambuf&, char delim ='\en');
	int	get();
	istream&	getline(char* ptr, int len, char delim='\en');
	istream&	getline(unsigned char* ptr, int len, char delim='\en');
	istream&	getline(streambuf& sb, int len, char delim='\en');
	istream&	ignore(int len=1,int delim=EOF);
	int	ipfx(int need=0);
	int	peek();
	istream&	putback(char c);
	istream&	read(char* s,int n); 
	istream&	read(unsigned char* s,int n);
	istream&	seekg(streampos pos);
	istream&	seekg(streamoff off, seek_dir d);
	streampos	tellg();

	istream&	operator>>(char*);
	istream&	operator>>(unsigned char*);
	istream&	operator>>(unsigned char&);
	istream&	operator>>(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&));
};

class istream_withassign {
		istream_withassign();
	istream&	operator=(istream&);
	istream&	operator=(streambuf*);
};

extern istream_withassign cin;

istream&	ws(iostream& i)	;
.fi
.ft R
.SH DESCRIPTION
\f(CWistream\fRs support interpretation of characters
fetched from an associated \f(CWstreambuf\fR.
These are commonly refered to as input operations.
.PP
Assume that
.br
\(em \fBins\fR has type \f(CWistream\fR.
.br
\(em \fBinwa\fR has type \f(CWistream_withassign\fR.
.br
\(em \fBinsp\fR has type \f(CWistream*\fR.
.br
\(em \fBc\fR has type \f(CWchar&\fR
.br
\(em \fBdelim\fR has type \f(CWchar\fR.
.br
\(em \fBptr\fR has type \f(CWchar*\fR or \f(CWunsigned char*\fR.
.br
\(em \fBsb\fR has type \f(CWstreambuf&\fR.
.br
\(em \fBi\fR, \fBlen\fR, \fBd\fR, and \fBneed\fR have type \f(CWint\fR.
.br
\(em \fBpos\fR is a \f(CWstreampos\fR.
.br
\(em \fBoff\fR is a \f(CWstreamoff\fR.
.br
\(em \fBdir\fR is a \f(CWseek_dir\fR.
.br
\(em \fBmanip\fR is a function with type \f(CWistream& (*)(istream&)\fR.
.PP
Constructors and assignment:
.TP
\fBistream(sb)\fR
Initializes \fBios\fR state variables and associates stream with
buffer \fBsb\fR.
\fBistream_withassign()\fR
Does no initialization.  This allows a file static
variable of this type
(\fBcin\fR for example) to be used before it is constructed provided
it is assigned to first.
.TP
\fBinswa=sb\fR
Associates \fBsb\fR with \fBswa\fR and initializes the entire
state of \fBinswa\fR.
.TP
\fBinswa=ins\fR
Associates \fBins->rdbuf()\fR with \fBswa\fR and initializes the entire
state of \fBinswa\fR.
.PP
Input prefix function:
.TP
\fBins.ipfx(need)
If \fBins\fR's error state is non-zero return immediately.
If neccessary (and it is non-null) \fBf.tie\fR is flushed.
Flushing is neccessary if either \fBneed==0\fR or there
are less than \fBneed\fR characters immediately available.
If \fBf.skip()\fR is non-zero and \fBneed\fR is zero
then leading whitespace characters are
extracted from \fBins\fR.  Return zero 
or an error occurs while skipping whitespace.
Otherwise it returns non-zero.
.PP
Formatted input functions:
.TP
\fBins\fP>>\fPx\fR
Calls \fBipfx(0)\fR and if that returns non-zero
extracts characters from \fBins\fR and converts them according
to the type of \fBx\fR.  It stores the converted value in
\fBx\fR.
Errors are indicated by setting the
error state of \fBins\fR.  \f(CWfailbit\fR means that characters
in \fBins\fR were not a representation of the required type.
\f(CWbadbit\fR indicates that attempts to extract characters failed.
\fBins\fR is always returned.
.RS
.PP
The details of conversion depend on the values of \fBins\fR's format
state variable (see \fIios\fR(3C++)) and the
type of \fBx\fR.  Except as noted, the extraction operators
do not change the value
of the format state variables.
.TP
\f(CWchar*\fR, \f(CWunsigned char*\fR
Characters are stored in the array pointed at by \fBx\fR
until a whitespace character is found in \fBins\fR.
The terminating whitespace
is left in \fBins\fR.
If \fBins.width()\fR
is non-zero it is taken to be the size of the array, and
no more than \fBins.width()-1\fR characters are extracted.
A terminating
null character (0) is always stored (even when nothing else is
done because of \fBins\fR's status).
\fBins.width()\fR is reset to 0.
.TP
\f(CWchar&\fR, \f(CWunsigned char&\fR
A character is extracted and stored in \fBx\fR.
.TP
\f(CWshort&\fR, \f(CWunsigned short&\fR, \f(CWint&\fR, \f(CWunsigned int&\fR, \f(CWlong&\fR, \f(CWunsigned long&\fR
Characters are extracted and converted to an integral value
according to the conversion specified by 
\fBins.convbase()\fR.
The first character may be a sign (\f(CW+\fR or \f(CW-\fR).  After that,
if \fBins.convbase()\fR
is 8, 10, or 16 the conversion is octal, decimal, or hexadecimal respectively.
Conversion is terminated by the first "non-digit," which is left
in \fBins\fR. 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 \fBins.convbase()\fR
is 0 then the number is interpreted according to C lexical
conventions.  That is, if the first characters (after the optional
sign) are \f(CW0x\fR or \f(CW0X\fR a hexadecimal conversion
is performed
on following hexadecimal digits.  Otherwise if the first character is a 
\f(CW0\fR an
octal conversion is performed and in all other cases a decimal conversion
is performed.
\f(CWfailbit\fR is set if there are no
digits (not counting the \f(CW0\fR in \f(CW0x\fR or \f(CW0X\fR) during
hex conversion) available.
.TP
\f(CWfloat&\fR, \f(CWdouble&\fR
Converts the characters according to C++ syntax for a float or double,
and stores the result in \fBx\fR.  \f(CWfailbit\fR is set if there are no
digits available in \fBins\fR or if it does not begin with a well formed
floating point number.
.RE
.PP
The type and name(\f(CWoperator>>\fR) 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.
.PP
Unformatted input functions, which call \fBipfx(1)\fR and proceed only
if it returns non-zero:
.TP
\fBinsp=&ins.get(ptr,len,delim)\fR
Extracts characters and stores them in
the byte array beginning at \fBptr\fR
and extending for \fBlen\fR bytes.
Extraction stops when \fBdelim\fR is encountered
(\fBdelim\fR is left in \fBins\fR and not stored),
when \fBins\fR has no more characters,
or when the array has only one byte left.
\fBget\fR always stores a terminating null, even if it doesn't extract
any characters from \fBins\fR because of its error status.
\f(CWfailbit\fR is set only if \fBget\fR encounters
an end of file before it stores any characters.
.TP
\fBinsp=&ins.get(c)\fR
Extracts a single character
and stores it in \fBc\fR.
.TP
\fBinsp=&ins.get(sb,delim)\fB
Extracts characters from \fBins.rdbuf()\fR and stores
them into \fBsb\fR.
It stops if it encounters end of file or if a store into
\fBsb\fR
fails or
if it encounters \fBdelim\fR (which it leaves in \fBins\fR). 
\f(CWfailbit\fR is set if it stops because the store into \fBsb\fR fails
.TP
\fBi=ins.get()\fR.
Extracts a character and returns it.
\fBi\fR is \f(CWEOF\fR if extraction encounters end of file.
\f(CWfailbit\fR is never set.
.TP
\fBinsp=&ins.getline(ptr,len,delim)\fR
Does the same thing as \fBins.get(ptr,len,delim)\fR with the exception
that it extracts a terminating \fBdelim\fR character from \fBins\fR.
In case \fBdelim\fR occurs when exactly \fBlen\fR characters
have been extracted, termination is treated as being due to the
array being filled, and this \fBdelim\fR is left in \fBins\fR.
.TP
\fBinsp=&ins.ignore(n,d)\fR
Extracts and throws away
up to \fBn\fR characters.
Extraction stops prematurely if 
\fBd\fR is extracted or end of file is reached.
If \fBd\fR is \f(CWEOF\fR it can never cause termination.
.TP
\fBinsp=&ins.read(ptr,n)\fR
Extracts
\fBn\fR
characters and stores them in the array beginning at \fBptr\fR
If end of file is reached before \fBn\fR characters have been
extracted, 
\fBread\fR
stores whatever it can extract and sets \f(CWfailbit\fR.
The number of characters extracted can be determined via \fBins.gcount()\fR.
.PP
Other members are:
.TP
\fBi=ins.gcount()\fR
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.
.TP
\fBi=ins.peek()\fR
Begins by calling \fBins.ipfx(1)\fR.
If that call returns zero or if \fBins\fR is at end of file,
it returns \f(CWEOF\fR.
Otherwise it returns (without extracting it) the next character.
.TP
\fBinsp=&ins.putback(c)\fR
Attempts to back up \fBins.rdbuf()\fR.
\fBc\fR must be the character before \fBins.rdbuf()\fR's get pointer.
(Unless other activity is modifying \fBins.rdbuf()\fR this
is the last character extracted from \fBins\fR.)
If it is not, the effect is undefined.
\fBputback\fR may fail (and set the error state).
Although it is a member of \f(CWistream\fR,
\fBputback\fR never extracts characters, so
it does not call \fBipfx\fR.  It will, however, return without
doing anything if the error state is non-zero.
.TP
\fBins>>manip\fR
Equivalent to \fBmanip(ins)\fR.
Syntactically this looks like an extractor
operation, but semantically it does an arbitrary operations
rather than converting a sequence of characters and storing the
result in \fBmanip\fR.
.PP
Member functions related to positioning.
.TP
\fBinsp=&ins.seekg(off,dir)\fR
Repositions \fBins.rdbuf()\fR's get pointer.
See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
.TP
\fBinsp=&ins.seekg(pos)\fR
Repositions \fBins.rdbuf()\fR's get pointer.
See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
.TP
\fBpos=ins.tellg()\fR
The current position of \fBios.rdbuf()\fR's get pointer.
See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
.PP
Manipulator:
.TP
\fBins>>ws\fR
Extracts whitespace characters.
.SH CAVEATS
.PP
There is no overflow detection on conversion of integers. There should
be, and overflow should cause the error state to be set.
.PP
There should be a way to input an arbitrary length string without 
knowing a maximum size beforehand.
.PP
.SH SEE ALSO
ios(3C++)
sbuf.pub(3C++)
manip(3C++)