C++ - Text Input
################

:Ref: http://www.learncpp.com/cpp-tutorial/132-input-with-istream/

..  include::   /header.inc

In almost all beginning C++ programs, we read user inputs using the standard
C++ library ``iostream``. You see code that looks like this:

..  literalinclude::    code/example1.cpp
    :linenos:

Those ``<<`` and ``>>`` operators are called insertion or extraction operators,
depending one which way the data will go. We "extract" something from the
outside world into our programs from the "standard input" stream
(``std::stdin``), and "insert" something that is going to that outside world as
part of the "standard output" stream (``std::stdout``) from our program.
(Occasionally, we might insert messages about problems by sending something to
the "standard error" stream (``std::stderr``)as well).

C++ Output
==========

We can send literal strings to output, as we commonly do in our very first C++
program (you did write your "Hello, World!" program, right?). We can also send
the contents of any user variable to output as well. The standard output system
can take any predefined variable type and figure out how to display that type
on the screen. If you construct your own data types (classes), we can extend
these operators so you can input and output these new types as well!

C++ Input 
=========

Input works in a similar way, but we have to deal with a few subtleties!

When we direct input into a user variable of some type, the system tries to
scan what is entered, looking for something that matches what is expected. It
will stop scanning when it runs into a character that cannot be part of the
data type specified for the variable you are trying to load!

In the example, we asked the user for an integer number. If they typed 12.5 in
as input, the program would stop at the "." character, since that cannot be
part of an integer.

Any additional input operations will start reading at that spot, giving you
unexpected results:

..  literalinclude::    code/example2.cpp
    :linenos:

Run this and enter 12.5 and see what happens.

We only entered one thing on input, but we got two results.

User Validation
***************

This example points out a serious problem you will have when asking a human for
something::

    Users cannot be trusted to do what you ask!

They will do what they want, and you have to be ahead of them!

..  note::

    I learned this lesson years ago, when I wrote the first program I expected
    to be paid to write. On my very first demo to the client who asked me to
    build a program for him, I watched his finger go for a key I never thought
    anyone would hit when asked for an input, and the program did what it was
    designed to do! It blew up and crashed! I never realized I had designed it
    to do that, and I never designed another program to do that again!

    Instead, I started "validating" all human inputs. (Grumble, Grumble! Dumb
    humans!)

Extraction Operators
********************

The extraction operator ``<<`` normally skips anything that displays as
"whitespace". That means it ignores spaces, tabs, and newlines! Try the previous
example by hitting a few of these before you actually enter the number.
..  vim:filetype=rst spell: