istream man page on Solaris

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

basic_istream(3C++)		       -		   basic_istream(3C++)

Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.

NAME
       basic_istream, istream, wistream

	-  Assists in reading and interpreting input from sequences controlled
       by a stream buffer.

SYNOPSIS
       #include <istream>
       template<class charT, class traits = char_traits<charT> >
       class basic_istream
       : virtual public basic_ios<charT, traits>

DESCRIPTION
       The class basic_istream defines member functions that assist in reading
       and interpreting input from sequences controlled by a stream buffer.

       Two  groups  of member function signatures share common properties: the
       formatted input functions (or extractors)  and  the  unformatted	 input
       functions.  Both	 groups	 of  input functions obtain (or extract) input
       characters from basic_streambuf. They both  begin  by  constructing  an
       object  of  class_basic_istream::sentry	and, if this object is in good
       state after construction, the function obtains the requested input. The
       sentry  object performs exception safe initialization, such as control‐
       ling the status of the stream or locking it in a	 multithread  environ‐
       ment.

       Some  formatted	input  functions  parse	 characters extracted from the
       input sequence, converting the result to a value of  some  scalar  data
       type, and storing the converted value in an object of that scalar type.
       The conversion behavior depends directly on  the	 locale	 object	 being
       imbued in the stream.

INTERFACE
       template<class charT, class traits = char_traits<charT> >
       class basic_istream
       : virtual public basic_ios<charT, traits> {

       public:

       typedef basic_istream<charT, traits>    istream_type;
       typedef basic_ios<charT, traits>	       ios_type;
       typedef basic_streambuf<charT, traits>  streambuf_type;

       typedef traits			   traits_type;
       typedef charT			   char_type;
       typedef typename traits::int_type   int_type;
       typedef typename traits::pos_type   pos_type;
       typedef typename traits::off_type   off_type;

explicit basic_istream(basic_streambuf<;charT, traits> *sb);
virtual ~basic_istream();

class sentry
  {
    public:
     inline explicit sentry(basic_istream<charT,traits>&,
			    bool noskipws = 0);
       ~sentry();
      operator bool ();
  };

istream_type& operator>>(istream_type&
			 (*pf)(istream_type&));
istream_type& operator>>(ios_base& (*pf)(ios_base&));
istream_type& operator>>(ios_type& (*pf)(ios_type&));

istream_type& operator>>(bool& n);
istream_type& operator>>(short& n);
istream_type& operator>>(unsigned short& n);
istream_type& operator>>(int& n);
istream_type& operator>>(unsigned int& n);
istream_type& operator>>(long& n);
istream_type& operator>>(unsigned long& n);
istream_type& operator>>(float& f);
istream_type& operator>>(double& f);
istream_type& operator>>(long double& f);

istream_type& operator>>(void*& p);

istream_type& operator>>(streambuf_type& sb);
istream_type& operator>>(streambuf_type *sb);

streamsize gcount() const;
int_type get();
istream_type& get(char_type& c);
istream_type& get(char_type *s, streamsize n);
istream_type& get(char_type *s, streamsize n,
		  char_type delim);

istream_type& get(streambuf_type& sb);
istream_type& get(streambuf_type& sb,char_type delim);

istream_type& getline(char_type *s, streamsize n);
istream_type& getline(char_type *s, streamsize n,
		      char_type delim);

istream_type& ignore(streamsize n = 1,
		     int_type delim = traits::eof());

int peek();
istream_type& read(char_type *s, streamsize n);
streamsize readsome(char_type *s, streamsize n);

istream_type& putback(char_type c);
istream_type& unget();
int sync();

pos_type tellg();
istream_type& seekg(pos_type&);
istream_type& seekg(off_type&, ios_base::seekdir);

};

//global character extraction templates

 template<class charT, class traits>
 basic_istream<charT, traits>&
  ws(basic_istream<charT, traits>& is);

template<;class charT, class traits>
basic_istream<;charT, traits>&
operator>> (basic_istream<charT, traits>&, charT&);

template<;class charT, class traits>
basic_istream<;charT, traits>&
operator>> (basic_istream<charT, traits>&, charT*);

template<;class traits>
basic_istream<;char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char&);

template<;class traits>
basic_istream<;char, traits>&
operator>> (basic_istream<char, traits>&, signed char&);

template<;class traits>
basic_istream<;char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char*);

template<;class traits>
basic_istream<;char, traits>&
operator>> (basic_istream<char, traits>&, signed char*);

TYPES
       char_type

   The type char_type is a synonym for the template parameter charT.

int_type

   The type int_type is a synonym of type traits::in_type.

ios_type

   The type ios_type is a synonym for basic_ios<charT, traits> .

istream

   The type istream is an instantiation of class basic_istream on type char:

   typedef basic_istream<char> istream;

istream_type

   The type istream_type is a synonym for basic_istream<charT, traits>.

off_type

   The type off_type is a synonym of type traits::off_type.

pos_type

   The type pos_type is a synonym of type traits::pos_type.

streambuf_type

   The type streambuf_type is a synonym for basic_streambuf<charT, traits> .

traits_type

   The type traits_type is a synonym for the template parameter traits.

wistream

   The	type  wistream	is  an	instantiation  of  class basic_istream on type
   wchar_t:

   typedef basic_istream<wchar_t> wistream;

PUBLIC CONSTRUCTORS
       explicit basic_istream(basic_streambuf<charT, traits>* sb);

   Constructs an object of class basic_istream, assigning  initial  values  to
   the base class by calling basic_ios::init(sb).

PUBLIC DESTRUCTORS
       virtual ~basic_istream();

   Destroys an object of class basic_istream.

SENTRY CLASSES
       explicit sentry(basic_istream<charT,traits>&,
		bool noskipws=0);

   Prepares  for formatted or unformatted input. If the basic_ios member func‐
   tion tie() is not a null pointer,  the  function  synchronizes  the	output
   sequence  with  any associated stream. If noskipws is zero and the ios_base
   member function flags() & skipws is nonzero, the function extracts and dis‐
   cards  each	character  as  long as the next available input character is a
   white space character. If after any preparation is completed, the basic_ios
   member  function  good()  is	 true, the sentry conversion function operator
   bool() returns true. Otherwise it returns false. In a multithread  environ‐
   ment	 the  sentry  object constructor is responsible for locking the stream
   and the stream buffer associated with the stream.

~sentry();

   Destroys an object of class sentry. In a multithread environment, the  sen‐
   try	object	destructor  is	responsible  for  unlocking the stream and the
   stream buffer associated with the stream.

operator bool();

   If after any preparation is completed, the basic_ios member function good()
   is  true,  the sentry conversion function operator bool() returns true else
   it returns false.

EXTRACTORS
       istream_type&
       operator>>(istream_type&
	  (*pf) (istream_type&));

   Calls pf(*this), then returns *this.

istream_type&
operator>>(ios_type& (*pf) (ios_type&));

   Calls pf(*this), then returns *this.

istream_type&
operator>>(ios_base& (*pf) (ios_base&));

   Calls pf(*this), then returns *this.

istream_type&
operator>>(bool& n);

   Converts a Boolean value, if one is available, and stores it in n.  If  the
   ios_base member function flag() & ios_base::boolalpha is false, it tries to
   read an integer value, which if found must be 0 or 1. If the boolalpha flag
   is  true,  it  reads	 characters until it determines whether the characters
   read are correct according to the locale function numpunct<>::truename() or
   numpunct<>::falsename().  If no match is found, it calls the basic_ios mem‐
   ber function setstate(failbit), which may throw ios_base::failure.

istream_type&
operator>>(short& n);

   Converts a signed short integer, if one is available, and stores it	in  n,
   then returns *this.

istream_type&
operator>>(unsigned short& n);

   Converts  an	 unsigned short integer, if one is available, and stores it in
   n, then returns *this.

istream_type&
operator>>(int& n);

   Converts a signed integer, if one is available, and stores it  in  n,  then
   returns *this.

