.. _IO:

Basic Input / Output (I/O)
===========================

.. index:: printf

.. _printf:
 
`printf()`
-------------------------

In the "Hello World" example we saw the use of `printf()` to display
a simple character string to the screen. Here we will look at how
to display the value of variables using `printf()`.

.. function:: printf(format, ...)

::

    #include <stdio.h>
    int printf( const char *format, ...);

The string pointed to by *format* consists of two types of items.  The first
type is characters that will be printed. The second type contains format
commands that define the way the other arguments are displayed.  Variables,
which are part of the output, are listed after the *format* string.

For example ...

::

    printf( "%s: your score for level %d was %f.\n", "Bill", 3, 89.3);

.. index:: format strings

Format modifiers
----------------

    Variable type specifier

        ======  ===========
        Letter  Meaning
        ======  ===========
        s       string
        c       character
        d       integer
        u       unsigned integer
        f       floating point
        o       octal
        x       hexadecimal
        ======  ===========

    l

        A long data type follows. It can be used with: d, o, u, x and f.
        `lf` is for type double.

    L

        Extra long data. 'Lf' for long double.

    field width

       An integer following the % sign indicates the field width. `'%5d'`,
       right justifies an integer in a 5 character field. The default padding
       is spaces, which can be modified with a second character: `'%05d'`, will
       print zeros to the left of the variable to fill out the 5 character
       space.

    negative sign 

      left justify. `'%-5d'` means that the integer is left justified in a 5
      character field.

    precision

       `'%.2f'` Will print exactly 2 digits of precision to the right of the
       decimal point.

Special formating symbols
--------------------------

============    ======================
Escape code     Meaning
============    ======================
`\\n`           New line
`\\t`           tab character
`\\\\`          A backslash character
============    ======================

Examples of :func:`printf()`
--------------------------------

::

    #include <stdio.h>
    
    int main(void)
    {
        int i = 3;
        char *string = "Howdy";
        double pi = 3.141592653589793;
        float r = 20.5;
    
        printf( "%s\t%d %lf %f\n", string, i, pi, r );
        printf( "%9s%-4d\t%10.2lf %5.4f\n", string, i, pi, r );
    }


::

    pilgrim:~> gcc print1.c 
    pilgrim:~> ./a.out
    Howdy 3 3.141593 20.500000
        Howdy3           3.14 20.5000


.. note::
   This the point where you should complete homework assignment 1: :ref:`hw1`.


.. _scanf:

`scanf()`
----------

.. index:: scanf
.. function:: scanf()

   The `scanf()` function is a general purpose input routine that reads from
   stdin, by default the keyboard, and stores the information read into the
   variables pointed to in its argument list.

    ::

        #include <stdio.h>
        int scanf( const char *format, ...);


The variables written to by `scanf()` are passed to it as pointers.
This is because arguments to functions are passed to C functions by
value, not by reference. A pointer provides a mechanism to
effectively pass arguments to a function by reference.

.. index:: pointer

**Definition:** A :dfn:`pointer` is a memory address. When a program runs,
each variable is stored at a certain location in the computer's
memory. So a pointer references, not to the value of the variable,
but the place in memory where the variable is stored.

A pointer to a variable is generated by the & symbol in front of
the variable name.

`scanf()` examples
--------------------

::

    int i;
    float y;
    
    scanf( "%d", &i );
    scanf( "%f", &y );
    scanf( "%d, %f", &i, &y );


Note that `scanf()`'s format string has three types of values:

- 
   Format specifiers -- `%x`, which follow the same syntax as format
   specifiers with :func:`printf()`.

- 
   Non-whitespace characters -- the comma in the third example is read
   by `scanf()` and discarded.

- 
   Whitespace characters -- spaces, tabs and even line returns are
   ignored by `scanf()` until it reads the desired number of
   variables.


.. warning::

    `scanf()` is good for reading a single variable, but is not the best at
    reading a large number of variables.  The problem relates to the user of
    the program. They may not understand exactly what data they are asked to
    provide.  Therefore, for complex data input, `scanf()` is *not
    recommended*. Later, we will discuss a routine called ReadLine() that is
    more robust (:ref:`readline`).

`getchar` / `putchar` Example
-------------------------------

This example illustrates an alternative to `scanf()` and `printf()`.  Here the
data is read one character at time.  Use of the `fflush()` function is to
force the display of any data that may still be in the standard output
buffer.  At this point, this example is informational only.

::

    #include <stdio.h>
    
    int main(void)
    {
        int c;
    
        while( (c=getchar()) != EOF )
            putchar(c);
        fflush(stdout);
        return 0;
    }

.. note::

   This is the point where you should complete homework assignment 2:
   :ref:`hw2`.