*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> c++/istream (3)              
Title
Content
Arch
Section
 

Contents


ISTREAM(3C++)							 ISTREAM(3C++)


NAME    [Toc]    [Back]

     istream - formatted and unformatted input

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     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<b>)
	       Initializes ios state variables and associates buffer sb	with
	       the istream..

	  istream_withassign()
	       Does no initialization.





									Page 2






ISTREAM(3C++)							 ISTREAM(3C++)



	  inswa<b>=sb
	       Associates sb with inswa	and initializes	the entire state of
	       inswa.

	  inswa<b>=ins
	       Associates ins<b>->rdbuf() with inswa and initializes the entire
	       state of	inswa.

   Input prefix	function:
	  i <b>= ins<b>.ipfx(need<b>)
	       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<b>==0 or if	there
	       are fewer than need characters immediately available.  If
	       ios::skipws is set in ins<b>.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<b>>>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<b>.width() is non-zero it
		    is taken to	be the size of the array, and no more than
		    ins<b>.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<b>.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<b>.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<b>>>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<b>=&ins<b>.get(ptr<b>,len<b>,delim<b>)
	       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<b>=&ins<b>.get(c<b>)
	       Extracts	a single character and stores it in c.

	  insp<b>=&ins<b>.get(sb<b>,delim<b>)
	       Extracts	characters from	ins<b>.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<b>=ins<b>.get().
	       Extracts	a character and	returns	it.  i is EOF if extraction
	       encounters end of file.	ios::failbit is	never set.

	  insp<b>=&ins<b>.getline(ptr<b>,len<b>,delim<b>)
	       Does the	same thing as ins<b>.get(ptr<b>,len<b>,delim<b>) 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<b>=&ins<b>.ignore(n<b>,d<b>)
	       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<b>=&ins<b>.read(ptr<b>,n<b>)
	       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<b>.gcount().

   Other members are:
	  i<b>=ins<b>.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<b>=ins<b>.peek()
	       Begins by calling ins<b>.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<b>=&ins<b>.putback(c<b>)
	       Attempts	to back	up ins<b>.rdbuf().	 c must	be the character
	       before ins<b>.rdbuf()'s get	pointer.  (Unless other	activity is
	       modifying ins<b>.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<b>=&ins<b>.sync()
	       Establishes consistency between internal	data structures	and
	       the external source of characters.  Calls ins<b>.rdbuf()->sync(),
	       which is	a virtual function, so the details depend on the
	       derived class.  Returns EOF to indicate errors.

	  ins<b>>>manip
	       Equivalent to manip(ins<b>).  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<b>=&ins<b>.seekg(off<b>,dir<b>)
	       Repositions ins<b>.rdbuf()'s get pointer.  See sbuf.pub(3C++) for
	       a discussion of positioning.

	  insp<b>=&ins<b>.seekg(pos<b>)
	       Repositions ins<b>.rdbuf()'s get pointer.  See sbuf.pub(3C++) for
	       a discussion of positioning.

	  pos<b>=ins<b>.tellg()
	       The current position of ios.rdbuf()'s get pointer.  See
	       sbuf.pub(3C++) for a discussion of positioning.

   Manipulator:
	  ins<b>>>ws
	       Extracts	whitespace characters.

	  ins<b>>>dec
	       Sets the	conversion base	format flag to 10.  See	ios(3C++).

	  ins<b>>>hex
	       Sets the	conversion base	format flag to 16.  See	ios(3C++).

	  ins<b>>>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    [Toc]    [Back]

      
      
     ios(3C++),	sbuf.pub(3C++),	manip(3C++)


									PPPPaaaaggggeeee 7777
[ Back ]
 Similar pages
Name OS Title
ostream IRIX formatted and unformatted output
sscanf Tru64 Convert formatted input
scanf IRIX convert formatted input
scanf Tru64 Convert formatted input
fscanf Tru64 Convert formatted input
curs_scanw IRIX convert formatted input from a curses widow
fwscanf Tru64 Convert formatted wide-character input
scanw FreeBSD convert formatted input from a curses window
vwscanw FreeBSD convert formatted input from a curses window
wscanw FreeBSD convert formatted input from a curses window
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service