Click above to get retro games delivered to your door ever month!

istream::operator>>

Usage

   #include <iostream.hpp>
   The prototypes of the extractor functions are listed in the public interface
   shown above.

Description

   The built-in extractors first call the extractor prefix function ipfx().
   If that returns zero, i.e. some error has ocurred, then the inserter does
   nothing. Otherwise it parses the incoming character sequence in an
   attempt to form a value of the required type.

   If the operation fails the error flags will be set. If input of the
   required type was detectably incomplete, and either an unexpected
   character or end of file is detected, the failbit flag is set. In the end
   of file case, eofbit is also set. If under these circumstances characters

   have been lost, that is removed from the associated streambuf, the badbit
   flag will also be set. The failbit flag will also be set if the input is
   such as to cause overflow of the specified type.

   For example, scanning the stream:

       abcdefg

   for an integer will result in failbit being set. No suitable characters
   were found, and therefore none were lost.

   In the case of the stream:

       0xhijklm

   Then both failbit and badbit will be set. The extractor happily removed
   0x from the stream, but could then make no sense of what followed.

   For the stream:

       0x

   each of failbit, badbit, and eofbit will be set, since the input was not
   complete, characters have been taken, and there is an end of file
   condition. The conversion process is controlled by the format flags and
   state variables of the ios part of the istream object. For the built-in
   types this happens as follows:

   char&

   A single character is taken from the input stream and stored in the
   character variable referred to.

   char *
   signed char *
   unsigned char *

   Characters are extracted and stored in the indicated array until a
   whitespace character is encountered, or until width()-1 characters have
   been extracted, or until an end of file condition is encountered. If

   termination is by a whitespace character, the whitespace character is not
   extracted.

   A terminating null character is then stored into the array, and if eof
   was encountered this may be the only result. The field width is reset to
   zero.

   signed char&
   short &
   int &
   long &
   unsigned char &
   unsigned short &
   unsigned &
   unsigned long &

   Conversion is controlled by the basefield format flags. The first
   character may be a sign, either + or -. Digits are then accepted until a
   non-digit is encountered.

   If ios::oct is set the acceptable digits are 0 through 7. If ios::dec is
   set, 0 through 9, and if ios::hex is set, 0 through 9 and a through f
   (either upper or lower case).

   If none of the basefield format flags are set, then the character stream
   is interpreted as per the language conventions: if the number starts with
   a 0, then scanning proceeds as if ios::oct were set, or if the sequence
   begins with 0x or 0X, then scanning proceeds as if ios::hex were set.
   Otherwise scanning looks for a decimal integer.

   If no digits are found other than the 0 in 0x or 0X, the error flags are
   set, and if the value read in this way can not be accomodated in a
   variable of the type being extracted into, i.e. there is overflow, the
   error flags are set (to badbit and failbit in the latter case, otherwise
   as discussed above).

   float &
   double &
   long double &

   Conversion is as per the C++ syntax for constants of these types,
   excluding any suffix character.

   The error flags are set if no digits are scanned, or if the stream does
   not contain a complete representation of a floating point number, or if
   there is an overflow condition.

   streambuf &

   All the characters that can be extracted from the input source are
   transferred as is to the referenced streambuf. Extraction stops only when
   an end of file condition occurs on the istream or on the streambuf.

   istream &(*)(istream &)
   ios &(*)(ios &)

   Pointers to functions of this particular form (pointer to function taking
   istream reference argument, and returning istream reference, and pointer
   to function taking ios reference argument, and returning ios reference)
   are treated specially. They act as parameterless manipulators, that is,

   the operator>> function does not neccessarily cause characters to be
   taken from the input stream and translated to give a value, rather it has
   an effect on the istream object involved. Manipulators of this sort are
   provided as follows:

   is >> dec;      // is.setf(ios::dec, ios::basefield);
   is >> oct;      // sets ios::oct similarly
   is >> hex;      // etc
   is >> ws;       // strips whitespace from input stream

Example 

   int i;
   double d;
   char buffer[10];
   cin.width(10);

   cin >> i >> d >> buffer;

Return Value

   Extractor functions must return a reference to the istream that is being
   extracted from.