..  _function-intro:

C++ Function Intro
==================

..  include::   /references.inc
..  wordcount::
..  vim:ft=rst spell:


We will be using code written by other programmers a lot in this course. Most
of the time we will access this code by calling the code into action using a
C++ ``function``. We need to start early in understanding these things,
otherwise a lot of your code is not going to make sense!

The easiest way to understand functions is to consider them blocks of code
inside a box with a name painted on the outside. Hopefully, the code inside the
box does something interesting. It would be especially nice if we needed the
code inside the box in several places in our program, but that is not really
necessary. 

When we want the code inside the box to do its thing, we need a way to activate
it. This is called *calling* the function. Perhaps we need to provide the code
inside the box some information that it needs to work, and perhaps the result
of activating the code will be to produce some answer that we will take and use
in other parts of our program. 

Defining a Function
-------------------

We create a function by coming up with a name, which should describe what the
function is going to do for us. Next, we identify any information the function
will need to accomplish its task; we call this information *parameters*.  Next,
we describe what kind of answer the function will produce (if any); this is
called the *return value*. Finally, we write the code that defines the action
of the function. 

Here is an example of how it all looks in C++: 

..  code-block:: c

    float my_sin(float angle) {
        float answer;
        // code to calculate the sin of an angle

        return answer;
    }


The first **float** keyword defines the kind of value the function will return,
a floating point number in this case. The name of the function is **my_sin**.
The function needs one piece of data to work with, that *parameter* will be
named **angle** inside the function, and it is another floating point number. 

The body of the function is the code between the curly braces. At some point in
that code, we need to include a **return** statement that causes the function
to quit work and hand back the value specified in the statement. The thing
after the word **return** is an expression, usually just the name of the
variable you used to calculate the answer, that you want to send back to
whoever called this function. 

Calling a Function
------------------

When we want the code inside the function to do its thing, we `call` the
function by creating a statement that contains the name of the function. That
reference will include parentheses inside of which we will provide actual
parameters we want the function to use to do its work. The parameters are
separated by commas if there are more than one of them. 

Parameters can be literal values, or the names of variables defined in our
calling code, or expressions the system will evaluate before calling the
function. The system will pass the data we specify into the function when the
function wakes up. For now, we will assume that the function has no idea where
the parameter information came from, it just uses the values passed in and
refers to those values using the parameter names we defined when we wrote the
function. 

Parameter names defined in the function code do not need to be the same as the
names from the caller code we place between the parentheses when we call the
function. 

Phew - sounds complicated, but it is actually fairly simple. (There are more
rules on these parameters, but this is enough for now!) 

Here is code that demonstrates calling the function: 

..  code-block:: c

    float mySin, myCos;
    float myAngle = 37.0;
    float PI = (float)acos(-1.0); // this is a pretty accurate PI

    myAngle = myAngle * PI / 180.0;
    mySin = my_sin(myAngle);
    mySin = my_sin(180 * PI);		// the expression is evaluated and the result passed in

    myCos = sqrt(1.0 - my_sin(myAngle)*my_sin(myAngle));	// sqrt is a new function


In each of these examples, the reference to the **my_sin** function is part of
an expression that is being evaluated. Once the entire expression has been
evaluated, the value is stored in the container named on the left side of the
equal operator. The normal rules of evaluating expressions are still being
followed, but when the system gets to the reference to the function, the
expression evaluation pauses for a bit while the code for the function figures
out the answer needed. That answer is returned to the expression evaluator
which continues on with its work.