istream man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

ISTREAM(3CC4)							 ISTREAM(3CC4)

NAME
       istream - formatted and unformatted input

SYNOPSIS
       #include <iostream.h>
       typedef long streampos;
       typedef long streamoff;
       class unsafe_ios {
       public:
	    // exported types

	    // stream operation mode
	    enum open_mode  {
		in	 = 0x01,	// open for reading
		out	 = 0x02,	// open for writing
		ate	 = 0x04,	// seek to eof upon original open
		app	 = 0x08,	// append mode: all additions at eof
		trunc	 = 0x10,	// truncate file if already exists
		nocreate = 0x20,	// open fails if file doesn't exist
		noreplace= 0x40		// open fails if file already exists
	    };

	    // stream seek direction
	    enum seek_dir { beg=0, cur=1, end=2 };

	    // formatting flags
	    enum    {
		skipws	  = 0x0001,	// skip whitespace on input
		left	  = 0x0002,	// left-adjust output
		right	  = 0x0004,	// right-adjust output
		internal  = 0x0008,	// padding after sign or base indicator
		dec	  = 0x0010,	// decimal conversion
		oct	  = 0x0020,	// octal conversion
		hex	  = 0x0040,	// hexidecimal conversion
		showbase  = 0x0080,	// use base indicator on output
		showpoint = 0x0100,	// force decimal point (floating output)
		uppercase = 0x0200,	// upper-case hex output
		showpos	  = 0x0400,	// add '+' to positive integers
		scientific= 0x0800,	// use 1.2345E2 floating notation
		fixed	  = 0x1000,	// use 123.45 floating notation
		unitbuf	  = 0x2000,	// flush all streams after insertion
		stdio	  = 0x4000	// flush stdout, stderr after insertion
		};

	    // see ios(3CC4) for remainder ...
       };
       class unsafe_istream : virtual public unsafe_ios {
       public:
	    // exported functions
	    // unformatted input functions
	    unsafe_istream& read(char* ptr, int count);
	    unsafe_istream& read(unsigned char* ptr, int count);
	    unsafe_istream& get(char* ptr, int count, char delim='\n');
	    unsafe_istream& get(streambuf& sbuf, char delim='\n');
	    unsafe_istream& get(char& ch);
	    unsafe_istream& get(unsigned char& ch);
	    unsafe_istream& get_line (char *ptr, int count, char delim='\n');
	    unsafe_istream& get_line (unsigned char *ptr, int count, char delim='\n');
	    int	 get();
	    int	 peek();
	    unsafe_istream& ignore(int count=1, int delim=EOF);
	    unsafe_istream& putback(char ch);

	    // wide character
	    unsafe_istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
	    unsafe_istream& get(wchar_t& wc);
	    unsafe_istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
	    unsafe_istream& wignore(count=1, wdelim=WEOF);
	    // other functions
	    int	 ipfx(int noform=0);
	    int	 wipfx(int noform=0);	       // wide character ipfx
	    unsafe_istream& seekg(streampos pos);
	    unsafe_istream& seekg(streamoff offset, unsafe_ios::seek_dir dir);
	    streampos tellg();
	    int	 sync();
	    int	 gcount();
       public:
	    // exported operator functions
	    unsafe_istream& operator>> (char* buf);
	    unsafe_istream& operator>> (unsigned char* buf);
	    unsafe_istream& operator>> (char&);
	    unsafe_istream& operator>> (unsigned char&);
	    unsafe_istream& operator>> (short&);
	    unsafe_istream& operator>> (int&);
	    unsafe_istream& operator>> (long&);
	    unsafe_istream& operator>> (unsigned short&);
	    unsafe_istream& operator>> (unsigned int&);
	    unsafe_istream& operator>> (unsigned long&);
	    unsafe_istream& operator>> (float&);
	    unsafe_istream& operator>> (double&);
	    unsafe_istream& operator>> (streambuf* sbufp);
	    unsafe_istream& operator>> (unsafe_istream& (*manip)(unsafe_istream&));
	    unsafe_istream& operator>> (unsafe_ios& (*manip)(unsafe_ios&) );
       public:
	    // wide character
	    unsafe_istream& operator>>(wchar_t&);
	    unsafe_istream& operator>>(wchar_t*);
       public:
	    // exported constructors
	    unsafe_istream(streambuf* sbuf);
       };
       class istream : virtual public ios, public unsafe_istream {
       public:
	    //exported functions

	    // unformatted input functions
	    istream&	    read(char* ptr, int count);
	    istream&	    read(unsigned char* ptr, int count);
	    istream&	    get(char* ptr, int count, char delim='\n');
	    istream&	    get(unsigned char* ptr,int count, char delim='\n');
	    istream&	    get(unsigned char& ch);
	    istream&	    get(char& ch);
	    istream&	    get(streambuf& sb, char delim ='\n');
	    istream&	    getline(char* ptr, int count, char delim='\n');
	    istream&	    getline(unsigned char* ptr, int count, char delim='\n');
	    int		    get();
	    int		    peek();
	    istream&	    ignore(int len=1,int delim=EOF);
	    istream&	    putback(char ch);

	    // wide character
	    istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
	    istream& get(wchar_t& wc);
	    istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
	    istream& wignore(int count=1, wchar_t wdelim=WEOF);
	    wint_t peekw();

	    // other functions
	    int		    ipfx(int noform=0);
	    istream&	    seekg(streampos pos);
	    istream&	    seekg(streamoff offset, seek_dir dir);
	    streampos	    tellg();
	    int		    sync();
	    int		    gcount();
       public:
	    // exported operator functions
	    istream&	    operator>>(char*);
	    istream&	    operator>>(unsigned char*);
	    istream&	    operator>>(char&);
	    istream&	    operator>>(unsigned 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&));
	    istream&	    operator>>(ios& (*)(ios&));
       public:
	    // wide character
	    istream& operator>>(wchar_t&);
	    istream& operator>>(wchar_t*);
       public:
	    // exported constructors
	    istream(streambuf*);

       };

       class istream_withassign : public istream {
       public:
	    istream_withassign();
	    istream_withassign& operator= (istream&);
	    istream_withassign& operator= (streambuf*);
       };
       extern istream_withassign cin;
	    ios&  dec(ios&);
	    ios&  hex(ios&);
	    ios&  oct(ios&);
	    istream& ws(istream&);

	    unsafe_ios&	    dec(unsafe_ios&) ;
	    unsafe_ios&	    hex(unsafe_ios&) ;
	    unsafe_ios&	    oct(unsafe_ios&) ;
	    unsafe_istream& ws(unsafe_istream&) ;