istream_type&
operator>>(unsigned int& n);

   Converts an unsigned integer, if one is available, and stores it in n, then
   returns *this.

istream_type&
operator>>(long& n);

   Converts a signed long integer, if one is available, and stores  it	in  n,
   then returns *this.

istream_type&
operator>>(unsigned long& n);

   Converts an unsigned long integer, if one is available, and stores it in n,
   then returns *this.

istream_type&
operator>>(float& f);

   Converts a float, if one is available, and stores it	 in  f,	 then  returns
   *this.

istream_type&
operator>>(double& f);

   Converts  a	double,	 if one is available, and stores it in f, then returns
   *this.

istream_type&
operator>>(long double& f);

   Converts a long double, if one is available,	 and  stores  it  in  f,  then
   returns *this.

istream_type&
operator>>(void*& p);

   Extracts  a	void  pointer,	if  one is available, and stores it in p, then
   returns *this.

istream_type&
operator>>(streambuf_type* sb);

   If sb is null, calls the basic_ios member function setstate(badbit),	 which
   may	throw  ios_base::failure. Otherwise extracts characters from *this and
   inserts them in the	output	sequence  controlled  by  sb.  Characters  are
   extracted and inserted until any of the following occurs:

	-    An end-of-file on the input sequence

	-    A failure when inserting in the output sequence

	-    An exception

   If  the  function stores no characters, it calls the basic_ios member func‐
   tion setstate(failbit), which may throw ios_base::failure. If  failure  was
   due to catching an exception thrown while extracting characters from sb and
   failbit is on in exception(), then the caught exception is rethrown.

istream_type&
operator>>(streambuf_type& sb);

   Extracts characters from *this and inserts them in the output sequence con‐
   trolled  by sb. Characters are extracted and inserted until any of the fol‐
   lowing occurs:

	-    An end-of-file on the input sequence

	-    A failure when inserting in the output sequence

	-    An exception

   If the function stores no characters, it calls the basic_ios	 member	 func‐
   tion	 setstate(failbit),  which may throw ios_base::failure. If failure was
   due to catching an exception thrown while extracting characters from sb and
   failbit is on in exception(), then the caught exception is rethrown.

UNFORMATTED FUNCTIONS
       streamsize
       gcount() const;

   Returns  the	 number	 of characters extracted by the last unformatted input
   member function called.

int_type
get();

   Extracts a character, if one is available. Otherwise,  the  function	 calls
   the	 basic_ios   member   function	 setstate(failbit),  which  may	 throw
   ios_base::failure.	Returns	  the	character   extracted	 or    returns
   traits::eof(), if none is available.

istream_type&
get(char_type& c);

   Extracts  a character, if one is available, and assigns it to c. Otherwise,
   the function calls the basic_ios member function  setstate(failbit),	 which
   may throw ios_base::failure.

istream_type&
get(char_type* s, streamsize n,char_type delim);

   Extracts  characters	 and stores them into successive locations of an array
   whose first element is designated by s. Characters are extracted and stored
   until any of the following occurs:

	-    n-1 characters are stored

	-    An end-of-file on the input sequence

	-    The next available input character == delim.

   If  the  function stores no characters, it calls the basic_ios member func‐
   tion setstate(failbit), which may throw ios_base::failure. In any case,  it
   stores a null character into the next successive location of the array.

istream_type&
get(char_type* s, streamsize n);

   Calls get(s,n,widen("\n")).

istream_type&
get(streambuf_type& sb,char_type delim);

   Extracts  characters	 and inserts them in the output sequence controlled by
   sb. Characters are extracted	 and  inserted	until  any  of	the  following
   occurs:

	-    An end-of-file on the input sequence

	-    A failure when inserting in the output sequence

	-    The next available input character == delim.

	-    An exception

   If  the  function stores no characters, it calls the basic_ios member func‐
   tion setstate(failbit), which may throw ios_base::failure. If  failure  was
   due to catching an exception thrown while extracting characters from sb and
   failbit is on in exception(), then the caught exception is rethrown.

istream_type&
get(streambuf_type& sb);

   Calls get(sb,widen("\n")).

