..  _elab1:

Exam 1 Lab
##########

..  include::   /references.inc

You should be reasonably comfortable with simple function parameters by now.
The parameters you have been using are called **value** parameters, because the
actual parameters provided by the caller are evaluated, and the final value is
passed to the function. Inside the function, the parameter name is initialized
with that value as the function starts processing.

There is another kind of parameter, the **reference** parameter. You cannot
place an expression on the call if you use one of these parameters. Instead,
you provide the name of a suitable variable in the function call. What happens
is different. The **addres** of the caller's variable is passed to the function.
Instead of setting up a new variable inside the function, the function uses the
caller's variable directly! That means it can mess with the data in the caller's
world. This is both powerful, and a bit scary!

In this lab project, we are going to run a simple experiment to see how
*reference* parameters work.

Creating Reference Parameters
*****************************

The only new thing you need to know is that you must add a "&" symbol after the
parameter type specification to set up a *reference* parameter:

..  code-block:: c

    int myfunc(int& vara) {
        vara = 42;
        return -42;
    }

When you call this function, provide the name of a variable from your world:

..  code-block:: c

    int testdata = 0;
    int dummy;

    dummy = myfunc(testdata);

With this, we can get a normal return value from our function. But a hidden
side effect is possible as well. If *myfunc* modifies the parameter variable
(**vara** in this case), the caller's **testdata** will be modified. It is
important that you realize this!

Your Assignment
***************

You are to build a project that has three files:

    * main.cpp

    * compare.cpp

    * compare.h

The Compare Function
====================

The "compare.cpp" file contains one function, also named "compare". This
function takes two integer **reference parameters** with names "param1" and
"param2" and compares them. It returns a **single character** based on what it
sees. Here is what you are to return:

    * "=" if the two values are equal
    
    * "<" if **param1** is less than **param2**
    
    
    * ">" if **param1** is greater than **param2**

Just to prove that the "compare" function really does have access to your
caller's variables, have the function **flip the sign of each parameter** before
you process the **return** statement you need in this function:

..  code-block:: c

    param1 = -param1;
    param2 = -param2;

..  warning::

    This will mess up your final output, but that is fine for what we are trying to see here!)

The Main Function
=================

Set up the main program that asks the user for two integer numbers, which are
stored in variables named "var1" and "var2". The main program then calls the
"compare" function described above, passing in the parameters "var1"
and "var2". Once you have the return character, you are to test that character
and print out a more complete English statement about the result. For example,
if you get back an "equal sign" character, you will print out this:

    * 1234 is equal to 1234

..  note::

    Since you flipped the sign in the **compare** function, you will actually
    see negative values here, not the positive values the user entered).

Add output statement similar to the above for the other two possible return
characters.

What to turn in
***************

Place your code in your **Homework** repository under a folder named
**Exam1Lab**. Push your code to GitHub_ and make sure you can see it in your
web browser before the deadline. You can (and probably should) use a Makefile
for this project, but I will not grade anything but the three files required
for this project. 

Your program must compile and run with no errors to be considered for grading.
If it does not run properly, you will at least get partial credit.

..  warning::

    This assignment is due by midnight on Sunday, March 3. I will check the
    time of your submission as it is recorded on GitHub_. Any work submitted
    after midnight will not be graded, so make sure you have something
    submitted before that time.