DESCRIPTION
       Class  istream supports formatted and unformatted extraction (input) of
       data from an associated streambuf.

       The istream object and  its  member  functions  are  protected  against
       access  by  multiple threads by mutex locks.  The unsafe_istream object
       and its member functions do not implement mutex	locking.   Aside  from
       this  difference,  the  functionality of istream and unsafe_istream and
       their respective member functions is identical.	For  more  information
       on  mt-safety,  mutex  locks and how these relate to iostreams objects,
       see the "MT-Safe libC Programmers Guide".

   ENVIRONMENT
   Constructors and Assignment
       istream(sbufp)
	      Associates the streambuf pointed to by sbufp with the stream and
	      initializes the ios state.

       istream_withassign()
	      Performs no initialization.

       istream_withassign isw = sbufp
	      Associates  the  streambuf pointed to by sbufp with isw and com‐
	      pletely initializes isw.

       istream_withassign isw = istr
	      The streambuf associated with istr becomes associated  with  isw
	      and the constructor completely initializes isw.

   About wide character operations
       Input functions that produce wide character results set failbit if they
       encounter an illegal sequence of bytes.	A sequence of bytes is consid‐
       ered  illegal  if  the  input function cannot interpret it as multibyte
       encoding of characters in the current locale.

       Do not directly follow a multibyte input operation that may peek	 ahead
       with  a	single-byte input operation.  A single-byte input operation is
       allowable after a seek (seekg).	streambufs need only  support  peeking
       one  byte  ahead,  so  multibyte	 input operations that peek may buffer
       "peeked" bytes in the istream itself.  seekg and tellg take account  of
       any such internal buffering.

   Input prefix function
       int i = istr.ipfx(noform)
	      Performs	setup  common to all extraction operations.  Formatted
	      extractors call ipfx(0); unformatted  extractors	call  ipfx(1).
	      If  the error state of istr is non-zero, ipfx returns zero imme‐
	      diately.	If a stream is tied to istr (see tie in ios(3CC4)) and
	      noform  is zero, the tied stream is flushed.  If the skipws flag
	      is set for the stream and noform	is  zero,  leading  whitespace
	      characters  (as defined by iswhite, see ctype(3c)), are skipped.
	      Function ipfx returns zero if any	 error	condition  is  encoun‐
	      tered, non-zero otherwise.

       int i = istr.wipfx(noform)
	      Wide  character  extractors use wipfx in place of ipfx.  This is
	      similar to ipfx(), but wipfx() skips over any multibyte space as
	      defined  by  iswspace  where  ipfx  skips over single-byte space
	      characters.  Furthermore wipfx() sets ios::failbit if encounters
	      an  illegal sequence of bytes.  This function is not in the pro‐
	      posed ANSI iostreams interface, so  avoid	 calling  it  directly
	      from application code.

   Formatted input (extraction) functions
       These call ipfx(0).  If it returns zero, no further action takes place.
       Otherwise, leading whitespace will be stripped if ios::skipws  is  set.
       If  only	 whitespace  is	 left  in the istream, no characters will then
       remain and the ios::failbit will	 be  set.   Wide  character  formatted
       input  functions	 call wipfx(0) and return with no further action if it
       returns zero.

       istr >> sbufp
	      Extracts characters from istr and inserts them into the  stream‐
	      buf  pointed to by sbufp.	 This function always returns a refer‐
	      ence to istr.  You can use this function to copy a stream	 effi‐
	      ciently,	but  you  should  be sure that neither stream is tied.
	      For example:
		   #include <iostream.h>
		   main()
		   {   // copy cin to cout
		       cin.tie(0);
		       cout.tie(0);
		       cin >> cout.rdbuf(); // see ios(3CC4) for rdbuf
		       return 0;
		   }

       istr >> x
	      Extracts characters from istr and converts them according to the
	      type  of	x.   If ipfx returns zero, no characters are extracted
	      and x is unchanged.  Any errors encountered are recorded in  the
	      error  state  of	istr.  In general, ios::failbit means that the
	      next available characters were not suitable for  the  type;  for
	      example,	leading	 letters for a numeric type, or leading white‐
	      space for any type.  The offending characters are not extracted.
	      In  general,  ios::badbit	 means	that  no  characters  could be
	      extracted; for example, attempting to extract past  the  end  of
	      file.  These functions always return a reference to istr.	 User-
	      written functions should be of the form
		   istream& operator>> (istream&, SomeType)
	      and should conform to these principles.

	      The type of x and the format state of the istream (see ios(3CC4)
	      determine	 the  details of the extraction and conversion.	 These
	      functions do not change the state of the	istream,  except  that
	      the width variable is reset to zero after each formatted extrac‐
	      tion.  The predefined formatted extractors are as follows:

       char&, unsigned char&
	      Extracts one character and stores it in x.

       wchar_t&
	      Extracts one multibyte character and stores it in x  as  a  wide
	      character if wipfx(0) succeeds and it does not encounter end-of-
	      file.  Sets ios::failbit if it encounters an illegal sequence of
	      bytes.

       short&, unsigned short&
	 int&, unsigned int&
	 long&, unsigned long&
	      Extracts	characters  and	 converts  them	 to  an integral value
	      according to the conversion base in the istream's format	flags,
	      and  stores  the	value in x.  The first character may be a plus
	      (`+') or minus (`-') sign.  The characters are then  treated  as
	      decimal,	octal,	or hexadecimal, if the ios::basfield flags are
	      dec, oct, or hex, respectively.  If none of these flags is  set,
	      the  number  is interpreted in the same way as integer constants
	      in C++.  That is, if the first  two  characters  are  ``0x''  or
	      ``0X'' the base is hex; otherwise, if the first character is `0'
	      the base is octal; otherwise the base  is	 decimal.   Extraction
	      (and  thus  conversion) stops with the first non-digit, which is
	      not extracted.  Valid digits are `0'-`7' for octal, `0'-`9'  for
	      decimal,	and  `0'-`9',  `a'-`f',	 `A'-`F' for hexadecimal.  The
	      error flag ios::failbit is set if no valid  digits  are  encoun‐
	      tered.   A  ``0x''  followed by a non-digit is an error.	In the
	      case of an error, the value of x is not changed.

       float&, double&
	      Extracts characters and converts them to a floating-point	 value
	      according	 to  the  C++  rules for floating-point constants, and
	      stores the value in x.  The error flag ios::failbit  is  set  if
	      the  characters  extracted  do not begin a well-formed floating-
	      point number; some characters may be  extracted  in  this	 case,
	      depending	 on  at what point the error is detected.  In the case
	      of an error, the value of x is not changed.

       char*, unsigned char*
	      Extracts characters and stores them in the array pointed to by x
	      until  a whitespace character is encountered.  The whitespace is
	      not extracted (but ipfx may have discarded leading  whitespace).
	      If the width formatting variable (see ios(3CC4)) is non-zero, at
	      most width-1 characters are extracted.  A terminating  null  (0)
	      is  always  stored  in  x,  even when nothing is extracted.  The
	      error flag ios::failbit is set if no  characters	are  available
	      for extraction.

       wchar_t*
	      Behaves  like  the extractor for char* except it decodes charac‐
	      ters in multibyte representation into an array of	 wide  charac‐
	      ters  until  it encounters a multibyte whitespace character.  In
	      addition sets ios::failbit if it encounters an illegal  sequence
	      of bytes.

   Unformatted input (extraction) functions
       These call ipfx(1).  If it returns zero, no further action takes place.
       Leading whitespace is not skipped, and no conversions take place.  Wide
       character input functions call wipfx(1) in place of ipfx(1).

       int c = istr.get()
	      Extracts	the  next character from istr and returns it.  Returns
	      EOF if no more characters are available; never  sets  ios::fail‐
	      bit.

       istr.get(ch)
	      Extracts	the  next  character  from  istr  and stores it in ch.
	      Stores EOF if no more characters are available; sets  ios::fail‐
	      bit when attempting to extract beyond EOF.  This function always
	      returns a reference to istr.

       istr.get(ptr, count, delim)
	      Extracts characters from istr and stores them in the char	 array
	      beginning	 at  ptr.   Extraction	stops after count-1 characters
	      have been extracted  or  when  a	character  matching  delim  is
	      encountered,  whichever  happens first.  If a delim character is
	      encountered, it is  not  extracted  or  stored.	This  function
	      always  stores  a	 terminating  null  (0)	 even  if  nothing  is
	      extracted.  It sets ios::failbit	only  if  EOF  is  encountered
	      before  any characters are stored.  This function always returns
	      a reference to istr.

       istr.get(sbuf, delim)
	      Extracts characters from istr and stores them in	the  streambuf
	      sbuf.  Extraction stops when a character matching delim (or EOF)
	      is encountered, or when a store into sbuf fails, whichever  hap‐
	      pens  first.   If	 a  delim  character is encountered, it is not
	      extracted or stored.  If delim is	 EOF,  extraction  stops  only
	      when  input  is  exhausted or when a store fails.	 This function
	      sets ios::failbit only if a store into  sbuf  fails;  it	always
	      returns a reference to istr.

       istr.get(wc)
	      Extracts the next character from istr and stores it in wc in its
	      wide character representation.  Stores WEOF if no	 more  charac‐
	      ters are available; sets ios::failbit when attempting to extract
	      beyond end of file or if it encounters an	 illegal  sequence  of
	      bytes.  Returns a reference to istr.

       istr.get(wptr, count, wdelim)
	      Same  as for single-byte characters, but wptr points to an array
	      of wchar_t and wdelim is of type wchar_t.	 Sets ios::failbit  if
	      it encounters an illegal sequence of bytes.  Returns a reference
	      to istr.

       istr.getline(ptr, count, delim)
	      This function  does  the	same  thing  as	 istr.get(ptr,	count,
	      delim),  except that delim, if encountered, is extracted but not
	      stored.  Once count-1 characters have been extracted,  the  next
	      character	 is  left in istr, even if it is delim.	 This function
	      always returns a reference to istr.

       istr.getline(wptr, count, wdelim)
	      As for single-byte characters, but wptr points to	 an  array  of
	      wchar_t  and wdelim is of type wchar_t.  Sets ios::failbit if it
	      encounters an illegal sequence of bytes.	Returns a reference to
	      istr.

       istr.ignore(count, delim)
	      Extracts	characters  from  istr	and discards them.  Extraction
	      stops when a character matching delim is encountered, when count
	      characters  have	been  extracted,  or  when EOF is encountered,
	      whichever happens first; the delim character is  extracted.   If
	      delim  is	 EOF,  all  of	the input is discarded.	 This function
	      always returns a reference to istr.

       istr.wignore(count=1, wdelim=WEOF)
	      As for ignore(), but if wdelim is not WEOF, count indicates  the
	      number of multibyte characters to skip rather than the number of
	      bytes to skip.  Even if wdelim is WEOF,  sets  ios::failbit  and
	      stops  if it encounters an illegal sequence of bytes.  Returns a
	      reference to istr.

       istr.read(ptr, count)
	      Extracts characters from istr and stores them in the char	 array
	      beginning	 at ptr.  Extraction stops after count characters have
	      been extracted or when EOF  is  encountered,  whichever  happens
	      first.   This  function  sets ios::failbit if EOF is encountered
	      before count characters are extracted; it always returns a  ref‐
	      erence to istr.  The number of characters extracted can be found
	      by calling istr.gcount().	 (See below.)

   Positioning functions
       These deal with the get pointer of the  streambuf  associated  with  an
       istream.	  See  .BR sbufpub (3CC4) for a complete discussion. Multibyte
       input operations may cause the get pointer of the streambuf  to	differ
       from  the  value	 reported  by  tellg(),	 but seeks done on the istream
       itself will still coordinate  correctly	with  all  operations  on  the
       istream.

       istr.seekg(pos)
	      Sets the position of the get pointer; returns istr.

       istr.seekg(offset, dir)
	      Sets the position of the get pointer; returns istr.

       streampos pos = istr.tellg()
	      Returns  the  current  position  of  the get pointer.  Multibyte
	      input operations may cause the get pointer of the	 streambuf  to
	      differ from the value reported by tellg(), but seeks done on the
	      istream rather than the streambuf	 will  still  coordinate  cor‐
	      rectly with all operations on the istream.

   Miscellaneous functions
       int i = istr.gcount()
	      Returns the number of characters extracted from istr by the last
	      unformatted input function.   Note:  Formatted  input  functions
	      might  call  unformatted	functions,  thus  changing  the count.
	      After an unformatted wide	 character  input  function,  gcount()
	      returns the number of (multibyte) characters extracted.

       int i = istr.peek()
	      First calls istr.ipfx(1).	 If ipfx returns zero or if istr is at
	      EOF, it returns EOF.  Otherwise, it returns the  next  character
	      without extracting it.

       int i = istr.peekw()
	      Calls  wipfx(1)  and  returns  (wint_t)WEOF if that fails.  Sets
	      ios::failbit and	returns	 WEOF  if  it  encounters  an  illegal
	      sequence of bytes.  If successful, returns the next character in
	      the stream as a wide character without moving past it.

       istr.putback(ch)
	      If istr.fail() returns non-zero, this function  returns  without
	      doing anything.  Otherwise, it attempts to back up the streambuf
	      associated with istr by pushing back character ch.   Because  it
	      does no extraction, it does not call ipfx.  It may fail, setting
	      ios::failbit.  In general, c must match the character  ahead  of
	      the   streambuf's	 get  pointer  (normally  the  last  character
	      extracted) - input might be coming from  a  read-only  in-memory
	      buffer.

       int i = istr.sync()
	      Forces a correspondence between the internal data structures and
	      the external source of characters in  an	implementation-defined
	      manner.	It  calls  the	virtual function istr.rdbuf()->sync(),
	      which of course will depend on the actual	 type  of  the	buffer
	      class.  It returns EOF on error.

   Predefined Manipulators
       A  manipulator  may  be	used  apparently  as  an inserted or extracted
       object, but many only change the state of the stream.  See  manip(3CC4)
       and  ios(3CC4)  for  more information.  Several manipulators are prede‐
       fined for use with istreams.

       istr >> manip
	      This is equivalent to the call manip(istr).

       istr >> dec
	      This sets the conversion base of istr to 10.

       istr >> oct
	      This sets the conversion base of istr to 8.

       istr >> hex
	      This sets the conversion base of istr to 16.

       istr >> ws
	      This extracts and	 discards  consecutive	whitespace  characters
	      from istr.

SEE ALSO
       ios.intro(3CC4), ctype(3C), ios(3CC4), manip(3CC4), sbufpub(3CC4),
       stdiobuf(3CC4), C++ Library Reference, Chapter 3, "The Classic iostream
       Library", and Chapter 4, "Using Classic iostream in a Multithreaded
       Environment"

				08 August 2000			 ISTREAM(3CC4)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net