istream_type&
getline(char_type* s, streamsize n, char_type delim);

   Extracts characters and stores them into successive locations of  an	 array
   whose first element is designated by s. Characters are extracted and stored
   until any of the following occurs:

	-    n-1 characters are stored

	-    An end-of-file on the input sequence

	-    The next available input character == delim.

   If the function stores no characters, it calls the basic_ios	 member	 func‐
   tion	 setstate(failbit), which may throw ios_base::failure. In any case, it
   stores a null character into the next successive location of the array.

istream_type&
getline(char_type* s, streamsize n);

   Calls getline(s,n,widen("\n")).

istream_type&
ignore(streamsize n=1, int_type delim=traits::eof());

   Extracts characters and discards them. Characters are extracted  until  any
   of the following occurs:

	-    n characters are extracted

	-    An end-of-file on the input sequence

	-    The next available input character == delim.

int_type
peek();

   Returns  traits::eof()  if  the  basic_ios  member  function good() returns
   false. Otherwise, returns the next available character. Does not  increment
   the current get pointer.

istream_type&
putback(char_type c);

   Inserts c in the putback sequence.

istream_type&
read(char_type* s, streamsize n);

   Extracts  characters	 and stores them into successive locations of an array
   whose first element is designated by s. Characters are extracted and stored
   until any of the following occurs:

	-    n characters are stored

	-    An end-of-file on the input sequence

   If  the function does not store n characters, it calls the basic_ios member
   function setstate(failbit), which may throw ios_base::failure.

streamsize
readsome(char_type* s, streamsize n);

   Extracts characters and stores them into successive locations of  an	 array
   whose first element is designated by s. If rdbuf()->in_avail() == -1, calls
   the basic_ios member function setstate(eofbit).

	-    If rdbuf()->in_avail() == 0, extracts no characters

	-    If	    rdbuf()->in_avail()	    >	  0,	 extracts     <br>min(
	     rdbuf()->in_avail(), n)

   In any case the function returns the number of characters extracted.

istream_type&
seekg(pos_type& pos);

   If	the   basic_ios	  member  function  fail(),  returns  false,  executes
   rdbuf()->pubseekpos(pos), which positions the current pointer of the	 input
   sequence at the position designated by pos.

istream_type&
seekg(off_type& off, ios_base::seekdir dir);

   If	the   basic_ios	  member   function  fail()  returns  false,  executes
   rdbuf()->pubseekpos(off,dir), which positions the current  pointer  of  the
   input sequence at the position designated by off and dir.

int
sync();

   If  rdbuf()	is  a  null pointer, return -1. Otherwise, calls rdbuf()->pub‐
   sync() and if that function returns -1 calls the basic_ios member  function
   setstate(badbit). The purpose of this function is to synchronize the inter‐
   nal input buffer, with the external sequence of characters.

pos_type
tellg();

   If the basic_ios member  function  fail()  returns  true,  tellg()  returns
   pos_type(off_type(-1))  to  indicate failure. Otherwise it returns the cur‐
   rent	 position   of	 the   input   sequence	  by   calling	 rdbuf()->pub‐
   seekoff(0,cur,in).

istream_type&
unget();

   If  rdbuf() is not null, calls rdbuf()->sungetc(). If rdbuf() is null or if
   sungetc() returns traits::eof(), calls the basic_ios member	function  set‐
   state(badbit).

NON-MEMBER FUNCTIONS
       template<class charT, class traits>
       basic_istream<charT, traits>&
       operator>>(basic_istream<charT, traits>& is, charT& c);

   Extracts a character if one is available, and stores it in c. Otherwise the
   function calls the basic_ios member function setstate(failbit),  which  may
   throw ios_base::failure.

