The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

wistream (3)
  • >> wistream (3) ( Solaris man: Библиотечные вызовы )
  • 
                           Standard C++ Library
                 Copyright 1998, Rogue Wave Software, Inc.
    
    
    NAME
         basic_istream
    
          - 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  pro-
         perties:  the  formatted input functions (or extractors) and
         the unformatted input functions. Both groups of input  func-
         tions    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 controlling the status of the stream
         or locking it in a multithread environment.
    
         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  parame-
            ter 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 param-
            eter 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  function  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 discards 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 environment the sentry object  construc-
            tor  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 sentry 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 member  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. Oth-
            erwise 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  function  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  excep-
            tion is rethrown.
    
    
    
         istream_type&
         operator>>(streambuf_type& sb);
    
    
            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  function  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  excep-
            tion 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 loca-
            tions of an array whose first element is designated by s.
            Characters are extracted and stored until any of the fol-
            lowing 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  function  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  function  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  excep-
            tion 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 loca-
            tions of an array whose first element is designated by s.
            Characters are extracted and stored until any of the fol-
            lowing 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  function  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 avail-
            able  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 loca-
            tions of an array whose first element is designated by s.
            Characters are extracted and stored until any of the fol-
            lowing 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 loca-
            tions 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  char-
                      acters
    
                 -    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()->pubsync()  and if that function returns -1 calls
            the basic_ios member function setstate(badbit). The  pur-
            pose  of  this  function  is  to synchronize the internal
            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 current position of the
            input sequence by calling rdbuf()->pubseekoff(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 setstate(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 loca-
            tions 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 char-
            acters 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  function  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_streambuf(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
    
    
    
    


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру