The class tt(istream) supports both formatted and unformatted (em(binary))
    hi(binary input) input.  The emi(extraction operator) (ti(operator>>)) is
used to extract values in a i(type safe) way from tt(istream) objects.  This
is called i(formatted input), whereby human-readable i(ASCII) characters are
converted, according to certain formatting rules, to binary values.

The extraction operator points to the objects or variables to receive new
values.  The normal associativity of rshift() remains unaltered, so when a
statement like
        verb(    cin >> x >> y;)

is encountered, the leftmost two operands are evaluated first (tt(cin)
rshift() tt(x)), and an tt(istream &) object, which is actually the same
tt(cin) object, is returned. Now, the statement is reduced to
        verb(    cin >> y)

and the tt(y) variable is extracted from tt(cin).

The rshift() operator has many (overloaded) variants and thus many types of
variables can be extracted from tt(istream) objects. There is an overloaded
rshift() available for the extraction of an tt(int), of a tt(double), of a
string, of an array of characters, possibly to the location pointed at by a
pointer, etc., etc.. String or character array extraction
    hi(string extraction) hi(extracting strings)
    by default first skips all whitespace characters, and then extracts
all consecutive non-whitespace characters. Once an extraction operator has
been processed the tt(istream) object from which the information was extracted
is returned and it can immediately be used for additional tt(istream)
operations that appear in the same expression.

    Streams do not support facilities for formatted input as offered by
bf(C)'s ti(scanf) and ti(vscanf) functions. Although it is not difficult to
add such facilities to the world of streams, tt(scanf)-like functionality is
in practice never needed in bf(C++) programs. Furthermore, as it is
potentially type-em(unsafe), it is better to avoid using bf(C)-type formatted
input.

    When hi(binary file) binary files must be read, the information should
normally not be formatted: an tt(int) value should be read as a series of
unaltered bytes, not as a series of i(ASCII) numeric characters 0 to 9. The
following member functions for reading information from tt(istream) objects
are available:
    itemization(
        ithtq(gcount)(int gcount() const)
            (the number of characters read from the input stream
by the last unformatted input operation is returned.)
        ithtq(get)(int get())
            (the next available single character is returned
as an unsigned tt(char) value using an tt(int) return type.
endOfFile() is returned if no more character are available.)
        ittq(istream &get(char &ch))
            (the next single character read from the input stream is
stored in tt(ch). The member function returns the stream itself which may be
inspected to determine whether a character was obtained or not.)
        ittq(istream &get(char *buffer, int len, char delim = '\n'))
            (At most tt(len - 1) characters are read from the input
stream into the array starting at tt(buffer), which should be at least tt(len)
bytes long. Reading also stops when the delimiter tt(delim) is
encountered. However, the delimiter itself is em(not removed) from the input
stream.

    Having stored the characters into tt(buffer), a 0-valued character is
written beyond the last character stored into the tt(buffer).  The functions
tt(eof) and tt(fail) (see section ref(IOSTATES)) return 0 (tt(false)) if the
delimiter was encountered before reading tt(len - 1) characters or if the
delimiter was not encountered after reading tt(len - 1) characters.  It is OK
to specifiy a 0-valued character delimiter: this way NTBSs may be read from a
(binary) file.
        )
        ithtq(getline)
        (istream &getline(char *buffer, int len, char delim = '\n'))
            (this member function operates analogously to the tt(get) member
function, but tt(getline) removes tt(delim) from the stream if it is actually
encountered. The delimiter itself, if encountered, is em(not) stored in the
tt(buffer). If tt(delim) was em(not) found (before reading tt(len - 1)
characters) the tt(fail) member function, and possibly also tt(eof) returns
true. Realize that the tt(std::string) class also offers a function
tt(std::getline) which is generally preferred over this tt(getline) member
function that is described here (see section ref(STRINGMEMBERS)).
            )
        ithtq(ignore)
        (istream &ignore())
            (one character is skipped from the input stream.)
        ittq(istream &ignore(int n))
            (tt(n) characters are skipped from the input stream.)
        ittq(istream &ignore(int n, int delim))
            (at most tt(n) characters are skipped but skipping characters
stops after having removed tt(delim) from the input stream.)
        ithtq(peek)(int peek())
            (this function returns the next available input character,
but does not actually remove the character from the input stream. endOfFile()
is returned if no more characters are available.)
        ithtq(putback)(istream &putback(char ch))
            (The character tt(ch) is `pushed back' into the input stream, to
be read again as the next available character. endOfFile() is returned if this
is not allowed. Normally, it is OK to put back one character. Example:
            verb(string value;
cin >> value;
cin.putback('X');
                // displays: X
cout << static_cast<char>(cin.get());)

)
        ithtq(read)(istream &read(char *buffer, int len))
            (At most tt(len) bytes are read from the input stream into the
buffer. If endOfFile() is encountered first, fewer bytes are read, with the
member function tt(eof) returning tt(true). This function is commonly used
when reading em(binary) files. Section ref(IFSTREAM) contains an example in
which this member function is used. The member function tt(gcount()) may be
used to determine the number of characters that were retrieved by tt(read).
            )
        ithtq(readsome)(istream &readsome(char *buffer, int len))
            (at most tt(len) bytes are read from the input stream into the
buffer. All available characters are read into the buffer, but if endOfFile()
is encountered, fewer bytes are read, without setting the tt(ios::eofbit)
or tt(ios::failbit).
        )
        ithtq(unget)(istream &unget())
            (the last character that was read from the stream is put back.)
    )
