..  _lab2:

Lab 2 - Simple C++ Functions
############################


For this lab, you will need to clone another repository using the invitation link below:

    * `COSC1337-002 <https://classroom.github.com/a/LcGW5-ji>`_

Writing a bigger program
************************

Now that we have seen how to put a simple program together that uses C++
functions, let's build a program that does the most basic job all students have
to contend with, process the grades on a test and produce a summary of the
results. The big wrinkle in this is that I want this to be a multi-file
program. 

We want to do three simple things:

    * Figure out the best score of all scores produced

    * Figure out the worst score of all scores produced

    * Assign a letter grade for each score produced

Here is our list of grades to process:

..  code-block:: c

    int grades[15] = {  55, 87, 93, 77, 92, 88, 67, 81, 84, 73, 81, 92, 89, 100, 62 };

This is formally an ``array`` of numbers. We will look at arrays later, but
they work much like lists in Python.

The big difference here, is that when we ask C++ to hand an array of data to a
function, we actually just hand the address of the first element of the array
to the function. We need to tell the function how many elements are in the
array and then use that number to loop over the array to make sure we use the
array correctly. 

..  warning::

    Messing this up is a huge source of bugs in programs!

Here is an example to make sure we do things right:

..  code-block:: c

    void show_grades(int data[], int num_values);

    int main(int argc, char * argv[]) {
        int grades[15] = { 55, 87, 93, 77, 92, 88, 67, 81, 84, 73, 81, 92, 89, 100, 62 };

        show_grades(grades, 15);
    }

Place this code in a file named ``grader.cpp``

Here is the function that will display the grades:

..  code-block:: c
    
    #include <iostream>

    void show_grades(int data[], int num_values) {
        for(int i=0 i<num_values;i++)
            std::cout << data[i] << std::endl;
        }
    }

This code is set up to live in a separate file, probably called something
useful, like ``utilities.cpp``.

When this code runs, the function wakes up with `data` actually pointing to the
`grades` array from the caller's data area. It also is using a value for
`num_values` set to 15, since that is what the caller indicated was the right
value.

It is up to the caller to make sure the right value is sent to the function. By
doing things this way we can write a general purpose function that can be used
for any data array of any size. That is kind of handy. But it is easy to mess
things up if the caller does things wrong. Oh well, that is a small price to
pay for such a useful system.

From our lecture, we should set up a header file to connect the main code and
this function properly.

Here it the header file we should create. Name it ``utilities.h``:

..  code-block:: c

    #ifndef UTILITIES_H
    #define UTILITIES_H

    void show_grades(int data[], int num_values);

    #endif

In many real header files, the parameter names are omitted. I like to include
them as a form of documentation. We will learn more about all of this later in
the course.

Building the Code
*****************

You will need to compile each code file (ending in .cpp) separately, and build
an associated object file (ending with .o). The link step will list all of the
object files like this:

..  code-block:: bash

    > g++ -c grader.cpp -o grader.o
    > g++ -c utilities.cpp -o utilities.o
    > g++ grader.o utilities.o -o grader.exe

That "-c" tell the compiler not to try to build an application, just
"compileonly". The last line runs the linker which puts together the real
application. (On a Mac/Linux ssystem, leave off the ".exe" extension)

Remember that you can edit the command lines you have previously entered. Just
use the up arrow key to work through the set of compile steps. Then link the
final code.

Your lab project
****************

You need to complete this lab by writing three functions in the utilities
file. Modify the header file and list the prototypes for each function.

You will call each function with the `grades` array as a parameter, and the number of values
in that array in your main routine and make it do the following work:

    * Use the max value function to print out the max value found in the grade array.
    
    * Use the min value function to print out the min value found in the grade array
    
    * Use the letter grade function to print out the grade number and the associated
      letter grade for each score in the array. This will require a nested
      if-then else statement to figure this out.

You get to pick names for these three funcitons, so pick something that names
sense.  Do not worry about making this output extremely pretty. All we are
doing here is trying to get our first fairly involved C++ program put together.
Place all of this code in a folder named ``LAB2`` in the new labs-username
rrpository

..  vim: set filetype=rst spell