template<;class charT, class traits>
basic_istream<;charT, traits>&
operator>>(basic_istream<charT, traits>& is, charT* s);

   Extracts  characters	 and stores them into successive locations of an array
   whose first element is designated by s. If  the  ios_base  member  function
   is.width()  is  greater than zero, then is.width() is the maximum number of
   characters stored. Characters are extracted and stored  until  any  of  the
   following occurs:

	-    If is.width()>0, is.width()-1 characters are extracted

	-    An end-of-file on the input sequence

	-    The next available input character is a white space

   If  the  function stores no characters, it calls the basic_ios member func‐
   tion setstate(failbit), which may throw ios_base::failure. In any case,  it
   then stores a null character into the next successive location of the array
   and calls width(0).

template<;class traits>
basic_istream<;char, traits>&
operator>>(basic_istream<char, traits>& is,
	   unsigned char& c);

   Returns is >> (char&)c.

template<;class traits>
basic_istream<;char, traits>&
operator>>(basic_istream<char, traits>& is,
	  signed char& c);

   Returns is >> (char&)c.

template<;class traits>
basic_istream<;char, traits>&
operator>>(basic_istream<char, traits>& is,
	  unsigned char* c);

   Returns is >> (char*)c.

template<;class traits>
basic_istream<;char, traits>&
operator>>(basic_istream<char, traits>& is,
	  signed char* c);

   Returns is >> (char*)c.

template<;class charT, class traits>
basic_istream<;charT, traits>&
ws(basic_istream<;charT, traits>& is);

   Skips any white space in the input sequence and returns is.

EXAMPLE
       //
       // stdlib/examples/manual/istream1.cpp
       //
       #include<iostream>
       #include<istream>
       #include<fstream>

       void main ( )
       {
 using namespace std;

 float f= 3.14159;
 int   i= 3;
 char  s[200];

  // open a file for read and write operations
 ofstream out("example", ios_base::in | ios_base::out
	       | ios_base::trunc);

  // tie the istream object to the ofstream filebuf
 istream in (out.rdbuf());

  // output to the file
 out << "Annie is the Queen of porting" << endl;
 out << f << endl;
 out << i << endl;

  // seek to the beginning of the file
 in.seekg(0);

 f = i = 0;

  // read from the file using formatted functions
 in >> s >> f >> i;

  // seek to the beginning of the file
 in.seekg(0,ios_base::beg);

  // output the all file to the standard output
 cout << in.rdbuf();

  // seek to the beginning of the file
 in.seekg(0);

  // read the first line in the file
  // "Annie is the Queen of porting"
 in.getline(s,100);

 cout << s << endl;

  // read the second line in the file
  // 3.14159
 in.getline(s,100);

 cout << s << endl;

  // seek to the beginning of the file
 in.seekg(0);

  // read the first line in the file
  // "Annie is the Queen of porting"
 in.get(s,100);

  // remove the newline character
 in.ignore();

 cout << s << endl;

  // read the second line in the file
  // 3.14159
 in.get(s,100);

 cout << s << endl;

  // remove the newline character
 in.ignore();

  // store the current file position
 istream::pos_type position = in.tellg();

 out << "replace the int" << endl;

  // move back to the previous saved position
 in.seekg(position);

  // output the remain of the file
  // "replace the int"
  // this is equivalent to
  // cout << in.rdbuf();
 while( !char_traits<char>::eq_int_type(in.peek(),
	 char_traits<char>::eof()) )
  cout << char_traits<char>::to_char_type(in.get());

 cout << "\n\n\n" << flush;
}
//
// istream example #2
//
#include <iostream>

void main ( )
{
 using namespace std;

 char p[50];

  // remove all the white spaces
 cin >> ws;

  // read characters from stdin until a newline
  // or 49 characters have been read
 cin.getline(p,50);

  // output the result to stdout
 cout << p;
}

SEE ALSO
       char_traits(3C++),   ios_base(3C++),   basic_ios(3C++),	 basic_stream‐
       buf(3C++), basic_iostream(3C++)

       Working Paper for Draft Proposed International Standard for Information
       Systems--Programming Language C++, Section 27.6.1

STANDARDS CONFORMANCE
       ANSI X3J16/ISO WG21 Joint C++ Committee

Rogue Wave Software		  02 Apr 1998		   basic_istream(3C++)
[top]

List of man pages available for Solaris

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